阶段门治理changingwang/dsh-stage-gate

dsh-stage-gate

为 DeepSeek Harness 提供的阶段门（Stage Gate）治理工具。

模型可直接调用的阶段门：创建验收清单、带证据核对、输出清晰的 通过 / 阻塞 结论——为运行多阶段工作的 Agent 提供治理层。状态保存在内存中，按会话隔离。

功能

在 ctx.tools 注册四个工具：

| 工具 | 用途 |
|------|------|
| gate_open(gateId, title, stage?, items) | 创建阶段门，含完整验收清单（状态 open）。 |
| gate_check(gateId, items) | 核对阶段门：每次提交整份验收项（整体替换）；每项 met/unmet/n/a + 可选 evidence。任一 unmet 则阻塞，全部 met/n/a 则通过。 |
| gate_list() | 列出会话中所有阶段门及其生命周期状态。 |
| gate_close(gateId, reason?) | 关闭阶段门（closed）。关闭后拒绝再次 gate_check，除非设置 allowReopen。 |

生命周期

open → in_review → passed   (全部项 met/n/a)
│                  │
│                  └── blocked   (存在 unmet) → (allowReopen) → open
└────────────────────────────→ closed (gate_close)

- 门的 status 是生命周期状态机。
- 最近一次 gate/check 的 conclusion 记录最近一次核对结果。

安装

dsh plugin --profile web add dsh-stage-gate
dsh web

工具即对模型可见。需已配置模型密钥与 DeepSeek provider（参见 DeepSeek Harness Web UI 指南）。

配置

allowReopen（默认 true）：是否允许对 closed 的 gate 再次 gate_check。为 false 时，核对已关闭的 gate 会抛出 Error: gate "" is closed。

在 profile 的 cordis.patch.yml 覆盖：

- id: tool-stage-gate
config:
allowReopen: false

工作原理

架构图

gate 状态保存在内存中，按 Agent 会话隔离（gate_open / gate_check / gate_close 操作以"会话 + gate id"为键的内存 Map）。

本插件刻意不写自定义会话事件（gate/*）。DeepSeek Harness 的会话持久化拒绝重载含"白名单之外事件类型"的日志（除非事件带 ignorable 标记），而 Session.append 无 API 设置该标记——自定义插件事件会导致会话重启后无法加载。详见 docs/BUG-2026-08-17-session-log-pollution.md。

取舍：gate 状态在 harness 重启后重置。这是外部插件在官方开放"下游插件事件注册面"之前的正确代价。

开发

pnpm install
pnpm test       # vitest（14 个测试）
pnpm typecheck  # 严格 tsc
pnpm build      # 产出 lib/

兼容性

- 需要 DeepSeek Harness >=0.1.0-rc.5。
- 仅 Web profile（工具面向模型）。
- gate 状态为内存态，harness 重启后重置（见"工作原理"）。

许可

MIT © 2026 changingwang