内置工具
工具是模型执行操作的入口。DSH 出厂自带 多个 @deepseek-ai/dsh-tool-* 包,按能力域分组如下。它们通过 ctx.tools 注册,自动出现在模型的工具清单里。
想给模型新增工具?见 写一个工具。本篇只讲内置的、开箱即用的能力。
一图总览
| 能力域 | 工具包 | 一句话 |
|---|---|---|
| 终端 | tool-bash / tool-bash-persistent / tool-pwsh / tool-pwsh-persistent / tool-terminal | 跑命令、长驻会话 |
| 文件 | tool-fs / tool-fs-search / tool-str-replace-editor | 读写、搜索、精确编辑 |
| 网络 | tool-web | web_search / web_fetch |
| 代码 | tool-lsp | 跳转定义、找引用、hover |
| 委托 | tool-subagent / tool-subagent-control | 把活派给子 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 层 |
pwsh(tool-pwsh-persistent) | 长驻 PowerShell 会话(与 tool-pwsh 同名) | 按 owner 隔离的持久 PowerShell(基于 PTY) |
终端类都会过 ctx.sandbox.confine(见 沙箱与安全)。执行环境统一由 shell-env(ctx.shellEnv)提供:每个前台/后台 shell 调用都收到一份新采集的受管 DSH_* 环境快照,内置 DSH_HOME、DSH_SHELL=1、DSH_SESSION_ID,其他插件可注册 effect 作用域的 contributor 追加事实;重复归属或未声明的运行时键会 loud fail。shell-env 默认挂载,process.env 从不被改写。 |
文件类
| 工具 | 关键用法 | 说明 |
|---|---|---|
fs | read / read_image / write / edit | 走 ctx.fs 能力缝 |
fs_search | glob / grep | 打包的 ripgrep,快速发现 |
str_replace_editor | 查看/创建/字面替换/插行 | 精确编辑,改动小、便于 review |
read_image 只在持久 ctx.attachments 服务已挂载时注册，且执行时拒绝未声明图像输入的模型路由；接受 PNG/JPEG/WebP/GIF（含无扩展名但按文件签名识别格式的路径），结果作为原生图像块随持久引用写入会话日志。
委托与并行
| 工具 | 关键用法 | 说明 |
|---|---|---|
subagent | 派发一次性子 Agent | 走 ctx.subagents seam |
subagent_control | send_message / interrupt_agent / list_agents | 全局控制可续子会话 |
完整委托模型见 子 Agent 与并行。可续子会话与父 Agent 通过
send_message双向传递后续消息（0.1.2-rc.1 起取代单向report工具，tool-subagent-report已移除）。
目标 / 作业 / 待办
| 工具 | 关键用法 | 说明 |
|---|---|---|
get_goal / create_goal / update_goal | 同会话长期目标 | 执行期权限检查 |
jobs | job_output / job_list / job_kill | 后台作业注册表 |
todo | todo_write | 写进事件溯源会话日志 |
详见 目标、作业与待办。用户暂停的目标只能由用户恢复：
update_goal不能把paused改回active（0.1.5）。
搜索 / 检索 / 提问
| 工具 | 关键用法 | 说明 |
|---|---|---|
session_search(等) | 历史会话搜索 / 轨迹 / 读事件 | 检索 DSH 自己的会话,opt-in(默认不挂) |
ask_user_question | 向用户提问 | 走 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)，地址 / DNS / 重定向检查及输出上限 | base 挂载 provider 且 tool-web 为 fetch: true；Web app 禁用 base 的 tool-web 行，standard / cordis / ptc 预设各自组合（同样 fetch: true） |
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 的注册跟着产品开关（base 已是 fetch: true；Web app 禁用 base 的 tool-web 行，由 standard / cordis / ptc 预设各自组合为 true，minimal 预设不含 web 工具）,不跟后端可用性——provider 缺失/不可用/歧义时工具 schema 仍在,执行时才抛结构化 WebError。provider 选择在 seam 内、执行时解析(显式 searchProvider/fetchProvider 或唯一可用 provider 自动选)。
出站网络统一遵循启动环境解析出的代理策略（0.1.3-alpha.1）：HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY 覆盖 LLM、web 搜索与 HTTP MCP 流量；loopback 保持直连，不受支持的代理 URL 会被报告并对该协议跳过。
代码
| 工具 | 关键用法 | 说明 |
|---|---|---|
lsp | goToDefinition / findReferences / goToImplementation / hover | 只读,基于 ctx.lsp |
自省与编排
| 工具 | 关键用法 | 说明 |
|---|---|---|
cordis | cordis_inspect_list/query/self + cordis_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_create 设提醒 + update_goal/todo_write 记进度 |
| 卡住问人 | ask_user_question 确认后再继续 |
工具是原子能力;把常用的串法固化下来就是 技能 或 工作流。
验证当前装了哪些工具
dsh web --dump-config | grep -E "tool-"
# 组合树里能看到每个 tool-* 插件与是否启用
工具的可配置性
每个工具包都能在 profile 层通过 patch 覆盖 config(例如是否默认关闭、超时、工作区授权)。工具呈现方式(native/ptc/both)由 ctx.tools.presentAs 决定,不是工具自身关心的事。PTC 模式下经 run_code 分发的受支持 bash / pwsh / terminal_send 子调用在 Web 工具卡里与根调用一样渲染为 terminal 卡片，命令与输出都可展开（0.1.3-alpha.2）；后台调用、工具错误等仍走通用回退。read_image 的顶层与 PTC 嵌套调用直接渲染图片，不再展示原始附件对象（0.1.3-alpha.1）。
源码基线：
0.1.5-alpha.1（5dda764ed3）。公开抓取有 SSRF 策略，不再是旧版的 deferred 防护；普通获准公开地址抓取不逐次申请网络审批。应检查最终 preset，而非只看 base。源码：packages/web/web-fetch-http、packages/util/http-proxy、packages/bundle/base/cordis.patch.yml与packages/preset/agent-presets/presets/。