cmhub/README.md

cmhub

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

它做什么

• 用户端（自助）：公开首页、注册/登录、扫码充值、查看充值记录/剩余点数/消费记录、查看可用模型、生成与删除 API Key、下载桌面端（新用户注册成功赠送 100 点试用点数）。
• 对外提供 HTTP API：生成标题、生成图片（旧同步接口 + 新异步提交/轮询接口）、多张图片理解并返回文字、查询点数余额、查询可用能力别名。
• 按「操作类型 + 能力别名（+ 可选分辨率）」计费，调用消耗不同点数；余额不足返回「点数不足，请先充值」。
• 预付费点数模型：用户在外部支付系统充值，付款成功由支付系统回调本服务，按汇率把金额转成点数存在本地；之后调用直接扣本地点数，扣费与上游解耦、低延迟。
• django-admin 运营后台：管理注册用户、点数余额、计费规则、充值订单、点数流水、调用记录。

技术栈

Python 3.12 / Django 5.2 LTS + DRF / django-admin / 用户端 Django 模板 SSR + Bootstrap 5 + allauth / MySQL 8.4 LTS（cmhub 专用独立实例，不复用 VPS 已有的 MySQL 5.7）。AI 上游调用复用 cmbot/src/services/ 的实现。详见 docs/03-tech-stack.md。

文档入口

本仓库采用 harness coding 文档约定。AI coding agent 与开发者请从这里进入：

• 人类总览：本文件。
• agent 工作入口：docs/00-ai-start-here.md。
• 文档导航：docs/README.md。
• 仓库级规则：AGENTS.md / CLAUDE.md。

当前状态

Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为“虾皮圈”、T-612 生图同步接口止血、T-613 抽生成核心 service、T-614 生图异步任务化接口、T-615 旧同步生图接口遥测 / 弃用口径、T-616 生图失败自动重试 2 次、T-617 桌面端版本文件大小字段与 T-618 客户端发布版本后台必填校验元数据。用户可通过公开首页进入注册、登录、下载客户端和下载导入模板；新用户注册后经计费层自动获得 100 点并写注册赠点流水；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页点数记录与可用模型；桌面端可匿名请求最新客户端版本 JSON，并读取 release.force_update 判断是否必须升级、读取 release.size_bytes 校验安装包大小；新版桌面端可用异步生图提交 / 轮询接口，旧同步生图接口继续兼容并写结构化用量日志；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、注册赠点记录、调用记录、图片生成任务、客户端发布版本和导入模板，客户端发布版本新增 / 编辑时必须填写 SHA256 与文件大小，并通过计费层带原因手工调点。生产侧仍需补真实支付回调到账闭环，并按日志观察旧同步生图接口迁移进度。详见 docs/current-state.md。

T-619 已完成：新增独立 vision 能力和同步 POST /api/v1/analyze/images 多图理解接口，按一次请求固定扣点；既有标题、生图和异步生图接口保持兼容。生产启用前需在 admin 配置同时具备 text、vision 能力的模型、vision-standard 默认别名及默认计费规则。T-620 已登记：图生图接口支持单图 / 多图，第一张为主图、后续为参考图。

⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 docs/05-coding-rules.md 第 8 节与 docs/04-architecture.md 第四节计费时序。

启动

./init.sh        # WSL / Git Bash / macOS / Linux
./init.ps1       # Windows 原生 PowerShell

脚本完成依赖安装 + 验证 + 打印启动命令。当前 Windows 标准入口为 ./init.ps1。