OPC/chorus
2
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

同步 chorus Wiki 镜像

Browse Source 
线上 Wiki 15 个核心页面已创建并回读确认，导出为 docs/ 只读镜像。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
ila
2026-08-20 11:30:58 +08:00
co-authored by Claude Opus 5
parent 3895c873ec
commit 69229a2bfd
15 changed files with 153 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/00-project-profile.md
+17 -9
View File
@@ -1,10 +1,18 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Project-Profile
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Project-Profile.-
wiki_revision: 6d404e71cece661087a73b6032fad23815bc7c6f
synchronized_at: 2026-08-20T03:29:20Z
<!-- gitea-wiki-mirror:end -->
# 项目档案
本页记录不经常变化、所有维护者都需要知道的信息。Wiki 初始化完成后，Wiki 的 `Project-Profile` 是事实来源，本文件是只读镜像。
## 文档状态
当前 chorus 的线上 Gitea Wiki **尚未初始化**，`docs/` 是初始人工版本。按 [新项目文档初始化](07-new-project-documentation-setup.md) 完成线上创建与回读后，本目录转为镜像，之后只改 Wiki。在此之前不要用本地文件的存在证明 Wiki 已就绪。
当前 chorus 的线上 Gitea Wiki **尚未初始化**，`docs/` 是初始人工版本。按 [新项目文档初始化](New-Project-Documentation-Setup.-) 完成线上创建与回读后，本目录转为镜像，之后只改 Wiki。在此之前不要用本地文件的存在证明 Wiki 已就绪。
## 基本信息
@@ -38,7 +46,7 @@
| `admin` 管理端二进制 | Provider/Model/路由池/记录/用户与点数管理 | Go + go-admin（Gin + GORM + Casbin + JWT）+ go-admin-ui（Vue 2） | `go build ./admin/...` | 跟随 `main` 分支构建 | 根 `AGENTS.md` | 依赖 `internal/core`；不得绕过核心域直接实现生成逻辑 |
| `migrations` 数据库迁移 | 业务表结构演进 | golang-migrate（SQL 文件） | `migrate up` / `migrate down` | 随代码提交，按序号前进 | 根 `AGENTS.md` | 表结构是三个交付单元的唯一共享契约 |
共享契约的唯一事实来源是 `migrations/` 中的 SQL 与 [业务规则与术语](03-business-rules-and-glossary.md)；不得在多处维护互不确认的表结构描述。MVP-0 只要求 `internal/core` 与 `portal` 可运行，`admin` 与 `migrations` 的完整形态在后续阶段补齐。
共享契约的唯一事实来源是 `migrations/` 中的 SQL 与 [业务规则与术语](Business-Rules-and-Glossary.-)；不得在多处维护互不确认的表结构描述。MVP-0 只要求 `internal/core` 与 `portal` 可运行，`admin` 与 `migrations` 的完整形态在后续阶段补齐。
## 技术栈与运行环境
@@ -65,13 +73,13 @@
## 阅读入口
- 新人入口：[Home](README.md)。
- 产品需求与 MVP 分期：[产品需求总览](09-product-requirements-overview.md)。
- 代码入口：[架构与代码地图](02-architecture-and-code-map.md)。
- 业务边界：[业务规则与术语](03-business-rules-and-glossary.md)。
- 运行验证：[本地开发与验证](04-local-development-and-verification.md)。
- 简单维护：[常见修改指南](05-common-changes.md)。
- 错误定位：[故障排查](06-troubleshooting.md)。
- 新人入口：[Home](Home)。
- 产品需求与 MVP 分期：[产品需求总览](Product-Requirements-Overview.-)。
- 代码入口：[架构与代码地图](Architecture-and-Code-Map.-)。
- 业务边界：[业务规则与术语](Business-Rules-and-Glossary.-)。
- 运行验证：[本地开发与验证](Local-Development-and-Verification.-)。
- 简单维护：[常见修改指南](Common-Changes.-)。
- 错误定位：[故障排查](Troubleshooting)。
## 常用命令
docs/01-workflow.md
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Development-Workflow
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Development-Workflow.-
wiki_revision: e65f6f00510ab961909d638f7271a2de64f8bf38
synchronized_at: 2026-08-20T03:29:22Z
<!-- gitea-wiki-mirror:end -->
# 开发工作流
## 事实来源边界
docs/02-architecture-and-code-map.md
+9 -1
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Architecture-and-Code-Map.-
wiki_revision: e2a808803b76303549ea374700d971dfa20f2fdd
synchronized_at: 2026-08-20T03:29:24Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
## 项目定位
@@ -46,7 +54,7 @@ MVP-0 的唯一目标是**让全流程跑通**，因此只实现上面结构的
| `portal` | 登录、双栏首页、提交生成、HTMX 轮询卡片、结果展示 | API Key 端点、限流、无限滚动分页 |
| `admin` | 暂不接入，provider 配置用迁移或一次性命令写入 | 全部管理端页面 |
暂缓项都在 [产品需求总览](09-product-requirements-overview.md) 中登记为后续阶段，不是被取消的需求。
暂缓项都在 [产品需求总览](Product-Requirements-Overview.-) 中登记为后续阶段，不是被取消的需求。
## 代码地图
docs/03-business-rules-and-glossary.md
+9 -1
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Business-Rules-and-Glossary
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Business-Rules-and-Glossary.-
wiki_revision: 311d04cdb64461caa1d40a2e9943a58811d947bf
synchronized_at: 2026-08-20T03:29:26Z
<!-- gitea-wiki-mirror:end -->
# 业务规则与术语
## 核心术语
@@ -19,7 +27,7 @@
## 工单状态
沿用 DevHarness：待确认、已确认、开发中、待验收、已交付、已停止。状态含义与流转规则见 [开发工作流](01-workflow.md) 和 [产品需求总览](09-product-requirements-overview.md)。
沿用 DevHarness：待确认、已确认、开发中、待验收、已交付、已停止。状态含义与流转规则见 [开发工作流](Development-Workflow.-) 和 [产品需求总览](Product-Requirements-Overview.-)。
## 稳定业务规则
docs/04-local-development-and-verification.md
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Local-Development-and-Verification
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.-
wiki_revision: 47b4993d26695f8513c4b3212781b6c6f4c6540c
synchronized_at: 2026-08-20T03:29:28Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
本页覆盖两类工作：**文档与流程**（现在就能跑）和 **Go 服务**（MVP-0 实现工单落地后可跑）。标注“MVP-0 落地后”的步骤在代码存在前会失败，这是预期的。
docs/05-common-changes.md
+9 -1
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Common-Changes
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Common-Changes.-
wiki_revision: becf3fdead14674cb74a7a48c4792c06eb9d454b
synchronized_at: 2026-08-20T03:29:30Z
<!-- gitea-wiki-mirror:end -->
# 常见修改指南
本页面向接手简单维护的初级程序员。每一类修改都给出改哪里、验证什么、什么时候必须停下来。
@@ -29,7 +37,7 @@
## 增加或调整一个上游 Provider
1. 优先通过管理端页面配置（管理端接入前用种子命令，见 [本地开发与验证](04-local-development-and-verification.md)）。
1. 优先通过管理端页面配置（管理端接入前用种子命令，见 [本地开发与验证](Local-Development-and-Verification.-)）。
2. 确认 `api_type` 选对：文生文用 `chat`，图生图用 `images_edits`。
3. 保存后用「连通性测试」打一次真实请求验证；没有该按钮时手工提交一次生成。
4. `api_key` 只填进配置，不要出现在工单、截图或日志里。
docs/06-troubleshooting.md
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Troubleshooting
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Troubleshooting
wiki_revision: 9400aa641e95bccd3903efb6dd935c06a59048e8
synchronized_at: 2026-08-20T03:29:32Z
<!-- gitea-wiki-mirror:end -->
# 故障排查
## 排查顺序
docs/07-new-project-documentation-setup.md
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: New-Project-Documentation-Setup
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/New-Project-Documentation-Setup.-
wiki_revision: 14eca6fde6902c48941550c49a570a5cb7e157b5
synchronized_at: 2026-08-20T03:29:35Z
<!-- gitea-wiki-mirror:end -->
# 新项目文档初始化
## 本页用途
docs/08-existing-project-adoption.md
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Existing-Project-Adoption-Guide
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Existing-Project-Adoption-Guide.-
wiki_revision: 2b20998dd7751c6fe3edfc26922722e44bf8496b
synchronized_at: 2026-08-20T03:29:39Z
<!-- gitea-wiki-mirror:end -->
# 已有项目接入 DevHarness 指南
## 本页用途
docs/09-product-requirements-overview.md
+14 -6
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Product-Requirements-Overview
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Product-Requirements-Overview.-
wiki_revision: 33319b0f3d34796ade13e4146f28cc5e5eb6d1d1
synchronized_at: 2026-08-20T03:29:42Z
<!-- gitea-wiki-mirror:end -->
# 产品需求总览
## 本页用途
@@ -25,14 +33,14 @@ chorus 尚未建立 Gitea 工单，下表的“实施工单”列在建单后填
| 需求领域 | 用户与场景 | 状态 | 版本 / MVP | 详细说明 | 实施工单 | 原型 | 验收入口 |
|---|---|---|---|---|---|---|---|
| 核心生成域与单上游打通 | 用户提交提示词（+原图）得到结果；先跑通再谈可用性 | 已确认，未开工 | MVP-0 | [架构与代码地图](02-architecture-and-code-map.md)、[业务规则](03-business-rules-and-glossary.md) | 待建单 | 无（非 UI 需求，用架构与数据设计代替） | 待建单 |
| 用户端生成页（双栏 + 异步卡片） | 终端用户在浏览器完成一次生成并看到结果 | 已确认，未开工 | MVP-0 | 本页“用户端布局”一节、[架构与代码地图](02-architecture-and-code-map.md) | 待建单 | **待制作**：新页面，需 HTML 审核快照并经确认 | 待建单 |
| 多 Provider 路由池与故障转移 | 单一上游失效时服务仍可用 | 已确认，未开工 | MVP-1 | [业务规则](03-business-rules-and-glossary.md) 选路与失败处理 | 待建单 | 无（非 UI 需求） | 待建单 |
| 核心生成域与单上游打通 | 用户提交提示词（+原图）得到结果；先跑通再谈可用性 | 已确认，未开工 | MVP-0 | [架构与代码地图](Architecture-and-Code-Map.-)、[业务规则](Business-Rules-and-Glossary.-) | 待建单 | 无（非 UI 需求，用架构与数据设计代替） | 待建单 |
| 用户端生成页（双栏 + 异步卡片） | 终端用户在浏览器完成一次生成并看到结果 | 已确认，未开工 | MVP-0 | 本页“用户端布局”一节、[架构与代码地图](Architecture-and-Code-Map.-) | 待建单 | **待制作**：新页面，需 HTML 审核快照并经确认 | 待建单 |
| 多 Provider 路由池与故障转移 | 单一上游失效时服务仍可用 | 已确认，未开工 | MVP-1 | [业务规则](Business-Rules-and-Glossary.-) 选路与失败处理 | 待建单 | 无（非 UI 需求） | 待建单 |
| 管理端配置与记录查看 | 运营配置 Provider/Model、勾选组池、查看生成记录 | 已确认，未开工 | MVP-1 | 本页“管理端页面”一节 | 待建单 | 代码生成器页面无需原型；三个定制页需低保真图 | 待建单 |
| 图片角色规则可编辑 | 用户按自己的场景描述“第几张图是什么” | 已确认，未开工 | MVP-1 | [业务规则](03-business-rules-and-glossary.md) 提示词与图片角色 | 待建单 | 属现有页面新增组件，需组件状态说明 | 待建单 |
| 点数只读展示与管理端发放 | 用户看到余额；管理员发放并留痕 | 已确认，未开工 | MVP-2 | [业务规则](03-business-rules-and-glossary.md) 点数与限流 | 待建单 | 沿用现有设计体系 | 待建单 |
| 图片角色规则可编辑 | 用户按自己的场景描述“第几张图是什么” | 已确认，未开工 | MVP-1 | [业务规则](Business-Rules-and-Glossary.-) 提示词与图片角色 | 待建单 | 属现有页面新增组件，需组件状态说明 | 待建单 |
| 点数只读展示与管理端发放 | 用户看到余额；管理员发放并留痕 | 已确认，未开工 | MVP-2 | [业务规则](Business-Rules-and-Glossary.-) 点数与限流 | 待建单 | 沿用现有设计体系 | 待建单 |
| API Key 与程序化调用 | 外部程序按 API Key 调用生成 | 已确认，未开工 | MVP-2 | 本页“程序化调用”一节 | 待建单 | 无（接口需求，用 API 设计代替） | 待建单 |
| 限流与生成物保留期 | 防止单人打满上游配额；控制磁盘增长 | 待确认（阈值与保留期未定） | MVP-2 | [业务规则](03-business-rules-and-glossary.md)“新项目需要补充什么” | 待建单 | 无 | 待建单 |
| 限流与生成物保留期 | 防止单人打满上游配额；控制磁盘增长 | 待确认（阈值与保留期未定） | MVP-2 | [业务规则](Business-Rules-and-Glossary.-)“新项目需要补充什么” | 待建单 | 无 | 待建单 |
### MVP 分期
docs/README.md
+23 -15
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Home
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Home
wiki_revision: cbfa12fdc6db48108ba816efae1df9a4dbaa1b69
synchronized_at: 2026-08-20T03:29:18Z
<!-- gitea-wiki-mirror:end -->
# chorus 文档中心
chorus 是从 cmhub 抽出、用 Go 重写的独立生图生文服务：用户提交提示词（可带原图）得到新图或文本，运营在管理端配置上游模型并查看生成记录。开发过程遵循 DevHarness——Gitea 工单管理任务、Wiki 管理长期文档、Git 记录代码变更、人由人确认与验收。
@@ -8,14 +16,14 @@ chorus 是从 cmhub 抽出、用 Go 重写的独立生图生文服务：用户
建议按以下顺序，用 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)：完整建单、实施、验收和归档流程。
1. [项目档案](Project-Profile.-)：项目目标、技术栈、环境、命令和目录边界。
2. [产品需求总览](Product-Requirements-Overview.-)：MVP 分期、已锁定决策、验收口径。
3. [架构与代码地图](Architecture-and-Code-Map.-)：两条执行路径、从哪个文件开始读。
4. [业务规则与术语](Business-Rules-and-Glossary.-)：Provider、路由池、生成状态机和不能破坏的规则。
5. [本地开发与验证](Local-Development-and-Verification.-)：怎样跑起来、怎样确认真的跑通了。
6. [常见修改指南](Common-Changes.-)：简单修改的步骤和停止条件。
7. [故障排查](Troubleshooting)：出错时按什么顺序查。
8. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和归档流程。
## 五分钟开始
@@ -42,9 +50,9 @@ go test ./...
go run ./portal
```
预期：编译通过、测试通过、服务监听 `:8080` 且日志显示 worker 已启动。完整的“走通一次生成”步骤见[本地开发与验证](04-local-development-and-verification.md)。
预期：编译通过、测试通过、服务监听 `:8080` 且日志显示 worker 已启动。完整的“走通一次生成”步骤见[本地开发与验证](Local-Development-and-Verification.-)。
如果失败，先看[故障排查](06-troubleshooting.md)，不要直接重置工作区或覆盖本地文档。
如果失败，先看[故障排查](Troubleshooting)，不要直接重置工作区或覆盖本地文档。
## 简单修改从哪里开始
@@ -72,16 +80,16 @@ go run ./portal
| 已确认的界面与交互 | `prototypes/<工单号>/<版本>/index.html` |
| 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 |
> **当前例外**：chorus 的线上 Wiki 尚未初始化，`docs/` 是初始人工版本。完成[新项目文档初始化](07-new-project-documentation-setup.md)后转为只读镜像，之后长期文档必须先改 Wiki、读取确认，再导出镜像。
> **当前例外**：chorus 的线上 Wiki 尚未初始化，`docs/` 是初始人工版本。完成[新项目文档初始化](New-Project-Documentation-Setup.-)后转为只读镜像，之后长期文档必须先改 Wiki、读取确认，再导出镜像。
## 项目入口
- [Gitea 工单](https://git.ilapage.cn/OPC/chorus/issues)
- [产品需求总览](09-product-requirements-overview.md)
- [产品需求总览](Product-Requirements-Overview.-)
- [代码仓库](https://git.ilapage.cn/OPC/chorus)
- [新项目文档初始化](07-new-project-documentation-setup.md)
- [交付文档指南](delivery/README.md)
- [任务归档模板](templates/task-archive.md)
- [新项目文档初始化](New-Project-Documentation-Setup.-)
- [交付文档指南](Delivery-Documentation-Guide.-)
- [任务归档模板](Task-Archive-Template.-)
## 同步原则
docs/delivery/README.md
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Delivery-Documentation-Guide
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Delivery-Documentation-Guide.-
wiki_revision: 5cd1d448d90af3672722596ad3647d327e05ce8a
synchronized_at: 2026-08-20T03:29:44Z
<!-- gitea-wiki-mirror:end -->
# 交付文档指南
## 本页用途
docs/delivery/audience-document-template.md
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Audience-Document-Template
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Audience-Document-Template.-
wiki_revision: b01add3e8f0a5e27a08101b8828ab0ef53161d2e
synchronized_at: 2026-08-20T03:29:47Z
<!-- gitea-wiki-mirror:end -->
# 岗位文档模板
> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。
docs/templates/deployment.md
Vendored
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Deployment-Template
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Deployment-Template.-
wiki_revision: 140d8bbf71ba8ec2ab5c9880241a824aae57a06a
synchronized_at: 2026-08-20T03:29:49Z
<!-- gitea-wiki-mirror:end -->
# 部署文档模板
> 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。
docs/templates/task-archive.md
Vendored
+8
View File
@@ -1,3 +1,11 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Task-Archive-Template
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Task-Archive-Template.-
wiki_revision: 41240e7746990f3132201ad27c8f8c3a59240189
synchronized_at: 2026-08-20T03:29:51Z
<!-- gitea-wiki-mirror:end -->
# <工单号> <标题>
- 类型：需求 / 缺陷 / 重构