docs(agents): 蒸馏内测闭环 A 段——new-api per-user 额度预置池 + S0 硬约束 + facade HMAC

tech-decisions §16:额度不自建钱包对接 new-api per-user 配额;S0 实测 admin
令牌不能替他人建 token(user_id 忽略/access_token 不可 API 写)→ 预置池 CAS claim;
生成计费以 new-api used_quota 为权威(worker 自估偏高);注册防枚举固定假 BCrypt
同码路 + fail-open IP 闸;facade 回调空 secret=可伪造 → 两端 HMAC-SHA256 验签。
README 索引行同步。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.agents/README.md

@@ -29,7 +29,7 @@
 | 文件 | 一句话说明 |
 |---|---|
 | `product-and-architecture.md` | 产品定位、13 模块与依赖、三仓三端分层架构蒸馏（中间件 Nacos/RocketMQ/Sentinel 三件套已自托管 mini-infra） |
-| `tech-decisions.md` | 技术栈与关键选型 ADR + 待确认项 + 生成主线口径（AgentScope 三档统一收敛）+ 便宜档 M1-M3 实测（§5.1）+ 配置控制面阶段〇/一①② 落地（§10-12）+ 生产 cutover 窗封口（§13：框架默认注入面审计红线 / stuck 签名对齐设计意图 / 运维三硬记）+ 升级 AgentScope 2.0.3（§15：兼容依据 + 原生 Budget/RAG/mem0 列而不迁） |
+| `tech-decisions.md` | 技术栈与关键选型 ADR + 待确认项 + 生成主线口径（AgentScope 三档统一收敛）+ 便宜档 M1-M3 实测（§5.1）+ 配置控制面阶段〇/一①② 落地（§10-12）+ 生产 cutover 窗封口（§13：框架默认注入面审计红线 / stuck 签名对齐设计意图 / 运维三硬记）+ 升级 AgentScope 2.0.3（§15：兼容依据 + 原生 Budget/RAG/mem0 列而不迁）+ 内测闭环 A 段落地（§16：new-api per-user 额度预置池 / S0「admin 不能替他人建 token」硬约束 / new-api 权威计量 / 注册防枚举 + facade HMAC 验签） |
 | `mvp-scope-and-milestones.md` | MVP 的 55 项 P0 产品功能范围、5 工位分工、M0-M5 里程碑与验收指标 |
 | `agentscope-2.0-facts.md` | AgentScope 2.0.3 真实架构速查 + 便宜档 cheap-worker 实现 API 速查（免重查）+ 护城河续修/软预算 middleware 的 2.0.3 机制速查（on_reasoning 拦 finish 续跑 / 洋葱序 / 软预算门判自挂） |
 

.agents/knowledge/tech-decisions.md

@@ -246,3 +246,15 @@ cutover S0–S4 与 A11 计费 e2e 在同一窗完成(证据=cutover plan §9
 2.0.3 原生补进了几样过去判定「框架没有、只能自建」的能力,记在这里,但本期都列而不迁。其一是 `ReplyBudgetControlMiddleware`——这正是早先设计反复核验「2.0.2 源码里不存在、故预算软刹必须自建」的那个类,2.0.3 把它补了进来(`middleware/_budget.py`)。它按加权 token 预算在 `on_reply` 里累计、到顶注入一条提醒消息,是软控;我们自建的软预算是 ¥ 两段式——软停线(便宜档 ¥10 / 富档 ¥50)只许收尾,硬地板(×1.5)fail-closed 数学封顶,属护城河(见 §11、运行时 SoT §5.2)。原生的 token 软控替不了这套 ¥ 制 fail-closed 硬闸,故保持自建,原生件只在「能否给 ¥ 闸做 token 估算上游」这一层评估。其二是中间件洋葱扩到工具执行层(`on_acting` 包裹 acting、middleware 可经 `list_tools` 贡献工具)、原生 RAG 管线(`rag/` 包:KnowledgeBase + chunker + qdrant 向量库)、mem0 长期记忆适配(`middleware/_longterm_memory/_mem0/`);它们对应 tier2 未来的经验召回与检索需求,排在生成主线达标之后按需评估,不趁升级顺手迁。
 
 follow-up:2.0.3 原生 `ReplyBudgetControlMiddleware` 能否给自建 ¥ 闸做 token 估算上游(接 §10 阶段〇留的「2.0.3 原生 token 限制 build-vs-buy」);原生 RAG 与 mem0 在 tier2 经验召回线的取舍;历史文档里「2.0.2 核验 ReplyBudgetControlMiddleware 不存在」这类句子是当时的真验证事实,按两层纪律留痕不回改,该类新事实只落在本条。
+
+## 16. 内测闭环 A 段落地(2026-07-07,注册/额度/dify/facade 收口)
+
+创始人把「7 月中旬内测」的开发面收敛成一条种子用户旅程:注册(用户名+密码、无短信、网关 IP 限流)→ 得 ¥100 额度 → 生成 → 试玩 → 发布到 feed → 数据飞轮回流。这条闭环的三个真开发缺口(注册登录、额度、dify 节点)已实现并在 dev 真机逐环验证,代码经 `neice/stage1-integ` 三方合并进 dev/2.0.0(merge `210ce701`,11 提交,全部 opt-in 默认关)。此处记的是过程里几个不查就会踩坑的事实与被现实推翻的方案,不是功能清单。
+
+**额度不自建钱包,对接 new-api 的 per-user 配额——但 new-api 的管理边界逼出了预置池。** 创始人拍板额度口径 = 复用 new-api 网关原生的按用户配额,每人 ¥100,生成消耗由 new-api 权威计量,而不是在 game-cloud 里新建 credits 钱包/扣额子系统。new-api(one-api 系,`100.64.0.8:3000`,DB=`infra-postgres:5432/new-api`)的原生模型是 `users`(quota/used_quota)+ `tokens`(每个 token 属于某 user,用它调用即扣该 user 配额),配额单位是 one-api 默认的 500000/$1、DB options 未覆盖,按 usd_rate 7.3 折算 ¥100 = 6849315 quota。原本设想注册时在线调 new-api 管理 API 开户+建 token+充额,但 S0 阶段实测撞到一条硬边界:**admin/root 令牌能建用户、能 setQuota,却不能替他人建 token**——`POST /api/token/` 永远把 token 绑到令牌自认证的那个用户身上,请求体里的 `user_id` 被忽略,而 `access_token` 也无法经 API 写入。这意味着「每个玩家一把自己的 token」这一步绕不开直接写 new-api 的 postgres。据此创始人拍板改走**预置池**:离线 ops 脚本(`game-runtime/tools/newapi_pool_provision.py`,纯 stdlib,每条四步 = 建 user → 直连 postgres UPDATE access_token → 以该 user 身份建 token → setQuota ¥100)预先造好一批 user+token 对灌进 game-cloud 的 `newapi_quota_pool` 表(FREE),注册成功后由消费者 CAS 抢占 FREE→CLAIMED 把池条目绑到玩家。注册走 outbox(注册成功落 outbox → RMQ → claim 消费者)让绑定与注册事务解耦、至少一次。任何后续要给用户发独立 new-api 凭据的活,都得先认这条管理边界,别再假设在线建 token 可行。
+
+**生成计费的权威是 new-api,不是 worker 自估。** job 组装时执行器把认领到的池 token 注入 `userToken` 位(只对真实 member 生效,系统/bake-off 局旁路),worker driver 从 `job["userToken"]` 取凭据调 new-api,new-api 就天然按该用户扣 used_quota。dev 上一次真生成后 new-api user17 的 used_quota 从 0 涨到 26651(¥0.389),而同一局 worker 自估 ¥1.03——两者不一致,正是「用 new-api 权威计量、不信 worker 自估」的实证理由。额度耗尽/凭据失效用跨契约共享枚举 `quota_exhausted` 分辨(`contracts/api-schemas/aigc.yaml` + `dify-workflow-io.json` + Java/Python 三处同批)。
+
+**注册登录、facade 回调这两块的坑都在「防伪」细节上。** 注册加的是 `game_player` 的 username/password 列、mobile 改可空、`uk_username` 唯一约束(Flyway V31);防用户名枚举的做法是准备一个固定的假 BCrypt hash,当用户名不存在时也照样跑一次 BCrypt 校验,使「用户名不存在」与「密码错」走同一码路同一时延、返回同一错误码,避免时序侧漏;IP 限流复用 passport 既有的 Redis 计数范式、按 scene 分桶且 fail-open(Redis 挂不拦正常注册)。facade 收口的是回调验签:dev 上后端与 worker 的 callback-secret 原本都空 = 验签关闭 = 内网可伪造回调驱动落包,内测必须两端配同一把非空密钥(后端 `AIGC_CALLBACK_SECRET` / worker `--callback-secret`,HMAC-SHA256 对原始 body 算签置 `X-Callback-Signature`)。dify 走形态A:mini-infra 已部署的 dify(:18080)建一个 HTTP「游戏开发节点」直连 cheap-worker `:9501/generate`,复用现成 agentscope 生成链,后端近零改;a-min 形态不带 userToken,driver 回落全局 key,与 per-user 计费天然隔离。
+
+follow-up:预置池当前是离线人工灌,放量前需接一条池水位告警+补池的运维线(池空则注册拿不到额度);dify 形态A 的 HTTP 节点已证 curl 可通,workflow UI 实搭是 ops 步待做;quota 单位 500000/$1 与 group 定价若日后改价需在折算处(ops 脚本 + 任何入队余额门)同步。相关活账见记忆 `neice-core-loop-e2e-live`、设计档 `docs/agent-specs/2026-07-07-内测-WU1/WU2/WU3-*.md`。