工具调用策略 Drifter-yh/dsh-tool-policy

dsh-tool-policy

dsh-tool-policy 是一个 DeepSeek Harness 工具调用策略插件。它会在工具真正执行之前，根据规则决定这次调用是直接允许（allow）、请求人工确认（ask），还是拒绝（deny）。

它提供一个声明式、默认拒绝（deny-by-default）的策略层，覆盖内置工具、第三方工具和 MCP 工具，并复用 Harness 已有的 approval 和 sandbox 机制。它负责单次调用的策略与路由，不是 capability sandbox。

社区插件，与 DeepSeek AI 无隶属关系，也不由其维护。

仓库：Drifter-yh/dsh-tool-policy

为什么需要它

DeepSeek Harness 已经提供了工具执行所需的基础能力：sandbox policy、一次性 approval、协作式 timeout、provider retry、重复调用提醒以及 session telemetry。缺少的是一个由部署方维护的策略层，用同一套规则覆盖所有工具，包括第三方工具和 MCP 工具。

常见用途包括：

- 允许选定的工具命名空间或工具族，例如 read_；
- 对 MCP 或其他外部工具（例如 mcp__）要求人工确认；
- 在匹配到的工具 body 启动之前，拒绝已知的危险命令模式；
- 为无人值守的 agent 或 job 配置默认拒绝（deny-by-default）的工具调用 allowlist；
- 避免把敏感参数值复制到策略反馈消息中。

典型的调用路径如下：

Agent wants to call a tool
v
dsh-tool-policy
+------+------+
allow ask deny
continue Harness stop before
pipeline approval tool body

这个插件不是 audit logger，也不实现 approval；这些扩展点由 Harness 自己负责。

安全模型

插件针对单次工具调用工作。它会在工具 body 运行之前，匹配可观察到的工具名和可选的参数模式：

- Harness sandbox — capability enforcement（能力约束）： 决定 agent 是否根本具备执行某类操作的能力。Harness sandbox 和 runtime isolation 负责约束文件写入或删除、网络访问、进程执行等 capability。
- dsh-tool-policy — per-call policy / routing（单次调用策略 / 路由）： 决定这次已知的工具调用应当允许、拒绝还是升级处理。匹配到 deny 时，只会阻止这次调用执行，不会撤销底层 capability。
- Harness Approval — human escalation verdict（人工升级裁决）： 为被 ask 升级的调用提供一次性人工裁决。

一条匹配 shell 参数模式（例如 rm -rf /foo）的规则，只约束符合该形状的调用。其他工具或命令序列仍可能产生相同效果。因此，tool policy 与 capability sandbox 是互补层；生产部署应将策略路由与限制性 Harness sandbox 结合使用。

它不做什么

dsh-tool-policy 不实现 sandboxing、capability enforcement、shell semantic analysis 或 equivalent-operation detection。deny 让匹配到的调用不可用，但不意味着一般意义上的破坏性行为变得不可能。它不会重写参数，也不会执行工具 body。

安装

[!IMPORTANT]
本项目官方 npm 包为 @drifter-yh/dsh-tool-policy。

npm registry 中未带 scope 的 dsh-tool-policy 由另一个第三方项目维护，并非本仓库发布。

从 npm 安装时请使用 scoped 包名。

已记录的验证基线使用公开的 Harness 0.1.1-rc.2 package line：

pnpm add --save-exact @drifter-yh/dsh-tool-policy @deepseek-ai/cordis@4.0.1 @deepseek-ai/dsh-tools@0.1.1-rc.2

Harness packages 是 peer dependencies，由宿主控制 runtime 版本。@deepseek-ai/schemastery 是插件的普通 runtime dependency。本 package 针对公开 registry artifacts 中的 0.1.1-rc.2 测试。

此示例固定两个直接的 Harness peer 版本，但不能复现完整的 CI lockfile。锁定的开发验证基线见 CONTRIBUTING.md。

从 GitHub 安装

上游 profile-plugin 文档支持直接从 GitHub 安装 TypeScript bundle：

dsh plugin --profile my-profile add github:Drifter-yh/dsh-tool-policy#e6f43c255345a6f6bbab66ee8c053a2e5457e3c7

Git 安装会拉取 source，因此这个 package 的 prepare script 只运行生成 dist/ 所需的独立 tsdown build。如果 pnpm 10 或更新版本报告 prepare script 被阻止，请将 package 加入 profile 的 pnpm-workspace.yaml build allowlist，然后重试：

allowBuilds:
'@drifter-yh/dsh-tool-policy@git+https://github.com/Drifter-yh/dsh-tool-policy.git#e6f43c255345a6f6bbab66ee8c053a2e5457e3c7': true

允许安装时执行代码前，请检查并固定 Git commit。prepare 不会运行测试，也不依赖 DeepSeek Harness checkout。

本地开发请从 clean clone 使用普通的 package-manager 流程：pnpm install。

Harness profile bundle

这个 package 也遵循 Harness 官方 profile-bundle contract：package.json 声明了 dsh.bundle.patch，发布包包含 cordis.patch.yml。将它安装到 profile：

dsh plugin --profile my-profile add @drifter-yh/dsh-tool-policy

安装会激活一个 tool-policy row，初始配置为 defaultDecision: deny 且没有规则。启动 agent 前，在 $DSH_HOME/profiles/my-profile/cordis.patch.yml 中配置该 row：

- id: tool-policy
config:
defaultDecision: deny
rules:
- tool: 'read_'
decision: allow
- tool: 'bash'
decision: ask
reason: 'Shell execution requires approval.'

Harness profile patch 根据 id 定位 row，并替换它的整个 config；请重复写出所有希望保留的配置字段。bundle patch 只是组合层：插件仍然可以作为直接的 Cordis entry 使用。

快速开始

将社区插件直接加入 Cordis composition。这个示例显式使用 deny-by-default，除非其他规则处理，否则只允许匹配 read_ 的工具：

- id: tool-policy
name: '@drifter-yh/dsh-tool-policy'
config:
defaultDecision: deny
rules:
- tool: 'read_'
decision: allow
- tool: 'bash'
decision: ask
reason: 'Shell execution requires approval.'
- tool: 'mcp__'
decision: ask
reason: 'External tool calls require approval.'
- tool: 'delete_'
decision: deny
reason: 'Delete operations are disabled in this deployment.'

插件挂载后，在工具调用层默认采用 fail-closed 行为：默认 decision 是 deny，因此只有显式允许的调用会运行。只有在明确要部署 targeted 或 advisory policy 时，才设置 defaultDecision: allow。

路由预设

两个可选起点会在编译前展开为普通规则：

- read-only：{ tool: 'read_', decision: 'allow' }。
- mcp-approval：{ tool: 'mcp__', decision: 'ask' }。

除非显式设置 defaultDecision，两者都保留默认拒绝。这些规则只匹配名称：名为 read_ 的工具未必真正只读，mcp__ 也不覆盖非 MCP 的外部工具。请检查实际工具并按部署需求调整规则。

preset: mcp-approval
rules: # 首先匹配：覆盖这个工具的预设行为
- tool: mcp__trusted__read
decision: allow
appendRules: # 在预设之后匹配
- tool: read_record
decision: allow

完整顺序是 rules、预设规则、appendRules，第一条匹配规则生效。追加规则不能覆盖之前已匹配的规则。不使用预设时，原有 rules 行为不变。trace 的规则编号对应展开后的顺序。TypeScript 中可通过两个 package 入口导出的 expandPolicy(config) 验证并取得可 JSON 序列化的普通 { defaultDecision, rules }，用于检查或保存；compilePolicy 在求值前展开相同配置。

预设只负责逐次调用路由，不能替代 Harness 沙箱和审批配置。请为 ask 配置 Harness 审批服务及处理器，并使用限制性 Harness 沙箱约束能力。

配置

defaultDecision: deny # deny (default), ask, or allow
trace: false # 通过 Cordis logger 输出不含参数的决策 trace rules: First matching rule wins.
- tool: 'bash'
decision: deny
reason: 'Destructive shell commands are disabled.'
argument:
path: /command
contains: 'rm -rf'

- tool: 'record.update'
decision: deny
reason: 'System records are immutable.'
argument:
path: /scope
equals: system

- tool: 'safe_'
decision: allow

- tool: ''
decision: ask
reason: 'Unlisted tools require approval.'

tool 是带一个通配符 的、锚定完整工具名的模式。其他正则表达式元字符都会按字面处理。argument.path 是指向已解析工具参数的 RFC 6901 JSON Pointer。一个 condition 必须在 equals（JSON scalar equality）和 contains（字符串上的非空 substring）中二选一。规则顺序明确且确定，第一条匹配规则生效。

Decision 的语义如下：

- deny 在工具 body 运行之前返回一个普通的 Harness tool error；
- ask 返回 { kind: 'ask' }，交给 ctx.approval 决定；没有 approval channel 时，Harness 会 fail closed；
- allow 调用 next()，因此不会覆盖之前或之后的 policy listener；
- defaultDecision 只在没有规则匹配时生效。

reason 不会插入调用参数。这可以避免把 secret 或大段参数复制到模型可见的 approval feedback 中。

Policy decision trace

当操作人员需要知道这个插件为什么做出某个决策时，可以显式开启 trace: true：

trace: true
rules:
- tool: 'read_'
decision: allow
- tool: 'bash'
decision: ask
reason: 'Shell execution requires approval.'

插件会通过 Cordis logger 输出一条 info 记录，包含工具名、本插件产生的 decision、匹配规则的编号（从 1 开始；使用 defaultDecision 时为 null），以及 ask 或 deny 使用的配置 reason。记录不会包含已解析的工具参数。trace 默认关闭、采用 best-effort 方式输出，也不替代 Harness 的 session audit event；后续的 policy listener 或单调 tool guard 仍可能让一个 allow 调用最终无法执行。

使用示例

参见可复制的 MCP、文件系统、shell 和无人值守任务示例，其中列出了 sandbox 和审批前提。

架构

flowchart LR
model["Model tool call"] --> logged["tool/call logged"]
logged --> policy["dsh-tool-policy\ntools/pre-execute"]
policy -->|deny| blocked["Tool error\nbody skipped"]
policy -->|ask| approval["ctx.approval\nexisting Harness seam"]
policy -->|allow| guards["Other pre policies\nand monotonic guards"]
approval -->|allowed-once| guards
approval -->|rejected or unavailable| blocked
guards --> execute["tools/execute\nbody\npost-execute"]
execute --> result["tools/result\nthen tool/result"]

插件只使用 inject: ['tools'] 和 ctx.on('tools/pre-execute', ...)。Cordis 负责 listener disposal 和 reload 行为。插件不会 patch ToolRuntime 或 agent-loop。

示例

仓库中已提交的 demo 会通过真正的 Cordis Loader 加载 @deepseek-ai/dsh-system-prompt、@deepseek-ai/dsh-tools、本插件和一个 fixture。它拒绝 delete_record、允许 read_record，并验证被拒绝的 body 从未被调用。

pnpm build
pnpm integration

预期输出包含：

{
"blocked": { "isError": true, "message": "deleting records is disabled in the demo" },
"allowed": { "isError": false, "value": "record:42" },
"executed": 1
}

与 DeepSeek Harness 的兼容性

插件声明的 dsh-tools peer 范围为 >=0.1.0-rc.5 <0.2.0 || 0.1.1-rc.2，Cordis 范围为 >=4.0.1 <5。当前使用公开的 0.1.1-rc.2 registry packages 和上游 tag dsh-v0.1.1-rc.2（commit b150a551b8d465e31e418e1b2eaf5e79bbb7d28e）验证。与 Harness 相关的代码只使用文档化的 Context、tools service 和 tools/pre-execute event。peer 范围不能证明兼容性，也不能检测范围内的 API 漂移。

package 的 dsh.bundle.patch metadata 遵循 Harness profile-bundle specification。cordis.patch.yml 按 module/package name 插入插件，profile composition 会在 profile 自己的 patch 之前应用这一层。bundle 默认 deny 且规则列表为空；运行工具前，请在 profile layer 配置插入的 tool-policy row。

DeepSeek Harness 将 MCP tools 暴露为 mcp__<serverName>__<rawName>，因此 mcp__ 规则可以覆盖完整的 MCP namespace。

当前限制

- 规则是 deployment-global 的；如果不同 agent 需要不同的 policy tree，请使用多个 Cordis context。
- 已记录的 Harness 验证基线是 prerelease 0.1.1-rc.2 registry 依赖集和上游 tag dsh-v0.1.1-rc.2。CI 只测试一组锁定依赖，并未测试 peer range 中的每个版本；显式声明的 0.1.1-rc.2 不包括其他 0.1.1 prerelease。
- 匹配只支持每条规则一个 condition、JSON Pointer scalar equality 或字符串 containment，不实现通用 expression language。
- ask 依赖 Harness approval service 和 answerer。插件不提供 UI，也不会自动批准请求。
- policy feedback 会有意排除参数；操作人员需要在 Harness session 或 telemetry stream 中查看原始工具调用。
- 插件是单次调用的 pre-dispatch policy，不负责 capability enforcement。文件系统、网络和进程隔离应交给 Harness sandbox。

Roadmap

已实现

- [x] 通过 Cordis logger 提供可选、无参数的 policy decision trace

下一步

- [x] 增加可复用的路由策略起点
- [x] 增加可直接复制的 MCP、filesystem 和 unattended-agent 配置 recipes

未来

- [ ] 针对首个稳定版 Harness 0.1 release 验证兼容性，并发布匹配的 package version
- [ ] 如果部署需要时间窗口配额，考虑单独设计、独立作用域的 rate-limit plugin

开发与验证

pnpm install
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build
pnpm integration

纯 matcher 由 unit tests 覆盖，Cordis plugin 通过 ToolRuntime 验证，tests/loader.integration.spec.ts 会启动真实的 Harness Loader composition。

社区状态

这是一个由社区维护的 DeepSeek Harness plugin，不隶属于 DeepSeek AI，也不代表 DeepSeek AI 的立场。

License

MIT