# progress 条目样例 · ai-agent-dev + backend-dev

> 本文件展示 2 个执行层 dev 的 progress 自报真实样例。**deck slide 38 引用** ai-agent-dev 这条做样板（图配真实 progress 截图 + 高亮 SIT 证据段）。

按 [`.claude/standards/ac-lifecycle.md`](../../../.claude/standards/ac-lifecycle.md) "Self-Reporting Pattern" 节强制对象 + [`agf-running-sit-tests`](../../../.claude/skills/agf-running-sit-tests/SKILL.md) skill SIT 证据段格式。

---

## 文件 1：`progress/ai-agent-dev.md`

```markdown
# ai-agent-dev · 旅游明信片三步链路实现

| 字段 | 值 |
|---|---|
| Task | postcard-feature #3 |
| 开始 | 2026-05-16 11:00 |
| 完成 | 2026-05-17 16:30（2 个工作日内）|
| Worktree | ~/wt/agf-postcard-ai/ |

## 实施摘要

按 ADR-001 选型，实现 Vision → LLM → 文生图 三步链路。
代码 380 行 + prompt 120 行（3 文件），Unit 12 用例，SIT 5 道盲测。

## 关键决策（实施中浮现）

1. **Vision 与 LLM 用同一 Seed-2.0-Pro 模型，但分两次调用（教学版）**
   - 原因：每步独立可观察 / 独立失败 / 独立 review
   - 进阶版（一次调用）放 §7 拓展讲，v1.1 production 后切换

2. **prompt 用 markdown 文件管理（不 hardcode 进 Python）**
   - `backend/app/agents/postcard_prompts/v1_*.md`
   - 改 prompt 必走 PR review（content 变更而非 code 变更）

3. **fallback 链验证（手动触发）**
   - 模拟 Pro 限流 → 自动切 Lite → latency 升 18%（仍满足 AC1）

## AC 自验逐条 ✓

| AC | 目标 | 实测 | 状态 |
|---|---|---|---|
| AC1 | P95 ≤ 30s | 27.4s（5 道盲测）| ✅ |
| AC2 | Vision 准确率 ≥ 85% | 92%（5/5 命中主体）| ✅ |
| AC3 | 文案相关性 ≥ 4/5 | 4.3 / 5（3 评委盲评）| ✅ |
| AC4 | 风格色调 hash ≥ 0.75 | 0.81 平均 | ✅ |
| AC5 | cost ≤ ¥0.30 / 张 | ¥0.21 / 张实测 | ✅ |

## Unit 测试（12 用例）

```bash
$ cd backend && pytest tests/unit/test_postcard_*.py -v
========================= 12 passed in 3.45s =========================
```

详见 `backend/tests/unit/`。

## **SIT 证据**（dev 自跑，code-reviewer 在 review 时 audit）

按 [`agf-running-sit-tests`](../../../.claude/skills/agf-running-sit-tests/SKILL.md) 标准：链路完整 / AC 覆盖 / 证据真实 / 反例边界 四项。

### SIT-1 链路完整性（5 道盲测）

5 张测试照片走完三步链路，每步输入输出可追溯：

```bash
$ python scripts/run_postcard_sit.py --photos tests/fixtures/postcard-blind-5/
[1/5] 海边日落.jpg → Vision: "夕阳/海面/剪影" (2.1s) → LLM: "夕阳把海面..." (4.8s) → 文生图: 1024×1024 (17.3s) → 24.2s ¥0.213
[2/5] 山林晨雾.jpg → Vision: "山林/晨雾/远景" (1.9s) → LLM: "晨雾在山谷..." (5.1s) → 文生图: 1024×1024 (18.0s) → 25.0s ¥0.215
[3/5] 城市夜景.jpg → Vision: "城市/夜景/灯光" (2.0s) → LLM: "夜色降临..." (5.3s) → 文生图: 1024×1024 (17.8s) → 25.1s ¥0.218
[4/5] 古城街景.jpg → Vision: "古建筑/石板路/行人" (2.2s) → LLM: "穿过古城..." (4.9s) → 文生图: 1024×1024 (18.2s) → 25.3s ¥0.214
[5/5] 田园风光.jpg → Vision: "稻田/远山/农舍" (2.0s) → LLM: "金色稻浪..." (5.0s) → 文生图: 1024×1024 (17.5s) → 24.5s ¥0.211

5/5 链路完整 · 平均 24.8s · 平均 ¥0.214
```

### SIT-2 AC 覆盖（5 AC 全覆盖）

- AC1 时延 → 5/5 全部 ≤ 30s
- AC2 Vision 准确率 → 5/5 主体命中
- AC3 文案相关性 → 3 评委盲评 4.3/5 详见 `docs/qa/postcard-blind-review-table.md`
- AC4 风格色调 hash → 平均 0.81（详见 `tests/sit/style_hash_log.json`）
- AC5 cost → 5/5 全部 ≤ ¥0.30

### SIT-3 证据真实（命令 / 输出 / 文件 hash）

- `tests/sit/sit-log-2026-05-17.txt` 含完整 stdout（含时间戳）
- `tests/sit/output-images/` 5 张实际生成的卡片图（SHA256 列在 sit-log）
- `tests/sit/style_hash_log.json` Seedream 出图色调与 LLM 关键词的对比数据

### SIT-4 反例边界（3 种异常）

- 上传纯文字图（无视觉主体）→ Vision 返回"无法识别主体"+ LLM 拒绝生成 ✓
- 上传违禁内容（暴力 / 色情）→ Vision 内容安全 hook 拦截 + 返回 422 ✓
- 上传 > 10 MB 大图 → 前置校验拒绝（< 1KB 流量浪费）✓

## Plan Mode 触发记录

本 task 未触发 Plan Mode（无模型切换 / prompt 重构 / 工具调用变更）。

## Skills used

- `agf-wiring-multi-llm-sdk` v1.2（OpenAI 兼容 adapter + cost guardrail）
- `superpowers:test-driven-development`（Unit test 先写，commit 顺序 test: → feat: → refactor:）
- `agf-running-sit-tests` v2.0（SIT 自跑 + 本段证据）

## 交接

- PR #287 已开（feature/postcard-link）
- @code-reviewer 接 review + SIT Audit
- @qa-engineer 准备 E2E 用例（业务方提 5 张照片）
```

---

## 文件 2：`progress/backend-dev.md`

```markdown
# backend-dev · 旅游明信片 API + DB schema

| 字段 | 值 |
|---|---|
| Task | postcard-feature #2 |
| 开始 | 2026-05-16 11:00 |
| 完成 | 2026-05-17 14:00 |
| Worktree | ~/wt/agf-postcard-be/ |

## 实施摘要

提供 ai-agent-dev 所需 API 契约 + 数据存储 + 图片文件管理。

代码 240 行 + Alembic 迁移 1 个 + Pydantic schema 4 个。

## 关键产物

| 类型 | 路径 | 说明 |
|---|---|---|
| API | `backend/app/api/postcards.py` | POST /api/postcards · GET /api/postcards/{id} |
| Schema | `backend/app/schemas/postcard.py` | PostcardCreate / PostcardRead 等 4 个 |
| 模型 | `backend/app/models/postcard.py` | SQLAlchemy ORM |
| Migration | `backend/alembic/versions/2026_05_16_add_postcards.py` | 新增 postcards 表 + index |
| 存储 | `backend/app/services/image_storage.py` | MinIO 适配（local dev）/ S3（prod） |

## AC 自验逐条

| AC | 目标 | 实测 | 状态 |
|---|---|---|---|
| AC1 时延 | API 自身延迟 ≤ 500ms | P95 320ms（不含 LLM）| ✅ |
| AC5 cost | API 不引入额外 cost | ✓ 仅存储成本 ¥0.001/张 | ✅ |

其他 AC（AC2-4）属于 ai-agent-dev 范围，本 task 不覆盖。

## Unit 测试

```bash
$ pytest tests/unit/test_postcard_api.py -v
========================= 18 passed in 1.92s =========================
```

## **SIT 证据**

### SIT-1 API 链路完整

```bash
$ curl -X POST http://localhost:8000/api/postcards \
    -F "photo=@tests/fixtures/blind-1.jpg" \
    -F "one_liner=和爸妈在西湖边的下午"
{
  "id": "pc_01H...",
  "status": "processing",
  "created_at": "2026-05-17T10:23:45Z"
}

# 24.2s 后查询
$ curl http://localhost:8000/api/postcards/pc_01H...
{
  "id": "pc_01H...",
  "status": "completed",
  "text": "夕阳把海面染成金色...",
  "image_url": "https://.../pc_01H....png",
  "cost_cny": 0.213,
  "elapsed_ms": 24200
}
```

### SIT-2 DB schema 完整性

```sql
\d+ postcards
-- 13 列 + 3 index（id PK, user_id, status）
-- migration apply / rollback 各跑 1 次 ✓
```

### SIT-3 MinIO 存储

5 张 SIT 测试图均成功上传 MinIO（local），下载可访问，CORS 配置已通过浏览器测试。

## 交接

- PR #288 已开（feature/postcard-be）
- @ai-agent-dev 可消费本 API 契约（Pydantic schema 在 PR description）
- @code-reviewer 接 review
```

---

## 引用与下游

- code review 进入：[04-review-report.md](./04-review-report.md)
- UAT 触发：见 [05-uat-report.md](./05-uat-report.md)
- deck slide 引用：slide 38（ai-agent-dev progress） / slide 39（SIT 证据高亮）
