本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-custom-tool

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add github:omdsh-dev/dsh-custom-tool

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• 用户无法扩展自己的 agent：以前加能力要发布 harness 包；现在一个工具就是设置里的一张表单——名字、描述、参数、代码，保存即生效、模型立即可调。
• 模型无法自我成长：custom_tool_create 让模型在会话中途持久化工具（热注册，下一步即可见），且与 UI 共用同一道校验门——UI 会拒绝的东西模型同样存不进去。
• 用户编写的代码在受限 worker 中执行：每次调用在独立 worker 线程的全新 node:vm 环境里按白名单、Node Permission Model 和硬预算执行。worker 不继承环境变量，也不能访问配置范围之外的文件或创建子进程。
• 设置界面（Custom Tool 区，专属导航图标）：列表、新建、编辑、启停、删除；模型创建与工作区工具带徽章。全部文案接入 harness 语言体系（中文 / English），随语言偏好即时切换。
• Monaco 编辑器：VS Code 引擎 + TypeScript 语言服务；args 按参数 schema 生成类型，env/沙箱全局量有声明，补全与报错实时。编辑器与 TS worker 内联打包——客户端 bundle 单文件。

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

我要怎么写一个自定义工具？

打开设置里的"Custom Tool"页，点 + 新建；填名字、描述、参数 schema、代码四样，保存即注册。代码字段就是 (args, env) => value 的 async 函数体，能用 fetch / console / TextEncoder / URL / setTimeout 等内置全局（README.md:76-90 / src/client/index.ts:80-117）。

模型可以自己造工具吗？需要我同意吗？

模型可以调用 custom_tool_create 自己造：默认存在当前工作区、完全自治；只要选 location 为 "global"（所有工作区都能用），插件就会弹一个 GUI 审批请求，拒绝或不可用就直接失败，模型拿不到工具。模型只能删除自己创建的（source: model），你写的它删不掉（README.md:53-56 / src/model-tools.ts:39-61）。

工具代码跑在哪里？安全吗？

每次调用开一个新 worker 线程，代码在 node:vm 沙箱里按白名单执行，并配合 Node Permission Model 加 --allow-net / --allow-fs-read / --allow-fs-write 等限制。worker 不继承任何环境变量，require / import / process 都被禁，超时或内存超限会被强制终止（src/executor.ts:20-32 / src/executor-worker.ts:32-50）。

工具代码能访问网络吗？

默认能。宿主侧 allowNetwork 为 true 时，工具里可直接用 fetch；把它改成 false 后，沙箱里的 fetch 会被替换成永远 reject 的占位（src/executor-worker.ts:118-153）。

工具能读写文件吗？

只有 scope = workspace 的工具有，且只能读写当前会话的工作区根目录。路径会被词法级 resolve + 前缀检查，越界直接报错；符号链接若指向工作区外则拦不住，源码注释已明确这是可信代码边界（README.md:35-40 / src/executor-worker.ts:61-95）。

工具名有规则吗？会和其他插件冲突吗？

名字必须匹配 /^[a-z][a-z0-9_]{0,63}$/，且不能用 custom_tool_create / custom_tool_remove / custom_tools_list 这三个本插件保留名。和其他插件同名时会注册失败，错误会出现在 custom_tools_list 的逐工具 error 字段里（src/shared/names.ts:2-5 / README.md:119）。

工具存放在哪？每个项目独立吗？

location 为 "global" 的工具存在 DSH 共享设置里（每个 workspace 都能用），location 为 "workspace" 的工具存在 <DSH_HOME>/workspace-tools/<hash>.json，按工作区根路径的 sha256 前 16 位分桶，只有匹配这个 workspace 的 agent 会话可见（src/workspace-store.ts:37-40 / README.md:44-49）。

怎么删除一个工具？

设置界面可以启停、删除任意工具。代码侧用 custom_tool_remove 只能删模型自己造的；用户写的工具被保护，模型尝试删会报错并被提示词引导让用户在 UI 里删（src/model-tools.ts:220-240 / README.md:55-56）。

没有"试运行"按钮吗？我怎么验证工具能用？

目前 UI 里没有一键试运行；可以在新会话里直接让模型调用该工具，或写一个测试用例走 headless 路径。这是 README.md:121 已声明的已知限制。

安装后 settings 里的 Custom Tool 页打不开/保存被拒怎么办？

这是 DSH 宿主层 WEB_SETTINGS_NAMESPACES 白名单没有包含 'custom-tools' 造成的：界面能渲染但保存会静默拒绝（settings-not-exposed）。需要把 'custom-tools' 加进宿主 packages/host/apiproxy/src/api-proxy.ts 的允许列表（上游 harness 提交 d6ea05b5 已加），详见 README.md:72。

— 源: plugin_wiki.faq_json

兼容性

• DSH: >=0.0.1（dsh.plugin.json 声明，未指定 rc/正式版本号）
• Node: >=22.19.0 或 >=24.0.0（engines.node ^22.19 || >=24）
• Platforms: macOS, Windows, Linux

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则