# 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 有对应记录。 ``` 完成以上步骤后,再进入真实模型调用和高级能力。