# chorus 文档中心

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

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

## 第一次阅读

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

1. [项目档案](00-project-profile.md)：项目目标、技术栈、环境、命令和目录边界。
2. [产品需求总览](09-product-requirements-overview.md)：MVP 分期、已锁定决策、验收口径。
3. [架构与代码地图](02-architecture-and-code-map.md)：两条执行路径、从哪个文件开始读。
4. [业务规则与术语](03-business-rules-and-glossary.md)：Provider、路由池、生成状态机和不能破坏的规则。
5. [本地开发与验证](04-local-development-and-verification.md)：怎样跑起来、怎样确认真的跑通了。
6. [常见修改指南](05-common-changes.md)：简单修改的步骤和停止条件。
7. [故障排查](06-troubleshooting.md)：出错时按什么顺序查。
8. [开发工作流](01-workflow.md)：完整建单、实施、验收和归档流程。

## 五分钟开始

在仓库根目录执行：

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

预期结果：

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

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

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

预期：编译通过、测试通过、服务监听 `:8080` 且日志显示 worker 已启动。完整的“走通一次生成”步骤见[本地开发与验证](04-local-development-and-verification.md)。

如果失败，先看[故障排查](06-troubleshooting.md)，不要直接重置工作区或覆盖本地文档。

## 简单修改从哪里开始

| 想做什么 | 先读哪里 | 主要验证 |
|---|---|---|
| 改用户端页面文案 | 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/` 是初始人工版本。完成[新项目文档初始化](07-new-project-documentation-setup.md)后转为只读镜像，之后长期文档必须先改 Wiki、读取确认，再导出镜像。

## 项目入口

- [Gitea 工单](https://git.ilapage.cn/OPC/chorus/issues)
- [产品需求总览](09-product-requirements-overview.md)
- [代码仓库](https://git.ilapage.cn/OPC/chorus)
- [新项目文档初始化](07-new-project-documentation-setup.md)
- [交付文档指南](delivery/README.md)
- [任务归档模板](templates/task-archive.md)

## 同步原则

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

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