45 lines
2.8 KiB
Markdown
45 lines
2.8 KiB
Markdown
# 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` 为准。
|