SPEC — MonkeyCode2API 架构与技术规格

本文档记录 monkeycode-ai.com（长亭百智云 MonkeyCode）的逆向结论与本项目的实现规格。 未实机验证项均明确标注。所有端点来自 SPA assets/index-*.js 逆向 + 官方文档 (monkeycode.docs.baizhi.cloud) 交叉核对。

1. 上游平台概览

项	值
前端	`https://monkeycode-ai.com/`（Vite React SPA）
集合	全部 `/api/v1/*` 打到同源后端（`credentials: same-origin` cookie 认证）
认证	长亭百智云 OAuth 授权；`GET /api/v1/users/login` 302 → baizhi cloud 授权页
账号注册	手机号/邮箱+验证码（`个人用户注册` 文档）
对话通道	Agent 任务：`POST /api/v1/users/tasks` + WebSocket `/api/v1/users/tasks/stream`

2. 权益：每日免费额度（来自额度说明文档）

用户类型	每日额度	覆盖模型（本次实机 measure 的可见 basic 档）
免费（basic 档）	1000 万 Token	kimi-k2.5 / minimax-m2.5 / qwen3.5-plus / monkeycode-basic/*（含 deepseek-v4-flash、kimi-k2.5、minimax-m2.5、qwen3.5-plus）/ qwen3.6-plus / deepseek-v4-pro / glm-5 / minimax-m2.7 / qwen3.7-max / minimax-m3 / gpt-5.4 / glm-5.1 / kimi-k2.6 / gpt-5.5（共 17 个可见，is_hidden=false）
高级（pro/ultra，需订阅）	更高	`models/available` 里会出现 access_level=pro/ultra 的模型（如 monkeycode-pro/、monkeycode-ultra/）

额度每日自动发放、用完隔日刷新、消耗免费额度；积分用于更贵模型补足。
模型白名单不硬编码：服务运行时从 GET /api/v1/users/models/available 拉取全部可见模型（去重后供 /v1/models 与对话）；model_id 用目录查表转 UUID。

到账检查（本项目的核心要求）

额度是自动发放、无需手动领。因此“检查到没到账”实现为每天 GET /api/v1/users/wallet 读取：

daily_token_balance  今日已用剩余额度
daily_token_limit    今日额度上限（免费=10000000）

判定：daily_token_limit > 0 → 该账号额度机制已生效（到账）。
调度器在每日 quota_check_hour 执行；signin.sh/credit.sh 可随时手动执行。结果回写 auths/monkeycode-<uid>.json 的 wallet 快照，并经 /status 与 CLI 展示。

3. 已确认端点

端点	方法	说明
`/api/v1/users/wallet`	GET	钱包/每日额度（到账检查）
`/api/v1/users/wallet/checkin`	GET/POST	签到状态 / `{captcha_token}` 执行签到(需 captcha)
`/api/v1/users/wallet/transaction`	GET	流水
`/api/v1/users/wallet/exchange`	POST	兑换码
`/api/v1/users/wallet/recharge`	POST	充值/续费计划
`/api/v1/users/subscription`	GET	会员档位/到期
`/api/v1/users/models/available`	GET	平台可选模型
`/api/v1/users/models`	GET/POST	用户自定义模型
`/api/v1/users/tasks`	POST/GET	创建类型任务
`/api/v1/users/tasks/stream`	WS	任务流（正文）
`/api/v1/users/tasks/rounds`	GET	轮次
`/api/v1/users/tasks/user-inputs`	GET	待输入
`/api/v1/users/me`	GET	当前用户
`/api/v1/users/logout`	POST	登出

4. 对话通道（Agent Task → OpenAI chunk）

/v1/chat/completions  (OpenAI)
        │  messages → content
        ▼
POST /api/v1/users/tasks   {content, cli_name:"opencode", model_id:<UUID>, task_type:"develop",
                            image_id:<devbox 镜像 UUID>, host_id:"public_host",
                            resource:{core:2,memory:8G,life:7200}}
        │ → {id: task_id}
        ▼
WS（WebSocket 安全通道）指向 `/api/v1/users/tasks/stream?id=<task_id>&mode=develop`
        │  事件流（type: round/message/delta/...，正文文本）
        ▼
组装成 OpenAI SSE chunks（content/role / finish_reason/[DONE]）

实机校准结果（已用真实账号部分验证）：

任务创建缺 image_id/host_id 或 model_id 传名字 → 上游 400 参数错误。已修正为 model_id 传 UUID、host_id:"public_host"、image_id 用公共 devbox 镜像。
业务码 10811 = 已有任务在运行（瞬态忙），非额度不足；已从 quota 类改判为 ErrBusy（短冷却让位切号），4002 记为额度/升级类。
每日免费额度真实来源：GET /api/v1/users/wallet 的 daily_token_balance/limit（免费=1000万）。

⚠ 尚存未实机敲定：任务流 WebSocket 的事件帧语法（type 名、正文字段名）需在账号任务槽空闲后跑通一次端到端对话后，再校准 internal/upstream/task.go 的 extractText 事件名。当前实现：

全量打日志便于排障；
从 round/message/assistant/delta/text/content/delta_text 事件尽量抽取文本；
对 done/finish/error 触发收尾；
缺图证明时，2api 以流式对话形式工作；若上游是纯 Agent（自动执行工具、等待用户输入）， chat.completions 只返回最终正文，与一般 Chat 有差异。这部分需实机校准（见 §6）。

5. 账号池 / 冷却

PickExcluding：先看谁还有 daily_token_balance > 0（分数=剩余额度），额度全空时退回积分最多账号（balance/1000）。
冷却类型：
- CoolHard（额度耗尽，默认 12h，隔日自动恢复）
- CoolSoft（429，60s）
- CoolErr（连续错误达阈值，10m）
401 / auth invalid → Disable(要求重新 ./login.sh)。

6. 部署与配置

参考 README.md。KEY 只走 env（MC2A_API_KEY），auths/data/config.json/.env 全部 gitignored。

7. 隐私 / 脱敏

日志只打 UID/Nickname/积分/额度，不打 Cookie。
auths/（含 Cookie）不落 git；.env/config.json 不落 git。
到账状态只显示“到账/未到账”，不打印明细凭证。

8. 已知限制与实机待办

任务流 WS 事件帧语法仍待实机敲定（见 §4）——任务创建车道已实机验证（缺 image_id/host_id/model_UUID 会 400；10811=忙），但会话 slot 空闲时才能拉取到第一个帧来校准 extractText。
~~每日签到需要验证码求解器~~ ✅ 已实现并经真实账号实机验证：签到 Cap.js PoW 验证码（FNV-1a 播种 + xorshift32 派生 salt/target，SHA-256 挖 nonce）内置在 internal/upstream/captcha.go；用真实 Cookie 实测 /checkin 返回 checked_in:true，签到/到账逻辑按预期幂等跳过。
免费额度覆盖 basic 档模型（17 个可见）；pro/ultra 档模型需对应订阅才会在 models/available 出现，服务可动态拉到它们。
对话本质是 Agent 任务（会开沙箱环境），与纯 LLM chat 语义不完全等价。

注：/api/v1/users/wallet/checkin 的 POST 需带 captcha_token；该 token 由签到验证码流程 POST /api/v1/public/captcha/challenge（获 {c,s,d}=难度 + token）→ 本地并行求解 c=50 个子挑战（每个：sha256(salt+nonce) hex 前缀 == target）→ POST /api/v1/public/captcha/redeem 换取。上述流程已对线上端点 + Python 参考实现（capjs-server）双重验证。

FilesExpand file tree

SPEC.md

Latest commit

History