44 道门禁：在 LLM 时代交付"真的能用"的科研工具
以 TPMS Explorer（浏览器端三周期极小曲面设计平台）的真实工程实录为素材，讲一套可以被任何 AI 辅助项目复用的验证方法论。文中主要工程数字附复现命令（均在仓库根执行）；历史事故数字来自审查实录（以 ROADMAP 为源）——这是全文方法论的自证边界。
一、问题：「看起来能用」的陷阱
我用 AI 结对编程做了一个科研工具：浏览器里设计 TPMS 骨支架，导出可打印的水密 STL、Abaqus 输入文件、可直接求解的 OpenFOAM 案例。项目从 2026 年 7 月做到 9 月，曲面族与物理仿真模块陆续上线。过程中反复撞上同一类事故——代码看起来对、跑起来报绿色、但交付物是错的。
三个真实案例（全部来自本项目审查实录）：
案例 1：语法通过 ≠ 能跑。 平台导出 MATLAB 复现脚本，早期登记"目检语法通过"。直到有一天我在真机 MATLAB R2025a 上无头跑了一遍——非欧映射分支当场崩掉：isonormals 内部的 interp3 假设网格各维坐标独立（separable），而径向映射逐点变形破坏了该假设。这条路径在语法层面无懈可击，在数值层面必炸。
# 复现：三支路真机冒烟（identity/倍频/非欧）——需本机 MATLAB，否则 SKIP 不算复现
node tpms/.verify/matlab_script_smoke.mjs
案例 2：同源宣称 ≠ 数值一致。 radial-grad UI 卡宣称"与 CLI 完全同源"。红队拿同参数对拍：UI 产出 192,376 三角/孔隙率 56.5%，CLI 产出 192,784/54.68%。根因是 HTML 滑块 step="0.05" 把标定表值 0.322 量化成了 0.30——一个控件层的一行属性，让 TS/JS/CLI 三方对拍全绿的同源管线系统性偏移 1.8 个百分点。
案例 3：门禁在跑 ≠ 门禁覆盖。 GPU IR 万点对拍门禁存在且全绿——但曲面清单停在上上批的 20 族，新加的 4 族从未进对拍。这类"清单漂移"在本项目历史上已发生三次（fcks 事故同模式）。
三个案例的共同点：每一处都有测试在绿、有代码在看、有宣称在档，但没有任何机制保证「测试覆盖的就是宣称的那件事」。LLM 结对把这个问题显著放大——AI 生成代码的速度远超人眼审查的吞吐，而 AI 的自信表达让"看起来对"的半衰期更长了。
二、门禁哲学：让"绿"有精确语义
本项目的解法是把验证体系当成产品来做。45 道 CI 门禁（成文时 44 门，后增文档一致性门）（Ubuntu/Windows/macOS 三平台），1000+ 断言，核心设计原则四条：
1. 行为级断言，禁止 mock 数学。 每道门禁通过 rolldown 把仓库里的真实 TS 源码打包进测试进程，断言的是"用户拿到的代码的真实行为"，不是测试脚手架里的复刻品。历史上最贵的一次事故就是复刻品与真品漂移：渲染查表版 diamond 公式与权威库差一个符号，2 万点 maxDiff=2.91，屏幕所见与导出物是两张不同曲面。
2. 最小断言数守卫（防"集体中和"）。 一段探针实验：把某门禁的全部断言中和后，它依然以 0 PASS / 0 FAIL 绿灯退出——if (fail) exit 1 这个祖传写法对"断言根本没执行"是盲的。此后每道门禁都带基线：执行断言数低于实测基线（如 parity_math 的 332）即红。
node tpms/.verify/parity_math.mjs # 四方同源对拍：TS/Python/MATLAB/GPU IR 数值一致（容差 1e-9~1e-12；GPU f32 另门口径 ≤1e-6），基线 332
3. fail-closed 优于 best-effort。 水密门：开放边/非流形/退化面任一非零即 exit 3 拒产 STL，并输出结构化诊断（哪类失败、建议升分辨率还是降周期数）。科研工具交付错误几何比不交付严重得多——一个不水密的"骨支架 STL"浪费的是一周打印时间。
node tpms/agent/tpms.mjs mesh --type gyroid --porosity 0.75 --resolution 96 --out demo.stl
# 水密自检 开放边=0 非流形=0 退化面=0 → 通过（产出约 23MB STL，跑完请删或改 --out 到临时目录）
4. 宣称必须指认一条当时跑过的命令。 项目规约：写进 README/论文的每个数字（"Diamond R96 偏差 0.13pp"、"K_int=2.34×10⁻⁹ m²"）都要能指认复现命令。这条纪律抓出过"论文宣称就绪实为两版前状态"、"注释宣称 CLI 有降周期建议而 CLI 里根本没写"这类账实分裂。
node tpms/agent/schema_check.mjs # 106 断言：契约↔实现↔README 三方对拍，含防漂移守卫
node tpms/.verify/run_ci_suite.mjs # 全量 45 门
三、红队实录：对抗审查抓什么
"每完成一件事必须对抗式审查后才算完成"是项目铁律。（版本注：原型期里程碑记至 v9.2.x，2026-09 起版本纪元重置为 v1.0.x 语义化序列；下文 v9.2 指原型期末轮。）v9.2 版发布前的一轮：4 路并行红队（几何/CFD、UI/管线、四方同源、文档宣称），0 CRITICAL、10 MAJOR、20 MINOR，全修。红队的工作方式：自设攻击用例、仓库零写入、每个发现必须带可复现证据、同时输出"攻击不可行清单"（证明审过的深度）。
那轮的 10 个 MAJOR 里，三个最有代表性：
「全档可产」四个字的代价。 schema 描述里写了"R96 k2 全档可产（open/nm/degen 全 0）"，而探针数据明明显示 qstar 在 p0.5 档有 nm=28 被水密门拒产。这段描述是 LLM 修复策略器的决策输入——错误的"全可产"会让 Agent 在死参数上无限重试。修复不是改一句话：改描述、补反向钉（把 nm=792 的拒产值钉进门禁防漂移）、重跑可产域探针。
node tpms/.verify/probe_c2_batch6.mjs # 可产域探针（数据源，先于宣称）
二阶缺陷。 修 fourPatch 端面语义（torus 容器无贯穿端口，旧口径把 71% 的侧壁阶梯面误归 inlet/outlet）后，conformal 门禁立刻爆红——暴露出一个从未被触发过的老 bug：空 patch 的 startFace 写 0，断 boundary 链。Math.max(0, -1) 这个"防御"把初始化哨兵值静默吞掉了。修复行为会打开新的可达路径，新路径上有旧 bug——这是红队对修复本身的审查价值。
数字转录。 k=6 标定数据（nm=10368 / 体积 −8.83% / …）从 JSON 抄进 schema description 时逐项核对——结果发现注释里宣称的"CLI 文档建议降周期数"在 CLI 里根本不存在。转录类错误用 grep 对拍源数据抓，宣称类缺口用"指认命令"纪律抓。
四、Agent 拦截器：给 LLM 修护栏而不是刹车
项目有完整的 NL→设计→验证 Agent 闭环（37 条中英指令回归、四档模型验收）。护栏工程的核心决策：LLM 只填意图槽位，一切数值由确定性代码生成（越界拒绝，非钳制）。
拦截器在工具调用下发前逐槽位校验：枚举白名单、数值范围、未知属性、路径穿越。对抗测试（路径穿越/越界孔隙率/注入指令）四模型零透传——注意归因纪律：对抗集里的 E1/E3 案例（越界孔隙率等）的"通过"很多是模型自觉改发了合法值，不构成拦截器动作的证据；拦截器自身的稳定性由离线确定性门禁单独证明（35 断言，含 ../x.stl 穿越写的实测拦截）。（E1/E3 等编号为内部回归用例标签，见 tpms/agent/ROADMAP.md 红队 M2 节。）
TPMS_ALLOW_MOCK_EXEC=1 node tpms/agent/llm-agent.mjs --provider mock "设计一个孔隙率 75% 的 Gyroid 骨支架"
node tpms/agent/llm_provider_selftest.mjs # 拦截器离线自检 35 断言
这套设计的可迁移点：验收一个 LLM 系统时，把"模型行为"与"护栏行为"的功劳分开计量。混在一起报告"对抗全过"是自我安慰——模型换个版本自觉性就变，护栏才是你能承诺的部分。
五、方法论迁移清单
从这些实录里提炼的五条，适用于任何 AI 辅助的工程项目：
- 给"绿"定义语义：每条 CI 通过意味着什么（行为级/基线数/fail-closed 方向），写进门禁头部注释。
0 PASS/0 FAIL不是绿。 - 宣称绑定命令：文档与代码之间建立"每个数字指认一条复现命令"的纪律，用静态断言门禁（grep 镜像）钉住高频宣称。
- 修复必须再审：红队不只审新代码，审"修复打开的新路径"。二阶缺陷（空 patch startFace）只有这种审法能抓。
- 清单即契约：类型清单、enum、白名单的"漏列"是静默失败温床（本项目三次事故同模式）。新条目接入时把清单本身做成门禁对拍对象。
- LLM 系统拆功劳：模型自觉与护栏拦截分开验收、分开报告。你能对客户承诺的只有护栏。
最后回到那个元问题：LLM 时代"真的能用"的标准是什么？我的答案是一句可以套用到任何项目的判词——当代码的每一分自信都能指认一条命令时，它才配叫交付。
本文素材全部来自 tpms-explorer 仓库实录（tpms/agent/ROADMAP.md 审查记录与门禁脚本）。在线体验：教学版 · 工程版。
