plugin-builder — DSH 插件开发全流程

一句话原则：先问清、再设计；先实现、再测试；先审计、再交付；默认不安装。

本 Skill 的产物是一个完整、可检查、可交付的插件项目目录，不是代码片段，也不是方案文档。

0. 硬性边界（贯穿所有阶段，不可协商）

只要用户没有在本轮对话中明确授权，以下动作一律不做：

原因：用户要先读代码，再自己决定是否上传 GitHub、以及是否通过 GitHub 安装。开发任务与环境修改任务必须分离。

允许的写入范围：当前工作区内的新项目目录、本 Skill 的模板、用户明确指定的路径。工作区外的写入先问。

0.1 本 Skill 自带的工具

全部在 scripts/ 下，纯 Node（无第三方依赖），用绝对路径调用：

模板：

参考文档：references/requirements.md（提问策略）、references/ui-design.md（布局选型）、 references/security-audit.md（审计清单）、references/github-release.md（发布与安装边界）、 references/dsh-plugin-api.md（已核实 API 与待验证清单）、references/scenarios.md（行为验收场景）。

这两个脚本做的是能自动化的那部分检查。它们通过 ≠ 插件可用：slot 渲染、主题观感、 安装后行为必须真机验证，交付报告里要如实写明未验证项。

1. 流程与阶段门

接收需求
  ↓
阶段 0  事实核对（真实 API / 环境 / 已有项目）
  ↓
阶段 1  需求提取与缺口分析          ── 缺 P0 信息 → 提问
  ↓
阶段 2  插件命名                    ── 无名称/不合规 → 选项确认   ★必须问
  ↓
阶段 3  交互布局与配置位置          ── 未指定 → 选项确认         ★必须问
  ↓
阶段 4  需求总结                    ── ★确认门
  ↓
阶段 5  架构设计                    ── ★确认门
  ↓
阶段 6  项目结构与代码实现
  ↓
阶段 7  测试与构建
  ↓
阶段 8  代码审计 + 隐私检查 + 脱敏
  ↓
阶段 9  README 与文档
  ↓
阶段 10 GitHub 发布准备（只准备，不执行）
  ↓
阶段 11 交付报告 → 停止

跳阶规则：用户已经给出的信息直接复用，不许重问；但阶段 2、3、4、5 的确认门不能跳——除非用户明确说"你决定 / 不用问我"。此时按 references/requirements.md §5 的规则记录所采用的默认值，并在需求总结里逐条标注"（默认，可改）"。

分阶段交互（不要一次抛 10 个问题）：

1. 名称 + 核心功能
2. 交互布局 + 配置方式
3. 必要细节（数据来源、导出格式、默认行为等）
4. 设计确认

2. 阶段 0：开工前必须核实的事

不要凭印象写 DSH API。 按下列顺序查，查不到就标记"待验证"并告诉用户。

1. 加载官方插件开发 Skill：会话目录里有 cordis-plugin-development、cordis-composition-reference 时，先 skill 加载并按其指引读 reference（bundle 清单、Client 模块、slot 注册、安装边界）。
2. 实时检查（最权威）：
   • cordis_inspect_list — 看当前有哪些只读探针
   • cordis_inspect_query + Config.listConfigs — 查已装插件的 Config JSON Schema 与 packageDir
   • cordis_inspect_query + Slots.listSubTree（client）— 查真实 slot 名、kind、注册参数；root=<slot> 看单个 slot 的 props
   • cordis_inspect_query + Theme.listTokens（client）— 查主题 token
   • cordis_inspect_query + Service / Event — 查 Host service 方法与事件签名
3. 读包文档：<packageDir>/README.md；源码在 lib/index.js、lib/types/**/*.d.ts（安装版）或 src/（源码检出）。
4. 读现有插件：工作区里已有插件项目、$DSH_PROFILE_DIR/node_modules/dsh-* 都可以作为事实来源；但只学结构，不照抄业务。

产出（内部记录，交付时附在报告里）：

已验证：DSH 版本、bundle 声明方式、Host/Client 出口、可用 slot 列表、主题 token、安装命令
待验证：无法查证的字段 / 行为（写明为什么查不到、需要用户怎么验）

本环境已核实的事实见 references/dsh-plugin-api.md（含"待验证"清单，不随版本升级自动维护——每次开工仍要重新核对）。

3. 阶段 1：需求提取与缺口分析

先做一张已知信息表，只问空格子。

更细的提问策略、优先级（P0/P1/P2）和选项写法见 references/requirements.md。

只问真正影响设计的必要问题，不要把清单机械地问一遍。用户说"你决定"时，在授权范围内取合理默认值并登记。

4. 阶段 2：插件命名（必须交互）

4.1 命名规则

4.2 用户没给名称

不得替用户决定最终名称。 生成 3 个候选，每个包含：名称、功能含义、推荐理由；再给"自定义名称"选项。用 ask_user_question 把候选做成选项（推荐项放第一并标注 (Recommended)）。

示例输出格式：

根据"聊天界面美化"的需求，给出三个命名方案：

A. dsh-chat-beautify —— 聊天界面美化；适合综合性的聊天 UI 美化插件。
B. dsh-chat-theme   —— 聊天主题管理；适合以主题切换与样式配置为核心。
C. dsh-chat-style-customizer —— 聊天样式自定义；词长，适合配置项非常丰富的插件。

请选择：
1. A   2. B   3. C   4. 自定义名称

用户选定后再按 4.1 复核一遍，不合规就改并说明改了什么。

4.3 用户已经给了名称

• 合规且与功能匹配 → 直接采用，不重命名。
• 不合规（如 ChatBeautify、dsh chat beautify、my-dsh-plugin）→ 给出最小改动的修正建议（dsh-chat-beautify），并问是否接受。
• 名称与功能明显错位（名为导出、实际做主题）→ 指出并问，不要擅自改名。

4.4 冲突检查的边界

有可靠检索能力时可以查 npm / GitHub 是否已有同名包；查不了就不许声称"已通过唯一性检查"，只能写"未验证，建议发布前自查"。

5. 阶段 3：交互布局与配置位置（必须交互）

根据插件实际功能问："你希望用户在哪里操作这个插件？"——按功能裁剪选项，不要六个全抛。

组合式方案必须说明每个区域各自承担什么，例如：

• 对话框：一句话触发导出、显示进度
• 侧边栏：导出入口与最近记录
• 设置页：默认格式、导出范围、字段开关

规则：

• 用户已指定布局 → 直接采用，写进需求总结，不再问。
• 不强迫每个插件都有侧边栏或设置页；纯 Host 工具插件可以完全没有 UI（要说明"没有界面入口，靠工具/命令触发"）。
• 插件的 Config（cordis.patch.yml 里的 config）与"设置页面"是两件事：前者是 Host 配置，后者是 UI。二者关系要讲清楚。
• slot 名、注册参数、props 必须取自实时 inspection，不靠记忆。详见 references/ui-design.md。

6. 阶段 4：需求总结（确认门）

用简洁结构展示，然后请用户确认或修改：

插件名称：dsh-session-export
主要功能：把选中的会话导出为 Markdown / JSON
功能模块：会话选择、内容选项、格式渲染、下载
交互方式：设置页面（settings.section）选择与导出；无对话框入口
配置需求：默认格式、默认包含项（写入 config，可留空用默认值）
UI 风格：简洁，跟随 DSH 主题 token
数据处理：只读会话日志；不写会话；不上传网络
关键约束：仅本机访问；导出内容不落盘到插件目录
默认值：格式=Markdown；范围=当前会话；不包含工具结果

关键需求仍不明确 → 继续问，不要进入架构。

7. 阶段 5：架构设计（确认门）

按需分析，不要过度设计：

• 插件入口：Host 半边做什么、Client 半边做什么；只做 UI 时 Host 可以是空实现
• 功能模块：UI 层 / 业务逻辑 / 配置 / 数据处理 / 工具函数
• 数据流：数据从哪来（会话日志、文件、网络）、经过什么、到哪去、是否持久化
• 外部依赖：能不用就不用；必须用时说明用途与许可证
• 权限与安全：文件读写范围、网络出口、是否读会话内容、是否需要用户确认
• 错误处理：失败时的用户可见反馈、降级策略、边界（大小、数量、超时）
• 日志：只记事件与错误，不记内容与凭据
• 测试方案：哪些能自动化（结构、语法、纯函数、静态断言），哪些必须真机验证

简单插件 3–5 个文件就够；复杂插件才拆 ui/、core/、config/、util/。项目结构参考 templates/project-structure.md。

向用户展示设计并确认关键决策（模块划分、数据是否离开本机、是否需要新依赖、UI 落点）。用户确认后再写代码。

8. 阶段 6：实现

实现纪律：

1. 先建目录，再按职责落文件；入口文件明确。
2. 只用已核实的 API。不确定的写法先做最小验证，或标"待验证"并告知。
3. 必须有错误处理：网络失败、文件不存在、权限不足、数据为空、超大输入。
4. 配置有默认值，缺省即能跑；非法值回落到默认值。
5. 关键操作有用户可见反馈（成功 / 失败 / 进行中）。
6. 不擅自增加收集数据、上报、遥测、自动执行的能力。
7. 不在代码里写死绝对路径、用户名、密钥。
8. UI 用主题 token（--dsw-alias-*）与 locale 文案，不自造配色、不硬编码中文到组件里。
9. 卸载要干净：所有注册都挂在 ctx.effect / ctx.on 上并返回清理函数。

文件职责（最小可用 bundle）：

可直接复制 templates/bundle-skeleton/ 起步（已按当前 DSH 校验过语法与结构），改名前先读一遍注释。

API 契约与常见坑见 references/dsh-plugin-api.md；UI 落点见 references/ui-design.md。

9. 阶段 7：测试与构建

至少检查：

• 目录结构完整，无遗漏的入口文件
• package.json 合法，exports / files / dsh.bundle.patch / dsh.client 指向真实存在的文件
• cordis.patch.yml 的 id、name 与包名一致，YAML 缩进正确
• 所有 .js / .mjs 通过语法检查（node --check）
• JSON 文件可解析；locale 含 meta.title / meta.description
• 图标格式、路径、大小合规
• 主要功能路径符合需求；错误分支有处理
• 纯函数 / UI 组件有可运行的自动化测试
• 隐私审计完成（阶段 8）

能跑就跑（两个脚本都在本 Skill 的 scripts/ 下，用绝对路径调用）：

# 结构与配置自检（命名/patch/入口/id/JSON/locale/图标/语法）
node "<skill>/scripts/check-project.mjs" "<项目目录>"

# 语法兜底：ESM 在部分环境中无法由上面的脚本校验，逐个跑
node --check index.js
node --check client.js

# 业务测试：直接执行，避免 node --test 在受限沙箱里 spawn 失败
node test/client.test.mjs

check-project.mjs 的退出码：0 无失败项，1 有失败项，2 参数或路径错误。 若它报告「当前环境无法校验 ESM」，说明 vm.SourceTextModule 不可用（常见于受限沙箱）， 必须再手动跑 node --check，不能把这条提示当作通过。

结果必须四分类表述，不许把未验证写成已完成：

构建失败先按错误修；修不动就停下来说明原因和用户需要执行的步骤，不要绕过去宣布完成。

10. 阶段 8：代码审计与隐私检查

三步，缺一不可：自动扫描 → 人工审计 → 修复并复扫。

10.1 自动扫描

node "<skill>/scripts/audit-scan.mjs" "<项目目录>"          # 人类可读
node "<skill>/scripts/audit-scan.mjs" "<项目目录>" --json   # 结构化
node "<skill>/scripts/audit-scan.mjs" "<项目目录>" --strict # 中危也算失败

退出码：0 无高危项，1 有高危项（--strict 时中危也算），2 参数或路径错误。

扫描覆盖：私钥/证书块（含 .pem/.key/.p12 等文件）、云厂商与平台 Key 前缀、 硬编码 Bearer、secret/token/password 式赋值、JWT、本地绝对路径、eval/new Function、 innerHTML、shell 拼接、出网调用、明文 HTTP、日志打印数据体；外加 bundle 结构检查 （命名规范、dsh.bundle.patch、Client 模块 id 与包名一致性、locale 元数据）。

扫描器是筛查不是保证：命中要人工判断（很多是真正的需求），未命中不代表安全。 占位符（<YOUR_API_KEY>、your-token-here、process.env.X）会被降级为提示，不误报高危。

10.2 人工审计

逐项过 references/security-audit.md 的清单，重点：

• 凭据：Key / Token / 密码 / Cookie / 私钥是否出现在代码、配置、示例、日志、README、测试夹具
• 隐私数据：聊天记录、文件内容、账号信息是否被读取、外发、写盘、写日志
• 网络：请求发往哪里、是否 HTTPS、是否可关闭、失败是否静默
• 文件：读写范围是否最小、是否可能越界（..、绝对路径、符号链接）
• 注入：innerHTML、eval、new Function、拼接 HTML、命令拼接
• 权限：调用了哪些 Host service、是否超出功能所需
• 依赖：新依赖是否必要、许可证是否可分发、是否引入安装脚本
• 发布面：.gitignore、示例配置、测试夹具、文档截图、本地绝对路径

10.3 修复与复扫

发现敏感信息：先删/换成占位符，再改成从环境变量或凭据服务读取，再检查日志与示例，再扫一遍，最后写进报告。

• 真实凭据已泄露过 → 明确提醒用户撤销或轮换。
• 曾写入 Git 历史 → 说明"改当前文件 ≠ 清历史"，给出去史建议（git filter-repo 等），但不代为执行。

10.4 审计报告

用 templates/audit-report-template.md 生成 AUDIT.md（或写入交付报告），必须包含：审计范围、检查项、发现的问题、已修复、未解决、隐私处理结果、是否发现真实凭据、是否可安全交付。

审计必须产出可见结果，不能只在内部过一遍。

11. 阶段 9：文档

生成 README.md（模板：templates/README-template.md），至少包含：

插件名称 · 功能介绍 · 功能列表 · 使用方式 · 配置说明 · 项目结构 · 依赖说明 · 隐私说明 · 安全注意事项 · 开发说明（构建 / 测试 / 关键 API）

若要配置：给示例配置、安全默认值、明确哪些字段必须由用户填写、不含真实凭据。

复杂项目补 docs/：目录说明、模块说明、关键 API、构建与测试方法。文档必须与实现一致，不描述不存在的功能。

12. 阶段 10：GitHub 发布准备（只准备，不执行）

准备：README.md、LICENSE（建议 MIT，注明版权人）、.gitignore、.gitattributes、示例配置、依赖说明、发布说明草稿、审计结论、目录结构。

发布前自查：

• 结构清晰，入口文件明确
• 配置与示例无真实凭据
• README 有可验证的安装与使用说明
• 安装说明基于真实 DSH 机制（dsh plugin --profile <name> add <spec> 或插件页添加）
• 无本地绝对路径（C:\Users\...、/home/...）
• 无临时文件、构建产物、调试日志、测试敏感数据
• .gitignore 覆盖 node_modules、.env、日志、个人配置

默认不做：上传 GitHub、建公开仓库、git commit、打 tag、发 Release。这些必须用户明确授权。详细清单见 references/github-release.md。

13. 阶段 11：交付报告（然后停止）

按此结构输出，不允许把未测试项写成已完成：

### 插件信息
- 名称：
- 功能：
- 交互布局：

### 实现情况
- 已实现：
- 未实现：
- 需要用户配置：

### 测试结果
- 实际运行：
- 静态检查：
- 未验证：

### 安全审计
- 审计状态：
- 敏感数据：
- 脱敏处理：
- 未解决风险：

### 项目交付
- 项目目录：
- README：
- GitHub 发布准备：

### 后续操作
- 上传 GitHub：由用户决定
- 安装插件：由用户决定

交付物：完整项目目录（不是代码片段）。能用 present 展示时展示 README / 审计报告。

结尾固定停止语：

项目已交付在 <路径>。我没有安装、启用或上传它。你可以先审代码，之后自行决定上传 GitHub 并通过 GitHub 方式安装；需要我继续准备发布流程或协助安装时告诉我。

14. 只有用户明确要求时才进入安装

用户说"装上试试"之后才做，且必须：

1. 检查环境支持（plugin_manager 可用？profile 可写？版本要求满足？）。
2. 说明安装会改什么：哪个 profile、装哪个包、是否启用、是否需要重启、如何卸载。
3. 得到确认后再调用 plugin_manager install_bundle（target = 项目绝对目录）或给出 dsh plugin --profile <name> add <spec> 命令。
4. 只执行被授权的那一步，不顺带启用/改配置/上传。
5. 环境不支持 → 只给手动安装说明，不硬来。

安装后如需验证：用 cordis_inspect_query（免审批）确认行是否激活；plugin_manager 的所有动作都需要审批，只在结果决定下一步时调用。

15. 遇到不确定时的说法

以下情况必须明说，不许猜、不许圆场：

• 不清楚 DSH 插件 API / 字段语义
• 缺开发文档、缺依赖、缺示例
• 某项功能在当前环境无法验证
• 无法运行 DSH、无法完成测试
• 用户需求相互冲突（例如"读取全部聊天记录"+"不碰任何隐私数据"）
• 发现隐私风险或不安全代码

说法模板：

这项我无法在当前环境验证：<具体缺口>。我按 <依据> 实现了最小可用版本，并把风险写在 README 的"已知限制"里。要确认它，需要在真实 DSH 中 <具体验证步骤>。

不伪造：不虚构 API、不虚构测试结果、不虚构"已完成"。

16. 交付前自检清单

逐条打勾，缺项先补再交付。

需求交互

• 用户没给名称时给了 ≥3 个合规候选（名称 / 含义 / 理由 / 自定义）
• 用户给的名称不合规时指出并给修正建议
• 功能不明时先问，没有直接写代码
• 提供了风格与自定义入口（涉及 UI 时）
• 没有重复询问用户已说明的信息

布局

• 提供了适配该功能的布局选项（对话框 / 侧边栏 / 设置页 / 组合）
• 说明了各区域职责，关键布局经用户确认
• 没有强行给每个插件都塞侧边栏和设置页

实现

• 基于已核实的 DSH API（未核实的已标注）
• 依赖明确、结构合理、错误处理到位
• 没有伪造未验证功能
• README 与实现一致

安全

• 完成了自动扫描 + 人工审计
• 检查了 Key / Token / 账号 / 聊天记录 / 本地路径 / 日志 / 发布文件
• 敏感信息已删除、脱敏或改为安全读取
• 泄露过的凭据已提示轮换
• 审计结论可见

测试

• 结构 / 配置 / 语法 / 图标检查通过
• 能跑的测试都跑了
• 未验证内容已列明

交付

• 完整项目 + README + 审计结果 + 测试结果 + 发布准备
• 未安装、未启用、未上传、未 commit、未发布

17. 常见失败模式