DeepSeek Harness 质量门禁体系解析用可机械验证的命令取代行文约定【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harnessgh_mirrors/de/deepseek-harness项目口号 Everything is a Plugin是一个主要交由 coding agent 开发的插件化 Agent 框架仓库。为了让数以百计的贡献变更在智能体轮换、人工评审介入之前就保持统一质量它建立了一套「机械质量门禁」mechanical quality gates体系每一条可机械检查的 AGENTS.md 承诺都对应一个以非零状态退出的命令。本篇文章以仓库中的实现记录 2026-06-11-quality-gates.md 为核心骨架结合 lefthook.yml、.oxlintrc.json、tsconfig.base.json、vitest.config.ts 等仓库内真实配置完整剖析这套门禁的组成、分工与演进。读完你将掌握为什么 gate 优于 prose、每道门禁的命令与配置细节、钩子与 CI 如何分工以及覆盖率为 100% 之后变异测试如何成为下一步对策。一、为什么选择「机械门禁」而不是「行文约定」1.1 背景coding agent 主导的开发模式仓库的开发主要由 coding agent 完成。原文记录指出一个关键判断与行文约定相比agent 遵守强制门禁的可靠性要高得多而当劳动由 agent 承担时「工作量大」也不再构成拒绝增加检查的合理成本论据。1.2 触发决策的早期证据文档记录了推动这一决策的真实事故未通过类型检查的测试被提交进了仓库——因为 vitest 本身不做类型检查vitest run只执行测试不校验类型这类问题只在后续人工评审中才被发现。这一案例说明仅靠「约定」无法阻止低成本错误必须把检查做成「不通过就退出非零」的硬性命令。1.3 核心决策每条可机械检查的 AGENTS.md 承诺都有一个以非零状态退出的命令。CI 执行完整集合而 Git 钩子将延迟预算留给可低成本发现的本地缺陷。这是一条「分层防线」设计本地钩子抓廉价缺陷CI 抓穷举违规。仓库根目录的 AGENTS.md 声明开发约束而这些约束的每一条都落在一个可执行、可验证、会失败的命令上。二、门禁全景六类机械检查原文档列举了六类核心门禁我们逐一结合仓库配置还原其真实形态。2.1 最严格 TypeScriptnoUncheckedIndexedAccess与exactOptionalPropertyTypes仓库在 tsconfig.base.json 中开启{ compilerOptions: { strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true } }noUncheckedIndexedAccess任何索引访问arr[i]、obj[key]的结果类型都自动带上undefined迫使开发者显式处理越界与缺键exactOptionalPropertyTypes可选属性的值一旦写入类型必须与声明完全一致禁止把undefined偷偷塞进可选字段。值得注意的分层设计文档明确记录示例、测试和脚本通过根目录 no-emittsconfig.json在 CI 中做类型检查而包/vendor 代码保持在各自 project-reference 边界之后。也就是说检查范围与编译范围刻意分离——CI 的typecheck命令见 package.json 中typecheck: npm run build:lib:host npm run typecheck:contracts-ready先准备生成的 Host Typert 契约再执行tsc -b tsconfig.client.json增量检查。2.2 Oxlint类型感知 lint 风格规则 文件内重复逻辑仓库用 Oxlint 取代了原先的 ESLint 体系。根目录 .oxlintrc.json 是权威配置关键点{ options: { reportUnusedDisableDirectives: warn, typeAware: true }, categories: { correctness: off } }typeAware: true启用oxlint-tsgolint后端做逐文件 TypeScript 项目发现包源码用包自身项目Host 测试与 website 用tsconfig.host.jsonClient 测试用tsconfig.client.json显式关闭 broad category、改为显式列出迁移自 strict-type-checked preset 的规则typescript/no-floating-promises、typescript/no-unsafe-*系列、typescript/switch-exhaustiveness-check等避免上游分类内容漂移改变门禁语义通过 jsPlugins 兼容层继续执行stylistic/eslint-plugin缩进 2、单引号、无分号、max-len: 140仅校验不自动修与eslint-plugin-sonarjsno-identical-functions、no-identical-conditions等文件内重复逻辑检查vendor/**、native/**、**/*.js、**/*.config.ts被排除——vendored 代码保留上游风格不在门禁范围内。2.3 jscpd跨文件克隆检测.jscpd.json 配置{ minTokens: 60, minLines: 6, mode: mild, pattern: **/*.{ts,tsx}, ignore: [**/tests/**, **/tsdown.config.ts], ignorePattern: [(?s)/\\* jscpd:ignore-start \\*/.*?/\\* jscpd:ignore-end \\*/], exitCode: 1 }它检测包的生产 TypeScript 与仓库脚本中的跨文件克隆minTokens: 60/minLines: 6控制灵敏度刻意并行实现的代码可以通过窄范围的/* jscpd:ignore-start */ ... /* jscpd:ignore-end */源码区间例外声明文档强调这是「记录在案的例外」而非默认放行。触发命令为pnpm run duplicationjscpd --config .jscpd.json packages scripts。2.4 按文件 100% 覆盖率v8vitest.config.ts 中coverage: { provider: v8, include: [packages/*/*/src/**/*.{ts,tsx}], exclude: [ packages/*/*/src/types.ts, packages/*/*/src/bin.ts, packages/*/*/src/worker.ts, // ... ], }覆盖范围是packages/*/*/src所有包的生产源码按文件 100%纯类型文件types.ts、自执行入口bin.ts/worker.ts等不参与统计并明确写入 exclude 理由不可达的防御性守卫使用/* v8 ignore */并注明理由而不是删除——这保留了防御性编程的价值同时保持门禁可满足后续还演化出覆盖率分区test:coverage:partitioned→scripts/run-coverage-partitions.ts与重套件豁免scripts/coverage-exempt.ts可参见 coverage-exempt.ts。2.5 knip / publint / workspace 约束 / NodeNext 消费方类型检查knip死代码/死依赖knip --treat-config-hints-as-errors把配置提示也视为错误publint包正确性通过 scripts/publint-all.ts 对全部待发布包做一致性校验workspace 约束来自 pnpm workspace 规则包必须 private、cordis 依赖必须是 peer dev、版本统一、输出必须 ESM——对应 check-workspace-constraints.tsNodeNext 消费方类型检查对构建出的包声明.d.ts按 NodeNext 模块解析做一遍消费方视角的 typecheck确保发布后的类型在真实 Node 环境下可用对应 verify-node-next-types.ts 与 CI 的check:ci:consumers通道。2.6 统一调度器scripts/run-gates.ts全部门禁通过 scripts/run-gates.ts 统一调度它支持多种模式源码中的GateMode联合类型ci-primary、ci-linux-primary、ci-static、ci-coverage、ci-snapshot、ci-artifacts、ci-consumers、check-all等。开发者可通过pnpm check:alltsx scripts/run-gates.ts check-all一次性本地排练完整门禁矩阵CI 通过check:ci系列命令选取不同子集。三、Git 钩子与 CI 的分工含演进3.1 原始设计钩子/CI 对称原文档的初始设计是「钩子与 CI 对称」钩子做本地快速子集CI 做穷举全集。注意原文档开头已声明这套钩子/CI 对称设计已由 快速本地 Git 钩子 取代但 CI 作为穷举执行路径的地位始终保留。快速钩子决策的核心论点是agent 在提交前已经运行过针对其变更的测试与检查而 push 与 CI 会重复更广的子集——因此完整 push 前套件只是延迟发布、放大无关抖动而 CI 又会立刻重跑完整矩阵。3.2 当前 lefthook 配置本地检查点lefthook.yml 是当前生效的本地防线安装方式node scripts/install-lefthook.mjspostinstall 自动执行pre-commit顺序执行translation pairing (staged records)对暂存的*.i18n.yaml跑verify-translation-pairing.ts --cached双语配对检查archived agent notes归档笔记格式校验lint (staged)用 .oxlintrc.staged.json继承主配置但typeAware: false即不加载项目做类型感知对暂存的*.{ts,tsx,mts,cts,mjs}跑scripts/run-oxlint.ts --fix并设置stage_fixed: true自动重新暂存安全修复带一次有界重试见 oxlint-only-fix-workflowthird-party notices (staged)依赖变更时自动重新生成 THIRD_PARTY_NOTICES.md生成而非拒绝whitespace (staged)git diff --cached --check拒绝已暂存的空白错误vendor manifest guardscripts/check-vendor-manifest.sh校验 vendored 源码元数据。pre-push只跑pnpm run typecheck——先准备生成的 Host Typert 契约再做 Client 增量类型检查。3.3 明确不放进钩子的内容快速钩子决策明确pre-commit 不跑类型分析、测试、快照、文档检查、构建与包卫生pre-push 只增加 typecheck 必需的 Host 契约构建。完整本地排练保留为显式请求pnpm check:all、CI 诊断或仓库级大变更时才做。这就是「本地低成本缺陷 CI 穷举」的最终形态。3.4 CI 完整矩阵CI.github/workflows/ci.yml在Node 22.19 与 26matrix22.19/26均 ubuntu-latestfail-fast: false上运行完整门禁矩阵并对构建产物执行冒烟测试覆盖六个入口路径入口说明Headless无 UI 的 Agent 运行入口TUI终端交互界面入口ACPAgent Client Protocol 入口见 packages/acpJSON-RPC远程调用入口见 packages/api/remotesworkflow工作流执行入口code-runtime代码运行时入口见 packages/code-runtime此外还有 Node 兼容性冒烟通道check:node-compat与 ci-master.yml 等主分支通道。仓库engines声明为^22.19.0 || 24.0.0见 package.json与 CI 矩阵一致。四、后果与代价门禁本身的自我演化4.1 正面收益约定不随 agent 更替而失效文档原文「Conventions survive agent turnover」——每个新 agent 都会撞上同样的机械失败而不是依赖阅读习惯缺陷分层捕获可低成本发现的 commit/push 缺陷在本地失败穷举违规在 CI 失败门禁即代码所有门禁配置都像普通代码一样接受评审The gates themselves are code to maintain; config changes are reviewed like any change。4.2 已知代价与对策100% 覆盖率的反噬文档坦诚记录了一个负面效应100% 覆盖率压力可能催生无断言的测试——测试跑到了每一行却没有断言来证明「这一行错了会被发现」。为此仓库提出变异测试提案status: proposed用 Stryker 的 vitest-runner 在packages/*/src上注入故意缺陷衡量测试套件能否「杀死」变异体计划 PR 级增量运行 夜间全量运行变异分数像覆盖率一样只升不降ratchet 策略行为保持等价equivalent mutant的变异体仿照/* v8 ignore */政策带理由地标注排除。这形成了「机械门禁 → 覆盖率 → 变异测试」的完整质量闭环演进链。五、给开发者的操作速查在本地仓库中你可以通过以下命令直接体验这套门禁均为只读验证不会修改仓库# 本地钩子安装postinstall 已自动执行过 node scripts/install-lefthook.mjs # 单条门禁命令 pnpm typecheck # 构建 Host 契约 tsc -b tsconfig.client.json pnpm lint # 准备契约后跑类型感知 Oxlint pnpm duplication # jscpd 跨文件克隆检测 pnpm test:coverage # vitest v8 按文件 100% 覆盖 pnpm knip # 死代码 / 死依赖 pnpm publint # 包发布正确性 # 完整本地排练贡献者命令 pnpm check:all # tsx scripts/run-gates.ts check-all门禁配置/脚本捕获目标严格 TStsconfig.base.json索引访问未定义、可选属性类型污染Oxlint.oxlintrc.json类型不安全、风格、文件内重复逻辑jscpd.jscpd.json跨文件克隆覆盖率 v8vitest.config.ts未执行的源码行knip / publintpackage.json死代码、发布包缺陷钩子lefthook.yml暂存区语法/风格/空白/元数据 push 类型CI 矩阵.github/workflows/ci.yml穷举全集 六入口构建冒烟总结DeepSeek Harness 的质量门禁体系回答了一个根本问题当代码主要由 agent 编写时如何保证质量不随写代码的人或 agent更换而波动。答案是把它从「应该做」变成「必须通过」——每一条 AGENTS.md 承诺都对应一个退出非零的命令本地钩子用最低延迟拦截廉价缺陷CI 用完整矩阵兜底穷举违规而门禁自身的配置也纳入同样的评审与演化流程。这套「机械门禁取代行文约定」的方法论对任何重度依赖 agent 协作的开源仓库都具有直接的借鉴价值。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考