diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index cb57a3e..b6fe0db 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -1,10 +1,18 @@ + +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 + + # 项目档案 本页记录不经常变化、所有维护者都需要知道的信息。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)。 ## 常用命令 diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 3a58958..fec28e7 100644 --- a/docs/01-workflow.md +++ b/docs/01-workflow.md @@ -1,3 +1,11 @@ + +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 + + # 开发工作流 ## 事实来源边界 diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index ebc59d1..e6c98ea 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -1,3 +1,11 @@ + +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 + + # 架构与代码地图 ## 项目定位 @@ -46,7 +54,7 @@ MVP-0 的唯一目标是**让全流程跑通**，因此只实现上面结构的 | `portal` | 登录、双栏首页、提交生成、HTMX 轮询卡片、结果展示 | API Key 端点、限流、无限滚动分页 | | `admin` | 暂不接入，provider 配置用迁移或一次性命令写入 | 全部管理端页面 | -暂缓项都在 [产品需求总览](09-product-requirements-overview.md) 中登记为后续阶段，不是被取消的需求。 +暂缓项都在 [产品需求总览](Product-Requirements-Overview.-) 中登记为后续阶段，不是被取消的需求。 ## 代码地图 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index c26a854..0f1c9db 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -1,3 +1,11 @@ + +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 + + # 业务规则与术语 ## 核心术语 @@ -19,7 +27,7 @@ ## 工单状态 -沿用 DevHarness：待确认、已确认、开发中、待验收、已交付、已停止。状态含义与流转规则见 [开发工作流](01-workflow.md) 和 [产品需求总览](09-product-requirements-overview.md)。 +沿用 DevHarness：待确认、已确认、开发中、待验收、已交付、已停止。状态含义与流转规则见 [开发工作流](Development-Workflow.-) 和 [产品需求总览](Product-Requirements-Overview.-)。 ## 稳定业务规则 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index f054208..50be2dd 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -1,3 +1,11 @@ + +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 + + # 本地开发与验证 本页覆盖两类工作：**文档与流程**（现在就能跑）和 **Go 服务**（MVP-0 实现工单落地后可跑）。标注“MVP-0 落地后”的步骤在代码存在前会失败，这是预期的。 diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md index f9769ad..93f6a14 100644 --- a/docs/05-common-changes.md +++ b/docs/05-common-changes.md @@ -1,3 +1,11 @@ + +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 + + # 常见修改指南 本页面向接手简单维护的初级程序员。每一类修改都给出改哪里、验证什么、什么时候必须停下来。 @@ -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` 只填进配置，不要出现在工单、截图或日志里。 diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md index 39c6007..b20a7eb 100644 --- a/docs/06-troubleshooting.md +++ b/docs/06-troubleshooting.md @@ -1,3 +1,11 @@ + +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 + + # 故障排查 ## 排查顺序 diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md index 45e07c0..94c7c89 100644 --- a/docs/07-new-project-documentation-setup.md +++ b/docs/07-new-project-documentation-setup.md @@ -1,3 +1,11 @@ + +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 + + # 新项目文档初始化 ## 本页用途 diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md index 93fffb9..fce61ba 100644 --- a/docs/08-existing-project-adoption.md +++ b/docs/08-existing-project-adoption.md @@ -1,3 +1,11 @@ + +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 + + # 已有项目接入 DevHarness 指南 ## 本页用途 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md index 4860df2..a1fee37 100644 --- a/docs/09-product-requirements-overview.md +++ b/docs/09-product-requirements-overview.md @@ -1,3 +1,11 @@ + +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 + + # 产品需求总览 ## 本页用途 @@ -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 分期 diff --git a/docs/README.md b/docs/README.md index 33295c1..46753a5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,11 @@ + +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 + + # 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.-) ## 同步原则 diff --git a/docs/delivery/README.md b/docs/delivery/README.md index fbaed9d..ecda4d9 100644 --- a/docs/delivery/README.md +++ b/docs/delivery/README.md @@ -1,3 +1,11 @@ + +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 + + # 交付文档指南 ## 本页用途 diff --git a/docs/delivery/audience-document-template.md b/docs/delivery/audience-document-template.md index fb03396..ad1e546 100644 --- a/docs/delivery/audience-document-template.md +++ b/docs/delivery/audience-document-template.md @@ -1,3 +1,11 @@ + +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 + + # 岗位文档模板 > 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。 diff --git a/docs/templates/deployment.md b/docs/templates/deployment.md index f60d499..4de761c 100644 --- a/docs/templates/deployment.md +++ b/docs/templates/deployment.md @@ -1,3 +1,11 @@ + +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 + + # 部署文档模板 > 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。 diff --git a/docs/templates/task-archive.md b/docs/templates/task-archive.md index 20d4be1..3b8982f 100644 --- a/docs/templates/task-archive.md +++ b/docs/templates/task-archive.md @@ -1,3 +1,11 @@ + +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 + + # <工单号> <标题> - 类型：需求 / 缺陷 / 重构