DSH入门

目录 / 第 9 章

第 9 章　创造模式：从使用者到扩展者

约 8 分钟 · 4,032 字 · 12 个小节

本章你会学会

  • 创造模式到底是什么，不是什么；
  • 它比标准模式多了哪些能力；
  • 什么时候该用，什么时候不该用；
  • 一次完整的“做插件”流程；
  • 不会编程的人怎么参与；
  • 怎么避免把 DSH 改坏。

9.1 创造模式是什么

创造模式是 DSH 的一个 Agent Preset，内部 id 是 cordis。[3]

它不是：

  • 另一个模型；
  • 另一套运行时；
  • 另一个软件；
  • 更聪明的标准模式。

它是：

在标准任务工具之上，额外提供运行时检查、插件管理、以及插件/Preset 开发指引的一种工作模式。

它和标准模式共用：

  • 同一个 Agent loop；
  • 同一个模型；
  • 同一个沙箱/权限系统；
  • 绝大部分任务工具。

差别只在“composition（插件组合）”。

9.2 它比标准模式多了什么

通常包括三类能力。

1. 运行时检查

可以查询 DSH 当前真实的：

  • Service 方法；
  • Config schema；
  • Tool schema；
  • Skill 列表；
  • 界面 Slot / theme token。

这解决了一个大问题：不用猜 API。

2. 插件管理

可以：

  • 列出已安装的 Bundle；
  • 安装/启用/停用/卸载；
  • 修改 profile 的插件选择；
  • 查看安装结果和警告。

这些操作会持久化到 profile，影响所有 Session，并在重启后保留。

3. 开发指引

创造模式会挂载一组 authoring Skill，告诉你：

  • 怎么写 Cordis 插件；
  • 怎么写 Bundle patch；
  • 怎么创建/覆盖 Preset；
  • 怎么验证插件真的生效。

它还会提供模板和参考资料，按需加载。

9.3 什么时候该用

适合：

  • 想给 DSH 加一个工具；
  • 想加一个界面/按钮/面板；
  • 想做一个自定义模式；
  • 想调试“插件为什么没加载”；
  • 想把自己的工作流封装成插件。

不适合：

  • 日常写代码；
  • 普通文件整理；
  • 只是想让 Agent 帮你查资料；
  • 你不需要扩展 DSH 的时候。

原因：

  • 多出的工具和 Skill 会占用上下文；
  • 插件安装是高风险操作；
  • 日常任务用标准模式更轻。

9.4 安全边界：这是高信任模式

创造模式可以做很多“普通模式不能做”的事，因为：

  • 安装插件会在 Host 进程执行代码；
  • 修改 profile 会影响所有 Session；
  • 插件可能读写文件、访问网络、运行命令；
  • 这些代码在 workspace sandbox 之外执行。

所以：

  • 插件管理通常需要 full access 或逐次审批；
  • 不要给不信任的代码 full access；
  • 先在测试 profile/工作区试；
  • 重要配置先备份；
  • 出问题要能停用/回滚。

创造模式不是“安全模式”，它是“高信任的扩展模式”。

9.5 一次完整的“做插件”流程

下面是一个通用流程，不要求你会写代码，但要求你能描述目标和验收。

第 1 步：描述能力

不要一上来就说“帮我写个插件”。先说清楚：

我想给 DSH 加一个能力：
- 它做什么；
- 在哪里使用（聊天/按钮/面板/工具）；
- 输入是什么；
- 输出是什么；
- 怎么验证它成功；
- 不需要做什么。

第 2 步：让它先检查

先不要写代码。
请用运行时检查工具，确认：
1. 这个能力应该挂在哪一层（Host 插件 / Preset 插件 / 纯配置）；
2. 可用的 Service / Slot / Tool API；
3. 是否需要新的 Bundle；
4. 有没有现成模板。
把结论和风险列给我。

第 3 步：做最小版本

先做一个最小可用版本。
不要做额外功能、不要做多个变体。
给出文件清单、安装方式、验证步骤。

第 4 步：安装并验证

安装到当前 profile。
安装后告诉我：
- 安装结果（applied / warnings）；
- 新增了哪些工具/Skill/界面；
- 怎么验证；
- 怎么卸载。

第 5 步：修复与迭代

只修观察到的问题，不要无限加功能。

第 6 步：收尾

请给出：
- 插件位置；
- 安装/卸载方式；
- 已验证的内容；
- 未验证的内容；
- 已知限制。

9.6 不会编程的人怎么参与

你不需要自己写代码，但你需要做三件事：

  1. 说清楚目标：用户是谁、在什么场景、输入输出是什么；
  2. 审查结果：它有没有做你没要求的事？有没有权限过大？
  3. 验收：按你定义的场景试一遍，不通过就具体反馈。

你可以要求：

不要只告诉我“完成了”。
请给出：
- 改了哪些文件；
- 新增了哪些能力；
- 我怎么手动验证；
- 如果失败，怎么回滚。

9.7 案例：把 GetNote CLI 做成一个 DSH 插件

前面几节讲的是方法。这一节用一个真实项目走一遍：GetNote（得到大脑）工具箱。

做这个插件的直接动机是：在我们开始的时候，官方 @getnote/dsh-plugin 还不支持 DSH Desktop[2]。Desktop 是大多数人日常使用的入口，所以我们需要一个能在本机 Desktop profile 里真正跑起来的版本。

这不是要替代官方插件，而是补上 Desktop 这个入口。也正因为如此，项目优先处理 Desktop 的本地 bundle、locale/icon 展示、CLI 发现和 Plugin Manager 可见性。

它的目标不是“照着某个插件抄几个工具”，而是把本机 getnote CLI 变成一组 Agent 能稳定使用的 Host 工具。代码已经公开：

https://github.com/leether/getnote-toolbox

源码已经公开，并已发布到 npm：@leether/getnote-toolbox。[1]

安装时可以通过 DSH Plugin Manager 使用 npm bundle，也可以在开发时从源码本地 link。

第一步：先审计能力，不要先写工具

先列 CLI 的 --help、输入输出、副作用、认证方式和版本差异，再决定哪些能力值得做成 Tool：

  • 高频、需要结构化参数、需要安全护栏的，做成 Tool；
  • 低频、复杂、变化快、需要领域判断的，留给 CLI 或 Skill；
  • 互逆操作要成对出现，比如 add / remove；
  • 不做通用 run_command 或任意 HTTP 透传。

这个项目最后有 15 个工具，覆盖搜索、保存、读取、更新、删除、标签、知识库和配额。15 不是目标；每个工具都要能回答“它替模型承担了哪项契约、护栏或归一化工作”。

第二步：把“能跑”变成契约

真正花时间的不是 spawn 一行命令，而是这些细节：

  • 19 位笔记 ID 一律按字符串处理，避免 JSON number 丢精度；
  • 列表的 limit 在旧版 CLI 上可能失效，插件在解析后自行截断；
  • 删除必须显式 confirm: true，标签删除要用标签 ID；
  • 参数以数组传给 spawn，不经过 Shell；
  • 超时、输出体积、登录失效都要给出可操作的错误；
  • 用 Config schema 暴露 binaryPath、timeoutMs 等字段；
  • 配一个 Skill，告诉 Agent 什么时候该用哪个工具。

到这一步，插件才从“命令包装”变成“模型可用的接口”。

第三步：假 CLI 做单测，真 CLI 做验收

测试不碰真实账号：仓库里的 fake CLI 覆盖 ID 精度、嵌套响应、旧版 -y 回退、标签回读、知识库 add / remove 等 28 个测试。

然后再用真实 CLI 做一次只读冒烟测试。真实输出可能包含笔记片段，所以：

  • 不把输出贴进 issue、聊天或提交；
  • 写测试只使用合成 ID；
  • 涉及写操作时，先建测试笔记，结束后清理。

第四步：先做隐私和公开审查，再公开

这是这个案例最重要的部分。代码能跑，不等于可以公开。

公开前我们逐项处理了：

  • 评测报告：evals/results/ 里有当前账号的笔记 ID、标题和对比结果，不能进公开仓库；
  • 内部草稿：给上游提 issue / PR 的 contrib/ 文档包含本机路径和操作计划，不公开；
  • git 历史：旧历史使用个人邮箱；公开版改用全新历史，提交作者用 noreply；
  • 包名：本机用户名 scope 改成公开身份 scope，避免把本地账号带出去；
  • 环境信息：删除“当前机器已 link 到某个 profile”这类描述；
  • 敏感扫描：检查密钥、Token、邮箱、绝对路径、.env、长数字 ID 和评测输出；
  • 文件清单：只保留受审的源码、测试、许可证和公开文档。

原则很简单：

先审查，再公开；不是公开后再删。

结果与边界

这个插件现在是公开源码项目，15 个工具、28 个测试，代码使用 MIT。它还有几个明确边界：

  • 与官方 @getnote/dsh-plugin 使用相同的 getnote_* 工具名，不能同时安装；
  • 本机 CLI 版本会影响 ID、limit 和确认 flag，建议固定 binaryPath 并验证版本；
  • npx 兜底会下载最新 CLI，在意供应链风险时应改用本地固定版本；
  • 它不是一个“万能 GetNote 插件”，很多低频能力仍应交给 CLI 或领域 Skill。

这个案例真正可复用的，不是 15 这个数字，而是四步：能力审计 → 契约设计 → 假 CLI 测试 → 隐私审查后再公开。

延伸阅读：认知篇《从 CLI 到 DSH 插件：一套让 Agent 少走弯路的判断顺序》已经发布，见 cognition.html。

9.8 常见误区

  • “创造模式是高级版标准模式”：不是。它是扩展模式。
  • “装插件只是改配置”：不是。插件可能执行代码。
  • “装了就会自动生效”：不一定，可能需要重载/重启。
  • “Preset 可以当沙箱”：不可以。
  • “让 Agent 直接改 profile 文件”：不要，用 Plugin Manager。
  • “一次做很大”：先最小版本，再迭代。

马上试试

  1. 新建一个创造模式任务；
  2. 不要安装任何东西；
  3. 让它列出当前可用的运行时检查能力；
  4. 问它：“如果我要加一个只读工具，应该挂在哪一层？为什么？”
  5. 读它的回答，不执行。

小结

  • 创造模式是 cordis Preset，不是模型/运行时。
  • 它多出运行时检查、插件管理、开发指引。
  • 适合扩展 DSH，不适合日常任务。
  • 插件代码在 Host 执行，必须有信任和回滚方案。
  • 先最小版本，再验证、再迭代。
  • 真实案例：先做能力审计与契约，再做隐私审查，最后公开。

参考

  1. GetNote Toolbox 插件仓库
  2. 官方 GetNote DSH 插件
  3. DeepSeek Harness 插件开发

链接均为公开来源；产品行为可能随版本变化。

↑