docs(.agents): tech-decisions §13 蒸馏——框架默认注入面击穿护城河(第三例跨路径封口·内建工具面红线)+ stuck签名承载同错语义+失败即时归因 + 运维三硬记(jar世代=env面随升/快照验完整性/并发争用污染测量) (cutover 窗蒸馏)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.agents/README.md

@@ -27,7 +27,7 @@
 | 文件 | 一句话说明 |
 |---|---|
 | `product-and-architecture.md` | 产品定位、13 模块与依赖、三仓三端分层架构蒸馏（中间件 Nacos/RocketMQ/Sentinel 三件套已自托管 mini-infra） |
-| `tech-decisions.md` | 技术栈与关键选型 ADR + 待确认项 + 生成主线口径（AgentScope 三档统一收敛）+ 便宜档 M1-M3 实测（§5.1）+ 配置控制面阶段〇/一① 落地（§10/§11：Nacos/RocketMQ/Sentinel + 护城河续修/软预算/门判 middleware） |
+| `tech-decisions.md` | 技术栈与关键选型 ADR + 待确认项 + 生成主线口径（AgentScope 三档统一收敛）+ 便宜档 M1-M3 实测（§5.1）+ 配置控制面阶段〇/一①② 落地（§10-12）+ 生产 cutover 窗封口（§13：框架默认注入面审计红线 / stuck 签名对齐设计意图 / 运维三硬记） |
 | `mvp-scope-and-milestones.md` | MVP 的 55 项 P0 产品功能范围、5 工位分工、M0-M5 里程碑与验收指标 |
 | `agentscope-2.0-facts.md` | AgentScope 2.0.2 真实架构速查 + 便宜档 cheap-worker 实现 API 速查（免重查）+ 护城河续修/软预算 middleware 的 2.0.2 机制速查（on_reasoning 拦 finish 续跑 / 洋葱序 / 软预算门判自挂） |
 

.agents/knowledge/tech-decisions.md

@@ -204,3 +204,13 @@ Nacos / RocketMQ / Sentinel 从「已选型未部署」推进到自托管 mini-i
 **follow-up**：真门 e2e 排 mini-desktop 窗口（单 POST 收敛 + 续修真拦 + C2 首轮不越界 + C1 成功局 costRmb≠0 + 并发不撞端口 + 七值回调 + 代理旁路 + **盲修空转率**——最后这条是决策留的头号观测项：cheap 无九门自检工具、agent 每次纯文本终止后 check 才第一次真跑门、不过就据 feedback 盲修，空转会显著抬时延，cutover 后量真实空转率再定是否加自检工具）；cheap-worker 全套有 14 个 `test_toolkit.py` 失败，是 pre-② 的测试隔离污染（某测试污染 test_toolkit 依赖的共享盘态，单文件跑与排除②新测试都复现），与配置控制面无关、待单独修；有界 worker 池真并发 cap（承①，端口池是为它设计的机制、真放开并发才用得上）。
 
 **mini-desktop 真门窗口验证（2026-07-03，两轮）**：② 归并 cutover 三接缝真门全闭合——单 POST 收敛 / 续修真拦放行 / C2 目录一致 / 代理旁路无 502 / result_out 承重，外加窗口暴露并已修实证的两个部署接缝。其一，requirements 补 `agentscope[service,storage]==2.0.2` extras——裸钉 `agentscope==2.0.2` 缺 fastapi/uvicorn/apscheduler/redis，全新 venv 起不动 Service，而 SDD 单测只 import 到 create_app 之下、真起服务才暴露（`cheap-worker` 与 `tier2/gen-worker` 同款）。其二，成本子系统改用 per-POST 凭据的 key（`current_model.credential.api_key`，SecretStr 公开字段）取价，不再依赖 Service 进程 env NEWAPI_KEY——成功局 costRmb 从 `0.0/degraded` 变 `1.0785/active`（commit `24e558a4`，B深 per-POST 取价 + B浅 `build_cheap_app` 调 `ensure_api_key_env` 双保险）。红线③ 用植入带 marker 的绿 verdict 做受控 e2e 坐实：marker 在 M3 完成前即被 driver 侧 unlink 清掉，终局是本局自产的真 verdict（pass=False）而非假绿。**但便宜档真生成当前系统性产「菜单空壳」（E_live/G_input/H_progress 未过、输入不驱动状态），并撞 MiniMax-M3 `400 tool result's tool id not found(2013)`（崩 ChatService.run → driver idle 600s 慢失败）——这属生成质量（WU-B/C/F）与 M3 可靠性，与 ② 归并正交，但决定便宜档实际可用率、cutover 真上线前需另线解。** 归并交付面 cutover-ready，「便宜档真能上线可用」是另一条线。
+
+## 13. 便宜档生产 cutover 窗:框架默认注入面审计 + 熔断签名对齐设计意图(2026-07-04 落地,切片一)
+
+cutover S0–S4 与 A11 计费 e2e 在同一窗完成(证据=cutover plan §9 执行记录),窗内抓修四件全在生产真流量下坐实。两件有跨项目复用价值,记在此;另两件(studio 透传拒因、C6 族错配直指)属产品语义修,细节看 plan §9 即可。
+
+**框架默认注入面击穿自有护城河(§12「跨路径封口」的第三例,也是最重的一例)**。AgentScope 2.0.2 Service 路的 `build_toolkit`(app/_service/_toolkit.py)把 workspace 内建工具(Bash/Edit/Glob/Grep/Read/Write)无条件并入每个 agent 的工具面,再拼我们的 extra 六工具。后果:便宜档写边界靠六工具白名单(write 越界拒 + basename 拒,I1 fail-closed),但内建 Write/Edit/Bash 根本不走白名单,Bash 甚至能以绝对路径越出工作区——护城河被框架默认面整体旁路。同时 12+ 个语义重叠的工具(Read vs read_file、Edit/Write vs write_file)对 M3 是实打实的混乱税:生产实测 80011 一局 14 次工具失败(拿内建 Bash 用相对路径 `ls` 连败、把框架 Read 的 `limit` 参数串到我们的 read_file 上、内建 Edit 的 read-first 约束连环撞),¥12.24 烧到 step_cap;关掉内建后同 brief 复跑(80012)零工具失败、¥2.13 一次过门。修法=第三块钉版本补丁 `ws_builtin_tools_patch`(monkeypatch `LocalWorkspace.list_tools` 返空;cheap Service 进程只跑便宜档 agent,进程内全局补丁作用域恰好;tier2 独立进程不受影响)。**教训升一级:接入任何框架的 Service/App 形态,必须逐项审计框架默认注入的能力面(工具/中间件/调度/团队/后台任务),与自有约束(白名单/预算/门)对账——CLI 路没有的面,Service 路可能默认全开;per-task review 结构上看不到这种「框架给的」面,要靠真流量观测或整链终审。**Planning/Team/Schedule 工具面收窄仍是 follow-up(工单 h,成本上界已有 ¥ 两段式硬地板兜)。
+
+**stuck 熔断签名必须承载「同错」语义,且失败必须即时可归因**。四道熔断里 stuck 的设计意图是「连续 N 次同一失败签名=死圈」,但实现把签名写成了 ToolResultState 的裸状态值——恒为 "error",任意 4 次异类临时失败也会误熔断(80009 生产实证 ¥2.6 作废),而且事后四路取证全空(trace 是 D11 瘦骨架无工具名、Redis 会话崩溃不 flush、结果文件只 dump 大结果、熔断消息只有 tool_call_id)。修法=签名富化为「工具名+状态+归一化错误头」(长 hex/数字→#,同类错误仅差 id/行号仍同签名),异类连败不再误判(交 step_cap/¥ 闸/timeout 兜底,80011 实证组合兜底链正确协同),并且每次工具失败即时打印一行(名字+错误头)。**教训:熔断/告警的触发凭据里必须带上「事后归因要用的最小事实」,否则每次触发都要重放一遍现场;观测修往往当场破案——签名富化上线后第一局就把内建工具面问题钉死了。**
+
+**运维面三条硬记**:① jar 世代升级=依赖面随升——新 jar 带上了阶段〇的 Nacos 接线,`NACOS_PASSWORD` env 缺 → 登录 403 → 注册 failFast → 进程静默退,连 boot banner 都不留;回滚资产要「旧 jar + 旧 env 面」两层,升级前先 diff 新世代多要什么 env。② 环境快照采集要验完整性——S0 的 `/proc/<pid>/environ` 快照只存到 PATH(采集半途失败没人发现),重启即 DB 密码丢;权威源是 `infra/.env`(裸赋值文件,source 前必须 `set -a`)。③ 并发争用会污染测量——bake_off conc=3 时 spec-smoke 100% 失败(Chrome/端口挤兑)→ 全场考卷回退 key-cycle,测出来的过门率是环境噪声不是生成质量;凡「测质量」的批必须串行或与基线同并发口径,且 smoke 一类哨兵失败必须打印真因(raw 尾),不能只留 PASS/FAIL 一个位。