OPC/chorus
2
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3895c873ecb36bdc21b22264ffb5eb0a5ec5982c
chorus/docs/00-project-profile.md
T
ilaandClaude Opus 5 3895c873ec 引导提交：接入 DevHarness 并建立 chorus 项目文档 
- 从 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>
2026-08-20 11:29:12 +08:00

9.0 KiB
Raw Blame History

项目档案

本页记录不经常变化、所有维护者都需要知道的信息。Wiki 初始化完成后，Wiki 的 Project-Profile 是事实来源，本文件是只读镜像。

文档状态

当前 chorus 的线上 Gitea Wiki 尚未初始化，docs/ 是初始人工版本。按 新项目文档初始化 完成线上创建与回读后，本目录转为镜像，之后只改 Wiki。在此之前不要用本地文件的存在证明 Wiki 已就绪。

基本信息

项目 内容
项目名称 chorus
一句话目标 提供独立于 cmhub 的 Go 生图生文服务：用户提交提示词与原图得到新图或文本，运营在管理端配置上游并查看记录
主要使用者 终端用户（Web 端生成）、运营与管理员（管理端）、Claude/Codex Agent、接手简单维护的初级程序员
Gitea 地址 https://git.ilapage.cn
仓库 OPC/chorus
默认分支 main
主要维护者 ila
需求来源 Obsidian 笔记《cmgen · 从 cmhub 抽取生图生文服务 — 需求与 Go 技术方案》（2026-08-20）；项目代号由 cmgen 改为 chorus
文档适用范围 默认分支当前版本

DevHarness 来源与基线

项目 内容
DevHarness 来源仓库 https://git.ilapage.cn/OPC/dev_harness
当前基线提交 3696663781c569c57f47bb26e3b5b6369180fdaa
最后接入或升级日期 2026-08-20
项目适配说明 完整保留 Harness 规则、工单模板、Wiki 镜像与结构检查工具；docs/00、02–06、09 和 docs/README.md 改写为 chorus 内容，docs/01、07、08、delivery/、templates/ 沿用上游文本

子项目与交付单元

子项目 / 交付单元 职责 技术栈 构建与测试 版本与发布方式 规则入口 共享边界
internal/core 核心域库 provider 调用、选路、生成编排、队列、存储、加密、SSRF 防护 Go 1.22+、GORM go build ./...；go test ./internal/... 不单独发布，随两个二进制发布 根 AGENTS.md 被 portal 与 admin 共用；不 import gin、不 import go-admin
portal 用户端二进制 用户 Web 界面、JSON API、API Key 端点，MVP 阶段内嵌 worker Go + Gin + html/template + HTMX + Alpine + Tailwind go build ./portal/...；go test ./portal/... 跟随 main 分支构建单二进制 根 AGENTS.md 依赖 internal/core，与 admin 共用同一 MySQL 库
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 与 业务规则与术语；不得在多处维护互不确认的表结构描述。MVP-0 只要求 internal/core 与 portal 可运行，admin 与 migrations 的完整形态在后续阶段补齐。

技术栈与运行环境

部分 技术 说明
HTTP 框架 Gin 与 go-admin 一致，减少两端框架分裂
ORM 与迁移 GORM + golang-migrate GORM 只做查询，生产不使用 AutoMigrate
数据库 MySQL 8.0 单库；队列用 SELECT … FOR UPDATE SKIP LOCKED
任务队列 无 Redis / 无 MQ 租约 + 心跳轮询，少一个运行组件
管理端 go-admin-team/go-admin + go-admin-ui 自带 RBAC / JWT / 代码生成器
用户端会话 alexedwards/scs 无需 Redis
熔断 sony/gobreaker 多 provider 故障转移，MVP-0 之后启用
缩略图 disintegration/imaging 纯 Go，无 CGO
限流 ulule/limiter 用户维度令牌桶
上游调用 手写 net/http 客户端 不用 go-openai SDK：多 provider 在多图上传、extra_body 透传、b64_json vs url 上差异大，强类型 SDK 反而挡路
用户端前端 html/template + HTMX 2.x + Alpine 3.x + Tailwind 4.x（standalone CLI） 无 npm、无构建链、无 SPA
开发环境 Windows + PowerShell + Git；MySQL 8.0 本地或容器 Harness 工具需 Python 3 标准库

建设基线评估结论

  • 管理端采用开源基线 go-admin（MIT）：已具备 RBAC、JWT、审计和代码生成器，Provider/Model/用户/点数等 CRUD 可近似零成本产出，定制范围可控。已知代价：go-admin-ui 属 vue-element-admin 系（Vue 2 已 EOL），定制页超过 3 个时须重新评估是否改为自建服务端渲染后台。
  • 核心生成域从零开发：cmhub 是 Django，语言已变，能带走的是设计（provider 抽象、任务租约、SSRF 校验、密钥加密）而非代码；现成 Go 系 LLM 网关（如各类 one-api 变体）与本项目在图生图多图上传、图片角色规则和自有点数展示上差异大，改造与跟随上游成本高于自建约 200 行 provider 层。
  • 基础组件按需复用：gobreaker、imaging、limiter、scs 均为单一职责库，各自记录用途、版本和可替换方案。

阅读入口

常用命令

所有命令默认从仓库根目录执行。标注“MVP-0 落地后可用”的命令在首个实现工单完成前不存在。

用途 命令 预期结果
查看工作区 git status --short --branch 显示分支且没有无关修改
检查文档结构 python dev_scripts/harness.py check --strict 输出“DevHarness 检查通过”
运行 Harness 测试 python -m unittest discover -s tests -v 所有测试通过
检查核心 Wiki 镜像 python dev_scripts/harness.py sync --check Wiki 初始化后输出核心镜像一致
编译（MVP-0 落地后可用） go build ./... 无错误
单元测试（MVP-0 落地后可用） go test ./... 全部通过
静态检查（MVP-0 落地后可用） go vet ./... 无输出
数据库迁移（MVP-0 落地后可用） migrate -path migrations -database "$CHORUS_DSN" up 迁移版本前进且无错误
启动用户端（MVP-0 落地后可用） go run ./portal 监听 :8080，日志显示 worker 已启动

目录边界

目录 职责 不应放入
internal/core/ 与框架无关的核心域 gin、go-admin 依赖，HTTP 处理，模板
portal/ 用户端 Gin 服务、页面模板与静态资源 上游调用与选路逻辑（属于 core）
admin/ go-admin 脚手架与业务 app 绕过 core 的生成实现
migrations/ golang-migrate SQL 文件 测试数据、一次性修数据脚本
docs/ 核心长期文档（Wiki 初始化后为只读镜像） 人工直接维护的最终事实（初始化后）
docs/task/ 人工按需导出的任务归档快照 讨论过程和临时方案
prototypes/ 按工单和版本保存的 HTML 审核快照 凭据、个人信息、生产数据
dev_scripts/ Harness 检查与 Wiki 同步工具 产品功能代码
tests/ Harness 工具测试（Go 测试与被测代码同目录） 生产数据

环境、配置与凭据

  • 核心 Wiki 同步配置：wiki-docs.json；Gitea 地址可用 GITEA_URL 覆盖。
  • Gitea PAT 仅通过 GITEA_TOKEN 或 MCP 安全配置提供，不写入仓库。
  • 数据库连接串通过 CHORUS_DSN 环境变量提供，不写入仓库。
  • Provider 的 api_key 使用 AES-GCM 加密落库，主密钥来自环境变量 CHORUS_MASTER_KEY，须预留轮换方案；明文密钥不得进入日志、工单、Wiki 或截图。
  • 生成物默认落本地文件系统（路径由配置指定），storage 从第一天就是接口，预留 S3/OSS。
  • 测试只使用构造数据和 mock 上游，不使用生产数据和真实上游密钥。

项目专用验收要求

  • 长期核心文档必须先更新 Wiki，再导出本地镜像；Wiki 初始化未完成前，文档修改直接在 docs/ 进行并在工单说明。
  • python dev_scripts/harness.py check --strict 必须通过。
  • MVP-0 落地后：go build ./...、go vet ./...、go test ./... 必须通过。
  • 涉及 retryable 判定、SSRF 校验、密钥加解密和迁移的修改必须有针对性单元测试。
  • 未执行或无法覆盖的验证必须记录到工单。
Reference in New Issue View Git Blame Copy Permalink