插件权限清单 taltara/capmark

capmark

面向 AI 智能体插件的 capability manifest。插件以 Markdown 声明它可以做什么，检查器则据此约束它。

安装插件就是用你的权限运行别人的代码——它可以读取你的文件、花掉你的凭据、访问网络。如今横在你和这一切之间的，只有一份 README 和你自己的阅读理解。扫描器是在事后查找已知的恶意代码。capmark 是另一半：插件事先声明它需要什么，以一种机器可以检查的形式。

capmark: 0.1
plugin: dsh-vision-toolkit

Capabilities

cap
grant fs:read scope=workspace
grant net:fetch

Contracts

cap
never proc:spawn
require approval for fs:read

它首先是 Markdown。一个从未听说过 capmark 的读者仍然能看到一份清晰可读的安全 README——对于不受支持的 manifest 来说，最坏的情况也不过是文档。

让这一切保持诚实的规则

词汇表中的每一项 capability 都必须指明一个真正能阻止它的机制。

这不是风格偏好。DSH discussion #174 记录了一条针对 rm -rf 的 deny 规则被绕过，方法是在同一次运行中先 rm 再 rmdir。模式拒绝的是拼写。capability 拒绝的是结果。

拒绝整个工具不是模式匹配——一旦 bash 被排除在外，你就无法换个说法绕到 bash。所以这里的单位是一组工具名称。任何更细的东西，比如主机允许列表，都只是建议性的，capmark 会明说出来，而不是让它冒充一堵墙：

warning advisory-scope scope on net:fetch is recorded and audited, but
nothing enforces it — do not rely on it as a boundary

一个悄悄夸大自己的权限系统比没有更糟，因为人们会不再阅读代码。

检查一个

npx capmark lint ./CAP.md

退出码 0 表示干净，1 表示有发现，2 表示无法运行。CI 中使用 --json。

没人会向权限系统索要的节省

工具 schema 会在每次请求时重新发送，因此一个智能体可能永远不会调用的工具，会在每个会话的每一轮都被付费。manifest 已经说明了哪些是这类工具，而 tools.restrict() 恰好接受由此得出的掩码。

针对一个已启动的 @deepseek-ai/dsh 0.1.0-rc.7 web profile 测量——schema 是从运行中的注册表捕获的真实数据，而非估算。又针对 0.1.1-rc.2 重新核对过，其中 standard、code 和 cordis 组合携带相同的行，因此这些数字仍然成立：

在 0.1.1-rc.2 上：

| preset | tools | schema bytes | with a fs:read + net:fetch manifest | cut |
| standard (default) | 25 | 25,965 | 5 tools, 3,122 B | 88.0% |
| code | 26 | 26,908 | 6 tools, 4,065 B | 84.9% |
| cordis | 32 | 33,453 | 5 tools, 3,122 B | 90.7% |

在 0.1.0-rc.7 上：

| preset | tools | schema bytes | with a fs:read + net:fetch manifest | cut |
| standard（默认） | 25 | 25,567 | 5 个工具，2,724 B | 89.3% |
| code | 26 | 26,510 | 6 个工具，3,667 B | 86.2% |
| cordis | 32 | 33,055 | 5 个工具，2,724 B | 91.8% |

两者都是实时捕获。版本不同是因为五个工具包编辑了它们的描述，而工具 schema 主要就是它的描述——比较包源码在此处预测没有变化，而启动每个版本后显示并非如此。

如实解读：那是工具负载，不是整个请求，而且它适用于一个真正限定在其所声明范围内的 agent——把一个通用 agent 遮蔽到只剩一个插件的授权会使其失效，这就是为什么该报告拒绝给一个不留下任何可调用内容的遮蔽打分。我们不声称延迟，因为我们没有测量延迟。参见基准测试以复现它。

code 行保留六个工具而非五个，因为 run_code 无法被遮蔽：注册表在限制应用之后会重新添加 Code Mode 传输，而且如果你命名它，tools.restrict() 会抛出异常。执行不受影响——子分派仍然通过策略瀑布——但负载保留了它，数字也如实反映。我们通过遮蔽一个实时 harness 发现了这一点；论文中的计算曾声称 89.7%。

状态

早期。已针对 @deepseek-ai/dsh 0.1.0-rc.7 和 0.1.1-rc.2 验证。检查所依赖的三个包——dsh-tools、dsh-agent-presets、dsh-scope——在这些版本之间字节完全相同，因此接缝在两处是相同的代码。0.1.1-rc.2 增加了一个工具包，它注册了一个词汇表已覆盖的名称。

词汇表包含十四种能力，每种都绑定到从启动的 @deepseek-ai/dsh profile 捕获的工具名称，而非从文档读取——其中两个（code:run、workflow:run）之所以存在，是因为测量发现了文档从未提及的工具。
格式版本 0.1；预计它会变动。

- packages/capmark — 解析器、linter、词汇表、工具遮蔽编译器、CLI。零依赖。
- packages/gate — dsh-capmark-gate，DeepSeek Harness 的参考执行器（readme）
- packages/probe — 测量工具；针对真实 profile 启动以捕获实时工具 schema。不随附发布。

执行

packages/gate 让一个实时 agent 遵守 manifest。在启动的 rc.7 harness 上测量，manifest 授予 fs:read 并禁止 proc:spawn：

tools visible: 25 -> 4
bash deny - reader declares never proc:spawn, and bash is part of it
write deny - reader declares no capability covering write
read allow

它不会沙箱化插件自身的代码——apply() 在任何工具调用存在之前就以完整 Node 权限在进程内运行。manifest 管辖的是一个 agent 可以调用什么。这一限制在 gate 的 readme 中说明，而不是留给别人去发现。

开发

pnpm install
pnpm test
pnpm typecheck
pnpm lint

许可证

MIT。参见 LICENSE。