装完子智能体提供方却没有工具，第一反应通常是「装坏了」。多数情况下，问题并非安装失败：你查的是包里有什么，而 agent 需要确认的是「本次请求注册了什么」。 两者之间还隔着重启边界与配置层选择。
这里还有一个必须提前说明的坑：官方 CLI 参考与当前提供方 README 对「工具怎么暴露」的描述并不一致。 CLI 参考描述了仅有提供方的组合——需要在复制出的 preset 里单独启用对应工具行，新 agent 才看得到；而当前 Codex 提供方参考说它的 bundle 会插入宿主级全局工具 subagent_codex，所有 preset 均可见，Claude Code 提供方参考对 subagent_claude_code 也有同样描述。
所以既不能断言「所有安装都必须编辑 preset」，也不能断言「所有旧安装都自动有全局工具」。唯一可靠的做法是核对你安装的版本，以及当前生效的 bundle 组合。本文不替文档裁决，只提供一条可执行的排查路径。
结论先行：四种现象对应四个不同的地方
| 你看到的现象 | 真正该查的地方 |
|---|---|
| 包加到了另一个 profile | 当前运行 profile 的 bundle 列表与名称 |
| 运行期间刚加了 bundle | 成员变化后需要重启 profile |
| 提供方在，但工具没有 | bundle 版本、已选层、工具行、preset 组合 |
| 工具有，但委派失败 | 提供方运行时、认证、权限与诊断 |
关键判据：「磁盘上有包」只证明第一列，不证明后三列。 安装、选层、注册、执行，是四个阶段。
一、安装本身：两条命令，别指望它们互相替代
CLI 参考给出两条独立的安装命令（将占位名称替换为目标 profile）：
dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex
dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-claude-code
三个必须知道的细节：
- 第一条不会顺带装上另一种提供方。 两者是独立可选的 bundle，不是「装一个全家桶」。
--profile必须写在转发给 pnpm 的参数之前。 顺序错了，它就会被当成包管理参数。- CLI 把包管理交给 pnpm，并要求 pnpm 在
PATH里。 因此，命令失败并不能证明 bundle 没装上，还要单独确认操作结果。
安装方式以及两个提供方的差异，参见 安装 Codex 与 Claude Code 子智能体提供方。
二、重启边界：运行中的 profile 保留的是「启动时那份」
这是最容易忽略、也最容易误判的一层：包管理操作改变的是磁盘上的 profile bundle 列表；正在运行的 profile 则保留本次启动时加载的集合。 加了 bundle 却没重启，看到的仍是旧状态。
通过 Web 或桌面端安装时，如果安装器提示需要重启，就按提供方说明操作。关于重启会改变什么、哪些内容会保留，可参见 插件更新后重启 profile。这里先记住一句：成员变化 → 重启 → 再看工具。
注意不要混淆两种「重启」：因 bundle 成员变化而重启的要求来自 CLI 参考；插件页面里开关某一层则是另一回事（见第四节）。
三、追踪一次工具暴露：五步
- 确认实际运行的 profile、所加的包及操作结果。 查看该 profile 的有效 bundle 组合，不要只看从别人环境复制来的命令。
- 改过 bundle 成员就重启。 没重启就继续往下查，查到的仍是过期状态。
- 将已安装版本与对应提供方文档对照。 根据当前文档描述的 bundle 组合，检查是否存在宿主工具行，以及后续补丁是否将其禁用。
- 如果装的是 CLI 参考描述的仅提供方组合，就检查复制出的 preset 中对应的工具行；启用后，创建新的 agent。不要假定「改了 preset」必然会影响已经创建的 agent。
- 查看目标 agent 的可用工具列表，再运行一个范围明确的小任务。 分开记录「工具缺失」和「执行失败」，并注明 profile 与配置层。
第 3 步还有一个常见陷阱：preset 里的同名工具可能遮蔽全局工具。 如果工具名出现在两个位置，先确认当前 agent 实际使用哪一行，再检查该行的配置。查看工具清单的方法见 查看某个 agent 可用的工具。
四、插件页的「关闭」和「移除」不是一回事
提供方 README 清楚地区分了插件页面里的两个动作：
- 关闭：取消选择该配置层，但保留已安装的包；
- 移除：这是独立的包操作，会把包拿掉。
因此，「package.json 里还有这个依赖」完全不能说明「这一层正在运行」。排查时必须同时确认两件事：包是否存在，以及当前宿主是否选中了该层。
在同一份 README 描述的模型中，选择或关闭某一层会在运行中的宿主里注册或移除全局工具，现有 agent 的下一次请求就能看到。不过要记住：这是那几份 README 描述的层操作，它不会取消 CLI 参考对「bundle 成员变化需要重启」的要求。 两种语义同时存在，不能拿一种去否认另一种。
五、工具出现了，但调用失败
工具存在，只说明注册成功。它不能证明某个具体请求、某个运行时或某套凭据一定可用。子智能体参考将「提供方注册」与「受管理的 activation」分开，这一区分在这里很有用。
两份提供方文档还分别描述了一次性的原生执行，以及各自的认证与权限模式。因此，不要假定两者在可执行文件选择、配置、权限语义或错误原因上完全一致——同一个现象，在两个提供方中的根因往往不同。
还有一条容易搞错的边界：子智能体参考说明，本地可继续的子会话支持后续消息，而外部执行不接受后续消息。 如果任务需要多轮互动，先确认所选提供方具备这项能力，不要把「不支持后续消息」误判为安装失败。子智能体与主智能体在会话形态上的差别，见 子智能体与主智能体。
排查结果需要提供给同事或提供方时，记录以下六项就够用：所装 bundle 的版本、目标 profile、插件页中该层是选中还是关闭、添加后是否重启、目标 agent 的可用工具列表，以及失败调用对应的任务。信息齐全，对方就不必反复追问；少了其中任何一项，讨论都容易回到「再装一次试试」这样的无效循环。
六、安全边界（这段不能省）
- 外部子智能体会在其自身的原生权限与沙箱设置下执行任务。 提供方参考列出了效果不同的模式，其中包括必须显式选择的危险绕过选项。
- 不要为了让工具出现而选择绕过。 这会用一个可见性问题的「解法」，换掉原本存在的一层保护。
- 工具可见、注册成功，都不能证明操作安全或已经获得授权。 这是两件独立的事。
- 确认该提供方应有的权限，并审查任务及其产生的修改。
- 引用资料对工具行的暴露方式存在差异，所以不能据此断言你的安装版本属于哪一种；请核对版本、生效组合与对应的升级说明。
- 提供方注册成功，不代表原生认证一定正常；工具缺失，也不必然是认证失败。
术语
- 提供方：注册之后执行某类子智能体 activation 的实现。
- bundle：向 profile 提供配置的包。
- 全局工具：当前提供方 README 中向各 preset 暴露的宿主级工具。
- preset：可以包含自身工具行的 agent 组合。
- activation：受管理的本地或外部子任务启动与执行。
排查清单
- 包加到的是当前正在跑的那个 profile 吗？
- 加完之后重启过吗？成员变化不重启，查的仍是旧状态。
- 生效的 bundle 组合里，到底有哪些？别只看命令历史。
- 你装的那个版本，走的是「全局工具」还是「仅提供方 + preset 工具行」？
- 如果是后者，新 agent 创建了吗？改 preset 不一定影响已存在的 agent。
- 当前 agent 实际用的是哪一行工具？preset 会不会遮蔽全局工具？
- 后续补丁有没有禁用那一行？重复插入工具行能解决吗？
- 插件页里是「关闭」还是「移除」？包在，不等于层在。
- 是工具缺失还是调用失败？两者的下一步完全不同。
- 有人为了「让它跑通」选了危险绕过选项吗？理由成立吗？
相关阅读
本文依据 DeepSeek Harness 官方 CLI 参考、子智能体参考与两份提供方 README 整理，由 DSH Plugin 社区（dsh-plugin.com）维护者撰写，首发于阿里云开发者社区。
插件与文档收录于：https://dsh-plugin.com/zh/blog
