cmhub/docs/README.md

项目文档导航

cmhub 项目文档总览。agent 真正开始编程时，以 00-ai-start-here.md 为工作入口。

一句话定位

cmhub 是一个自助用户端 + 计费型 AI 能力网关 + 运营后台三合一服务：终端用户自助注册、扫码充值、管理 API Key；用户的程序用 API Key 调用把 cmbot 的「生成标题」「生成图片」能力封装成的 HTTP API，按点数计费；运营用 django-admin 管理用户、点数与记录。

文档导航

• ../AGENTS.md：Codex / 通用 AI coding agent 的仓库级入口。
• ../CLAUDE.md：Claude Code 的薄入口，具体规则以 AGENTS.md 为准。
• ../progress.md：执行历史流水，只追加记录任务执行、验证、阻塞和决策。
• 一页汇报版 / 电梯陈述：最短版本，用于口头汇报或投影。
• 项目介绍（给管理层）：面向决策与汇报的业务视角概览，非技术执行文档。
• AI 开发入口：每次开始工作的入口、阅读顺序和任务领取规则。
• 项目愿景：为什么做、为谁做、产品原则、非目标。
• 需求：要什么、用户故事、验收标准（含资金风险）。
• 技术栈：Django + DRF + django-admin 及运行命令。
• 架构设计：系统结构、计费时序、数据模型、关键风险和开发顺序。
• 编码规则：硬性约束，含资金/点数安全专项（第 8 节）。
• 任务看板：按依赖拆分的小任务，agent 每轮只做一个。
• Phase 0 骨架审核：T-001~003 代码审核结论与修补清单（P1/P2/P3），对应任务 T-004。
• Phase 1 AI 层审核：T-101~104 代码审核结论与修补清单（P1/P2/P3），对应任务 T-105；重点提示图片同步风险未退与 parameters 越权计费隐患。
• Phase 2 计费核心审核：T-201~203 代码审核结论（资金安全逐条核对）与加固清单（零 P1，P2/P3），对应任务 T-204。
• Phase 3 对外 API 与充值审核：T-301~305 代码审核结论（鉴权/回调/幂等/入账逐条核对）与优化建议，对应任务 T-306；P1 提示 image_url SSRF 上线前必修。
• API 合约：对外接口、支付回调、AI 调用模块合约、错误码。
• 路由与页面结构：API 路由与 django-admin 后台职责。
• 环境变量与配置：Django、数据库、AI 密钥加密、支付、对象存储等配置项。
• 当前实现状态：可覆盖的当前快照、可运行命令、下一步任务。
• 已有项目接入清单：把模板补进已有代码库时的迁移步骤。
• 收尾检查清单：会话结束前逐项检查。
• 方法对照表：失败模式 → 首要修复 → 工件。
• 评审评分表：单次会话输出的结构化评审。
• 质量文档：代码库长期健康度追踪。
• ../init.sh / ../init.ps1：标准启动与验证入口（按操作系统二选一）；换命令只改脚本顶部三个变量。

任务 / 进度 / 当前状态

• 06-tasks.md 维护任务看板：任务 ID、依赖、验收要点和状态。
• ../progress.md 维护执行进度：每轮做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。
• current-state.md 维护当前快照：当前目录、可运行命令、已完成摘要和下一个可领取任务。

维护原则

• 需求变化先改文档，再改代码。
• 代码现实变化后同步 current-state.md 和 06-tasks.md，执行过程追加到 ../progress.md。
• API、数据模型、计费时序、错误码一旦在文档中定稿，代码不得另起一套。
• 涉及点数/资金的改动，先读 05-coding-rules.md 第 8 节与 04-architecture.md 第四节。
• agent 开始新任务前，必须从 00-ai-start-here.md 进入。