<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Home
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Home
wiki_revision: 3d6efad79056ff85f7532e28a90c80f2c710c332
synchronized_at: 2026-08-20T07:00:57Z
<!-- gitea-wiki-mirror:end -->

# chorus 文档中心

chorus 是从 cmhub 设计中抽取并用 Go 重写的独立生图生文服务：用户提交提示词（可带原图）得到图片或文本，运营在管理端配置上游并查看生成记录。Gitea 工单记录任务过程，Wiki 是长期文档事实来源，Git 记录代码与镜像。

当前处于 **MVP-0：安全、可观测地跑通单上游闭环**。文档基线由工单 [#1](https://git.ilapage.cn/OPC/chorus/issues/1) 更新；这不表示产品功能已经开工。

## 第一次阅读

1. [项目档案](Project-Profile.-)：固定 go-admin 来源、工具链、目录和安全边界。
2. [产品需求总览](Product-Requirements-Overview.-)：MVP 分期、UI 状态和验收。
3. [架构与代码地图](Architecture-and-Code-Map.-)：同步/worker 路径、租约 CAS、代码生成边界。
4. [业务规则与术语](Business-Rules-and-Glossary.-)：数据、状态、SSRF、身份和排除范围。
5. [本地开发与验证](Local-Development-and-Verification.-)：目标环境、隔离库、测试策略。
6. [常见修改指南](Common-Changes.-)：修改步骤和停止条件。
7. [故障排查](Troubleshooting)：按证据定位环境、队列、上游和生成器问题。
8. [部署与运维](Deployment-and-Operations.-)：生产迁移、服务、健康、备份和回退。
9. [开发工作流](Development-Workflow.-)：建单、确认、实施、验收与归档。

## 五分钟开始

```powershell
git status --short --branch
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
$env:GITEA_URL = "https://git.ilapage.cn"
python dev_scripts/harness.py sync --check
```

MVP-0 产品代码落地且环境达到 Go 1.26.5/MySQL 8.0 后，再执行 `go build ./...`、`go vet ./...`、`go test ./...` 和 `go run ./portal`。当前本机版本差距见本地开发页，不能把无法执行的命令记为通过。

## 简单修改从哪里开始

| 想做什么 | 先读 | 主要验证 |
|---|---|---|
| 改纯显示文案 | Common-Changes、模板 | 375/768/1024 最小界面检查 |
| 改默认 prompt template | Business-Rules | mock 生成并核对 rendered_prompt |
| 加 ProviderModel | Common-Changes | mock 协议 + SSRF；真实测试仅单次人工触发 |
| 排查生成失败 | Troubleshooting | attempts/error/lease 时间线 |
| 使用 go-admin 生成 CRUD | Architecture、Local-Development | migration → 隔离库 → 导表 → 生成差异审查 |
| 改长期文档 | 对应 Wiki、Common-Changes | 回读 revision + sync --check |
| 部署或回退 | Deployment-and-Operations | 迁移、健康、dev-tools、备份证据 |
| 更新需求 | Product-Requirements | 状态、工单、原型和验收入口 |

retryable、SSRF、密钥、迁移、租约/CAS、身份权限、点数写入、AutoMigrate、代码生成副作用、删除/清理和不可逆操作都不是简单修改。

## 事实来源

| 信息 | 事实来源 |
|---|---|
| 单元任务状态、讨论、阻塞和验收 | Gitea 工单 |
| 长期需求导航 | Product-Requirements-Overview |
| 架构、规则、开发、排错、部署、归档 | Gitea Wiki |
| 生产数据库结构和配置种子 | `migrations/` 可逆 SQL |
| 源码和固定版本资料 | chorus Git；外部来源提交记录在 Project-Profile |
| 已确认界面与交互 | `prototypes/<工单号>/<版本>/index.html` |
| 离线核心文档 | Git 中的 `docs/` Wiki 只读镜像 |

`D:\github\goadmin` 是已审查来源，不是运行时事实来源。线上 Wiki 已初始化；长期文档必须先改 Wiki、回读 revision，再同步镜像。

## 项目入口

- [Gitea 工单](https://git.ilapage.cn/OPC/chorus/issues)
- [产品需求总览](Product-Requirements-Overview.-)
- [部署与运维](Deployment-and-Operations.-)
- [代码仓库](https://git.ilapage.cn/OPC/chorus)
- [新项目文档初始化](New-Project-Documentation-Setup.-)
- [交付文档指南](Delivery-Documentation-Guide.-)
- [任务归档模板](Task-Archive-Template.-)

## 同步原则

```text
修改 Wiki → 在线回读 revision → 导出 docs → 校验差异 → 提交镜像
```

- `wiki-docs.json` 显式映射核心和项目专用页面，普通同步不处理任务归档。
- 带 `generated: true` 的文件不得手工编辑；有未提交镜像修改时同步停止。
- 页面删除、重命名和事实源变化必须先更新工单并确认。
- 凭据、个人数据、真实 prompt、生成文件和生产数据不得进入文档、工单或原型。