517 行
9.8 KiB
Markdown
517 行
9.8 KiB
Markdown
|
|
# AstrBot ImageStudio Codex / Hermes 开发流程指南 v3.0
|
|||
|
|
|
|||
|
|
> 生成日期:2026-07-04
|
|||
|
|
> 目标:让 Codex / Hermes 能按正确顺序读懂并实现插件,不跑偏、不乱改、不单独起端口。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 代理分工
|
|||
|
|
|
|||
|
|
### Codex
|
|||
|
|
|
|||
|
|
定位:主代码实现代理。
|
|||
|
|
|
|||
|
|
适合:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
数据库模型
|
|||
|
|
Repository / Service / Route
|
|||
|
|
接口实现
|
|||
|
|
队列逻辑
|
|||
|
|
单元测试
|
|||
|
|
前端组件实现
|
|||
|
|
Bug 修复
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Hermes
|
|||
|
|
|
|||
|
|
定位:需求整理和二次审查代理。
|
|||
|
|
|
|||
|
|
适合:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
需求归纳
|
|||
|
|
开发任务拆解
|
|||
|
|
文档维护
|
|||
|
|
UI 与后端契约检查
|
|||
|
|
验收清单
|
|||
|
|
代码审查提示
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 禁止
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
禁止 Codex 和 Hermes 同时修改同一分支。
|
|||
|
|
禁止一次性要求代理“实现整个插件”。
|
|||
|
|
禁止把真实 API Key / Cookie / Token 发给代理。
|
|||
|
|
禁止让代理擅自启动独立 Web 端口。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 推荐阅读顺序
|
|||
|
|
|
|||
|
|
交给 Codex 或 Hermes 前,按此顺序提供文档:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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. 分支策略
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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:仓库初始化
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
建立目录结构
|
|||
|
|
建立配置文件
|
|||
|
|
建立测试框架
|
|||
|
|
建立基础 DB helper
|
|||
|
|
建立通用响应格式
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
交给 Codex 的任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
任务 S0-1:创建项目目录结构和空模块。
|
|||
|
|
任务 S0-2:实现 common response DTO。
|
|||
|
|
任务 S0-3:实现 request_id / audit logger 基础工具。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Stage 1:数据库与 Repository
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
实现 UI 必需事实表。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
优先表:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
character_profiles
|
|||
|
|
profile_workflows
|
|||
|
|
workflow_nodes
|
|||
|
|
generation_images
|
|||
|
|
material_categories
|
|||
|
|
materials
|
|||
|
|
wardrobe_items
|
|||
|
|
workflow_sessions
|
|||
|
|
generation_tasks
|
|||
|
|
media_files
|
|||
|
|
audit_logs
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Codex 任务示例:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
任务 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 注册
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
所有 P0 API 可被 Plugin Page Bridge 和 Standalone Web 调用。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
验收:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
- 所有 API 返回统一 JSON。
|
|||
|
|
- 401/403/404/422/500 错误格式统一。
|
|||
|
|
- 写接口记录 audit_logs。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Stage 3:双 UI 挂载
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
Plugin Page UI 和 Standalone Web UI 都能打开。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Codex 任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
验收:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
- AstrBot 插件页内可打开轻量 UI。
|
|||
|
|
- 浏览器可直接打开 /web。
|
|||
|
|
- 两个 UI 调用同一个 dashboard/summary。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Stage 4:单图流闭环
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
用户可以从 Web UI 创建单图流、提交生成、查看图片卡片。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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 状态
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
验收:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
- 至少支持 mock backend。
|
|||
|
|
- 任务状态 CREATED -> QUEUED -> RUNNING -> SUCCEEDED。
|
|||
|
|
- 图片卡片展示 prompt/model/seed。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Stage 5:角色工作流
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
角色档案驱动的标准角色流和专业角色流。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
S5-1 quick_profile_service
|
|||
|
|
S5-2 character_flow 标准模式节点生成
|
|||
|
|
S5-3 professional 八阶段节点模板
|
|||
|
|
S5-4 workflow_history 采纳图写入
|
|||
|
|
S5-5 回溯 / 另开方案
|
|||
|
|
S5-6 review_flow 轻量稳定性检查
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
验收:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
- 快速人设问卷可生成 profile。
|
|||
|
|
- 角色流节点可显示和推进。
|
|||
|
|
- 已选择图有特殊状态。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Stage 6:素材区
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
素材分类、上传、识别、确认入库。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
验收:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
- 上传素材后进入 pending_confirm。
|
|||
|
|
- 用户确认后进入指定分类。
|
|||
|
|
- 卡片可查看素材 prompt。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Stage 7:角色衣橱与扩展
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
实现 wardrobe 和 private_companion 每日穿搭联动。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
验收:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
- 外部插件请求命中衣橱。
|
|||
|
|
- 未命中时走随机提示词。
|
|||
|
|
- 日志区能查看联动事件。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Stage 8:高级配置与 API Discovery
|
|||
|
|
|
|||
|
|
目标:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
完成模型配置、能力探测、RenderPlan 校验、Review 策略。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
任务:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
验收:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
- safe 探测不产生费用。
|
|||
|
|
- unknown 不等同于 false。
|
|||
|
|
- Secret 不回显。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 交给 Codex 的标准任务模板
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
当前任务编号: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 必查:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
[ ] 是否单独起了新端口?
|
|||
|
|
[ ] 是否绕过 AstrBot register_web_api?
|
|||
|
|
[ ] 是否有真实 API Key / Token 泄露?
|
|||
|
|
[ ] 是否有绝对磁盘路径进入数据库?
|
|||
|
|
[ ] 是否有写接口未鉴权?
|
|||
|
|
[ ] 是否有写接口未写 audit_logs?
|
|||
|
|
[ ] 是否有删除操作绕过二阶段删除?
|
|||
|
|
[ ] 是否有图片文件无 media_files 记录?
|
|||
|
|
[ ] 是否有生成图片无 generation_images 记录?
|
|||
|
|
[ ] 是否有任务无 generation_tasks 记录?
|
|||
|
|
[ ] 是否破坏通用响应格式?
|
|||
|
|
[ ] 是否新增 API 但没更新 API 契约?
|
|||
|
|
[ ] 是否让 unknown capability 等同 false?
|
|||
|
|
[ ] 是否让重复点击创建重复任务?
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Hermes 审查提示词
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
请作为需求审查代理,检查本次实现是否符合 ImageStudio v3 UI 调整版开发文档。
|
|||
|
|
|
|||
|
|
重点检查:
|
|||
|
|
1. UI 需求是否都有后端事实表支撑。
|
|||
|
|
2. Profile / Workflow / Node / Image Card 是否闭环。
|
|||
|
|
3. 素材区上传识别确认是否闭环。
|
|||
|
|
4. 是否违反“不单独起端口”定案。
|
|||
|
|
5. 是否遗漏角色衣橱或 private_companion 联动。
|
|||
|
|
6. 是否存在 Secret / 权限 / 审计风险。
|
|||
|
|
7. 是否有未更新 API 契约的接口变化。
|
|||
|
|
|
|||
|
|
请输出:
|
|||
|
|
- 通过项
|
|||
|
|
- 风险项
|
|||
|
|
- 必须修复项
|
|||
|
|
- 可延后项
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. Codex 首轮推荐任务顺序
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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. 严格禁止项
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
禁止实现时另起端口。
|
|||
|
|
禁止把 Standalone Web UI 做成外部独立服务。
|
|||
|
|
禁止把 Plugin Page UI 和 Standalone Web UI 做成两套业务后端。
|
|||
|
|
禁止让 UI 直接读写本地文件。
|
|||
|
|
禁止在前端保存 API Key。
|
|||
|
|
禁止跳过任务表直接调用模型。
|
|||
|
|
禁止图片生成成功但不写 generation_images。
|
|||
|
|
禁止素材上传后直接入库而不确认。
|
|||
|
|
禁止删除真实文件前不写 delete_pending。
|
|||
|
|
禁止 Codex 自行扩大任务范围。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. 最小可运行验收
|
|||
|
|
|
|||
|
|
P0 最小验收命令或步骤:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
1. 启动 AstrBot。
|
|||
|
|
2. 安装插件。
|
|||
|
|
3. 打开插件详情页 ImageStudio Plugin Page。
|
|||
|
|
4. 能看到仪表盘。
|
|||
|
|
5. 点击“打开完整工作台”。
|
|||
|
|
6. 浏览器打开 /web 页面。
|
|||
|
|
7. 新建角色档案。
|
|||
|
|
8. 创建单图流工作流。
|
|||
|
|
9. 创建一个节点。
|
|||
|
|
10. mock 生成一张图片卡片。
|
|||
|
|
11. 查看图片详情 prompt/model。
|
|||
|
|
12. 选择该图片,卡片边框状态变化。
|
|||
|
|
13. 查看 audit_logs 有对应记录。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
完成以上步骤后,再进入真实模型调用和高级能力。
|