前言¶

在 DeepSeek Harness（DSH）里扩展智能体能力，常见做法是把新功能做成 harness 包再发布。每次小改动都要走打包与安装流程，迭代成本高。另一方面，模型本身无法在中途持久化自己需要的工具——会话结束后，临时能力就消失了。

dsh-custom-tool 针对这两类问题：用户在设置界面用 Monaco 编辑器编写 JavaScript 工具，模型则通过 custom_tool_create / custom_tool_remove / custom_tools_list 自行增删工具集。工具持久化存储、热注册，下一步系统提示词即可见。

这是什么¶

• 插件名称：dsh-custom-tool
• 维护者：omdsh-dev
• 分类：admin-security
• GitHub 星标：24
• 许可证：MIT
• 当前版本：v0.1.2

一句话定位：在 DSH 设置 UI 中创建与管理沙箱 JavaScript 工具，配备 Monaco 编辑器与模型驱动的工具生命周期。

核心功能¶

设置界面¶

设置页新增 Custom Tool 分区（独立导航图标），支持列出、创建、编辑、启用/禁用、删除工具。模型创建的工具与工作区作用域的工具带有标识。界面字符串跟随 harness 语言偏好（中文/英文）切换。

Monaco 编辑器¶

使用 VS Code 引擎与 TypeScript 语言服务：args 根据参数 schema 自动补全类型，env 与沙箱全局变量有声明，补全与诊断实时生效。编辑器与 TS worker 内联打包，客户端 bundle 为单文件。

持久化与热注册¶

工具存储在 custom-tools 设置命名空间（schema 默认值、组合基类、用户文档——普通 settings 分层）。编辑即时生效，重启后恢复。启用的工具在 settings 写入提交时即注册到 ctx.tools；禁用或删除后立即注销。Harness 自动将工具 schema 组装进系统提示词。

模型自助管理¶

三者与 UI 共用同一套校验门控。模型创建的工具有 source: model 标记；用户创建的为 source: user，模型不得删除后者。

创建 location: 'global' 的工具需用户显式批准（harness approval 弹窗）；location: 'workspace' 的工具可自主创建。

执行作用域与权限边界¶

每个工具声明两种执行作用域之一：

workspace 作用域的路径限制：

• 根目录为会话工作区目录（发起 agent 的 cwd），调用时解析。
• 相对路径从根目录解析；绝对路径不得越出根目录。
• 无发起者上下文时返回 no workspace root，而非无边界运行。
• 限制为词法级别（resolve + 前缀检查）；工作区内符号链接仍可能指向外部——workspace 作用域面向可信代码，不是对抗恶意宿主的全隔离沙箱。

存储位置¶

两个维度可自由组合：例如 location: global + scope: workspace 的工具，在任意工作区被调用时，其 fs 操作作用于调用方的工作区。

沙箱执行¶

每次调用在独立的 worker 线程中执行，运行于 node:vm realm，配有显式 allowlist、Node Permission Model 与硬性预算。Worker 不继承环境变量，无配置范围外的文件系统访问，无子进程能力。

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

• 每次调用一个 worker 线程，超时、中止或完成后终止。
• 墙钟截止（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 要求：settings 命名空间须通过 WEB_SETTINGS_NAMESPACES allowlist 暴露给 web 配置客户端（packages/host/apiproxy/src/api-proxy.ts 中需包含 'custom-tools' 字符串；上游 harness commit d6ea05b5 已添加）。缺失时 UI 可渲染但保存会被静默拒绝（settings-not-exposed）。

典型用法¶

工具代码契约¶

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

// args 根据你声明的参数 JSON Schema 自动类型化
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 值（string、number、boolean、null、array 或 plain object）；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 及对应 clear。env 为 { tool, scope }；workspace 作用域额外提供 fs。

配置项¶

在 cordis.yml 的 dsh-custom-tool 条目下调整：

适用场景与注意¶

适合谁

• 需要在 DSH 中快速扩展智能体能力、又不想每次改动都打包 harness 的开发者。
• 希望模型在会话中按需创建并持久化工具的场景（如重复的数据处理、文件操作工作流）。
• 关注 admin-security 分类、需要明确权限边界的部署环境。

注意事项

1. 插件以当前 dsh 进程权限运行；安装前应检查源码与 MIT 许可证。
2. workspace 作用域的 fs 限制是词法级别，不防符号链接逃逸；仅将可信代码放入 workspace 工具。
3. 模型创建 global 位置工具需用户批准；用户创建的工具只能由用户在设置 UI 删除。
4. 默认 allowNetwork: true；若环境不允许工具访问外网，应在配置中关闭。
5. Node 引擎要求：^22.19 || >=24。

结尾¶

dsh-custom-tool 把「扩展智能体」从打包发布降为设置表单：Monaco 编辑器写工具、沙箱 worker 执行、模型通过 API 自助增删。对于需要在 DSH 中灵活定制工具链的开发者，这是 admin-security 分类下较完整的方案之一。

• 目录页：https://www.skillhub.cn/plugins/omdsh-dev/dsh-custom-tool
• GitHub：https://github.com/omdsh-dev/dsh-custom-tool