/dsh-plugin-dev

DSH Plugin Dev

DSH 插件开发指引 Skill（2026-09-29 由 dsh-plugin-lint 并入吸收：开发主线 + 机械审查一体）。沉淀来源：dsh-plugins 仓库全程开发实测（真实 DSH Desktop 2.0.15 / 内嵌运行时 0.1.7-rc.2，五次隔离装载实验、14 个 PR 的独立审查修复）+ dsh-contract-copilot 0.1.2 期开发实测。

本技能不代替实现者：创建插件时先做设计预检，实现后回来做正式验收——审查器与生产者不混同责任。

配套文件

• scripts/lint.mjs → 机械审查层（版本感知，规则清单见下）
• scripts/test-lint.mjs → 自测（自包含 fixture，证明每条规则抓得住无效样本、放行有效对照）
• config/harness-path.example.yaml → 复制为 config/harness-path.local.yaml 填本地 harness 仓库路径（不提交）
• templates/plugin-quality-report.md → 正式审查的报告模板（结论带 NOT_VERIFIED 语义）

依赖

• Node ≥ 18.6（lint.mjs 用 node:module.isBuiltin），无第三方包——脚本开箱即用。
• harness 溯源需要本地一份 DSH 源码仓库；三者皆缺时版本相关检查标 NOT_VERIFIED（进程不崩）。本机 Desktop 内嵌运行时（/Applications/DSH Desktop.app/.../node_modules/@deepseek-ai/）是另一事实源，二者对照用。

开发路径

1. 定形态：插件身份（package.json name + dsh.bundle.patch → cordis.patch.yml，insert 行 id/name 均 string）、半体范围（先 Host-only 再 client）、服务依赖（inject——硬依赖缺失插件等待不激活）、零依赖原则（@deepseek-ai/* 视为宿主 external）。要点见 host-plugin-essentials。Pi 插件 DSH 化起手切片（PR #37 三插件实证）：新建打包层三件套（package.json/patch/index.mjs，Pi 源码一字不动、不 import）+ bizlink 消费者（owner kind 命名空间）+ 自检链（只断言自身命名空间）——mock 级先行，装载验证批量入用户窗口。起手后的领域平移走 porting-semantics：源码去 flopi-candidate 找全量、语义出处行号锚定、偏离只许更严方向、外部 IO 一律注入缝 + 缺省 fail-closed（PR #42/#45/#46/#49/#51 实证）。
2. 写 Host 半体：手写 ESM function plugin（name/inject/apply 命名导出）；同目录有 CJS 遗留源码时不声明 type: module、入口用 .mjs（实测组合回归）；ctx.provide + ctx.logger.info 启动标记 + ctx.effect 返回 disposer。类型查找先搜 dsh-tool-cordis/lib/types/api-catalog.js 与各包 README.zh.md——内嵌树 .d.ts 已剥离，包 lib 导出面查不到 ≠ 全树缺失。
3. 接业务：会话状态用投影（projection-cookbook：register 必填 stateVersion、通知只走 wire、真实 turn id 是数字）；业务对象↔会话关联走共享服务（dsh-bizlink 先例：owner 在 revision 权威处做乐观并发）；模型调用与一切公共能力先查官方复用（official-capabilities：目录 + 查证方法；已核 ctx.llm 为唯一受支持模型调用入口，勿自建）。
4. 隔离装载验证：按 desktop-load-and-isolation 建实验 profile（GUI profile 必须直接含 @deepseek-ai/dsh-web-app；官方 bundle 从安装锚点解析，本地插件放符号链接即可零物化装载）、DSH_HOME 隔离启动、宿主日志找激活标记、SIGTERM 分步退出、恢复生产（profile-selection 快照/恢复）。
5. 宿主级验证：mock 全绿 ≠ 宿主可用——真实 cordis ctx 代理（未声明 inject 的属性读取抛错→可选服务用 ctx.get）、域 schema 只在 open 边界校验、写路径须过真实域校验的回归用例（防 best-effort 吞错造成静默失效）依次核过。headless 验证入口与证据纪律见 pitfalls-log「宿主验证与证据纪律」节（每轮异名落盘、driver/dump 同 commit 互证、门序断言确认前道门未短路、计数器须真注入、文件级≠记录级、离线桩≠网络失败）。
6. 审查与回写：mock ctx 集成测试（真实双插件串接）→ 机械审查（下节）→ 独立审查（角色分离）→ 装载证据绑定候选。踩坑回写 pitfalls-log，版本迁移差异回写 harness-facts。

机械审查（scripts/lint.mjs）

node skills/dsh-plugin-dev/scripts/lint.mjs <插件目录> --harness-root <DSH 源码仓库>
node skills/dsh-plugin-dev/scripts/test-lint.mjs   # 自测，退出码 0 = 全部规则自证有效

harness 根解析优先级：--harness-root 参数 → DSH_HARNESS_ROOT 环境变量 → config/harness-path.local.yaml。--json 追加机器可读行；退出码 = FAIL 数。规则节：§0 harness 溯源（版本/commit/模块表）｜§1 package.json 版本漂移｜§2 dsh.bundle｜§3 exports 入口｜§4 dsh.client（inject 目标声明、external 自引用/越界）｜§5 client 工件（banner/footer、bare require ↔ 模块表、构建 external 对账）｜§6 主题变量声明集对账｜§7 类型化 locale 与 CJK 硬编码｜§8 卫生｜§9 文档版本残留。

审查工作原则（继承自 lint 1.0.0）：先机械后语义；版本感知不冻结假设；对 harness 的每个 API/事件/slot 引用必须溯源到源码路径（实测案例：文档写过不存在的 CLI flag 与 agent/post-step 事件）；不采信自报 PASS；客观缺陷 fail-closed，语义不确定只出 WARN/NOT_VERIFIED 绝不出假 PASS。

必须守住的边界

• 版本匹配：开发依据的源码/文档版本必须与本机 Desktop 内嵌运行时一致（npm latest = 内嵌版；next 是预发布无桌面内嵌）。错位研究必须按实物重核。
• 生产隔离：实验只用 DSH_HOME 隔离目录 + 合成数据；不读生产 sessions/凭据/settings；动共享 userData 前快照后恢复；关生产实例前后向用户报备。
• 退出时序：SIGTERM 后分步验证进程真正消失再执行恢复命令——单例锁会把 premature 的 open -a 转发给未死尽的实验实例。
• 不伪造验证：mock 冒烟 ≠ 宿主验证 ≠ GUI 验证，三层分开陈述；宿主日志是 Host 半体权威证据；缺失标 NOT_VERIFIED。
• 组合回归意识：单分支 diff 看不见共享目录声明的相互作用（如同目录 package.json 的 type 字段）——此类变更合并前后必须全量重跑既有测试。

交付物与完成线

一个开发切片：结构校验 → mock 集成测试 →（有条件时）隔离装载宿主日志证据 → 独立审查处置 → 文档与踩坑回写。发布验收按上节正式模式。缺装载证据明标 NOT_VERIFIED，不宣称"已在真实宿主可用"。

参考

• 官方能力复用目录：自建公共层前先查官方的查证方法（源码锚定/包 README/消费者范例）+ 已核七条目（ctx.llm 模型调用、ctx.jobs 会话内长任务、packages/schedule 持久定时、ctx.tools 模型工具注册、ctx.storageDomain 持久 KV——后两条含零依赖实现姿势；插件 Config/settings 表单机制与 domain/changed 存储域变更事件——含手写 schema 三暗门与进程内边界）与待查清单。
• 移植语义纪律：flopi-candidate 源码定位规律、行号锚定、偏离只许更严、不虚构未验证分支、外部 IO 注入缝（fail-closed）、并发分支测试计数；Python→JS 跨语言平移六条（零宽后顾断言不可降级为消耗式前缀、URL 编码差分对照、内容哈希当不了修订号、round/日期/排序三件套、替换串捕获组即语义、差异申报或消除）。
• Host 插件要领与版本差异：形态、装载解析、零依赖与 schema 策略、api-catalog 类型查找、0.1.2→0.1.7 迁移表。
• 会话投影 Cookbook：sessionProjections 契约、wire 通知、数字 turnId、水位与 fork。
• Desktop 装载与隔离实验：profile 工作区、装载实证、DSH_HOME/单例锁/SIGTERM/向导状态/renderer 已知问题。
• 0.1.7-rc.2 事实快照：版本矩阵、内嵌包速查、与 0.1.2 规范差异清单。
• 踩坑日志：按症状索引的实测坑（含出处），跨版本累积。
• 0.1.2 开发规范（历史权威）：插件形态/分发/工具/事件/slot/client 工件契约/主题/locale 全量规范 + 14 条实测坑与 harness 参考文件索引。
• 实证仓库：maoscripts/dsh-plugins（evidence 与 PR 审查修复记录，本 Skill 事实的原始出处）。

已知限制（继承 lint）

• 正则级解析不构建 AST：复杂 patch 结构、嵌套词典转人工（WARN/NOT_VERIFIED，不出假 PASS）。
• 产物 bare builtin require、JSX CJK 检测为启发式，需人工确认。
• 平台模块表/纯度正则/主题变量集均为运行时从 --harness-root 读取的当前事实，不预置版本号。
• 不自动执行目标仓库 build/test（报告应跑的命令）。