ilaandClaude Opus 5
3895c873ec
- 从 dev_harness (3696663) 复制流程骨架：AGENTS/CLAUDE、工单模板、harness 工具与测试、通用流程文档 - 按需求方案改写为 chorus：项目档案、架构与代码地图、业务规则、本地验证、常见修改、故障排查、产品需求总览 - 需求分期为 MVP-0（跑通全流程最小闭环）/ MVP-1 / MVP-2 - AGENTS.md 增加 12 条 chorus 专用红线 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
97 lines
4.8 KiB
Markdown
97 lines
4.8 KiB
Markdown
# 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、镜像、原型或工单。
|