【DSH #1】跳出工具调用执念：AI Coding的工程质量保证与抗熵增

写在前面的话：这是【DSH 工程哲学】系列的第一篇。在以 deepseek-harness 开源仓库为代表的 AI 原生工程演进中，Agent 已经从单一会话的辅助者演变为代码库的主要协作者。本系列旨在穿透狂热的技术名词表象，系统探讨 AI 深度介入后软件生命周期的范式转移。后续篇章将深入多 Agent 协同拓扑解耦与物理收据闭环，而本篇将从最核心的命题切入：为什么“工具调用”救不了复杂的工程项目？

2026 年下半年，随着 deepseek-harness 等大型 AI 原生项目的持续演进，开发者对智能体的认知发生了一次剧烈的断层跃迁。就在不久前，行业对 Agent 的认知还几乎完全被“工具调用”（Tool Use / Function Calling）所绑架——给模型挂载数十至上百个端点、打通诸多 SaaS 插件，似乎就足以宣称实现了全自动软件工程。

但当真正的生产环境展开时，现实迅速给出了冰冷回击：面对拥有数百个模块、经验估计约数十万行代码的大型工程体系时，Agent 的崩溃往往不是因为它“缺少某个 API 工具”，而是源于极其微小的技术熵增蔓延——一次自作主张的越权重构、一个悄悄修改的全局构建配置、或者一段为了让单测跑通而偷偷吞掉的异常。

工具调用（Tool Use）只是赋予了智能体感知外部世界与执行动作的原子能力，它解决的是“能不能触达”的问题；而真正决定系统生死的，是包裹在它之外的系统治理框架与确定性边界。

一、第一性原理：对抗概率系统的基石

在 DeepSeek Harness 的源码演变中，其支撑约 260 个 npm 包和数千个模块并发演进的底座，不是提示词的堆砌，而是高度收敛并被代码严格约束的第一性原理（First Principles）：

1. 可验证性原理（Verifiability）

约定的生命力完全等于它的可验证性。凡只靠道德自觉与提示词约束的约定，在规模增长与轮次迭代中必然衰减。凡机械可查的承诺，必配一条非零退出的命令。 在 DSH 源码中，这一原理被推演到了极致：门禁本身也必须被门禁检验——每一个验证门禁都强制配备负样本规格（Negative Sample Spec），必须构造显式的非法用例证明门禁确实会拒绝，坚决杜绝“纯运行不报错即通过”的虚假安全感。

DSH 源码落地：门禁自证与负样本拦截 在 scripts/ 下维护了大量原生门禁脚本及其伴生测试（如 verify-md-links.spec.ts、verify-concrete-terms.spec.ts、persistence-schema.spec.ts）。以 scripts/verify-md-links.spec.ts 为例，测试套件并不直接断言合法链路通过，而是主动构造 mkdtempSync 临时工程，注入无效相对路径、不存在的 #fragment 锚点和跨包孤儿链接，显式断言门禁函数必须抛出 target 或 fragment 异常。凡不能在测试中通过注入恶意/畸形样本自证拦截能力的脚本，不允许作为 CI 门禁上线。

2. 形意分离原理（Form-Intent Separation）

语义规范负责定义“什么是好的”，而结构设计负责把语义承诺转化为可检验的物理影子（例如状态写入路径、哈希严格封印、强制文档链接化）。大模型本质上是一个强大的概率解释器，能为任何错误的架构写出看似天衣无缝的理由。因此，机械门禁必须只锁定物理影子、从不交给大模型做主观语义裁决。在机器触达不到的真实性与价值判断边界，通过正反样例校准人工 Review，坚决不写假门禁。

DSH 源码落地：物理影子与 AST 硬约束 在 scripts/verify-concrete-terms.ts 中，工程规范要求代码与注释中严禁使用模糊隐喻或未落地的意图词（如将特定模糊词加入黑名单）。DSH 没有让大模型跑 prompt 审查，而是通过纯文本 AST 遍历和正则逐行扫描物理文件，一经匹配立即非零退出。在 ADR 文档体系中（.agents/notes/），状态流转（proposed / implemented / archived）直接体现为物理目录位置；任何行为变更必须在同提交中更新对应路径下的物理影子，CI 仅校验文件树与路径有效性，绝不交由 LLM 做主观判断。

3. 不变量经济原理（Invariant Economy）

架构质量并不取决于写了多少页架构文档，而是取决于不变量的强度乘以捍卫者的机械程度。在 DSH 的工程哲学中，“没有机械捍卫者的不变量不是架构，只是愿望”。无论是单调递增的架构版本号、强类型 branded id，还是进程内部状态的单一真源，每一个架构不变量都必须由编译器静态类型、加载期拦截器或运行时断言寸步不让地捍卫。

DSH 源码落地：Schema 单调递增与沙箱写域硬阻断 以会话持久化与沙箱治理为例：在 packages/sandbox/sandbox-policy/ 与 packages/sandbox/sandbox-local/ 中，workspace-write 策略在底层直接挂接操作系统的物理沙箱能力（Linux 下的 bwrap / landlock、macOS 下的 Seatbelt / sandbox-exec），越界写调用在系统内核层被 SIGKILL 或 EPERM 掐断，而不是寄希望于模型“自觉遵守目录规则”；在持久化状态层（packages/session），数据演进强制遵循单调递增的 SCHEMA_VERSION，scripts/persistence-changes.ts 在预提交阶段对所有导出的 TypeGraph 提取物理摘要，任何破坏单向版本兼容或未声明迁移的变更，直接中断编译并强行拒绝并入。

二、编写权让渡与裁判权收拢

在经典软件工程中，写代码与审代码的成本基本平衡：人类工程师一天产出几十行经过推敲的核心逻辑，代码审查（Code Review）通过同行肉眼尚能兜底。

但当代码生成被推向秒级、千行量级，甚至在多 Agent 协同并发运转时，人类彻底沦为审阅瓶颈。更致命的是，大模型的“局部合理解释能力”极易制造障眼法。面对这种吞吐量与伪装性的倾轧，软件工程的支点发生了不可逆的位移：

代码编写权可以全面让渡给模型，但裁判权必须死死收拢至确定性的物理世界。

所谓的机器裁判权，绝非让另一个大模型充当“代码法官”（提示词驱动的 LLM-as-judge 本质上是概率系统对概率系统的二次震荡）。真正的裁判权，必须建立在非零即一的物理反馈之上：

严格的静态类型检查与编译期校验（TypeScript / Rust 静态类型断言）；
不可逃逸的原生 Exit Code 与覆盖率物理边界；
测试分权底线：严禁代码编写者（Executor）同时负责验收测试的裁决；验收测试一经冻结，实施者只读不可改。
DSH 源码落地：发布物理门禁与测试分权 在 scripts/verify-public-repository-links.ts、scripts/verify-npm-install-layout.ts 与 scripts/verify-package-meta.ts 中，任何“貌似正确”的提交都会在发布前被原生 Node 进程以 exit 1 拒绝；scripts/verify-package-dependencies.ts 通过 TypeScript 解析器对全部导出面的 import/export 做静态类型校验，绝不依赖模型自我声明。在 .agents/notes/implemented/testing/ 下的测试策略 ADR 中，明确规定了验收测试一经冻结即对实施者只读：Executor 与验收裁决者分离，测试文件任何被顺手“修复”的改动都会在 CI 的 git diff 检测门禁上以非零退出被当场拦截。

三、熵增的本质是契约失控

在长链路任务中，Agent 最容易陷入一种隐秘的破坏：借修复局部 bug 之名，顺手重构非因果关联的代码。

表面上看，它甚至帮你的代码格式化得更工整了；但实际上，它破坏了隐式的上游契约，引入了难以溯源的增量噪音。在 DSH 的工程体系中，对抗这种契约失控依靠的是不可逃逸的物理约束：

写域拓扑隔离（Write Scope Isolation）：在拓扑层面明确声明各任务的写域前缀，越权写入在系统沙箱层面被直接拦截。
同提交契约互锁（Same-Commit Governance）：任何改动了外部行为的提交，必须在同一次提交中同步更新其对应的架构决策记录（ADR）与文档，否则 CI 门禁直接非零退出阻断。
真实断言先决（Receipt-Driven Assertions）：禁止空跑放行与吞异常，每一次交付都必须附带原生命令的物理收据（机器原生 Exit Code 0、确定性的终端输出）。

四、工程师的新角色：确定性系统的架构师

当智能体能够自主装配工具、调度子任务、生成海量代码时，工程师的核心价值不再是熟练背诵 API 语法糖的“代码搬运工”。

未来的核心工程能力，在于如何将模糊的业务意图，编译成机器可裁决的硬边界。谁能定义不可逾越的红线、谁能设计具备物理收据的验收闭环，谁就能在混沌的概率生成海洋中，稳固地打下一座确定性的工程基石。这也正是我们开启【DSH 工程哲学】系列想要与所有开发者共同探讨的核心命题。

五、从原理到实践：软件工程质量元框架 PonyGo

理论如果不变成可复用的机械工具，就依然停留在愿望阶段。为了将 DeepSeek Harness 这套工程质量保证与抗熵增原理沉淀为普适解法，我们构建了 PonyGo——一个专为 AI 辅助编程与工程化治理设计的轻量级元框架（非本站 ponygo.fun，而是单文件、零依赖的通用 CLI 工具）。

在实际落地中，PonyGo 主要承担两类关键使命：

新项目骨架建立：通过标准化的治理脚手架（如 .agents/ 运行时规范与 .meta/ 机器态门禁），让新项目从 Day 1 起就天然具备抗熵增防线与物理门禁；
旧项目评估与查漏补缺：通过自适应巡检机制（ponygo audit / ponygo status），系统体检存量项目的质量断层与契约漂移，生成清晰的治理成熟度阶梯与补齐路径。

值得一提的是，PonyGo 内置了独立的 observe（可观测性） 治理维度（覆盖 metrics、tracing、logs、issues 四维归属与巡检门禁）。在多 Agent 并发与长链路自治场景中，如何让系统行为透明可查、如何对智能体带来的复杂运行时进行无死角度量？工程项目的可观测性，将是我们未来要深入展开的下一个核心话题。

🐙 开源元框架仓库：https://github.com/lanhui100/ponygo