# build-dsh-plugin Skill 完整介绍

## 一、Skill 是什么

`build-dsh-plugin` 是一套用于规划、生成、审计、调试、打包、发布和验收 DeepSeek Harness（DSH）插件的 Agent Skill。它把过去多个 DSH 项目中积累的宿主兼容性、Bundle 结构、工具卡片、权限设计、Profile 写入、安全测试、版本发布和真实运行验收经验，整理成可重复执行的标准流程。

它解决的核心问题不是“怎样快速写出一个看起来像插件的项目”，而是“怎样把一个产品想法稳定地转换成标准、可安装、可验证、可回滚且不破坏 DSH 的插件工程”。

仓库同时提供两种入口：`build-dsh-plugin/` 可部署到 Codex、Claude、Grok 等兼容 `SKILL.md` 的 Agent；仓库根目录是标准 DSH Skill Provider Bundle。DSH `0.1.2-alpha.4`、`alpha.5` 与 `rc.1` 的公开 SkillRegistration 接口一致，并通过隔离文件系统 Provider 的安装、配置合成与冷启动。DSH 适配层不安装其他 Agent Runtime、不运行生命周期脚本，也不修改官方 Skill Provider。

## 二、适合处理哪些任务

它可以用于：

- 根据自然语言需求直接创建新的 DSH 插件源码；
- 创建 Host-only、Host + Browser Client 等标准 Bundle；
- 为模型 Tool 设计 DSH `presentCall`、`presentResult` 和 `presentationMeta` 卡片契约；
- 创建 Skill Adapter、外部 CLI 适配器或 ApiProxy Bridge；
- 设计插件商城、Catalog、插件清单和版本检查能力；
- 判断现有第三方仓库为什么不能进入 DSH STORE，并给出直接上架、单仓库多包、适配器或阻断路线；
- 从开发第一天生成商城兼容的 Manifest、Patch、Entry ID、生命周期、许可证，并严格分开无安装能力的发现候选与可信 Catalog 提案；
- 设计需要安装、更新、启停、卸载或迁移插件的生命周期管理器；
- 判断第三方项目能否作为 DSH 插件安装；
- 审查现有项目是否符合 DSH Bundle、权限和安全要求；
- 规划 GitHub Release、商城发布和固定 Commit 来源；
- 区分源码完成、自动测试、隔离安装、真实 Profile、真机和公网验收；
- 对高风险 Profile、重启、远控和凭据能力设计确认与回滚协议。

当用户提出“做一个 DSH 插件”“把这个项目接入 DSH”“审计这个 DSH 插件”“给插件增加界面、联网、移动控制或更新能力”等请求时，都可以调用它。

## 三、用户需要提供什么

Skill 将产品意图和技术实现分开。用户不需要先理解 Cordis、Bundle Patch、Client Slot、ApiProxy 或事务协议，只需要说明产品层面的事实。

最少需要三项信息：

1. 现在遇到什么问题；
2. 希望插件带来什么结果；
3. 怎样才算成功，至少给出一条可观察的验收标准。

推荐输入模板：

```markdown
使用 `$build-dsh-plugin` 直接生成 DSH 插件源码。

插件名称：（可选）
目标用户：（可选）
现在遇到的问题：
希望达到的结果：
核心能力：（可选）
需要模型工具/卡片：（可选，只需说明希望用户看到什么）
需要读取的数据：（可选，默认无）
需要执行的动作：（可选，默认只读）
需要界面：（可选，默认 Host-only）
外部依赖：（可选，默认无）
明确不能做什么：（可选，默认套用 DSH 红线）
怎么才算成功：
交付位置：（可选）
希望上架 DSH STORE：（可选；默认只保持商城兼容结构，不提交）
第三方 GitHub 仓库：（评估现有插件时提供）
```

用户也可以直接给一段自然语言，或者使用 Skill 内置的结构化 JSON Brief。只要问题、目标和成功标准清楚，Agent 就可以直接开始生成源码，不再要求用户回答一套宽泛的技术问卷。

## 四、Skill 会自动推导什么

用户提供产品意图后，Skill 会自动完成以下技术工作：

- 判断目标是否真的属于 DSH，还是原生 Obsidian、VS Code、浏览器、桌面或 MCP 项目；
- 给出 `compatible`、`adapter-required` 或 `incompatible` 的宿主结论；
- 推导 `R0–R3` 风险等级；
- 比较 Host-only、Host + Client、Optional Web、Skill Adapter、ApiProxy 和 Lifecycle Manager；
- 生成包名、Entry ID、Manifest、`dsh.bundle.patch` 和 `cordis.patch.yml`；
- 设计 Host 服务、Client Slot、Route、Schema、权限矩阵和失败模型；
- 为每个模型 Tool 分开设计规范 JSON、模型渲染、pending/completed 卡片、持久化元数据、通用降级与 live/replay 测试；
- 设计输入校验、脱敏、大小限制、限流、超时、清理和 fail-closed 行为；
- 生成单元、契约、负向、安全和故障注入测试；
- 规划一次性 DSH_HOME/Profile 的 E3 隔离验收；
- 运行静态量化审计并给出下一道门；
- 推导 `direct`、`monorepo`、`adapter-required` 或 `blocked` 商城路线；
- 先生成 `installable: false` 且没有允许操作的发现候选；晋级时再检查固定 Commit、Manifest、Patch、Entry ID、生命周期、许可证、权限、固定源时间、四级可信证据、实时官方最新三个 DSH 版本的操作证据、分类和重复身份；
- 区分仓库发布与真实 Profile 安装；
- 区分候选发现、晋级审查、固定来源验证、Registry CI、合并 Catalog、公开页面与真实安装；
- 明确哪些事项仍需要用户授权、凭据、设备或公网环境。

## 五、安全默认值

当用户没有提供可选信息时，Skill 不会停下来反复询问，而是采用公开、保守、可覆盖的默认值：

- 默认模式为生成源码，不自动安装或发布；
- 默认使用标准 DSH Bundle；
- 默认只读，不写 Profile 或用户数据；
- 默认由用户明确手动触发，不增加后台自动行为；
- 默认 Host-only，只有用户需要界面时才增加 Client；
- 默认从 Tool 语义推导 DSH 卡片并保留 generic fallback，不创建或覆盖官方 Tool 的自定义 Client 卡片；
- 默认无外部网络、进程、账号、凭据或设备；
- 默认仅本机访问，不开放 LAN 或公网控制口；
- 默认不重启 DSH；
- 默认不修改真实 Profile；
- 默认不发布 GitHub 或商城版本；
- 默认仍采用可上架的标准包结构，避免发布前重做工程，但不会静默修改 DSH STORE；
- 默认目标是 E3 一次性 Profile 验收；
- 默认不修改 DSH 核心、`@deepseek-ai/*`、官方插件或官方清单。

这些默认值会被明确列为假设。用户可以覆盖，但只要覆盖会扩大权限、写入面或外部暴露，就必须重新评估风险和证据要求。

## 六、标准架构模式

Skill 根据目标选择或组合以下模式：

### 1. Host-only Bundle

用于工具、服务、只读分析或不需要 Browser UI 的能力。优点是结构最小、权限集中、测试简单；缺点是没有可视页面。

### 2. Host + Browser Client

用于设置页、Dashboard 或 Slot UI。Host 保留 Node、文件、进程和 Profile 权限，Client 只显示经过窄化和脱敏的数据。优点是权限隔离清楚；代价是需要维护 Host API、Client 加载、错误状态和双端契约。

### 3. Optional Web

需要 Web Route 时，通过延迟注入处理 `webServer`，保证 headless 或无 Web Profile 仍能启动。优点是兼容更多 Profile；代价是生命周期和测试更复杂。

### 4. Skill Adapter

用于把外部 CLI 或已有 Skill 接入 DSH。适配包、外部 Runtime、账号和具体渠道分开安装与验收，不能因为适配包加载成功就声称外部功能全部可用。

### 5. ApiProxy Bridge

用于移动端、远程设备或窄化的 DSH 控制。必须使用明确白名单、字段脱敏、认证、加密、大小限制和重放防护，禁止直接代理整个 Host API。

### 6. Lifecycle Manager

用于安装、更新、启停、卸载、迁移或重启。它属于 R3，任何真实操作都必须通过一次性计划、精确确认、前置哈希、备份、原子写入、健康检查和回滚。

### 7. Tool Card Contract

用于模型 Tool 的用户可见展示。规范 JSON 给程序调用，`output.render` 给模型，`presentCall`/`presentResult` 给 DSH 客户端，必要的结果期结构通过有界 JSON `presentationMeta` 持久化。优点是跨客户端、可回放和可降级；代价是必须维护纯函数、字段限额、脱敏、旧记录降级和 replay 测试。只有内置卡片语义无法满足插件自有 Tool 时，才考虑自定义 Client Slot；不能覆盖官方 Tool 卡片 key。

## 七、十二阶段工作流

Skill 使用阶段门管理完整生命周期：

1. **结果简报**：把功能想法变成用户结果和成功标准；
2. **宿主契约**：确认目标属于 DSH 或需要适配器；
3. **风险与信任边界**：识别资产、角色、写入、外部系统和恢复责任；
4. **架构决策**：比较不同实现模式的能力、权限、成本和运维影响；
5. **接口与权限设计**：确定 Schema、调用方、脱敏、限制、失败、禁止动作和 Tool 卡片矩阵；
6. **实现**：生成标准 Bundle、Host、Client、Patch、唯一 ID、显式生命周期和测试；
7. **自动化验证**：执行语法、单元、契约、负向、安全、卡片 replay/fallback/bounds、事务故障和商城预检；
8. **一次性运行验收**：在隔离 DSH_HOME/Profile 中安装、合成和启动，核对 Tool 卡片 live/replay；
9. **仓库发布**：同步版本、README、固定 Commit 和公开回读；如需商城，另外生成并验证 Catalog 候选；
10. **真实 Profile 验收**：在独立确认后安装、重启和读取真实状态；
11. **真机、账号、公开商城与公网验收**：读取合并 Catalog 和公开页面，或获得其他 E5 证据；
12. **交付与复盘**：保存问题、原因、选择、优势、代价、证据和重评条件。

每个阶段只能是 `PASS`、`PARTIAL` 或 `BLOCKED`。`PARTIAL` 必须说明缺什么以及仅允许的下一步；`BLOCKED` 会停止写入、安装或发布。

## 八、风险等级

- `R0`：只读清单、元数据和 UI 投影；
- `R1`：Host 工具、导入导出或插件自有状态写入；
- `R2`：外部进程、网络、OAuth、凭据、设备或桥接；
- `R3`：Profile 生命周期、重启、远程控制或广域管理。

风险等级决定测试和验收强度。不确定时使用更高等级；增加权限、网络、凭据、设备、重启或 Profile 写入后必须重新分级。

## 九、证据等级

- `E0`：需求、想法和计划；
- `E1`：Manifest、Patch 和源码静态检查；
- `E2`：单元、契约和故障注入测试；
- `E3`：一次性 Profile、配置合成、隔离启动、API/UI Smoke；
- `E4`：真实 Profile 的版本、进程、官方清单/API 和可见 UI；
- `E5`：真机、真实账号、公网流量及对应恢复或回滚。

证据不能跨级替代。HTTP 200 不证明 UI 可见，安装命令成功不证明重启健康，模拟器不证明真机，仓库发布也不证明本机 Profile 已升级。

## 十、100 分量化门禁

Skill 的只读审计由 80 分静态工程质量和 20 分当前运行证据组成：

- 宿主契约：16 分；
- 不破坏 DSH：16 分；
- 写路径事务纪律：16 分；
- 打包、版本和固定来源：12 分；
- 测试与故障注入：12 分；
- 文档和状态边界：8 分；
- 当前运行证据：20 分。

分数用于判断下一步，不是操作授权：

- 90–100：可以提交受控真实 Profile 验收计划，仍需确认；
- 75–89：可以进入一次性隔离验收；
- 60–74：先补实现、测试或打包缺口；
- 低于 60：重新判断宿主、架构和范围。

任何硬阻断都会覆盖分数。例如修改 DSH 核心、遮蔽官方清单、Client 接收秘密、使用 Shell 字符串执行 Profile 操作、测试写真实 `~/.dsh`、没有回滚的 Profile 写入等，都会直接标记为 `BLOCKED`。

## 十一、真实写入协议

安装、更新、启停、卸载、迁移和重启必须分别创建一次性计划。计划需要包含：

- 具体操作和目标 Profile；
- 包名、版本和不可变来源；
- 精确文件范围与写前 SHA-256；
- 固定 executable、argv、cwd，并明确 `shell=false`；
- 备份位置；
- 配置、进程、端口、官方清单/API 和 UI 健康检查；
- 回滚步骤；
- 唯一确认语；
- 过期时间和 single-use 状态。

目标、来源、哈希、确认、过期时间或使用状态任一变化，计划立即失效。仓库 Release 不授权真实 Profile 更新，重启也必须作为独立操作确认。

## 十二、内置工具

Skill 包含四类主要脚本：

### Brief 归一化器

```bash
node scripts/normalize-brief.mjs /path/plugin-brief.json
```

输出需求完整度、源码生成状态、风险等级、候选架构、建议包名、安全假设、源码阻断、真实操作阻断和下一步。

### Brief 自测

```bash
node scripts/test-normalize-brief.mjs
```

验证 R0、R3、最小输入、缺失关键字段和疑似秘密五类场景。

### 插件静态审计

```bash
node scripts/audit-plugin.mjs /path/to/plugin
node scripts/audit-plugin.mjs /path/to/plugin --json
```

审计 Bundle、Client、Tool 卡片 discriminant、Presenter 纯度信号、replay/fallback/bounds 测试、权限、Profile 事务、打包、来源和文档，并输出 `/80 + /20`。它不会自动证明真实运行。

### DSH STORE 上架预检

```bash
node scripts/audit-marketplace-entry.mjs /path/to/plugin \
  --entry /path/to/catalog-entry.json \
  --registry /path/to/current/catalog.json
node scripts/test-marketplace-entry.mjs
```

预检会判断直接上架、单仓库多包、需要适配器或阻断，核对固定 GitHub Commit、Manifest、Patch、Entry ID、生命周期、许可证、权限、兼容性、分类和重复包名，并输出最小整改与下一道门。它不会证明 Registry PR 已合并或公开页面已经显示。

所有脚本使用 Node.js 18 或更高版本，不依赖第三方 npm 包。

## 十三、核心边界

Skill 始终坚持：

- 不修改 DSH 源码或 `@deepseek-ai/*`；
- 不禁用、替换或遮蔽官方插件清单；
- 不调用 Loader/Fiber 变更 API；
- 包操作只使用官方 DSH CLI 固定参数数组；
- 自动测试只使用一次性目录和 Profile；
- Client 不接触 Node、Host、凭据或完整用户文件；
- Tool Presenter 不做 I/O，不读当前会话/Profile，不依赖时钟、随机数或可变全局状态；卡片元数据必须有界、可序列化、可回放并保留 generic fallback；
- 外部桥只开放白名单，不提供任意 Shell、文件、设置或插件管理；
- Git/商城来源固定到完整 Commit；
- 未验证的权限或兼容性显示 unknown；
- 插件仓库、Catalog 候选、DSH STORE 贡献分支和真实 Profile 保持独立写入范围；
- 商城候选、Registry CI、合并 Catalog、公开页面和 Profile 安装分别报告；
- 规划、源码、测试、发布、安装、运行、UI、真机和回滚分别报告。

## 十四、使用示例

```markdown
使用 `$build-dsh-plugin` 直接生成 DSH 插件源码。

插件名称：DSH 会话健康概览
现在遇到的问题：会话很多时，很难快速找到失败或长时间无响应的任务。
希望达到的结果：在 DSH 设置页看到异常会话及原因摘要。
核心能力：读取状态、筛选异常、展示有界详情。
明确不能做什么：不能修改会话、DSH 核心和真实 Profile。
怎么才算成功：一次性 Profile 中页面可见；异常夹具分类正确；真实 Profile 保持不变。
```

预期行为是：Skill 归一化 Brief，公开假设，判断为 R0，选择 Host + Client，设计只读权限与测试，直接生成源码并推进到隔离验证；它不会在没有新授权时安装到真实 Profile 或发布到外部仓库。

## 十五、部署与兼容性

在 Codex 中，将完整的 `build-dsh-plugin/` 目录放到 skills 目录，并确保入口是 `build-dsh-plugin/SKILL.md`。在支持 `SKILL.md` 的其他 Agent 中，也应保持 `references/`、`assets/` 和 `scripts/` 的相对结构。

在 DSH 中，安装仓库根目录的 Bundle，而不是 Agent Skill ZIP。Bundle 的唯一 Patch 条目为 `dsh-build-plugin-skill-provider`，只扫描本仓库的 Skill 根。真实 Profile 安装仍需单次计划和确认；E3 必须在首次 CLI 调用前设置临时 `DSH_HOME`。不要用真实 DSH home 下不存在的 Profile 运行 `dsh plugin --profile <name> --help`，因为 CLI 可能先创建 Profile 再显示帮助。

如果目标 Agent 没有原生 Skill 机制，可以把 `SKILL.md` 作为任务级系统/工作流指令加载，并允许它按相对路径读取参考文件。此时核心方法论仍然可用，但自动触发、UI 元数据和脚本执行能力取决于目标 Agent。

## 十六、明确限制

- Skill 不自带 DSH Runtime，也不会自动安装 DSH；DSH Bundle 要求 `>=0.1.0-rc.8 <0.2.0` 的 Skill Filesystem Provider，当前最新窗口为 `0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`。三个版本的公开接口已核对并完成隔离安装、配置合成与冷启动；
- 静态评分不能证明运行、UI、真机、公网或回滚；
- 外部项目仍需重新检查当前宿主和许可证；
- DSH 版本、Profile、Catalog、网络和依赖变化后，旧证据可能失效；
- DSH STORE schema、分类、保护 ID 或审核策略变化后，必须重新读取当前 Registry 契约再提交；
- 没有设备、账号、凭据或发布授权时，相关结果必须保持 partial 或 unverified；
- Skill 能自动生成技术方案，但不能替用户决定产品目标、敏感数据授权和真实系统操作权限。

它的最终价值，是让每个 DSH 插件都从统一、可解释、可量化、可回滚的起点开始，而不是重复踩宿主错误、权限扩张、版本漂移和证据过度声明的问题。