插件脚手架 skyzhao1223/dsh-plugin-scaffold

dsh-plugin-scaffold

一个最小、可运行的 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//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 包是自包含的。