docs: add cmhub planning documents

AGENTS.md

@@ -0,0 +1,44 @@
+# 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` 为准。