DeepSeek Harness 的 PACT 治理插件

前言¶

DeepSeek Harness（DSH）采用「一切皆插件」的理念，将功能拆分为可插拔模块。当团队需要为智能体开发引入统一治理策略时，DHS 提供的 AgentFactory 与 ReactLoopAgent 足够灵活，但也意味着你需要自行处理策略与执行之间的协调。如果治理逻辑与运行时耦合，后续扩展和审计都会变得困难。

下面介绍 dsh-plugin-pact：一个专注于「决策与执行分离」的治理插件，它接管 AgentFactory 的注册者，但不重写 DSH 的 ReactLoopAgent。PACT 只决定「这一步能不能开始、这个工具能不能执行」，模型调用、工具执行与会话持久化仍由 DSH 完成。

定位与维护者¶

dsh-plugin-pact 是 DeepSeek Harness（DSH）的 PACT 治理插件，由 onlookor 维护，分类为「模型推理」。它不进入任何 Rust workspace，零运行时 npm 依赖，只包含 DSH 侧的插件代码；PACT 引擎与 WASM 宿主在上游仓库。本仓库由 pact-collab 的 plugins/dsh 目录迁出（2026-10-23），运行时行为未改。

安装与启用¶

从 npm 安装：

dsh plugin --profile web add dsh-plugin-pact

直接从 GitHub 安装：

dsh plugin --profile web add github:onlookor/pact-dsh

本地开发（link 安装）：

dsh plugin --profile web add link:/path/to/pact-dsh

安装后，package.json 的 dsh.bundle.patch 会指向 cordis.patch.yml。该 patch 会禁用原始 agent-loop 行，并插入 pact-agent-loop（同一 agentLoop 服务）与 dsh-pact-observe 两行。@deepseek-ai/dsh-agent-loop 为 peer，由 DSH 运行时解析。

检查组合结果应看到 agent-loop 带 disabled: true，并出现 pact-agent-loop：

dsh --profile web --dump-config

注意：

DSH 的 patch 只按 id 覆盖字段，name 仅作一致性校验；不能把 agent-loop 行直接改名为插件模块，否则该 patch 会被跳过。
禁用原行会丢弃其 config；当前 base 模板为 agents: []；若你的 profile 在该行配置了 agents，请写进本插件的 pact-agent-loop 行。
链接安装时 pnpm 会提示 peer 不会从目标 node_modules 解析；DSH 运行时会用安装副本解析 peer，实测可用。

档位与治理范围¶

插件提供两种档位：

档位	行为	阻断
`observe`（缺省）	镜像 `session/event` 到有界缓冲；配置 `mirrorDir` 时追加 JSONL	否
`govern`	`agent/pre-step` 与 `tools/pre-execute` 查询 PACT 门，拒绝返回 `reject` / `deny`	是

只有 agentPreset 以 pact- 开头的 agent 进入治理；其余 agent 原样委托官方 loop。tools/post-execute 与 agent/turn-stopping 只审计；stopOnTermination=true 时 Rule-T 终止后 steer 收尾。

配置¶

配置只从 PACT_DSH_CONFIG 读取：JSON 文件路径或内联 JSON；缺省 observe + fake。

{
  "mode": "govern",
  "backend": "fake",
  "domain": "dsh",
  "defaultParticipant": "agent",
  "presetPrefix": "pact-",
  "participants": { "pact-review": "reviewer" },
  "mirrorDir": "/home/me/.pact/dsh-audit",
  "mirrorLimit": 256,
  "denyTools": ["shell"],
  "stopOnTermination": false,
  "fakeEnabled": true
}

常用配置项说明：

mode=govern 时 failClosed 强制为 true。
backend=wasm 时必须提供 wasmModule。推荐指向上游仓库的组装入口 crates/pact-wasm/js/open-host.js（需先 clone pact-collab），并用 wasmOptions 提供宿主参数：

  {
    "mode": "govern",
    "backend": "wasm",
    "wasmModule": "/home/me/pact-collab/crates/pact-wasm/js/open-host.js",
    "domain": "dsh",
    "wasmOptions": {
      "module": "/tmp/pact-wasm-pkg",
      "storeRoot": "/home/me/.pact/dsh-wasm",
      "declaration": "types { … } rules { … }",
      "ts": "2026-10-23T00:00:00.000Z"
    }
  }

先在上游仓库构建产物：cargo build --locked -p pact-wasm --target wasm32-unknown-unknown --profile wasm-release，再 wasm-bindgen --target nodejs --out-dir /tmp/pact-wasm-pkg target/wasm32-unknown-unknown/wasm-release/pact_wasm.wasm（CLI 版本须与 crate 一致，当前 0.2.127）。wasmOptions 原样透传；产物缺失时治理调用返回 BackendUnavailable（fail-closed）。
- fakeEnabled=false 让假后端对所有参与者返回未启用，用于预演 agent/pre-step 拒绝路径；仅对 backend=fake 生效。
- 非法配置在加载期 fail-fast（PactConfigError）。

后端实现¶

PactBackend 接口包括 enabled(participant, key)、gates、status、seed、produce、consume、close；key = domain/instance。

FakePactBackend：单测/演示用，只模拟插件消费的表面（参与者启用、token 存在性、request_id 幂等），不解释门表达式。
WasmPactBackend：惰性动态导入上游的 openPactHost(options)，适配 pact-wasm 的 PactHost；宿主返回的 enabled 是 Rule-W 可生产选项数组，适配层收窄为布尔（非空即可执行）。

审计与安全¶

只记录 type/seq/工具名/call id；不记录工具参数、结果、源码或用户内容。
mirrorDir 目录 0700、文件 0600；不新增端口、不拉子进程、不联网。
实例键由 session id 消毒为 [A-Za-z0-9_-]{1,128}。
govern 模式 fail-closed：后端不可用、门查询异常都按拒绝处理。

已知限制¶

resume 的钩子在会话发布后安装，恢复后的第一步不受门控。
本轮不做 token 级工具映射（produce/consume 与补偿），也不注册 PACT 原生工具。
依赖 DSH 预发布 API（AgentLoop、AgentFactory、agent/pre-step、tools/pre-execute）；DSH 升级需复核。
已用 @deepseek-ai/dsh@0.2.1-rc.2（developer preview）验证真实装载：--dump-config 显示原行禁用与替代行插入，启动后 ctx.agentLoop 为 PactAgentLoop 且继承官方 AgentLoop。
已在真实 DSH 会话中验证门控（deepseek-official/deepseek-flash）：pact-* 预设下 govern 允许 bash 执行并返回 PACT_TOOL_OK、denyTools 返回 pact: tool denied by policy、fakeEnabled=false 使 agent/pre-step 拒绝并直接结束 turn（无模型请求）。
已用 backend=wasm（wasm-bindgen 0.2.127 产物 + open-host.js）在同一 headless profile 复跑上述三条路径并通过；插件退出时不显式关闭宿主，实例锁文件可能残留，下次打开按 pid 存活检测自动回收。

适用场景与注意¶

适合需要为 DSH 智能体引入统一治理策略的团队。插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。本仓库许可为 MIT。社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。

小结¶

dsh-plugin-pact 在 DSH 生态中提供了一种「决策与执行分离」的治理路径：PACT 负责门控与审计，DSH 负责模型调用与状态持久化。通过 observe 和 govern 档位、fake 和 wasm 后端，你可以先在安全环境内演练，再逐步切换到真实 PACT 策略。如需更详细的规范与实现背景，可参考上游 PACT 仓库的决策 D37 / 需求 FR25（设计 §17、手册 §13）。