astrbot_plugin_imagestudio/imagestudio_codex_hermes_dev_flow_v3.md

9.8 KiB

AstrBot ImageStudio Codex / Hermes 开发流程指南 v3.0

生成日期:2026-07-04
目标:让 Codex / Hermes 能按正确顺序读懂并实现插件,不跑偏、不乱改、不单独起端口。


1. 代理分工

Codex

定位:主代码实现代理。

适合:

数据库模型
Repository / Service / Route
接口实现
队列逻辑
单元测试
前端组件实现
Bug 修复

Hermes

定位:需求整理和二次审查代理。

适合:

需求归纳
开发任务拆解
文档维护
UI 与后端契约检查
验收清单
代码审查提示

禁止

禁止 Codex 和 Hermes 同时修改同一分支。
禁止一次性要求代理“实现整个插件”。
禁止把真实 API Key / Cookie / Token 发给代理。
禁止让代理擅自启动独立 Web 端口。

2. 推荐阅读顺序

交给 Codex 或 Hermes 前,按此顺序提供文档:

1. imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md
2. imagestudio_api_contract_v3_ui_adjusted.md
3. imagestudio_codex_hermes_dev_flow_v3.md
4. 原始后端 PRD v2:astrbot_imagestudio_prd_v2_engineering.md
5. UI 需求:生图插件的UI界面.md

如果上下文容量不足,优先给 1、2、3。


3. 分支策略

main
├── feature/p0-db-models-codex
├── feature/p0-api-routes-codex
├── feature/p0-plugin-page-ui-codex
├── feature/p0-standalone-web-ui-codex
├── docs/ui-contract-hermes
└── review/p0-audit-hermes

规则:

  1. 一个任务一个分支。
  2. 一个代理一次只处理一个任务。
  3. 合并前必须人工看 diff。
  4. 合并前必须运行测试。
  5. 数据库迁移必须单独审查。

4. 开发阶段总览

Stage 0:仓库初始化

目标:

建立目录结构
建立配置文件
建立测试框架
建立基础 DB helper
建立通用响应格式

交给 Codex 的任务:

任务 S0-1:创建项目目录结构和空模块。
任务 S0-2:实现 common response DTO。
任务 S0-3:实现 request_id / audit logger 基础工具。

Stage 1:数据库与 Repository

目标:

实现 UI 必需事实表。

优先表:

character_profiles
profile_workflows
workflow_nodes
generation_images
material_categories
materials
wardrobe_items
workflow_sessions
generation_tasks
media_files
audit_logs

Codex 任务示例:

任务 S1-1:
实现 character_profiles 表、Repository、Service。
不得修改 UI。
验收:能创建、查询、更新、软删除 profile。

任务 S1-2:
实现 profile_workflows 和 workflow_nodes。
验收:一个 profile 下能创建 workflow,workflow 下能列出 nodes。

任务 S1-3:
实现 generation_images。
验收:能按 node_id 查询图片卡片,支持 selected 状态。

Stage 2:Web API 注册

目标:

所有 P0 API 可被 Plugin Page Bridge 和 Standalone Web 调用。

任务:

S2-1 ui/bootstrap
S2-2 dashboard/summary
S2-3 profiles CRUD
S2-4 workflows + nodes
S2-5 images
S2-6 jobs
S2-7 settings schema/current
S2-8 media sign/fetch

验收:

- 所有 API 返回统一 JSON。
- 401/403/404/422/500 错误格式统一。
- 写接口记录 audit_logs。

Stage 3:双 UI 挂载

目标:

Plugin Page UI 和 Standalone Web UI 都能打开。

Codex 任务:

S3-1:
实现 pages/imagestudio/index.html 轻量 UI。
只显示 dashboard summary、queue、recent jobs、打开完整工作台按钮。

S3-2:
实现 web/index.html 静态挂载。
不单独起端口。
路径为 /api/v1/plugins/extensions/astrbot_plugin_imagestudio/web。

S3-3:
实现 PluginPageClient 和 DirectWebClient。

验收:

- AstrBot 插件页内可打开轻量 UI。
- 浏览器可直接打开 /web。
- 两个 UI 调用同一个 dashboard/summary。

Stage 4:单图流闭环

目标:

用户可以从 Web UI 创建单图流、提交生成、查看图片卡片。

任务:

S4-1 single_flow engine
S4-2 nodes/{node_id}/generate
S4-3 queue_manager 基础队列
S4-4 generation_tasks 状态迁移
S4-5 image_service 保存 VFS + thumbnail
S4-6 selected image 状态

验收:

- 至少支持 mock backend。
- 任务状态 CREATED -> QUEUED -> RUNNING -> SUCCEEDED。
- 图片卡片展示 prompt/model/seed。

Stage 5:角色工作流

目标:

角色档案驱动的标准角色流和专业角色流。

任务:

S5-1 quick_profile_service
S5-2 character_flow 标准模式节点生成
S5-3 professional 八阶段节点模板
S5-4 workflow_history 采纳图写入
S5-5 回溯 / 另开方案
S5-6 review_flow 轻量稳定性检查

验收:

- 快速人设问卷可生成 profile。
- 角色流节点可显示和推进。
- 已选择图有特殊状态。

Stage 6:素材区

目标:

素材分类、上传、识别、确认入库。

任务:

S6-1 seed material_categories
S6-2 material list/detail
S6-3 upload material
S6-4 recognition mock / VLM adapter
S6-5 confirm material
S6-6 custom accessory categories

验收:

- 上传素材后进入 pending_confirm。
- 用户确认后进入指定分类。
- 卡片可查看素材 prompt。

Stage 7:角色衣橱与扩展

目标:

实现 wardrobe 和 private_companion 每日穿搭联动。

任务:

S7-1 wardrobe_items
S7-2 从素材库加入衣橱
S7-3 wardrobe match
S7-4 daily-outfit integration endpoint
S7-5 fallback random prompt
S7-6 integration logs

验收:

- 外部插件请求命中衣橱。
- 未命中时走随机提示词。
- 日志区能查看联动事件。

Stage 8:高级配置与 API Discovery

目标:

完成模型配置、能力探测、RenderPlan 校验、Review 策略。

任务:

S8-1 config_service
S8-2 secret_service
S8-3 models/providers
S8-4 api-discovery/probe-provider safe 模式
S8-5 backend_capability_profiles
S8-6 validate-render-plan
S8-7 review/policies

验收:

- safe 探测不产生费用。
- unknown 不等同于 false。
- Secret 不回显。

5. 交给 Codex 的标准任务模板

当前任务编号:Sx-y

任务目标:
<一句话描述>

必须阅读:
- imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md 第 X 章
- imagestudio_api_contract_v3_ui_adjusted.md 第 X 章

允许修改文件:
- path/to/file1.py
- path/to/file2.py

禁止修改文件:
- config.yaml
- unrelated modules
- frontend/*  (如果是纯后端任务)

接口契约:
<复制相关 API 请求/响应>

实现要求:
1. 使用统一响应格式。
2. 写接口必须记录 audit_logs。
3. 不得明文处理 Secret。
4. 不得启动独立端口。
5. 重复请求必须考虑幂等。

验收方式:
- pytest xxx
- 手动调用 endpoint xxx
- 检查数据库记录 xxx

完成后输出:
1. 修改了哪些文件。
2. 实现了哪些接口。
3. 如何测试。
4. 是否涉及数据库迁移。
5. 已知限制。

6. 代码审查清单

每个 PR 必查:

[ ] 是否单独起了新端口?
[ ] 是否绕过 AstrBot register_web_api?
[ ] 是否有真实 API Key / Token 泄露?
[ ] 是否有绝对磁盘路径进入数据库?
[ ] 是否有写接口未鉴权?
[ ] 是否有写接口未写 audit_logs?
[ ] 是否有删除操作绕过二阶段删除?
[ ] 是否有图片文件无 media_files 记录?
[ ] 是否有生成图片无 generation_images 记录?
[ ] 是否有任务无 generation_tasks 记录?
[ ] 是否破坏通用响应格式?
[ ] 是否新增 API 但没更新 API 契约?
[ ] 是否让 unknown capability 等同 false?
[ ] 是否让重复点击创建重复任务?

7. Hermes 审查提示词

请作为需求审查代理,检查本次实现是否符合 ImageStudio v3 UI 调整版开发文档。

重点检查:
1. UI 需求是否都有后端事实表支撑。
2. Profile / Workflow / Node / Image Card 是否闭环。
3. 素材区上传识别确认是否闭环。
4. 是否违反“不单独起端口”定案。
5. 是否遗漏角色衣橱或 private_companion 联动。
6. 是否存在 Secret / 权限 / 审计风险。
7. 是否有未更新 API 契约的接口变化。

请输出:
- 通过项
- 风险项
- 必须修复项
- 可延后项

8. Codex 首轮推荐任务顺序

1. S0-1 建立目录结构
2. S1-1 character_profiles
3. S1-2 profile_workflows + workflow_nodes
4. S1-3 generation_images
5. S2-1 ui/bootstrap
6. S2-2 dashboard/summary
7. S3-1 Plugin Page UI
8. S3-2 Standalone Web UI 挂载
9. S4-1 Single Image mock flow
10. S4-2 图片卡片 selected 状态

做到第 10 步,插件已经具备 UI 原型闭环。


9. 严格禁止项

禁止实现时另起端口。
禁止把 Standalone Web UI 做成外部独立服务。
禁止把 Plugin Page UI 和 Standalone Web UI 做成两套业务后端。
禁止让 UI 直接读写本地文件。
禁止在前端保存 API Key。
禁止跳过任务表直接调用模型。
禁止图片生成成功但不写 generation_images。
禁止素材上传后直接入库而不确认。
禁止删除真实文件前不写 delete_pending。
禁止 Codex 自行扩大任务范围。

10. 最小可运行验收

P0 最小验收命令或步骤:

1. 启动 AstrBot。
2. 安装插件。
3. 打开插件详情页 ImageStudio Plugin Page。
4. 能看到仪表盘。
5. 点击“打开完整工作台”。
6. 浏览器打开 /web 页面。
7. 新建角色档案。
8. 创建单图流工作流。
9. 创建一个节点。
10. mock 生成一张图片卡片。
11. 查看图片详情 prompt/model。
12. 选择该图片,卡片边框状态变化。
13. 查看 audit_logs 有对应记录。

完成以上步骤后,再进入真实模型调用和高级能力。