xyzzing/dsh-captain-guard

dsh-captain-guard

用于 DSH Captain 智能体的运行时可切换工具允许列表。

License: MIT
DSH Plugin

为什么需要它

工具增强型 LLM 智能体正越来越多地被授予对高后果操作的访问权限，然而大多数工具选择方法都将每个工具视为暴露出来同样安全。近期关于工具调用智能体能力最小化的研究主张，可见工具集是一个安全控制面：一个被暴露但非必需的高风险工具会扩大攻击面，并使得通过提示注入进行滥用成为可能。工具可见性应被视为临时授权，而非被动能力——即将最小权限原则应用于智能体工具暴露。

这并非理论空谈。面向工具调用智能体的最小权限框架表明，重建权限层级并在工具层面强制执行最小权限，能够限制不可靠 LLM 可能造成的损害。关于多智能体系统委托安全的研究证明，权限在从用户传递到编排器、再到子智能体、再到工具的过程中并不会衰减——一个被攻陷的子智能体会继承完整的授权，而单独获得授权的操作可以组合成被禁止的结果。

dsh-captain-guard 在 DSH 智能体层实现了这一原则。它将 Captain 会话的可见工具集锁定为只读允许列表，因此即使 Captain 被提示注入、混淆代理攻击或推理漂移所攻陷，那些会修改状态的工具根本不会出现在它的目录中。

角色分离的理由

Captain/Coder 拓扑并非随意设计。关于面向语言模型智能体的自适应对话内团队构建的研究表明，角色专门化的智能体显著优于通用型单智能体方法。面向智能体团队的治理框架描述了同样的模式：Captain 决定哪个角色应当为某项任务进行读取、实现、验证、审查或汇集证据——而这种角色分离减少了单智能体的漂移。

同一批文献确立了本插件所执行的最小权限执行模型：团队智能体按角色扩展，而不是通过赋予每个工作者更广泛的权限来扩展。权限保持角色范围限定。Reviewer 可以在不持有 file.write 的情况下检查草稿；Evidence Collector 可以在不持有 git.write 的情况下汇总产物。

为什么该防护可在运行时切换
静态权限是一种已知的失效模式。《关于有界智能体的工作》指出，在会话开始时，智能体的权限被设定，但此后保持静态，每个请求都被独立评估，而不考虑先前的操作。运行时状态文件使操作者能够在不重启 DSH 的情况下撤销或授予该防护——当你正处于调查过程中，需要为单个会话扩大或缩小工具范围时，这一点很重要。

它的作用

当 DSH 创建智能体时，dsh-captain-guard 会检查该智能体的会话头是否声明了 agentPreset: captain。如果是，该插件会应用带有固定允许列表的 tools.restrict({ allow })，屏蔽该智能体作用域上所有其他继承的工具。

Worker、辅助智能体和标准会话不受影响。只有 Captain 会看到缩减后的目录。

┌──────────────────────────────────────────────────┐
│  Captain 会话 (preset: "captain")                │
│  可见工具: 12                                     │
│  ├── graft_map, graft_skeleton, graft_ask        │
│  ├── fs_read_range                                │
│  └── agent_teams_* (仅协调)                       │
│                                                   │
│  不可见: fs_write, bash, str_replace_editor       │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│  Worker 会话 (preset: "standard")                │
│  可见工具: 全部 27 个                             │
│  不受此插件影响                                   │
└──────────────────────────────────────────────────┘

安装

从 GitHub 安装（推荐）

固定版本 — 可复现，对供应链友好
dsh plugin --profile web add github:YOUR_USERNAME/dsh-captain-guard#v0.1.0

main 分支最新版 — 仅用于开发
dsh plugin --profile web add github:YOUR_USERNAME/dsh-captain-guard

从 npm 安装（发布后）

dsh plugin --profile web add dsh-captain-guard

前置条件

你需要一个名为 captain 的智能体预设。通过复制内置的 standard 预设来创建一个：

BASE="$HOME/.npm-global/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-agent-presets/presets"
mkdir -p ~/.dsh/.agent-presets/captain
cp "$BASE/standard/agent.cordis.yml" ~/.dsh/.agent-presets/captain/agent.cordis.yml

cat > ~/.dsh/.agent-presets/captain/preset.yml  ~/.dsh/captain-guard.state

开启防护
echo on  > ~/.dsh/captain-guard.state

重置为配置默认值
rm ~/.dsh/captain-guard.state

Shell 别名

alias captain-guard-on='echo on  > ~/.dsh/captain-guard.state && echo "captain-guard: ON"'
alias captain-guard-off='echo off > ~/.dsh/captain-guard.state && echo "captain-guard: OFF"'
alias captain-guard-status='cat ~/.dsh/captain-guard.state 2>/dev/null || echo "config default"'

状态文件优先于配置字段。这让你可以在运维层面覆盖每个 profile 的配置，而无需编辑 YAML。

设计决策及其原因

这个插件中的每一个选择都对应着 agent 安全文献中记录的一种失败模式或实证结果。

为什么限制工具目录，而不是在运行时过滤调用

大多数先前的工作通过相关性或效率来评估工具选择，展示名称或 schema 与请求匹配的工具。但这把所有工具都视为同等安全地展示：一个只读的搜索工具和一个不可逆的 delete_file 或 transfer_funds 工具会被同一标准过滤。

运行时过滤——在工具调用发出时检查并拒绝危险调用——有一个根本问题：模型仍然看见该工具，提示注入仍然可以尝试调用它。更安全的方法，也是本插件采用的方法，是将该工具从可见集合中完全移除，除非它既位于通往目标的最小因果路径上，又受一个已满足的授权前置条件所约束。

Captain 完成其工作从不需要 fs_write。因此 fs_write 不应存在于 Captain 的目录中。不是“被调用时拒绝”——而是不存在。

为什么 allowlist 是固定常量，而不是启发式规则

通用最小权限框架会重建反映工具调用之间关系的权限层级，并将其与移动端风格的权限模型相结合。对于通用 agent 平台来说，这是正确的设计，因为在那里工具是无界的且由用户定义。
DSH 的 Captain 角色并非通用角色。它只有一项职责：规划、分解、委派和审查。它所需的工具是预先已知的，并且不会因任务而变化。固定的允许列表既比重建的层级结构更简单，也更严格，因为不存在可能出错的重建步骤。

为什么允许列表是只读的

Captain 的严格限制——绝不编写实现逻辑，绝不编辑源文件——之所以存在，是因为按角色分离的编排通过将狭窄的只读、验证或审查任务路由到更窄的角色提示词或更廉价的模型层级，减少了不必要的 token 暴露。

这就是上下文屏蔽原则：通过禁止 Captain 进行代码编辑和整文件读取，提示词 token 的增长保持线性而非指数级。Captain 负责派发；Coder 负责执行。Captain 花在阅读源代码上的每一个 token，都是没有花在规划上的 token。

为什么 worker 的 allowed_tools 比 Captain 的更重要

委派安全研究证明了智能体主体链的爆炸半径单调性和组合健全性：权限在从编排器传递到子智能体再到工具的过程中不会衰减。如果 Captain 拥有 fs_write 并委派给 worker，worker 就会继承它。如果 worker 直接拥有 fs_write，那么 Captain 的限制就形同虚设。

这就是为什么该插件在工具目录层面对两个角色都进行限制，而不仅仅是在调用过滤层面。Captain 的允许列表由该插件强制执行；worker 的允许列表由 dsh-agent-teams 配置强制执行。二者共同形成闭环。

为什么需要确定性验证（test_command 契约）

Captain 的派发契约要求每个任务都指定一个 worker 必须执行的 test_command。这不是官僚主义——而是确定性门禁模式。

近期关于确定性门禁的测量工作报告称，在零额外模型调用的情况下，智能体基准测试取得了显著改进：门禁不增加推理成本，因为其运行时仅限于确定性读取和谓词求值。只有当行动前预先注册的预测与代码观察结果相匹配时，一项主张才会被采纳。

test_command 就是那个预测。worker 不执行它就无法将任务标记为完成。

为什么守卫针对的是预设，而不是角色

该插件通过读取 agent.session.header.agentPreset 来检测 Captain。这与基于角色的编排用来按角色路由任务的身份信号相同：Captain 决定哪个角色应该为任务读取、实现、验证、审查、总结或汇集证据。

使用预设名称而非运行时角色标志，意味着该守卫是声明式且可检查的。仅从会话头就能看出适用哪条策略。没有隐藏状态，没有注册步骤，也不存在角色分配与策略应用之间发生竞态条件的可能。
为什么需要运行时状态文件

对静态会话权限的批评——即在会话开始时设置智能体的权限，但这些权限随后保持不变——对于默认情况是正确的，但对于实际操作情况则不然。有时你确实希望在调查过程中扩大工具范围，或者在怀疑遭到入侵后缩小范围。

一个基于文件的开关，并在下一次创建智能体时立即生效，是最小可行的解决方案。它不需要重启 DSH，不需要编辑配置，也不需要与 WebUI 交互。操作员的 shell 就是控制平面。

为什么单块 GPU 需要更小的上下文窗口

本插件不管理上下文，但它存在于一个必须管理上下文的栈中。在 24 GB 显卡上运行 27B 模型时，KV 缓存是约束瓶颈。针对多智能体系统以 KV 缓存为中心的 serving 的研究表明，空间争用会导致关键智能体的缓存被驱逐，并且在 GPU 显存有限的情况下，仅靠前缀缓存是不够的。

应对措施是将上下文窗口限制在硬件实际能够维持的数值——32k，而不是 98k——并限制进入窗口的内容。Graft 处理后半部分；本插件处理前半部分，通过确保 Captain 永远不会将源文件拉入自己的上下文。

为什么 max_parallel_workers: 1

同样是 KV 缓存的经济学。在单块 GPU 上运行两个并发 worker 意味着两个 KV 缓存争夺同一块 VRAM，当缓存溢出到主机内存时，解码步骤受限于跨互连传输的数据量。一次只运行一个 worker 可以让缓存保持常驻，并使 token 生成速度保持在峰值。

为什么 agent_teams_ 工具在允许列表中

Captain 的职责是协调。移除协调工具会使这一限制自相矛盾——Captain 将无法派发任务、检查状态或接收结果。允许列表不是“尽可能少的工具”；而是“该角色实际需要的工具，不多不少”。这就是最小权限原则：一个已暴露但不必要的高风险工具会扩大攻击面。协调工具是必要的。写入工具则不是。

验证

安装并重启 DSH 后，检查启动日志：

timeout --kill-after=3s 10 dsh --profile web --no-open 2>&1 | grep -i captain-guard

预期输出：

[captain-guard] captain-guard loaded {"defaultEnabled":true,"currentState":"ON","stateSource":"config","captainPreset":"captain","allowCount":12}
[captain-guard] not the captain — skipping {"sessionId":"session-...","reason":"preset=\"standard\" (want \"captain\")"}

第二行是正确行为——辅助智能体在 standard 下运行，而不是 captain，因此守卫会跳过它们。

要验证强制执行，请使用 Captain (Read-Only) 预设创建一个会话，并观察：

[captain-guard] captain allowlist applied {"sessionId":"session-...","reason":"preset=\"captain\"","allowCount":12}

该行确认允许列表已应用。

兼容性
| DSH 版本 | 状态 |
|-------------|--------|
| 0.1.5-alpha. 及更高版本 | ✅ 已测试 |
| 更早版本 | ⚠️ 未测试 — agentPreset 会话头字段可能不存在 |

该插件要求 agent.session.header.agentPreset 字段已被填充。所有支持 agent 预设的 DSH 版本中都存在该字段。

研究基础

该插件的设计借鉴了以下研究方向。每一项均以标题引用，以便读者直接查找论文。

| 工作 | 相关性 |
|------|-----------|
| Capability Minimization as a Safety Primitive | 将工具可见性视为临时授权；最小权限暴露 |
| MiniScope: A Least Privilege Framework for Authorizing Tool Calling Agents | 权限层级重建；移动端风格的权限模型 |
| Bounded Agents: Delegation Security for Multi-Agent AI Systems | 权限非衰减；爆炸半径单调性；组合健全性 |
| Adaptive In-conversation Team Building for Language Model Agents（Captain Agent） | 队长-工作者拓扑；角色专业化优于通用型 agent |
| Deterministic gates for agent verification（reason-less-verify-more 模式） | 零模型调用验证；预测预注册 |
| The LLM Proposes, the Executive Disposes | 确定性执行器掌握信念；结构化验证 |
| Team Agents and Captain-style orchestration | 角色范围权限；最小权限执行模型 |
| KV-cache-centric serving for multi-agent systems（TokenCake 及相关工作） | KV 缓存空间争用；单 GPU 并发限制 |
| KVFlow: Efficient Prefix Caching for Multi-Agent Workflows | 在有限 GPU 内存下前缀缓存不足 |

如需添加具体 arXiv ID，请在发布前于 https://arxiv.org/abs/ 逐一核实。

常见问题

该插件能防止提示注入吗？

不能。它限制的是成功注入的爆炸半径。委托安全方面的研究指出，提示注入只有在 agent 拥有执行此类操作的权限时才会构成风险。该插件移除了这种权限。模型仍可能被操纵；它只是无法通过变更类工具将这种操纵付诸行动。

这会取代 dsh-agent-teams 的工作者允许列表吗？

不会。二者是互补的。该插件限制的是队长。agent-teams 配置限制的是工作者。组合健全性要求两者兼备：只有当限制集覆盖了权限可以被行使的每一条路径时，该限制集才是健全的。

如果队长没有使用 captain 预设会怎样？

插件会跳过它。它会记录 not the captain — skipping 以及检测到的预设名称。不会应用任何限制。如果你在本意作为队长的会话中看到这条日志，请检查会话编辑器中的预设选择器。

我可以为特定任务放宽允许列表吗？
编辑 cordis.patch.yml 中的 allowlist 数组并重启 DSH。allowlist 在 agent/created 时求值，因此配置更改会在下一个 agent 上生效。如果你需要按会话的灵活性，请使用运行时状态文件为该会话完全禁用该防护。

为什么不使用 tools.restrict({ deny }) 而不是 { allow }？

拒绝列表要求你枚举每一个危险工具，并且当新增一个工具时会失效开放（fail open）。允许列表要求你枚举安全工具，并且会失效关闭（fail closed）。能力最小化的全部论据在于，一个暴露但不必要的高风险工具会扩大攻击面。失效关闭是正确的默认值。

这能与非 web 配置文件一起使用吗？

可以。设置 DSH_PROFILE 或将 --profile 传递给所有命令。该插件本身与配置文件无关；只有安装路径和配置路径不同。

许可证

MIT。参见 LICENSE。

贡献

欢迎提交 issue 和 PR。如果你要扩展 allowlist 或更改检测逻辑，请在 PR 描述中解释理由——该设计基于上面列出的论文，更改也应如此。