自定义工具工坊 omdsh-dev/dsh-custom-tool

dsh-custom-tool

给 DeepSeek Harness 用的自定义工具：用户可以在设置界面里用 Monaco（VS Code）编辑器写自己的 JavaScript 工具，带 TypeScript 智能提示；模型自己也能通过 custom_tool_create / custom_tool_remove / custom_tools_list 增删同一套工具集。每个工具都会持久保存、热注册，并在下一步写进模型提示词。

Custom Tool 设置页面

工具编辑器

解决什么问题

- 用户没法扩展自己的智能体：在这个插件之前，想加一项能力就得发一个 harness 包。现在工具就是设置界面里的一个表单——名称、描述、参数、代码——保存即生效，模型马上就能调用。
- 模型没法自己长大：custom_tool_create 让模型在会话中途持久保存工具（热注册，下一步就能看见），走的是和界面同一道校验关卡——界面会拒绝的东西，模型也存不进去。
- 用户写的代码跑在受限 worker 里：每次调用都在全新的 worker 线程中执行，位于 node:vm realm 内，带显式白名单、Node Permission Model 和硬性预算。worker 拿不到继承的环境变量、配置范围之外的文件系统访问权限，也没有子进程能力。

功能

- 设置界面（Custom Tool 分区，独立导航图标）：列表、新建、编辑、启用/禁用、删除。模型创建的工具和 workspace 作用域的工具都有标记。所有文案跟随 harness 语言（中文 / 英文），随语言偏好切换。
- Monaco 编辑器：VS Code 引擎 + TypeScript 语言服务；args 按参数 schema 给出类型，env / 沙箱全局变量都有声明，补全和诊断实时生效。编辑器和 TS worker 内联打包——客户端产物是单个文件。
- 持久存储：工具存放在 custom-tools 设置命名空间（schema 默认值、组合基础、用户文档——就是常规的设置分层）。编辑实时生效；重启后恢复。
- 实时注册：设置写入提交的那一刻，启用的工具就注册进 ctx.tools；禁用/删除的工具立即注销。harness 自动把工具 schema 组装进系统提示词。
- 模型自助：custom_tool_create（按名称 upsert）、custom_tools_list、custom_tool_remove 共用界面的校验关卡和下面的归属规则。

工具作用域与权限边界

每个工具都要声明两种执行作用域之一。这条边界是本插件核心的安全契约：

| | global（默认） | workspace |
| 用途 | 纯计算、外部数据、工作流 | 会话 workspace 内反复出现的文件任务 |
| fetch（网络） | 按 allowNetwork 配置 | 按 allowNetwork 配置 |
| console、定时器、TextEncoder、URL、…… | 有 | 有 |
| fs 能力 | 否 | readFile / writeFile / list，限制在会话工作区根目录内 |
| require / import / process | 从不 | 从不 |

workspace 作用域的隔离规则

- 根目录就是会话工作区目录（发起智能体的 cwd），在调用时解析。
- 相对路径从根目录解析；绝对路径必须留在根目录内；任何逃出根目录的路径都会被拒绝，并给出明确错误。
- 不在会话中时（没有发起方上下文），工作区工具会以 no workspace root 失败，而不是在没有边界的情况下运行。
- 隔离是词法层面的（resolve + 前缀检查）。工作区内的符号链接仍可能指向外部——工作区作用域是可信代码，不是用来防御恶意宿主机的沙箱。下面的存活预算对两种作用域都适用。

存储位置

每个工具还会声明它存在于哪里：

- location: 'global' —— 存放在共享设置命名空间中；在移除之前，每个工作区都可用。
- location: 'workspace' —— 存放在 <dsh home>/workspace-tools/ 下按工作区划分的文件中，以规范工作区根目录为键；只有该工作区的会话可见（注册进每个匹配智能体自己的工具作用域）。

两个维度可以自由组合：一个 global 位置、workspace 作用域的工具（比如 PDF 阅读器，用户到处都保留的持久文件任务），会在调用它的任意工作区上运行自己的 fs。

面向模型的归属与授权规则

- 模型可以创建、列出、移除模型创建的工具（source: model）。
- 创建 global 位置的工具需要用户明确批准：custom_tool_create 会发起 harness 审批请求（GUI 提示）；被拒绝或无法获得答复时，创建按失败关闭处理。workspace 位置的工具则自主进行。
- 模型不得移除用户创建的工具（source: user）；custom_tool_remove 会拒绝它们，系统提示词指引里也说明要让用户在设置 UI 中删除。
- 设置 UI 管理一切：两种来源、两种作用域、两种位置、启用/禁用、删除。

执行预算（两种作用域都适用）

- 每次调用一个工作线程；超时、中止或完成时，线程终止。
- 墙钟截止时间（timeoutMs）、堆上限（memoryLimitMb）、结果文本上限（maxResultChars）、代码大小上限（maxCodeBytes）、已存工具上限（maxTools）。

安装

dsh plugin --profile web add https://github.com/omdsh-dev/dsh-custom-tool/archive/refs/tags/v0.1.2.tar.gz
dsh web # restart the server to pick the plugin up

包中声明了 dsh.bundle.patch（挂载宿主插件）和 dsh.client（在 /plugins/dsh-custom-tool/client.js 提供浏览器端部分）。lib/ 已提交，所以从 GitHub tarball 安装无需构建步骤。
Harness 要求：设置命名空间通过 packages/host/apiproxy/src/api-proxy.ts 里的 WEB_SETTINGS_NAMESPACES 白名单暴露给 Web 配置客户端；其中必须包含字符串 'custom-tools'（上游 harness 提交 d6ea05b5 添加了它）。缺少它时，UI 能渲染，但保存会被静默拒绝（settings-not-exposed）。

工具代码契约

code 字段是 async 函数体 async (args, env) => value：

// args is typed from the parameter JSON Schema you declared.
const url = https://api.example.com/weather?city=${encodeURIComponent(args.city)}
const response = await fetch(url)
if (!response.ok) throw new Error(upstream returned ${response.status})
return await response.json()

- 返回值：JSON 值（字符串、数字、布尔值、null、数组或普通对象）；返回 undefined 或非 JSON 值会导致调用失败。
- 参数：以对象为根的 JSON Schema，属于 harness 子集 —— type、properties、required、items、enum、const、oneOf、additionalProperties、description、title、default、examples。
- 全局对象：fetch（allowNetwork: false 时被禁用）、console、TextEncoder/TextDecoder、URL/URLSearchParams、atob/btoa、structuredClone、AbortController、setTimeout/setInterval 及对应的清除函数。env 为 { tool, scope }。工作区作用域额外提供 fs。

配置

所有可调项都是 dsh-custom-tool 条目的 cordis.yml config 字段：

| 字段 | 默认值 | 含义 |
| timeoutMs | 30000 | 每次调用的墙钟时间预算 |
| memoryLimitMb | 128 | 每次调用的 worker 老生代堆上限 |
| maxResultChars | 16000 | 渲染结果文本预算 |
| maxCodeBytes | 65536 | 每个工具函数体的 UTF-8 字节预算 |
| maxTools | 100 | 已存储工具数量上限 |
| allowNetwork | true | 工具函数体是否可以调用 fetch 或使用网络 API |

开发

pnpm install # links the sibling dsh checkout for types and tests
pnpm run build # worker bundles -> inline sources -> declarations -> bundles
pnpm run test # builds workers first (pretest), then vitest
pnpm run typecheck
pnpm run lint
pnpm run check # typecheck + lint + test + build

Node 环境测试把 @deepseek-ai/dsh-client-runtime/client 别名指向源码，把 monaco-editor 别名指向 mock（见 vitest.config.ts）。

已知限制与待办工作

- 自定义工具名不能遮蔽其他包拥有的工具；冲突会在 custom_tools_list 中表现为单个工具注册失败。
- 工作区隔离是词法层面的，无法防住符号链接（见作用域表）。
- UI 里还没有单个工具的测试运行按钮；只能通过模型调用或无头运行来验证工具。