cmhub/AGENTS.md

AGENTS.md

Codex / 通用 AI coding agent 的仓库级入口。进入本仓库后，先读本文，再进入 docs/00-ai-start-here.md。

项目定位

cmhub 是一个对外计费 API 服务 + 运营管理后台。它把原桌面工具 cmbot（位于 D:\chengma\cmbot）里的 AI「生成标题」「生成图片」能力抽出来，封装成带点数计费的 HTTP API，供其他项目调用，并提供 django-admin 运营后台管理用户、点数与调用记录。

核心机制：预付费点数模型。用户在外部支付系统充值，支付成功后由支付系统回调本服务，按汇率把金额转换成点数存在本地；之后每次调用直接扣本地点数，点数不足返回「点数不足，请先充值」。本服务的点数余额是唯一权威账本，不在调用链路上实时查支付系统。

文档位置

项目文档集中在 docs/；根目录有 progress.md（执行流水）、README.md（人类视角总览）、init.sh / init.ps1（统一启动验证入口）。

agent 开始编程时，以 docs/00-ai-start-here.md 为工作入口；它会继续导航到愿景、需求、技术栈、架构、编码规则、任务看板、API 合约、当前状态。

必读顺序

每次开始工作前，按顺序读取：

1. README.md：了解本服务用途。
2. docs/00-ai-start-here.md：项目入口、阅读顺序、任务领取规则。
3. docs/05-coding-rules.md：硬性编码纪律（尤其涉及资金/点数的安全规则）。
4. progress.md 与 docs/current-state.md：恢复已验证状态、下一步、当前 blocker。
5. 与当前任务相关的具体文档（api.md / 04-architecture.md 等）。

如果用户要求修改某类内容，优先阅读对应文件，不要只凭文件名猜内容。

工作规则

• 涉及点数、金额、充值、扣费、退款的逻辑属于高风险，必须按 05-coding-rules.md 第 8 节执行：显式验收、并发安全、幂等、留痕。
• 复用 cmbot/src/services/ai_text_service.py、ai_image_service.py 的上游调用逻辑，不要另写一套 AI 调用实现。
• 不把真实 API Key、密钥、支付凭证写进代码或文档样例；只用占位符或环境变量名。
• 修改数据结构必须同步更新 docs/04-architecture.md 和 docs/api.md。
• 修改导航时，必须同步检查 README.md 和 docs/README.md 的链接。

风格

• 文档默认使用中文，代码标识符使用英文。
• 内容面向 agent 执行：每条规则尽量落到「读取什么、修改什么、验证什么」。

验证

统一入口为根目录 ./init.sh（Windows 原生 PowerShell 用 ./init.ps1），完成安装 + 验证 + 打印启动命令。真实命令以 docs/03-tech-stack.md 和 docs/current-state.md 为准。