内置工具
工具是模型执行操作的入口。DSH 出厂自带 21 个 @deepseek-ai/dsh-tool-* 包,按能力域分组如下。它们通过 ctx.tools 注册,自动出现在模型的工具清单里。
想给模型新增工具?见 写一个工具。本篇只讲内置的、开箱即用的能力。
一图总览
| 能力域 | 工具包 | 一句话 |
|---|---|---|
| 终端 | tool-bash / tool-bash-persistent / tool-terminal / tool-pwsh | 跑命令、长驻会话 |
| 文件 | tool-fs / tool-fs-search / tool-str-replace-editor | 读写、搜索、精确编辑 |
| 网络 | tool-web | web_search / web_fetch |
| 代码 | tool-lsp | 跳转定义、找引用、hover |
| 委托 | tool-subagent / tool-subagent-control / tool-subagent-report | 把活派给子 Agent |
| 调度 | schedule | 定时提醒 |
| 目标 | tool-goal | 会话级目标 |
| 作业 | tool-jobs | 后台作业输出/列表/终止 |
| 待办 | tool-todo | todo_write |
| 技能 | tool-skill | 加载技能 |
| 会话检索 | tool-session-query | 历史搜索/轨迹 |
| 提问 | tool-ask-user | 问用户 |
| 自省 | tool-cordis | 查询 Host/Client 契约，定义并管理版本化动态插件 |
| 编排 | tool-workflow / tool-ralph | JS 编排、Ralph 迭代 |
| 模型可带 | 由各 seam 决定 | 呈现与调度 |
终端类
| 工具 | 关键用法 | 说明 |
|---|---|---|
bash | 执行 shell 命令,可选后台作业、沙箱升权 | 通用命令执行 |
bash(tool-bash-persistent) | 长驻 shell 会话(与 tool-bash 同名) | 按 owner 隔离的持久 Bash(基于 PTY) |
terminal | 六个持久终端工具 | 交互式终端,owner 隔离,接后台作业 |
pwsh | 执行 PowerShell | Windows 场景的 shell 层 |
终端类都会过 ctx.sandbox.confine(见 沙箱与安全)。执行环境统一由 shell-env(ctx.shellEnv)提供:每个前台/后台 shell 调用都收到一份新采集的受管 DSH_* 环境快照,内置 DSH_HOME、DSH_SHELL=1、DSH_SESSION_ID(agent 调用还带 DSH_SESSION_JSONL 位置提示),其他插件可注册 effect 作用域的 contributor 追加事实;重复归属或未声明的运行时键会 loud fail。shell-env 默认挂载,process.env 从不被改写。 |
文件类
| 工具 | 关键用法 | 说明 |
|---|---|---|
fs | read / write / edit | 走 ctx.fs 能力缝 |
fs_search | glob / grep | 打包的 ripgrep,快速发现 |
str_replace_editor | 查看/创建/字面替换/插行 | 精确编辑,改动小、便于 review |
委托与并行
| 工具 | 关键用法 | 说明 |
|---|---|---|
subagent | 派发一次性子 Agent | 走 ctx.subagents seam |
subagent_control | send_message / interrupt_agent / list_agents | 全局控制可续子会话 |
report(tool-subagent-report) | 子 Agent 回报 | 子作用域内可用 |
完整委托模型见 子 Agent 与并行。
目标 / 作业 / 待办
| 工具 | 关键用法 | 说明 |
|---|---|---|
goal | 同会话长期目标 | 执行期权限检查 |
jobs | job_output / job_list / job_kill | 后台作业注册表 |
todo | todo_write | 写进事件溯源会话日志 |
详见 目标、作业与待办。
搜索 / 检索 / 提问
| 工具 | 关键用法 | 说明 |
|---|---|---|
session_search(等) | 历史会话搜索 / 轨迹 / 读事件 | 检索 DSH 自己的会话,opt-in(默认不挂) |
ask_user | 向用户提问 | 走 ctx.userQuestions |
dsh-tool-session-query注册session_search/session_trace/session_event_read等,检索 DSH 自己的历史会话;该包 opt-in,默认不挂载。
网络
模型可见的是 web 工具(web_search / web_fetch),两者走同一个 ctx.web 能力缝。真正的检索/抓取由注册进 ctx.web 的 provider 后端完成,tool-web 只负责呈现(工具名、schema、结果格式、HTML→markdown):
| 后端 | 类型 | 说明 | 挂载 |
|---|---|---|---|
web-search-deepseek | 搜索 provider | Anthropic 兼容 Messages API + 原生 web_search 工具,解析结构化结果块,复用 DEEPSEEK_API_KEY | 默认挂载(searchProvider: deepseek-official) |
web-fetch-http | 抓取 provider | 匿名公开 HTTP(S),同源重定向、字节/字符上限、拒绝二进制;SSRF 防护 deferred | opt-in(base 默认 fetch: false,不挂 fetch provider) |
web-search-exa | 搜索 provider | Exa POST /search,auto/keyword/neural;无生成答案,content 省略 | opt-in(需 EXA_API_KEY) |
web-search-perplexity | 搜索 provider | OpenAI 兼容 chat/completions,生成答案 content + 引用 sources[] | opt-in(需 PERPLEXITY_API_KEY) |
provider 注册的是能力不是工具;tool-web 的注册跟着产品开关(fetch 默认关),不跟后端可用性——provider 缺失/不可用/歧义时工具 schema 仍在,执行时才抛结构化 WebError。provider 选择在 seam 内、执行时解析(显式 searchProvider/fetchProvider 或唯一可用 provider 自动选)。
代码
| 工具 | 关键用法 | 说明 |
|---|---|---|
lsp | goToDefinition / findReferences / goToImplementation / hover | 只读,基于 ctx.lsp |
自省与编排
| 工具 | 关键用法 | 说明 |
|---|---|---|
cordis | inspect_list/query/self + define/run/stop/undefine | 版本化动态 Cordis 工具集 |
workflow | 跑 JS 编排脚本 | 走 ctx.workflowEngine |
ralph | 新鲜 Agent 的 Ralph 迭代循环 | 结合 workflow + subagent |
详见 工作流与 Ralph。
常见组合(怎么串起来干活)
| 想要 | 组合 |
|---|---|
| 检索 + 读文件 + 改代码 | session_search 找历史 → fs/str_replace_editor 改 |
| 终端跑步 + 后台作业 | bash 常驻 + jobs 收后台输出 |
| 拆大任务并行 | subagent 派发 + subagent_control 收 |
| 定时推进 | schedule 设想起 + goal/todo 记进度 |
| 卡住问人 | ask_user 确认后再继续 |
工具是原子能力;把常用的串法固化下来就是 技能 或 工作流。
验证当前装了哪些工具
dsh web --dump-config | grep -E "tool-"
# 组合树里能看到每个 tool-* 插件与是否启用
工具的可配置性
每个工具包都能在 profile 层通过 patch 覆盖 config(例如是否默认关闭、超时、工作区授权)。工具呈现方式(native/code/both)由 ctx.tools.presentAs 决定,不是工具自身关心的事。