完工门禁 AGSQ11/dsh-completion-gate

dsh-completion-gate

Completion Gate 是 DeepSeek Harness 插件，用来阻止编码智能体在任务有改动后顺利收尾——除非有证据表明工作确实已经就绪。

它把两道相关的防线合在一起：

1. 提前停止防护 —— 如果模型自然停下，而它自己最新的输出又明确说还有活没干完，插件就会安排一轮新的 DSH 后续回合，把没做完的任务接着做下去。
2. 生产就绪门禁 —— 代码一旦有改动，根智能体必须先给出机器证据和一份结构化的最终审查，这一回合才允许正常结束。

目标不是让模型嘴上说测试通过了，而是让 DSH 真正跑起可用的检查，把结果绑定到当前仓库状态上，并拒绝过期或不完整的完成证据。

为什么要有这个插件

LLM 编码智能体经常停在这几种状态：

"Now I need to inspect the call site..."
→ tool call
→ reasoning
→ model naturally stops

或者：

"Implemented. Looks good."

其实根本没跑过仓库的测试、构建、lint、类型检查，也没逐个看过改动过的文件。

Completion Gate 针对这些失败模式，在宿主侧加了一道边界。

Agent works
│
├── model stops while clearly unfinished
│ └── Premature Stop Guard → continue
│
└── model appears genuinely finished
│
└── Completion Gate
├── repository changed?
├── tests
├── build
├── lint
├── typecheck
├── TODO/FIXME regression scan
├── security regression tripwires
├── changed-file review
└── acceptance criteria → evidence
│
PASS ─┴─ BLOCK

核心行为

1. 提前停止防护

模型自然停下、且没有任何工具调用或排队中的续接让这一回合继续存活时，DSH 会触发 agent/turn-stopping。

Completion Gate 会检查最新一回合，寻找模型自己说还有活没干完的强证据，比如：

- Now I need to inspect...
- Next I will run...
- I still need to...
- Let me trace...
- ...and in parallel...
- 工具操作之后只有推理输出，没有面向用户的完成说明

一旦检测到，插件就排队一个唤醒用的 agent.followup()，开启新一轮，内容类似：

PREMATURE STOP RECOVERY:
Continue the unfinished task.
Execute the pending investigation or implementation now.
Do not summarize or claim completion yet.

恢复链由 prematureStopMaxContinuations 限制次数，所以反复出现的提前停止或空恢复回合不会造成无限后续循环。

像 Let me know if you want changes 这类泛泛的客套话，不算未完成的工作。

2. 根智能体的完成裁决权

默认情况下：

gateSubagents: false
只有根智能体才拥有最终的生产就绪判定权。派生出的 DSH 子代理可以正常完成各自被委派的任务。

使用自主编排、Phoenix/model 故障转移、AI Council、评审器或大型子代理团队时，推荐采用这套设置。根智能体仍然负责整合各项工作，并通过最终关卡。

如果某个项目确实需要，你可以在控制中心显式启用子代理门控。

3. 工作区指纹

完成证据与当前仓库状态的 SHA-256 指纹绑定。

指纹涵盖：

- 会话基线 Git HEAD；
- 智能体会话期间创建的提交；
- 已暂存的改动；
- 未暂存的改动；
- 未跟踪的文件。

这一点很关键，因为干净的工作树并不能证明智能体没有改动：它可能早已把改动提交了。

如果代码在检查或证明通过之后又发生变化，指纹就会改变，旧证据随之失效。

4. 机器证据

Completion Gate 能自动识别并执行常见的项目检查。

| 生态 | 识别 / 检查 |
| Node.js | test、build、lint、typecheck 等 package scripts |
| npm / pnpm / Yarn / Bun | 根据项目 lockfile 选择包管理器 |
| Python | 存在测试/配置时运行 pytest；配置了 Ruff 和 Mypy 时运行它们 |
| Go | go test ./...、go vet ./... |
| Rust | cargo test --all-targets、cargo check --all-targets |
| Composer / PHP | 存在 scripts 时运行 composer test、composer lint |
| 任意项目 | 操作者自定义检查 |

启用 requireTests 后，未检测到可执行测试命令的项目会被视为阻塞，而不是悄悄当作已测试。

机器检查成功的结果会按精确的工作区指纹缓存。这样就不会因为智能体还需要多跑一轮才能提交最终评审，而重跑一套十分钟的测试。

5. 新增代码绊线

关卡可以检查新增的行里是否出现：

TODO
FIXME
HACK
XXX

以及一组刻意收窄的、明显的安全回归模式，例如：

- 疑似硬编码凭据；
- 关闭 TLS 证书校验；
- eval(...) / 动态构造 Function；
- chmod 777；
- 需要人工复核的 shell 执行启用；
- 原始 HTML 注入面。

这是回归绊线，不能替代专门的 SAST/安全工具。

6. 完成证明

机器检查无法证明每一条需求。最终完成之前，可以要求智能体调用 completion_gate 工具，并提交与当前工作区指纹绑定的证明。

示例：

{
"action": "attest",
"reviewed_files": [
"src/engine.ts",
"tests/engine.test.ts"
],
"review_summary": "Reviewed the complete diff, error paths, state transitions and backwards compatibility.",
"acceptance_criteria": [
{
"criterion": "Risk sizing uses ATR",
"evidence": "单元测试覆盖 ATR 推导出的风险仓位计算，完整测试套件通过。"
},
{
"criterion": "现有行为保持兼容", "evidence": "回归测试与类型检查通过；已审查改动过的调用点。"
}
],
"unresolved_issues": []
}

严格模式下，门禁会校验：

- 每个改动过的文件都列在 reviewed_files 中；
- 存在改动文件审查摘要；
- 至少提供一条验收标准；
- 每条标准都有具体证据；
- unresolved_issues 为空；
- 证明指纹仍与仓库匹配。

控制中心

打开：

Settings → Completion Gate

控制中心既是运行时仪表盘，也是持久化配置编辑器。

行为

- Enable Completion Gate — 总开关。
- Mode
- Strict：门禁失败会把智能体拉回来，阻止正常收尾。
- Advisory：照常收集证据，但失败不会强制再走一步。
- Gate subagents — 把 DSH 子级／子代理的停止边界也纳入。自治团队建议关闭。
- Premature-stop guard — 对明显还留着待办工作的自然停止，安排新一轮跟进把它捞回来。
- Max recovery follow-ups — 单条连续提前停止恢复链的安全上限。

机器证据

- Auto-detect checks
- Require tests
- Require build when available
- Require lint when available
- Require typecheck when available
- Block new TODO/FIXME markers
- Security regression scan

完成证据

- Require final attestation
- Gate only changed workspaces
- Maximum changed files

执行限制

- Check timeout — 单条命令的最长时间。
- Stored command output — 每项检查最多保留多少条脱敏后的失败输出。

自定义检查

UI 可以添加任意由操作者定义的检查：

Name: integration-tests
Category: test
Command: npm run test:integration
Required: yes

自定义命令在 DSH 主机上的项目工作区里执行。只配置你信得过的命令。

保存设置

Save settings 立即生效，并在 dsh web 重启后依然保留。

配置优先级为：

built-in defaults
↓
profile / cordis.patch.yml configuration
↓
settings saved from the Completion Gate UI

门禁策略一旦变化，缓存的机器证据、证明和操作者覆盖都会被作废。策略刚改过，之前那次 PASS 绝不会被复用。

Reset to profile defaults 会移除保存下来的 UI 覆盖层，立即回到当前 DSH 配置档提供的插件配置。

主机侧设置文件有意不在浏览器 UI 或门禁报告中暴露。

命令

/gate

立即对当前根会话运行门禁。

/gate

想在模型尝试收尾之前先看看准备情况，这条命令很好用。

/gate-status

显示当前会话的最新报告。

/gate-status

/gate-reset

丢弃当前会话缓存的机器证据、证明和操作员覆盖。

/gate-reset

/gate-override <reason>

针对当前工作区指纹的显式操作员覆盖。

/gate-override accepted temporary compatibility risk

如果之后任何文件或提交发生变化，覆盖即失效。

这是给人类操作员用的，不是给智能体留的后门。

智能体工具

插件注册了：

completion_gate

动作：

- run —— 立即执行就绪检查；
- status —— 返回最新/当前报告；
- attest —— 提交最终的变更文件和验收标准审查。

Completion Gate 还会添加一段系统提示词，告诉编码智能体：在声称完成之前，门禁是权威依据。

头部状态

对话头部显示一条紧凑状态：

Gate · ready Gate · 1 blocked Gate · off

这只是操作员摘要。权威结果仍然是绑定工作区的门禁报告。

默认配置

内置的配置档补丁开头是：

- insert:
- id: completion-gate
name: dsh-completion-gate
config:
enabled: true
mode: strict
gateSubagents: false
preventPrematureStops: true
prematureStopMaxContinuations: 3
autoDetectChecks: true
requireTests: true
requireBuildWhenAvailable: true
requireLintWhenAvailable: true
requireTypecheckWhenAvailable: true
blockNewTodos: true
securityScan: true
requireAttestation: true
gateOnlyChangedWorkspaces: true
commandTimeoutMs: 600000
maxOutputChars: 12000
maxChangedFiles: 500
customChecks: []

以上所有内容都可以在控制中心修改。配置档配置仍是基线，Reset to profile defaults 会回到这里。

安装

1. 把源码仓库解压或克隆到一个固定的本地目录。
2. 把该源码目录添加到 DSH Web 配置档。
3. 重启 DSH Web。

以下示例在包含插件源码的父目录中执行：

dsh plugin --profile web add .\dsh-completion-gate
dsh web

然后打开 Settings → Completion Gate，先检查默认值，再决定是否在生产仓库上依赖 strict 模式。

这个插件不需要安装任何依赖。

更新

用更新的源码版本替换插件源码，然后重启 dsh web。

UI 保存的 Completion Gate 设置与插件源码分开存储，所以替换源码目录不会主动重置操作员偏好。如果你想要新的配置档默认值，请使用 Reset to profile defaults。

与模型故障转移 / Phoenix 的交互

Completion Gate 的作用域是会话/工作区，不是模型。

如果某个模型失败：

Model A
↓ 429 / timeout / provider failure
Phoenix / DSH failover
↓
Model B continues same session
↓
Completion Gate still owns the same baseline and workspace evidence

替换模型可以接着做修复，不用重启任务。如果替换模型改了代码，工作区指纹就会变化，过期的 gate 证据自然失效。

建议在自主故障转移/团队编排时设置 gateSubagents: false，这样根级的生产就绪策略就不会无谓地阻塞子任务。

gate 阻塞时会发生什么

严格模式下，DSH 会收到一条类似这样的引导消息：

COMPLETION GATE BLOCKED. Do not claim completion.

- Node test: test failed.
- Changed files not reviewed: src/engine.ts
- Acceptance-criteria evidence is missing.

Fix the failures, review every changed file, then call completion_gate
with action=attest and concrete acceptance-criteria evidence.

智能体从现有任务/工作区状态继续。

重要限制

提前恢复会开启新回合

Premature Stop Guard 有意使用 agent.followup()，而不是 agent.steer()。follow-up 让自然停止的回合先关闭，再立刻用未完成工作的指令唤醒新回合。这样能更好地配合服务商重试/故障转移，也避免在同一回合内做恢复步骤——那种做法会明显注入上下文，然后闲置下来。

实际的 Production Readiness Gate 仍然使用 agent.steer()，因为阻塞失败的就绪检查必须否决当前的自然完成边界。

DSH 在最终停止钩子之前就记录了助手输出

DSH 可能在 agent/turn-stopping 运行之前就记录一条 assistant/message。因此 Completion Gate 能阻止回合关闭并强制再走一步，但无法追溯抹掉不合规模型已经输出的提前结论。

Premature Stop Guard 和系统提示词指令的作用，是让正常路径在任务被视为完成之前继续下去。

测试的好坏取决于项目本身

测试通过不能证明正确。gate 只能证明配置的检查在特定仓库指纹上通过了。

证明是结构化的模型证据

gate 验证证明结构的完整性和新鲜度；它无法从数学上证明 LLM 的语义审查有多深刻。独立审查插件、Council、安全工具和人工审查仍然有价值。

安全扫描有意做得很窄

内置扫描器只捕获明显新增的高风险模式。它不是全面的漏洞扫描器。

自定义检查会执行 shell 命令

自定义检查是在 DSH 主机上由操作者控制的代码执行。对待它要像往 CI 配置里加命令一样谨慎。

自主开发团队的推荐配置

enabled: true
mode: strict
gateSubagents: false
preventPrematureStops: true
prematureStopMaxContinuations: 3
autoDetectChecks: true
requireTests: true
requireBuildWhenAvailable: true
requireLintWhenAvailable: true
requireTypecheckWhenAvailable: true
blockNewTodos: true
securityScan: true
requireAttestation: true
gateOnlyChangedWorkspaces: true

这样既给子代理留出实现自由，也允许模型故障转移，同时在根智能体处保留一道硬性就绪边界。

隐私与安全

- Gate 报告只暴露仓库/工作区的基名，不暴露本地文件系统的绝对路径。
- 捕获到的命令输出会先做净化处理，再保留或展示。
- 存储的失败输出中，常见凭据/token 模式和本地绝对路径都会被脱敏。
- 浏览器设置端点要求同源请求。
- UI 保存的设置持久化在宿主侧；持久化路径本身不会发送到浏览器。
- 模型无法通过 completion_gate 证明工具添加自定义检查命令。

精简的安全模型见 SECURITY.md。

许可证

MIT。见 LICENSE。