Index of every page on this site: llms.txt
All skills
cat-xierluo avatar

/dsh-plugin-dev

@5fb69a0
Run it yourself

DeepSeek Harness(DSH)插件的设计、开发、装载验证、版本迁移与发布审查指引(版本感知)。在用户要为 DSH Desktop 开发插件、把 Pi/Hermes 插件迁移到 DSH、做隔离装载实验、排查插件在真实宿主的行为、跟进 DSH 版本升级适配,或在发布前做机械审查与验收(dsh.bundle / dsh.client 双面包工件契约、inject/external 对账、主题变量、类型化 locale)时使用。不要用于普通 npm 包审查或与 DSH 无关的 agent 项目。

Use this Skill: https://skilld.dev/gh/cat-xierluo/legal-skills/dsh-plugin-dev

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈135 tokens for metadata: the name and description. ≈3k when used: this file. ≈34k more on demand in 14 files.

Description uses 3.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈269 characters, or 3.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 的独立审查修复;2026-10-15 已按安装版 2.0.17 / 0.2.0-rc.2 复核,2026-10-17 增补真宿主实证批(三标记复现 + C-1 装载实验,见 harness-facts-020rc2 实证修订节))+ 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(当前基线 0.2.0-rc.2;历史 0.1.7-rc.2 另存)。

机械审查(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 文档版本残留。

模式 时机 必做
设计预检 写代码前 过一遍 development-standards 契约节 + 本 SKILL 踩坑;事件/slot 名先溯源;涉客户端界面/交互设计时先读 ui-ux-workbench
快速审查 第三方/草稿 机械 + 事实 + 契约;结论带 NOT_VERIFIED
正式验收 发布/声称完成前 全部 + 候选绑定证据(commit + 干净 profile 安装 + boot 无错 + 工具真实调用 + 浏览器渲染截图;缺任一 → NOT_VERIFIED)

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

必须守住的边界

  • 版本匹配:开发依据的源码/文档版本必须与本机 Desktop 内嵌运行时一致——锚点是安装版实物(安装包 manifest 直读),不是 npm channel(2026-09-30 实测 npm latest 与安装版不同步;「next 是预发布线、无桌面内嵌」是历史观察,每次以实物为准)。错位研究必须按实物重核。
  • 生产隔离:实验默认只用 DSH_HOME 隔离目录 + 合成数据,不读生产 sessions/凭据/settings;动共享 userData 前快照后恢复;关生产实例前后向用户报备。仅在用户明确授权复用登录/API 配置做并行 Desktop 验收时,才可把最小必要账号记录、API 引用与 provider 配置快照到隔离 DSH_HOME;保留隔离实例自己的 browser-session 密钥,不输出明文,不复制生产 sessions/storages/profile,不写生产配置。
  • 退出时序: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.2.0-rc.2 事实快照:当前基线(Desktop 2.0.17)——版本矩阵、Host 消费面零破坏结论、新版增量事实速查(settings 客户端族/表名正则/宿主不变式/schedule 留存/llm discovery 面/tools 无损校验)、client 侧 90-slot 台账与 shadowing 语义、primitives/tokens 现状、NOT_VERIFIED 边界。
  • 0.1.7-rc.2 事实快照:历史基线(Desktop 2.0.15)——版本矩阵、内嵌包速查、与 0.1.2 规范差异清单。
  • 插件工作台与运行视图设计:新增可视化插件、重排主界面或用户反馈「能跑但不愿使用」时先读——真实入口观察、版式按产品任务选择、跨插件可复用经验与产品自有任务源的边界。
  • 踩坑日志:按症状索引的实测坑(含出处),跨版本累积。
  • 0.1.2 开发规范(历史权威):插件形态/分发/工具/事件/slot/client 工件契约/主题/locale 全量规范 + 14 条实测坑与 harness 参考文件索引。
  • 实证仓库:maoscripts/dsh-plugins(evidence 与 PR 审查修复记录,本 Skill 事实的原始出处)。

已知限制(继承 lint)

  • 词典平价为静态叶路径解析(嵌套对象按 a.x 完整路径比对;同文件顶层不相交 const 展开可解析合并;嵌套展开、重复键、属性重叠展开转 NOT_VERIFIED,跨文件展开/计算键/方法简写转 NOT_VERIFIED),不执行词典代码。
  • patch 结构检查识别简单 insert/id/name 行;复杂 YAML 形态转人工(NOT_VERIFIED),不出假 PASS。
  • 产物 bare builtin require、JSX CJK 检测为启发式,需人工确认。
  • client 源扫描范围固定 src/client(ts/tsx/js/mjs/jsx/css);其他源布局(如 lib/client)不在机械覆盖内,0 文件时明示 WARN 转人工。
  • 平台模块表/纯度正则/主题变量集均为运行时从 --harness-root 读取的当前事实,不预置版本号;事实源缺失时对应检查降级 NOT_VERIFIED,不误报 FAIL。
  • 不自动执行目标仓库 build/test(报告应跑的命令)。

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning18d3 checks · Risk MEDIUM
  • Gen Agent Trust Hub18d

    The skill provides a development environment for DeepSeek Harness plugins, including a linter script that executes code from a user-specified harness directory. This execution model poses a risk as it allows for the execution of untrusted JavaScript files found within the provided path.

  • Socket18d

    No alerts

  • Snyk18d

    Risk: LOW · No issues

Signed by skilld at 5fb69a0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago
homepage
https://github.com/cat-xierluo/legal-skills
author
杨卫薪律师(微信ywxlaw)
version
0.6.6

README badge

README badge for cat-xierluo/legal-skills/dsh-plugin-dev