# THX-cctv-image-gen 工作链路与自检闭环

本文档说明运营同事在 Codex 中调用 `THX-cctv-image-gen` 时，Agent 应如何完成从短需求到出图、自检、返修的完整闭环。

## 定位

`THX-cctv-image-gen` 是 THX Codex-only Skill。

它不是 WorkBuddy Skill，不走 WorkBuddy 上传、zip 安装或安装页分发。它依赖 Codex 环境里的 `image_gen / image2` 直接出图。

## 运营怎么说

同事不需要写长 prompt。日常最短格式：

```text
请使用 THX-cctv-image-gen，直接出图：野鸟V8，红雀叼种子，TikTok 图。
```

如果是正式产品图，上传对应产品参考图，再补一句：

```text
按我上传的产品图锁结构。
```

当前可直接识别的产品名：

- 野鸟V5
- 野鸟V8
- 火箭款黄色
- 蜂鸟

## Agent 的完整工作链路

### 1. 解析短需求

先从用户短句里提取：

| 信息 | 示例 |
|---|---|
| 产品 | 野鸟V5、野鸟V8、火箭款黄色、蜂鸟 |
| 鸟种 | 红雀、山雀、蓝松鸦、蜂鸟 |
| 动作 | 叼种子、低头啄食、站横杆、悬停 |
| 用途 | TikTok、Facebook、Shop、概念测试 |
| 参考图 | 用户是否上传了真实产品图 |

如果没有参考图，Agent 要在心里标记：这张只能作为构图/风格测试，不作为正式产品结构验收。

如果用户上传或点名参考图，用户图优先级最高。多张图结构不一致时，不要混合生成；先说明差异，再选定本轮要锁定的结构。

### 2. 打开参考图

产品相关任务必须先打开参考图，再编译 prompt：

| 场景 | 必做 |
|---|---|
| 用户上传或点名图片 | 打开用户图片，按用户图片锁结构 |
| 用户只说 V5 / V8 / 火箭款 / 蜂鸟 | 读 `references/reference-gallery-index.md` 和 `references/reference-image-catalog.md`，打开 `assets/reference-gallery/usable-images/` 中对应的单张可用图 |
| 没有型号备注 | 标记为待确认，不能把产品结构判为最终通过 |
| 没有可用单张参考图 | 标记为构图/风格测试，不判产品结构通过 |

参考图打开后，先写出本轮结构锚点：前挡板、透明件、食盆/格栅、横杆、logo、鸟脚落点。不要从多种产品图里拼一个不存在的结构。

### 3. 读取规则

按任务需要读取 reference：

- 产品结构：`references/product-structure-dictionary.md`
- Prompt 组件：`references/prompt-library-v1.md`
- 可用图标准：`references/usable-image-criteria.md`
- 返修规则：`references/repair-playbook.md`
- 鸟种动作：`references/bird-presets.md`
- 可用图索引：`references/reference-gallery-index.md`

只读取当前任务需要的部分，不要把所有 reference 一次性塞进输出。

### 4. 编译实际生图 Prompt

短需求不能原样丢给 image2。Agent 要把它扩成完整 prompt，包含：

- 产品结构锁定
- 鸟脚落点
- 鸟体比例
- 动作细节
- 普通后院背景
- 低码率监控画质
- 种子和使用痕迹
- 负面约束

例如用户说：

```text
野鸟V8，红雀叼种子，TikTok 图。
```

Agent 应扩写为：

```text
Nafnti Wild Bird V8 blue-and-orange seed bird feeder, blue body and blue round rails, orange front grid tray with visible seed slots, visible Nafnti logo, northern cardinal holding one seed in its beak, both feet gripping the rail, ordinary American backyard, low-bitrate feeder-camera screenshot, 16:9 source image for TikTok cropping...
```

### 5. 调用 image2 出图

在 Codex 环境可用 `image_gen / image2` 时，直接调用生图工具。

不要只输出 prompt 让运营自己复制，除非当前环境没有生图能力。

### 6. 打开生成图自检

出图后必须看图再回复，不能只说“已生成”。

如果没有打开生成图完成视觉检查，不允许把任何项目写成“通过”。产品结构错时，即使背景、鸟脚和监控感很好，也必须判“不通过”或“需返修”。

自检表：

| 项目 | 通过标准 |
|---|---|
| 产品结构 | 产品分支正确，不跑成其他款 |
| 产品锚点 | 主色、横杆、食盆/格栅/花蜜口、logo 或关键结构清楚 |
| 鸟脚/关系 | 鸟脚真实落在横杆、食盆、格栅或边缘；蜂鸟靠近花蜜口 |
| 鸟体比例 | 鸟像真实站在喂鸟器上，不是远景小鸟或巨鸟压住产品 |
| 动作 | 叼种子、啄食、站立或悬停动作清楚 |
| 背景 | 普通真实后院，不是豪宅、棚拍、广告布景 |
| 监控感 | 近景广角、低码率、轻微鱼眼，不是商业大片 |
| 种子/使用痕迹 | 种子颗粒、散落、划痕或使用感可见 |

### 7. 发给运营的固定格式

每次出图后，都必须同时发：

```markdown
**图片**
[生成图]

**本次使用的 Prompt**
[实际传给 image2 的完整 prompt]

**自检结论**
- 产品结构：[通过/半通过/不通过 + 原因]
- 鸟脚/比例：[通过/半通过/不通过 + 原因]
- 背景/监控感：[通过/半通过/不通过 + 原因]
- 种子/使用痕迹：[通过/半通过/不通过 + 原因]

**如果要返修**
[1-3 条短返修建议]

**任务归档**
- GitHub Issue：[本次出图任务 Issue 链接]
- 图片归档：[本次 run 的线上归档链接]
```

Prompt 必须给出，因为运营要复用、对比和填试用表。

### 8. 出图任务归档

正式运营使用时，每次直接出图后都要自动创建一条 GitHub Issue，不要求运营转发给负责人。

归档内容包括：

| 字段 | 说明 |
|---|---|
| 原始需求 | 运营同事发来的短需求 |
| 图片 | 候选图；如果已有最终可用图，单独标出 |
| Prompt | 本次实际传给 image2 的完整 Prompt |
| 自检结论 | 产品结构、鸟脚比例、背景监控感、种子使用痕迹 |
| 运营反馈 | 首次创建时可留“待补充” |
| 当前状态 | 待判断 / 需返修 / 可用 / 废弃 |
| GBrain 候选 | 只标记可复用产品结构、Prompt 规则、自检 SOP |

默认使用：

```bash
scripts/create-image-run-issue.sh
```

Issue 池：

```text
haloshin/bird-feeder-image-generator
```

图片归档：

```text
http://8.135.42.221/thx-workbuddy/cctv-image-gen/runs/
```

运营同事只需要继续在 Codex 里说哪里不好或哪张可用；负责人直接看 Issue 池做判断。

### 9. 返修闭环

如果运营反馈失败点，不要重写整段 prompt。先保留原图正确部分，只修失败点。

用户说：

```text
鸟脚悬空，背景太豪宅，产品格栅没了。
```

Agent 应做：

1. 保留原产品分支。
2. 保留鸟种和动作。
3. 只加强脚落点、普通后院、格栅结构。
4. 再次调用 image2。
5. 再次自检并给出新 prompt。
6. 更新同一个出图任务 Issue：追加返修图、返修 Prompt、失败原因和新自检结论。

每张图最多返修 3 次。超过 3 次仍不可用，记录为最终不可用。

## 产品分支核查重点

### 野鸟V5

- 蓝绿色主体。
- 蓝绿色横杆。
- 必须先选定单张参考图，不要只凭“V5”猜结构。
- 若参考 `黑鸟2.png` / `黑鸟和红雀.png`：蓝绿色弧形前挡板、居中 Nafnti logo、透明矩形料盒、横向蓝绿色圆杆、低矮前景种子槽。
- 若参考 `红雀2.png`：橙色分格盘结构，不要混入透明矩形料盒结构。
- 不要把多张参考图里的配件混成一个不存在的产品。
- 不能变成火箭款黄色或蜂鸟花蜜口。

### 野鸟V8

- 蓝色主体和蓝色横杆。
- 前方橙色格栅/孔位食槽。
- Nafnti logo 或前方机身区域可见。
- 不能跑成 V5 开放食盆。
- 不能跑成火箭款黄色。

### 火箭款黄色

- 黄色或黄绿色主体。
- 黄色横杆。
- 黄色食物区域和深色孔位/格栅。
- 可出现红黄圆形侧盖。
- 不能跑成 V5 或 V8。

### 蜂鸟

- 使用蜂鸟专用花蜜喂食器。
- 蜂鸟靠近 feeding port。
- 不出现混合种子或黑瓜子。
- 不套用野鸟V5/V8 种子喂食器。
- 没有参考图时只能做概念测试。

## 成功标准

单张图：

- 产品结构至少半通过。
- 已打开单张参考图或用户上传图，并按选定图锁结构。
- 鸟脚/比例不能明显失败。
- 画面像喂鸟器监控截图。
- Prompt 和自检结论完整返回。

10 张试用：

- 首轮可用率 >= 50%。
- 平均返修次数 <= 2。
- 最终可用率 >= 80%。

达标后再考虑更大范围 Codex 试用；不进入 WorkBuddy 安装流程。
