插件构建器 kingjly/dsh-plugin-builder

dsh-plugin-builder

License: MIT
DeepSeek Harness
Agent Skill
Tests

中文文档

一个 Agent Skill，用于决策、构建、增量修改、验证、打包和管理可安装的 DeepSeek Harness（dsh）插件。

它在生成代码之前会选择最窄的受支持扩展点：工具、策略守卫、provider 接缝、LLM 适配器、Client Conversation Node、主题或 shell 贡献、协议桥接——或者根本不需要插件。有效的请求会变成独立的 TypeScript ESM 包，带有 dsh.bundle、开发覆盖层、设计记录、冒烟测试和验证命令。

已在 Windows 上使用 @deepseek-ai/dsh@0.1.0-rc.6 验证。Harness 仍处于开发者预览阶段，可能会引入破坏性变更。

真实、经过测试的展示

该仓库包含四个使用此 Skill 生成的插件。它们全部安装在本地 web profile 中，在 Settings 中可见，并通过实际的 Web UI 进行了测试。

| Package | 形态与扩展点 | 可见效果 |
| dsh-aurora-ui | 纯 Client Web UI；ctx.theme.register()、附加式 shell.overlay 和 ctx.layout | 使用青色/紫色 Aurora 主题为整个应用重新着色，并添加一个浮动控制器，用于主题、侧边栏和详情操作。 |
| dsh-luna-pet | 纯 Client Web UI；附加式 shell.overlay，内嵌 8×9 WebP 图集 | 复用用户现有的 Luna 宠物，带有无边框、可拖拽的覆盖层、持久化位置、九种动画和紧凑模式。 |
| dsh-release-readiness | Host tool + Client Conversation Node；ctx.tools.register() 和 conversation.chat.node | 模型提交有证据支持的关卡，Chat 渲染一个带警告和阻塞项的分级发布仪表盘。该卡片在服务重启后从核心 tool/result 元数据重放。 |
| dsh-command-safety | 单调策略守卫；ctx.tools.guard() | 看起来具有破坏性的 bash 或 pwsh 调用会在 shell 运行之前被拒绝，并在对话中显示匹配的规则。 |

全应用 Aurora 工作台

dsh-aurora-ui 注册了一个第三方语义主题，并贡献了一个附加式 shell 覆盖层。下面的真实控制器在 Aurora 和原始主题之间切换、折叠并恢复侧边栏，并在不替换第一方 shell 表面的情况下关闭详情面板。

Real DeepSeek Harness Aurora Web UI plugin

动画 Luna 桌面宠物 dsh-luna-pet 复用用户现有的 Luna 图集，而不修改 ~/.codex/pets/luna。这张真实的 DSH Web 截图展示了 Luna 被拖离输入区域后的无边框浮层。拖动 Luna 本身即可重新定位她；经视口钳制后的位置在重新加载后依然保留。这些控件可在 idle、work、wait、review、patrol 和 failure 状态之间切换，而悬停、点击和紧凑模式则保留其原有的交互方式。

DeepSeek Harness 中真实的无边框且可拖动的 Luna 宠物

发布仪表盘

一个已配置的第三方模型名为 release_readiness，带有五个真实项目门禁。该插件计算出 90/100，渲染出四项通过和一项警告，并且在重启 Harness 后再次验证了同一张卡片。

真实的 DeepSeek Harness 发布就绪仪表盘

命令拒绝

该模型针对一个已确认不存在的路径尝试了一次 Remove-Item -Recurse -Force 探测。dsh-command-safety 在 PowerShell 运行之前就拒绝了它，并显示出确切匹配的策略。

真实的 DeepSeek Harness 命令安全拒绝

可搜索的插件清单

在 Settings → Plugins → Plugin list 中搜索 showcase，会返回所有四个已挂载并启用的条目。

真实的 DeepSeek Harness 插件清单搜索

这五张图片均直接截取自 http://127.0.0.1:3080 上运行的本地实时服务；它们并非生成或合成的。

安装 Skill

将仓库克隆到你的 agent 客户端所扫描的 Skill 目录中。保持文件夹名称为 dsh-plugin-builder。

git clone https://github.com/kingjly/dsh-plugin-builder.git "$HOME/.grok/skills/dsh-plugin-builder"

常见位置：

~/.grok/skills/dsh-plugin-builder/ # Grok
~/.claude/skills/dsh-plugin-builder/ # Claude Code
.agents/skills/dsh-plugin-builder/ # project-local clients

当 SKILL.md 存在于该目录根目录时，Skill 即已就绪。

使用它

显式调用：

/dsh-plugin-builder Create a release-readiness tool with a replayable Web conversation card. Package it as an installable bundle and test it locally.

为获得最精确的结果，请说明能力与副作用、输出目录、所需的交付形式（--patch、可安装包，或两者兼有），以及凭据环境变量名称。切勿将实时密钥粘贴到生成的文件中。

默认值为：树外 Host 插件、TypeScript ESM、web 配置文件、不修改 agent 循环，以及在安装前进行本地浮层测试。

修改现有插件

该 Skill 可以更新现有的树外插件，而无需重新生成其脚手架。将其指向该包并描述所需行为：

/dsh-plugin-builder Modify ./showcase/dsh-luna-pet: remove the outer card, make Luna draggable, persist her position, then rebuild and verify it in the real Web UI.
对于修改任务，Skill 首先审计当前包和扩展形态，然后保留包名、原始入口 id、配置键以及现有的持久化语义。它只更改必要的源代码和文档，重新运行静态验证器和包测试，并演练相关的 Host 或 Client 行为。Client UI 更改会在全新的浏览器页面中检查；依赖或 bundle 清单的更改仍然需要重启服务。

决策优先的工作流

| 请求 | 选定的扩展 |
| 添加结构化模型能力 | 使用 defineTool() 注册的 Tool |
| 拒绝或约束现有的工具调用 | 单调的 ctx.tools.guard() 策略 |
| 替换文件系统、shell、搜索、沙箱或子代理执行 | 现有的 Service Provider 接缝 |
| 添加或路由模型后端 | 优先配置 dsh-llm-pi-ai；仅在必要时编写适配器 |
| 添加可重放的 Chat 界面 | Host 结果/事件加上 Client Conversation Node |
| 更改整个 Web UI 或添加 shell 控件 | 使用语义主题和附加式 shell 插槽的 Client 插件 |
| 连接 IM、IDE 或自动化协议 | 基于 ctx.agents 的协议桥接 |
| 修改 agent-loop、复制 bash 或重写现有的 MCP 工具 | 拒绝并指向受支持的接缝 |

每个生成的包在实现之前都会在 plugin-design.md 中记录其选择。

运行 showcase

先决条件：Node.js 22+、pnpm、Python 3.10+ 以及 DeepSeek Harness。

pnpm add --global @deepseek-ai/dsh@0.1.0-rc.6
py -3 scripts/render_showcase_overlays.py
cd showcase
pnpm install
pnpm build
pnpm test

从源代码运行全部四个包：

dsh web --patch ./cordis.dev.yml

或者从仓库根目录将全部四个包安装到持久的 web 配置文件中：

$env:DSH_HOME = (Join-Path (Get-Location) '.dsh-home')
dsh plugin --profile web add .\showcase\dsh-aurora-ui .\showcase\dsh-luna-pet .\showcase\dsh-release-readiness .\showcase\dsh-command-safety
dsh --profile web --dump-config
dsh web --port 3080

插件安装和每次重启时始终使用相同的 DSH_HOME。不带它启动一次会打开不同的配置文件和存储根目录，这可能导致模型设置和对话看起来消失了，即使原始数据仍然完好无损。

在 Windows 上，cordis.dev.yml 中的本地 ESM 入口必须是 file:///C:/... URL。render_showcase_overlays.py 会为当前检出重新生成可移植的绝对导入说明符。

编译、静态验证、测试、bundle 安装或 --dump-config 不需要模型密钥。只有端到端对话才需要配置模型。

热启用和禁用已安装的插件

Skill 现在区分运行时状态与安装状态。对于保持安装并列出在 dsh.profile.bundles 中的包，向活动配置文件的 cordis.patch.yml 添加精确的条目覆盖：

- id: showcase-aurora-uimarkdown
disabled: true

设置 disabled: false（或仅移除该覆盖项）即可重新启用它。DSH 会监视用户补丁层，因此 Host 清单无需重启服务即可变更。已打开的浏览器页面可能仍需要刷新一次，才能加载或卸载某个 Client UI 贡献。

这与 dsh plugin add/remove 或编辑 profile 的 package.json 不同：那些操作会更改依赖和 bundle，并且需要重启服务。始终先解析活动进程实际的 DSH_HOME 和原始 bundle 条目 id；像 include:showcase-aurora-ui 这样的清单 id 是 Loader 路径，不一定是写入补丁的 id。

尝试可见效果

安装 dsh-aurora-ui 后，整个 Web UI 会切换到 Aurora，右下角的控制器可以恢复原始主题、切换工作区侧边栏，或关闭详情面板。

安装 dsh-luna-pet 后，拖动 Luna 本人即可移动无边框浮层；所选位置在重新加载后仍会保留。使用浮动控件可选择 Idle、Work、Wait、Review、Patrol 或 Oops。将鼠标悬停在 Luna 上可触发她的摸头回应，点击她可触发满足的动画，使用 Compact 可只保留动画宠物可见。

让模型调用 release_readiness，并显式指定诸如 Build、Tests、Documentation、Screenshots 和 Distribution 等门禁。每个门禁必须为 pass、warn 或 fail；仪表盘是确定性的。

对于安全演示，首先确认探测路径不存在： powershell Test-Path -LiteralPath .\__dsh_plugin_builder_nonexistent_probe__

然后让模型调用 pwsh，参数为： powershell Remove-Item -LiteralPath ".\__dsh_plugin_builder_nonexistent_probe__" -Recurse -Force

该策略应在 Chat 中拒绝此调用。示例规则仅用于说明；不要将其视为完整的沙箱。

生成的包契约 text dsh-/ ├── src/index.ts # name + inject + apply + Schemastery Config ├── src/client/index.ts # optional Web Client plugin: node, theme, or shell contribution ├── test/smoke.test.mjs # success, failure, and replay/guard paths ├── cordis.dev.yml # source overlay with absolute import specifier ├── cordis.patch.yml # installed bundle layer ├── plugin-design.md # shape decision and verification record ├── package.json # ESM + dsh.bundle + optional dsh.client ├── tsconfig.json └── README.md

验证生成的插件 powershell py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-release-readiness py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-command-safety py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-aurora-ui py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-luna-pet

校验器会检查 ESM 和 bundle 元数据、条目、导出的插件契约、Schemastery 配置、存在时的 Client 元数据、与随附工具名称的冲突、可能的硬编码凭据，以及无效的裸 Windows 路径。它是一个快速的静态门禁；真正的交付还应编译、运行测试、加载 overlay、检查 --dump-config，并演练 Web UI。

仓库地图

├── SKILL.md # 路由与交付契约 ├── assets/templates/ # ESM 插件与 bundle 模板 ├── references/ # 工具、guard、适配器、UI、生命周期、安全、发布规则 ├── scripts/ # overlay 渲染器与静态校验器 ├── showcase/ # 四个有意义、经过测试的插件 ├── examples/ # 请求夹具 └── evals/ # 评分标准、失败分类法、评估用例

重要限制

- DeepSeek Harness 处于开发者预览阶段；版本变更时请重新核对官方契约。
- 官方插件清单为只读。此 Skill 可以安全地编辑活动 profile 补丁，但当前 Settings 列表未暴露启用/禁用控件。
- 宿主条目会在运行中的进程内热切换；现有页面可能需要刷新后，Client UI 才会出现或消失。
- dsh-command-safety 是一个示例策略层，并非完整的 shell 沙箱或审批系统。
- dsh-release-readiness 将其 UI 载荷存储在核心 tool/result 展示元数据中，以便持久化会话保持可重放。
- dsh-aurora-ui 在运行时激活其自定义主题；Harness 仅持久化其内置主题偏好，因此该插件会在 Client bundle 挂载时重新应用 Aurora，并在被请求或卸载时恢复该偏好。
- dsh-luna-pet 在其 Client bundle 中嵌入了经过验证的 1.69 MB Luna WebP 图集（base64 嵌入后约 2.26 MB）。其第 3/4 行交互被有意命名为 petted 和 content，以匹配用户现有的美术资源，而非通用的 wave/jump 标签。
- Git 安装仅在包管理器构建权限允许时运行 prepare。优先使用可信、锁定提交的来源或预构建的 tarball。
- 这四个 showcase 包尚未发布到 npm。

许可证

MIT