dsh-plugin-scaffold

English | 中文

一个最小、可运行的 DeepSeek Harness（dsh）插件脚手架。它在共享的 ctx.tools 服务上注册一个模型可调用的工具（hello），用最小的代码面完整验证加载链路——插件解析 → Loader 挂载 → 工具注册 → 模型调用。

这是一个外部/社区插件：它不在 deepseek-harness monorepo 内，而是基于已发布的 npm 包（@deepseek-ai/dsh-tools、@deepseek-ai/dsh-llm、@deepseek-ai/cordis）构建。这正是项目鼓励的贡献方式——参见 CONTRIBUTING.md：目前项目不接受外部 PR，但欢迎带有 dsh-plugin 标签的生态插件。

工具做什么

hello 工具接收一个 name，返回结构化 JSON：

{ "greeting": "Hello, World!", "cwd": "/path/to/cwd" }

它的作用是验证链路是否打通，而不是做真实工作。把它当作开发真实能力（文件访问、网页抓取、Shell、定时任务……）的起始模板。

从这里能做什么

这个脚手架只是插件的一种形态——模型可调用的工具。DeepSeek Harness 的设计是一切皆插件，所以同样的加载路径可以解锁很多其他扩展点。挑一个方向，把 hello 工具替换成真实行为即可：

方向	做什么	例子
数据查询工具	模型调用工具，你拉取 API 并返回 JSON	天气、汇率、股票、GitHub
数据库工具	执行校验过的查询	只读 SQL、内部看板
文件/工作区工具	读写、汇总项目文件	定制 grep、批量重命名、代码统计
外部服务桥接	为模型封装 REST/GraphQL/CLI API	翻译、OCR、发邮件、触发 CI
事件监听	观察 agent/*、tools/* 事件并响应	自动会话标题、护栏、用量日志
上下文注入	每次模型请求附带持久上下文	agent.inject() 注入项目/时间/环境信息
模型 provider	在 ctx.llm 注册新适配器	本地 Ollama、OpenAI 兼容接口
人工命令	不经过模型直接执行的 /command	ctx.commands，如 /deploy
后台任务	长任务或定时任务	ctx.jobs、轮询、提醒
策略/沙箱	限制 fs/shell/subprocess 访问	审批门、白名单
UI 卡片	定制工具在 Web UI 中的展示	presentCall / presentResult、diff/终端卡片
自我修改	让 agent 检查并装卸自己的插件	官方 web-cordis 示例

可参考的现成示例见官方 examples/：web-schedule（持久提醒）、mcp-memory（通过 MCP 接外部记忆）、web-cordis（agent 修改自己的插件树）、headless-agent（一次性任务）。扩展点地图见 docs/architecture.md。

每种形态都遵循本脚手架演示的同一套模式：一个 name/inject/Config/apply 模块，其注册是卸载时可回滚的 effect。

项目结构

src/index.ts        # 插件本体：name / inject / Config / apply（函数插件，无 default export）
scripts/verify.ts   # 通过 ctx.plugin() 验证加载链路（真实 dsh-tools 运行时）
scripts/verify-loader.ts  # 通过 Cordis Loader + cordis.yml 验证加载链路（dsh 真实的启动路径）
cordis.yml          # 可选 overlay：把插件行插入 dsh 组合配置
verify.cordis.yml   # verify-loader.ts 使用的自包含 Loader 组合配置

环境要求

• Node.js ^22.19.0 || >=24.0.0
• 能解析已发布 @deepseek-ai/* 包的 dsh 安装
• pnpm（用于开发）

开发

pnpm install
pnpm build       # tsc -> lib/index.js + lib/types
pnpm test        # vitest：导出形态、注册、调用、卸载回滚
pnpm verify      # ctx.plugin() 路径：挂载真实 dsh-tools + 插件，调用 `hello`
pnpm verify:loader  # Loader 路径：通过 Cordis Loader 启动 verify.cordis.yml，调用 `hello`

两个 verify 脚本会断言结果为非错误，失败时以非零码退出。vitest 套件覆盖插件导出形态、工具注册与规范返回值、非法参数拒绝、以及卸载时的 effect 回滚。CI 在 Node 22 和 24 上运行全部四项。

挂载到 dsh

把 overlay 传给 dsh web（或 dsh headless）：

dsh web --patch "$PWD/cordis.yml"

overlay 会 insert 一行。使用指向构建产物的相对路径，让 Loader 相对配置文件目录解析，不依赖包安装：

- insert:
    - id: dsh-plugin-scaffold
      name: './path/to/lib/index.js'

本仓库的 cordis.yml 就带的是这种相对形式。在 Web UI 里，让模型「用我的名字调用 hello 工具」即可看到效果。

裸包名解析（「发布插件」的真正含义）

Cordis Loader 从它自身的模块位置解析裸包名（dsh-plugin-scaffold、@deepseek-ai/*），而不是启动目录。所以裸 name: dsh-plugin-scaffold 只有在包被安装到 dsh 安装树的 node_modules 里才能解析（例如 npm install -g dsh-plugin-scaffold 让它和 Loader 相邻，或安装到 profile 的 node_modules）。两种可靠方式：

• 发布到 npm 并全局安装——裸包名即可从 Loader 位置解析。
• 使用相对/绝对路径指向构建产物 lib/index.js——总是相对配置文件位置解析。

如需持久安装，把同样的 insert 块加到 $DSH_HOME/profiles/<name>/cordis.patch.yml（单个 profile）或 $DSH_HOME/cordis.patch.yml（所有 profile），参见 web-schedule 示例。不要覆盖已有文件——它可能已经包含无关的用户补丁。

关于已发布的 @deepseek-ai/* 包

本脚手架依赖 npm 发布的版本（0.1.0-rc.6），而非 monorepo 的 workspace 版本。如果未来版本修改了 defineTool / ToolRuntime 契约，请同步更新这里的 peerDependencies / devDependencies。插件刻意保持轻量依赖：只有 @deepseek-ai/cordis（类型 + Context）、@deepseek-ai/dsh-tools（defineTool + ctx.tools）、@deepseek-ai/dsh-llm（ContentBlock，仅类型）、@deepseek-ai/schemastery（Config schema）。

在 monorepo 内验证

如果 clone 了 deepseek-harness 来查看真实运行时，注意全量安装 workspace 会拉取大型可选 provider 二进制（Claude Codex SDK、网站用的 mermaid），在慢网络上容易超时。本脚手架的验证不需要它们：已发布的 @deepseek-ai/dsh-tools 包是自包含的。