WeClaw_88｜论文依赖活体代码时，怎么重构才不烧掉自己的实验：一次提示词瘦身的安全骨架
系列文章第 88 篇 - 冻结契约 · 快照门禁 · 门禁驱动验收 · 回归归因 · 论文代码漂移治理
📚 专栏信息
《从零到一构建跨平台 AI 助手：WeClaw 实战指南》专栏
专栏定位：面向开发者和技术决策者的实战专栏，用真实案例和完整代码带你理解如何构建生产级 AI 应用
上一篇讲了系统提示词瘦身的「攻」：怎么把 244,357 tokens 砍到 48,845。这一篇讲「守」——WeClaw 同时是一个在演化的产品和三篇在投论文的实验平台，论文实验脚本直接 import 活体代码。在这种项目里，一次善意的重构足以烧掉已发表的数字。本文记录我们为这场高风险重构搭设的四道安全骨架，每一道都对应一次真实踩过的坑或差点踩的坑。
👨💻 作者与项目
作者简介：翁勇刚 WENG YONGGANG 新概念龙虾-WeClaw 开发团队负责人，一群专注于跨平台 AI 应用的实践者 理念："再复杂的技术，也能用代码讲清楚"
- 💻 项目地址：https://github.com/wyg5208/weclaw.git
- 🌐 官网地址：https://weclaw.link
- 📝 作者 CSDN：https://blog.csdn.net/yweng18
- ⭐ 欢迎 Star⭐、Fork🍴、贡献代码🤝
📝 摘要
本文结构概览：
「论文依赖活体代码」为什么是一种特殊危险（比依赖快照更脆）→ 第一道骨架：先冻结不可逆的东西（数据快照门禁）→ 第二道骨架：冻结契约 + 10 条 query 的快照护栏 → 第三道骨架：门禁驱动的批次验收，每一步全绿才放行 → 第四道骨架：用 git stash 做回归归因，把「既有失败」和「新增回归」分开 → 收尾：论文与代码的 5 处漂移如何在重构中一并清算 → 四条可复用的纪律。
核心观点：安全不是重构完成后的验收动作，而是重构开始前的结构布置。等代码改完再想「会不会破坏论文」，已经晚了。
一、一种特殊的依赖：论文 import 了你的活体代码
常规项目里，论文和代码的关系是单向的：写完论文，代码继续演化，论文里的数字是历史快照，互不打扰。
WeClaw 不是这样。三篇在投论文（工具暴露机制、跨会话经验、异步工具编排）的实验脚本直接从源码树 import：意图分类器、工具注册表、上下文压缩器……跑一次实验脚本，读的就是当下的活体代码。这意味着：
- 任何人「顺手优化」一下意图分类器的关键词表，已发表表格里的准确率就不可再生成了；
- 提示词瘦身这种看起来只碰文本的改造，极易顺手「统一」几个被实验脚本依赖的符号签名。
我们把这种风险叫做活体依赖（live dependency），它比数据丢失更隐蔽——代码照常运行，测试照样通过，只有重跑实验脚本时才会发现数字变了，而那时你往往已经不知道是哪次提交改的。
应对原则只有一句话：把「会变的」和「不许变的」在结构上分开。 下面是四道具体的骨架。
二、骨架一：先冻结不可逆的东西（数据快照门禁）
方案排期上我们做的第一件事不是改代码，而是给数据上锁。
排查发现：异步编排论文的实验脚本对生产库做全表扫描，没有日期过滤。生产库每天都在增长——今天跑出 21.32s，下周跑可能就是 21.4s。已发表的数字正在缓慢变得不可再生成，而没有人察觉。
这是整个改造中唯一不可逆的风险：代码改坏了可以回滚，数据窗口漂移了永远找不回来。于是设立了「P-1 门禁」——三项未完成，一行生产代码都不许动：
- 快照冻结：只读数据库快照落盘归档（脚本 + 快照同仓存放）；
- 脚本护栏：实验脚本加
--until日期参数，所有查询显式带 cutoff 过滤； - 论文声明：正文补一段采集截止日期与快照可用性说明。
# run_cfta_experiments.py 加上的日期护栏（示意）
parser.add_argument("--until", default="2026-08-08 23:59:59",
help="数据采集截止日期，所有查询显式过滤")
...
WHERE created_at <= ? # 每条查询都带上，无一例外
纪律：重构的风险清单里，不可逆项永远排第一个处理。可逆的错误可以边做边修，不可逆的错误只能事前拦截。
三、骨架二：冻结契约 + 快照护栏（给 API 立界碑）
数据冻结后是符号冻结。全库 grep 出一份清单：实验脚本到底依赖哪些符号的哪些行为？
结论写成方案里的「冻结契约」：
detect_intent_with_confidence/IntentResult/INTENT_CATEGORIES等论文复现面符号只增不改——可以增加新符号、新参数，但既有符号的签名与语义在本次改造中保持逐位不变。
契约本身只是文字，让它长出牙齿的是快照护栏：改造开始前，用 10 条代表性 query 跑一遍分类器，把 (primary_intent, confidence, 暴露工具集) 三元组落盘成基线 JSON；此后每个批次的验收脚本都重跑这 10 条，与基线逐位比对，任何漂移当场红灯。
# verify_domain_guides_split.py 的 E4 护栏（示意）
for snap in baseline["snapshots"]:
r = detect_intent_with_confidence(snap["query"])
assert (r.primary_intent, round(r.confidence, 3), sorted(r.intents)) == \
(snap["primary_intent"], snap["confidence"], snap["intents"])
10 条 query 的选取刻意覆盖了边界：高置信命中、低置信命中、以及 4 条返回空意图的「分类器盲区」——盲区 query 守护的正是「未命中路径」不被重构顺手改掉。
纪律：冻结契约要配可执行的断言。写在文档里的契约会被遗忘，写进验收脚本的契约只会被遵守。
四、骨架三：门禁驱动的批次验收
改造被切成 P-1 → P0 → P1 → P2 → P3 五个批次，每个批次有独立的门禁脚本，全绿才放行到下一批。门禁的设计有三条讲究：
1. 只读、可重复。 门禁脚本不修改任何生产代码，任何时候重跑结果一致。验收不是一次性仪式，而是随时可做的体检——本文写作时就重跑了一遍，数据与首次验收逐项相同。
2. 等价性要构造性可证。 「切分后内容没丢」不靠目测，靠数学：CORE 中未被指南区间覆盖的部分按序拼接即核心残量，所以「残量 + 全部指南 ≡ 原 CORE」由定义成立，验收脚本只是把这个定义翻译成非空行多重集比对。
3. 回退路径也要被验收。 灰度开关关闭时输出必须与改造前逐字节一致——门禁脚本真的 monkeypatch 了开关、真的断言了 ==。「应该能回退」和「断言过能回退」是两种完全不同的安全感。
门禁清单（全部在仓库 scripts/ 下）：
| 脚本 | 守护什么 |
|---|---|
verify_prompt_slimming_v3.py | 实施前假设验证（G1-G6），不成立不开工 |
verify_domain_guides_split.py | 切分等价 / 场景正确 / 冻结护栏 / 回退等价（E1-E5） |
verify_prompt_assembly_p2.py | 双路径字节一致 / 预算丢弃 / 兜底回补（A1-A5） |
probe_sp_tokens.py | 效果度量，自动对照实施前基线输出降幅 |
五、骨架四：回归归因——把「既有失败」和「新增回归」分开
定向回归跑完：274 项里 12 项失败。重构者的本能反应是慌——是不是我改坏的？
慌解决不了问题，归因方法可以。我们的标准动作：
git stash push # 把本次改造的全部变更暂存，回到干净 HEAD
# 复跑那 12 个失败用例
git stash pop # 恢复改动
干净 HEAD 上仍然失败 → 既有问题，与本次改造无关，如实记录不阻塞；干净 HEAD 上通过 → 本次引入的回归，立即修复再放行。
这次的结果：12 个失败全部是既有问题（工具分类显示名漂移 ×3、经验链路 ×3、阶段常量断言 ×5、集成测试索引错误 ×1），零新增回归。这套动作的价值不止于免责——它逼着你为每个失败写下归因记录，项目对「哪些测试本来就是坏的」第一次有了完整账本。
纪律：回归失败清单里的每一项都必须有归宿：要么是「我改坏的，我修」，要么是「本来就坏，证据在此」。不允许存在第三种状态叫「应该没关系吧」。
六、收尾动作：论文与代码的漂移一次清算
重构的验收清单里还藏了一项与代码无关的工作：论文一致性同步。瘦身改造让三篇论文里 5 处表述失实或过时，既然三篇都还没投出，此刻修订成本最低：
| # | 漂移 | 修订 |
|---|---|---|
| 1 | 「提示词预算 20,000 字符」（代码采集时实际另有其值，重构后为 26,000） | 改为「采集时口径 + 事后重构限定」表述 |
| 2 | CFTA「lightweight system prompt」实为 19.9K tokens 全量 | 改造后名副其实（~3.9K tokens），措辞同步为「紧凑索引替代全量指南」 |
| 3 | 三篇论文意图类别数口径不一（14 / 23 / 25） | 统一为「23 主类（25 子映射）」 |
| 4 | 「不消耗额外 token（未用的提示词空间被替换）」前提被瘦身削弱 | 改为「在既定 2000 字符预算内，不触发预算竞争」 |
| 5 | 瘦身后 CFTA 绝对收益缩小 | Limitations 主动补敏感性披露（相对降幅 55-58% 稳定） |
第 5 项值得多说一句：主动披露「我们的改造让绝对收益变小了」看似自曝短板，实际是最强的防御——收益来源的机制解释（把工具执行移出首响应关键路径）因此变得无可辩驳。审稿人发现叫事故，作者披露叫严谨。
七、四条可复用的纪律
- 不可逆风险前置：数据窗口、快照、已发布数字——重构开始前先冻结，这是唯一没有「事后补救」选项的类别；
- 冻结面要有牙齿：契约写进验收脚本的快照断言，红灯机制代替自觉；
- 等价与回退都要被断言：构造性等价证明 + 逐字节回退断言，是把「高风险」降为「可承受」的两块承重墙；
- 漂移一次清算：代码重构顺手暴露的论文/文档漂移，趁热一次修完，留到下次就永远没人修了。
代码会持续演化，论文会陆续投出，但只要骨架在，每一次演化都不会烧掉过去的工作。这大概是一个「产品 + 论文」双栖项目最值钱的基础设施。
📎 本文涉及的脚本：
scripts/verify_prompt_slimming_v3.py、scripts/verify_domain_guides_split.py、scripts/verify_prompt_assembly_p2.py、scripts/probe_sp_tokens.py📊 版本：v9.13.0 ｜ 前篇：WeClaw_87（瘦身战役全记录）