9.8 KiB
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
规则:
- 一个任务一个分支。
- 一个代理一次只处理一个任务。
- 合并前必须人工看 diff。
- 合并前必须运行测试。
- 数据库迁移必须单独审查。
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 有对应记录。
完成以上步骤后,再进入真实模型调用和高级能力。