chorus/docs

chorus 文档中心

chorus 是从 cmhub 抽出、用 Go 重写的独立生图生文服务：用户提交提示词（可带原图）得到新图或文本，运营在管理端配置上游模型并查看生成记录。开发过程遵循 DevHarness——Gitea 工单管理任务、Wiki 管理长期文档、Git 记录代码变更、人由人确认与验收。

当前处于 MVP-0：跑通全流程的最小闭环。目标不是把功能做全，而是先让一条数据从提交走到结果全程可运行、可验证。

第一次阅读

建议按以下顺序，用 10～20 分钟建立整体认识：

1. 项目档案：项目目标、技术栈、环境、命令和目录边界。
2. 产品需求总览：MVP 分期、已锁定决策、验收口径。
3. 架构与代码地图：两条执行路径、从哪个文件开始读。
4. 业务规则与术语：Provider、路由池、生成状态机和不能破坏的规则。
5. 本地开发与验证：怎样跑起来、怎样确认真的跑通了。
6. 常见修改指南：简单修改的步骤和停止条件。
7. 故障排查：出错时按什么顺序查。
8. 开发工作流：完整建单、实施、验收和归档流程。

五分钟开始

在仓库根目录执行：

git status --short --branch
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v

预期结果：

• 工作区没有不属于当前任务的修改；
• 输出“DevHarness 检查通过”；
• 所有测试通过。

MVP-0 的实现工单落地后，再加上：

go build ./...
go vet ./...
go test ./...
go run ./portal

预期：编译通过、测试通过、服务监听 :8080 且日志显示 worker 已启动。完整的“走通一次生成”步骤见本地开发与验证。

如果失败，先看故障排查，不要直接重置工作区或覆盖本地文档。

简单修改从哪里开始

想做什么	先读哪里	主要验证
改用户端页面文案	Common-Changes、portal/web/templates/	浏览器最小界面检查
改角色规则默认模板	Business-Rules、prompt_templates 表	一次真实生成，核对 rendered_prompt
加一个上游 Provider	Common-Changes	连通性测试或一次真实生成
看懂一次生成为什么失败	Troubleshooting	generations.attempts 与 error_message
改文档	对应 Wiki 页面、Common-Changes	Wiki 同步检查
查看或更新产品需求	Product-Requirements-Overview	状态、链接和事实来源核对
增加 Harness 检查	dev_scripts/harness.py	成功与失败用例都要有

选路与 retryable 判定、熔断、SSRF、密钥加解密、数据库迁移、队列租约、权限、点数写入、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。

事实来源

信息	事实来源
任务状态、讨论、阻塞、验收过程	Gitea 工单
长期产品需求的统一导航和状态	Product-Requirements-Overview
架构、业务规则、开发规范、操作手册、交付文档、任务归档	Gitea Wiki
数据库表结构（跨交付单元的共享契约）	migrations/ 中的 SQL
源码和与特定代码版本强绑定的文档	Git 仓库
已确认的界面与交互	prototypes/<工单号>/<版本>/index.html
核心长期文档的离线浏览副本	Git 仓库中的 docs/ Wiki 镜像

当前例外：chorus 的线上 Wiki 尚未初始化，docs/ 是初始人工版本。完成新项目文档初始化后转为只读镜像，之后长期文档必须先改 Wiki、读取确认，再导出镜像。

项目入口

• Gitea 工单
• 产品需求总览
• 代码仓库
• 新项目文档初始化
• 交付文档指南
• 任务归档模板

同步原则

修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像

• 核心页面与本地路径通过 wiki-docs.json 显式映射；普通同步不处理任务归档。
• 镜像头记录来源页面、Wiki revision 和同步时间；带 generated: true 的文件不得手工编辑。
• 已映射镜像存在未提交修改时同步必须停止。
• 页面删除、重命名和映射变更必须人工确认。
• 凭据、个人数据和生产数据不得进入 Wiki、镜像、原型或工单。