DeepSeek Harness 自定义工具工作室（DSH Custom Tool Studio）

前言¶

DeepSeek Harness（DSH）的设计理念是「一切皆插件」。开发者可以在不重启 DSH 的情况下，通过插件动态扩展工具集。其中，dsh-custom-tool-studio 插件允许你在 DSH 环境中编写并运行 Python 工具：它们会以「第一类 DSH 工具」的身份注册，模型可以直接调用，且数据仅存储在本地。

插件定位¶

名称：dsh-custom-tool-studio（DSH Custom Tool Studio）
维护者：xtt-xt
分类：工作流
仓库：https://github.com/xtt-xt/dsh-custom-tool-studio
许可证：MIT
当前版本：1.1.0（README）

插件通过 DSH bundle 插件机制提供，支持在 Web UI 与 AI 侧两种入口管理 Python 工具，并提供危险工具审批、工具包分组与延迟加载等能力。

核心功能¶

1. 创建与即时注册¶

在 Web UI 的「自定义工具」页面或通过 AI 的 custom_tool_manage 工具，起一个工具名、写描述、参数 JSON Schema 与 Python 代码。
保存/启用/改名/删除后，DSH 会立即对账并注册或注销工具，无需重启 DSH。
所有工具数据存储在本地 %DSH_HOME%\custom-tools\tools.json，不会上传。

2. 试运行¶

Web UI 的「测试」对话框可填 args JSON 并直接运行，查看结果、stdout、stderr 与耗时。
AI 通过 custom_tool_manage 的 action="test" 也可试运行。

3. 危险工具与内置审批¶

在编辑对话框中开启「危险工具」开关，或 AI 侧传入 dangerous: true，该工具每次执行前都会触发 DSH 内置审批界面。
危险工具执行审批与 DSH 内置的自动审查（@deepseek-ai/dsh-experimental-auto-review）兼容。
非危险工具不会触发审批。
管理操作（创建、修改、删除）可通过页面「设置」中的开关让 AI 操作也走审批，删除默认开启审批。

4. 工具包（分组）¶

工具包用于将多个工具归到同一分组，支持一键启停整包。
包内工具仍各自注册为独立的 DSH 工具，仅做分组与整包开关。
工具包支持「始终解锁」与成员管理。

5. AI 主动解锁模式（延迟加载）¶

页面「设置」中开启「AI 主动解锁模式」后，每个对话初始只可见两个工具：custom_tool_manage 与 custom_tool_unlock。
AI 通过 custom_tool_unlock 的 action="unlock" 解锁指定包后，包内启用工具在下一轮请求中可见。
解锁状态按会话 ID 记录在 unlocks.json 中，不同对话独立。
支持包的「始终解锁」与未分组工具单独解锁。

Python 工具约定¶

入口函数¶

def run(args):
    ...

必须定义 def run(args):；页面与 AI 侧会校验。
args 由模型按参数 JSON Schema 传入，为普通 Python dict。
返回值必须是可 JSON 序列化的值（dict/list/str/数字/bool/None）。
print() / sys.stdout 作为日志通道（最多保留末尾 8,000 字符）。
sys.stderr 的内容进入 stderr；抛出的异常抓为 error。
结果 JSON 超过 20,000 字符会被截断。
脚本在独立 Python 进程中执行，工作目录为 DSH 进程当前目录。

超时与解释器¶

默认超时 60 秒；可通过环境变量 DSH_CUSTOM_TOOL_TIMEOUT_MS 调整（毫秒），改完重启 DSH。
解释器探测顺序：DSH_CUSTOM_TOOL_PYTHON（完整路径）→ python → python3 → py -3。

参数 JSON Schema¶

参数根节点必须是 JSON 对象：

{
  "type": "object",
  "properties": {
    "text": { "type": "string", "description": "要统计的文本" },
    "limit": { "type": "integer", "description": "最多返回几行" }
  },
  "required": ["text"]
}

description 写给模型看。
required 列出必填参数。
无参数时填 {"type": "object", "properties": {}}。

工具命名规则¶

规则：^[a-z][a-z0-9_]{1,47}$（小写字母开头，长度 2–48，仅含小写字母/数字/下划线）。
run_code 为 DSH 保留名，不可使用。
不能与内置工具或其它插件已注册的工具重名。

AI 侧管理工具 `custom_tool_manage`¶

模型可直接调用 custom_tool_manage 完成管理操作，与 Web UI 共用同一套逻辑。常用 action 与参数如下：

list：列出所有自定义工具（含启用/危险状态与工具包名）。
get：查看某个工具的完整定义（含代码与所属包）。
create：新建并注册工具（必填：name、description、code）。
update：修改已有工具（必填：name + 至少一个字段）。
delete：删除工具（同时从 DSH 注销）。
set_enabled：启用/停用工具。
test：用给定参数试运行一次。
pack_list：列出工具包及成员。
pack_get：查看一个工具包的成员与描述。
pack_create：新建工具包（必填：name；可选：description、tools、alwaysUnlocked）。
pack_update：改包描述/成员/改名/始终解锁（必填：pack + 至少一项）。
pack_delete：删除工具包（工具保留，变未分组）。
pack_set_enabled：一键启停整包。

适用场景与注意¶

适合在 DSH 中需要运行本地 Python 脚本、扩展工具集的场景。
插件以当前 DSH 进程权限运行 Python 脚本，危险操作需通过「危险工具」开关与内置审批进行控制。
安装前建议检查仓库源码与许可证（MIT）。
所有工具数据存储在本地 %DSH_HOME%\custom-tools，可整体备份与迁移。

总结¶

DSH Custom Tool Studio 让开发者能够用 Python 快速扩展 DSH 的工具能力，并利用内置审批与工具包机制控制风险与组织结构。通过 Web UI 或 AI 侧工具，即可创建、管理并运行自定义工具，无需重启 DSH。更多细节可参见插件目录页与 GitHub 仓库。