# chorus

chorus 是把 cmhub（Django）中的「提示词 + 原图 → 新图」和「提示词 → 文本」能力抽出来重写的**独立 Go 服务**，包含一个面向终端用户的 Web 端和一个运营管理端。

- 不改动 cmhub，也不依赖 cmhub 运行；核心逻辑是**重写移植**而非代码复用。
- 技术栈：Go + Gin + GORM + go-admin（管理端）+ html/template + HTMX + Alpine（用户端），MySQL 8.0，单库。
- 开发过程遵循 DevHarness：Gitea 工单是单次任务唯一事实来源，Gitea Wiki 管理长期文档，Git 记录代码变更，由人工确认方案与验收。

## 当前阶段

项目处于 **MVP-0（跑通全流程的最小闭环）**。目标不是把方案里的功能一次做全，而是先让一条数据从「用户提交提示词」走到「页面看到结果」全程可运行、可验证，再逐步补齐多 Provider 路由、熔断、管理端定制页等能力。

MVP-0 的范围、非目标和验收口径见 [产品需求总览](docs/09-product-requirements-overview.md)。

## 快速开始（Wiki 初始化门禁）

线上 Gitea Wiki 已于 2026-08-20 初始化完成，当前 16 个映射页面均已创建并回读确认，`docs/` 已转为只读镜像。以下是该门禁的完整顺序，供后续项目复用与核对：

1. 创建 Gitea 远端仓库并推送当前引导提交，启用工单和 Wiki。
2. 配置 `wiki-docs.json` 和安全访问方式；优先使用已配置的 Gitea MCP，MCP 不可用时才使用 Gitea API 并记录原因。令牌只通过环境变量或 MCP 安全配置提供。
3. 按 [新项目文档初始化](docs/07-new-project-documentation-setup.md) 查询线上 Wiki；`Home` 不存在时先创建并回读 `Home`，取得 revision 后再创建其他核心页面。
4. 逐页把 `docs/` 中的初始内容写入 Wiki 并回读确认；本地 `docs/` 的存在不能证明线上 Wiki 已初始化。
5. 把项目不可违反的安全规则写入根目录或子目录的 `AGENTS.md`。
6. 使用 `.gitea/issue_template/` 中的模板创建第一个 Epic、MVP 和单元任务。
7. 运行：

   ```powershell
   python dev_scripts/harness.py sync --verify
   ```

新仓库在 Gitea 尚未建立前允许一次不关联工单的引导提交。远端和工单系统配置完成后，新功能、接口/配置契约、数据库、高风险、跨模块和重大 UI 工作必须先有单元任务工单；明确的低风险修改边界见开发工作流。

默认不创建任务归档。任务专项快照和原型 HTML 只在用户明确要求或项目专用规则要求时创建；已有快照继续作为历史证据保留。

## 文档入口

| 想知道什么 | 读哪里 |
|---|---|
| 项目目标、环境、命令、目录边界 | [docs/00-project-profile.md](docs/00-project-profile.md) |
| 长期需求、MVP 分期、状态 | [docs/09-product-requirements-overview.md](docs/09-product-requirements-overview.md) |
| 代码从哪里开始读、两条主要执行路径 | [docs/02-architecture-and-code-map.md](docs/02-architecture-and-code-map.md) |
| 术语、状态机、不能破坏的规则 | [docs/03-business-rules-and-glossary.md](docs/03-business-rules-and-glossary.md) |
| 怎样跑起来、怎样验证 | [docs/04-local-development-and-verification.md](docs/04-local-development-and-verification.md) |
| 简单修改怎么做、什么时候必须停 | [docs/05-common-changes.md](docs/05-common-changes.md) |
| 报错了先查什么 | [docs/06-troubleshooting.md](docs/06-troubleshooting.md) |
| 怎样部署、检查、备份和回退 | [docs/10-deployment-and-operations.md](docs/10-deployment-and-operations.md) |
| 建单、实施、验收、关闭流程 | [docs/01-workflow.md](docs/01-workflow.md) |

`docs/` 是 Wiki 的只读镜像，不是编辑入口。修改长期文档的顺序见 [项目档案](docs/00-project-profile.md) 的“文档状态”。

## 目录

```text
AGENTS.md                         Agent 的通用工作规则
CLAUDE.md                         Claude Code 的规则入口
.gitea/issue_template/            Epic、MVP、单元任务工单模板
docs/                             核心长期文档（Wiki 初始化后转为只读镜像）
docs/task/                        人工明确要求的专项或历史兼容 Wiki 快照
prototypes/                       按需导出的本地 HTML 原型快照
wiki-docs.json                    核心 Wiki 页面到本地镜像的显式映射
dev_scripts/harness.py            check / sync 入口，兼容 archive / export
tests/                            Harness 工具自动化测试
```

Go 代码目录（`internal/core`、`portal/`、`admin/`、`migrations/`）在 MVP-0 首个实现工单落地，规划见架构与代码地图。