rootkiller6788/dsh-plugin-anything

  dsh-plugin-anything：让所有软件都成为 DSH 原生插件

把任何东西变成 DeepSeek Harness 插件。
一条流水线，一个编译器，一个验证器——为那个一切皆已是插件的 harness 而生。

一个 agent 原生的编译器与验证流水线，将软件能力转化为可安装、可测试、可验证的 DSH 插件。

一条命令：dsh plugin --profile  add dsh-plugin-anything-bundle —— 安装、重启，然后调用
工具。能在重启后存活才是关键；这正是动态包做不到的事。

黄金 E2E

主张就在名字里，而这样的主张，其价值取决于它最薄弱的那一类。每一类都是一个虽小但真实的代表，
跑完整个确定性流水线——IR → 编译 → 静态门禁 → 构建 → 类型检查 → 包完整性：

Git CLI            ██████████  PASS
Python CLI         ██████████  PASS
npm CLI            ██████████  PASS
Local Script       ██████████  PASS
GitHub Repository  ██████████  PASS
OpenAPI            ██████████  PASS
MCP Server         ██████████  PASS

Pipeline coverage        15 / 15 stages mechanized
Runtime acceptance       PASS   (accept → accepted, with evidence)
Package integrity        PASS   (every promised entry is in the artifact)

node --experimental-strip-types scripts/golden-e2e.mjs

上面的表格是由该命令生成，并由 scripts/check-readme-status.mjs 固定的——手工维护的状态表会漂移，
而漂移的状态表会被当作最新状态来读。
MCP 的 PASS 是一种拒绝，而这正是正确的结果。 MCP 服务器已经有一条受支持的途径
接入 dsh；为它生成插件只会重复那条途径。它的黄金用例断言编译器会拒绝
它并指明应改用的途径——一个通过生成冗余插件而“通过”的类别将是一种
回归，而 bundle/src/compile.ts 会抛出异常来防止这种情况。

流水线才是单元，而非工具

bundle/src/pipeline.ts 包含二十个阶段，每个阶段都有一个归属方以及
该归属方的理由。覆盖率由它计算得出，而非断言得出：

| 归属方 | 含义 | 如果它没有工具 |
|---|---|---|
| deterministic | 有正确答案，或有无法在每次运行时重新推导的契约 | 一个漏洞 |
| runtime | 只能通过运行中的测试框架触达 | 一个漏洞 |
| agent | 需要判断力 | 正确——将其机械化会用启发式取代智能 |
| external | 归属在本项目之外 | 无；之所以列出，是为了让流水线没有隐性缺口 |

八个工具覆盖十五个阶段，因为像验收这样的裁决是由七项检查构成的一个决策。
要关注的是覆盖率数字——而不是工具数量。 docs/pipeline.md 是
完整的地图。

这是什么

DeepSeek Harness（dsh）构建于内嵌的 Cordis 之上，
在那里一切都是插件：模型适配器、工具注册表、会话日志，以及智能体循环
本身。没有特权核心，每个部分都可以从 cordis.patch.yml 替换——那是用户
自己的层，在每个 bundle 层之后应用。

dsh-plugin-anything 是通往该架构的缺失入口。给定任何可操作的目标——一个外部
CLI、一个 HTTP/REST API、一个本地服务——它都会生成一个可安装的插件 bundle，dsh 智能体可以
加载、调用，并且在重启后仍然保有它。

它刻意同构地镜像了 CLI-Anything：相同的
逐阶段方法论，相同的“使用真实系统，不要重新实现它”的铁律，相同的
注册表打包方式——只是每个落点都被翻译成了 dsh 的原生概念。

| CLI-Anything | dsh-plugin-anything |
|---|---|
| GUI 软件 → 智能体可用的 CLI | 任何东西 → dsh 插件 bundle |
| HARNESS.md 8 阶段 SOP | 同样的 8 个阶段，dsh 落点 |
| core/ + utils/_backend.py | src/ + src/provider.ts（唯一的出口模块） |
| click + REPL | defineTool + ctx.tools.register |
| SKILL.md | SKILL.md（dsh frontmatter）+ 一行挂载记录 |
| setup.py → PyPI | package.json → npm / tarball / git |
| registry.json + cli-hub | 现有的 market 注册表——复用，而非重建 |

它为何存在

dsh 已经附带了一个根据请求生成插件的循环：cordis 智能体预设挂载了
tool-cordis，模型可以检查自己的运行时、编写一个包并运行它。那个循环是
非常适合探索，但对交付毫无用处：

动态包只存在于共享的 DSH 进程内存中。[…] 它们不创建 Plugin 文件、不安装任何
包、不更改 cordis.yml 或个人/项目配置，无法在重启后存活，也无法被
自动提升。
— packages/extensions/tool-cordis/README.md

缺口不在于生成，而在于提升——把只对一个会话有效的东西，变成能够持久化、安装和分发的 bundle。
这一点，再加上围绕它的 SOP、模板、验证器和 CI 纪律，正是本项目所提供的内容。

布局

dsh-plugin-anything/
├── kit/                             # SOP 工具包——bundle 如何构建的唯一事实来源
│   ├── HARNESS.md                   #   8 阶段方法论。先读这个，再读其他任何东西。
│   ├── commands/                    #   /plugin-anything、:list、:refine、:test、:validate
│   ├── guides/                      #   渐进式披露——每个深入领域一份指南
│   ├── templates/                   #   生成 bundle 时用于组装的文件
│   ├── scripts/verify-plugin.mjs    #   静态门禁
│   └── tests/                       #   门禁自身的验收测试
│
├── bundle/                          # npm 包：plugin_anything_* 工具
│   ├── src/                         #   tools.ts、pipeline.ts、ir.ts、compile.ts、accept.ts、……——14 个模块
│   ├── tests/                       #   覆盖整个表面的 141 个测试
│   ├── scripts/                     #   verify-plugin.mjs，以及 accept/package/render/typecheck 测试框架
│   ├── templates/ sop/ skills/ docs/  #  工具在运行时读取内容的随附副本
│   └── cordis.patch.yml             #   bundle 的补丁层
│
├── examples/
│   ├── golden/                      # 每个目标类别一个真实代表性示例
│   └── dsh-plugin-git/              # 一个生成的 bundle，由模板渲染而来
│
├── registry/                        # awesome-dsh-plugin 条目，以及该格式所缺少的元数据
├── notes/                           # Agent Notes——各项决策，以及被否决的内容
├── scripts/                         # 验收阶梯、golden E2E、四项一致性检查
├── docs/                            # pipeline.md、runtime-acceptance.md，以及归档的计划
└── .github/workflows/               # CI：门禁、golden E2E、针对真实 dsh 的组合

这些目录中有两个对分发很重要，而其中只有一个会被发布：
| 目录 | 它是什么 | 如何发布 |
|---|---|---|
| bundle/ | npm 包 dsh-plugin-anything-bundle | cd bundle && npm publish — 由 dsh plugin add 安装 |
| kit/ | SOP、模板和门禁 | 无需发布。 它是本仓库自身的工具链和 agent 所读取的内容。 |

快速开始

1. 阅读 SOP。它是每个阶段的权威依据。
kit/HARNESS.md

2. 对生成的 bundle 进行静态门禁检查。
node kit/scripts/verify-plugin.mjs examples/dsh-plugin-git

3. 安装并验证组合。
dsh plugin --profile dev add ./examples/dsh-plugin-git
dsh --profile dev --dump-config | grep -A3 '# == dsh-plugin-git'

4. 启动它，使用这些工具，然后重启并再次使用它们。
能在重启后存活才是关键——这正是动态包做不到的。
dsh --profile dev

工具包

用于产出可安装 bundle 的方法论、模板和门禁。生成的 bundle 是它的产物，这里没有任何内容派生自生成的 bundle。

内容

| 路径 | 它是什么 |
|---|---|
| HARNESS.md | 8 阶段 SOP。在做任何其他事情之前先读它。 |
| commands/ | 执行 SOP 的斜杠命令：/plugin-anything、:list、:refine、:test、:validate |
| guides/ | 渐进式披露。每个指南按需加载，绝不预先加载。 |
| templates/ | 组装生成 bundle 所用的文件——manifest、patch、plugin 入口、provider、tool、构建配置、skill |
| scripts/verify-plugin.mjs | 静态门禁。捕获那些会静默失败的问题。 |
| tests/verify-plugin.test.mjs | 门禁自身的验收测试——每项检查都针对一个必须失败的变异体 |

指南

在某个阶段到达它们时才加载，而不是提前加载。

| 指南 | 何时阅读 |
|---|---|
| seam-vs-consumer.md | 决定插件的形态（§3）。默认：Consumer。 |
| backend-cli.md | 目标是外部 CLI 二进制文件 |
| backend-http.md | 目标是 HTTP/REST API |
| backend-mcp.md | 目标使用 MCP 通信——通常你根本不应该生成插件 |
| tool-contract.md | 编写工具：定义对象、schema DSL、渲染意图、执行流水线 |
| skill-authoring.md | 发布 SKILL.md，以及 mount 行中的 baseUrl 陷阱 |
| in-tree-vs-out-of-tree.md | 任何关于 manifest 的问题——以及过时文档陷阱 |
| snapshot-testing.md | 规划测试（§8）。快照层级是强制性的。 |
| bundle-distribution.md | 发布它（§7），以及为什么 git 安装是一个信任决策 |
| static-promotion.md | 将实时动态包提升为 bundle |
| registry-entry.md | 使其可被发现。不要构建 hub。 |
| verification.md | 门禁能证明什么、不能证明什么 |
| agent-notes.md | 记录一项非平凡的决策 |

模板

package.json、cordis.patch.yml、index.ts、provider.ts、tool.ts、tsconfig.json、
tsdown.config.ts、SKILL.md —— 每个模板都以注释形式携带其产物的已验证契约，包括那些会导致
bundle 构建干净却加载失败的陷阱。

门禁

node kit/scripts/verify-plugin.mjs    # a generated bundle
node kit/scripts/verify-plugin.mjs --kit          # the kit's own structure
node --test kit/tests/verify-plugin.test.mjs      # prove the gate's checks can reject

它是一种静态近似，并且它自己也这么说。它能捕获那些静默失败的错误——门禁的 glob 永远看不到的
patch 文件、匹配不到任何内容的行、被 Loader 丢弃的条目。它从不声称插件能够启动；只有真正的
dsh --profile  --dump-config 和一次实时工具调用才能做到这一点。

约定

- kit 中的每条规则都引用了强制执行它的 dsh 源码。当 dsh 文档与其门禁不一致时，
以门禁为准——这种情况已经发生过一次，
in-tree-vs-out-of-tree.md 记录了它。
- 一项检查在被观察到拒绝过某些东西之前，不算证据。
- 生成的输出绝不通过手工编辑来修正；要修就修模板。

三条规则

1. 包装真实系统。绝不重新实现它。 在生成的插件中，恰好有一个模块接触外部世界；其余一切都是纯逻辑，
无需后端即可测试。
2. 渲染意图是设计的一部分。 generic / terminal / diff 和 locations 要事先决定，
绝不事后追加。
3. Presenter 是纯函数。 它们既运行在实时流式传输上，也运行在会话日志回放上——没有 I/O，
没有会话状态，没有时钟。

门禁强制执行不可协商的事项

文件名不包含 cordis 的 patch 文件；缺失的 dsh.bundle.patch；未列在 files 中的 patch；
只有注释的 patch（它会在启动时抛出异常）；config/disabled 之外的 !!js；行中未声明的裸插件名；
带 default 导出的函数插件；不纯的 presenter——每一项都会被拒绝。

门禁本身也针对单字段变异体进行了测试：插件验证器可能走到的全部十六条拒绝分支，都有一项测试观察其中
一条触发并断言其消息。--kit 这一级检查的是本仓库而不是插件，并且没有变异体测试。

状态

流水线是完整的：需要机械化的 15 个阶段中有 15 个已机械化，而不需要机械化的四个阶段按设计属于判断。
以下所有内容都有证据，而非断言。

| | 证据 |
|---|---|
| 该套件的门禁通过，且每个门禁都能拒绝一个变异体 | 对两个测试套件运行 node --test |
| 生成的 bundle 能针对真实的 @deepseek-ai/dsh-tools 类型进行编译 | 脚手架输出和编译输出两者 |
| 安装、组合、加载、注册、持久化 | 针对真实的 dsh，在两条发布线上 |
| 模型能看到并调用这些工具 | 一个真实回合列出了全部八个并调用了其中一个 |
| 呈现器重放 | 来自真实会话记录的 tool/result |
| 完整验收判定 | accept → accepted，全部七个阶段均有证据 |
| 七个目标类别 | scripts/golden-e2e.mjs，7/7 |

不包含的内容。 publish——即向注册表提交——不归本项目管；该条目在格式上已完整，只差一个公开仓库存在。而 dsh 本身处于开发者预览阶段，并警告将会出现破坏兼容性的变更，因此你所 peer 的版本很重要：
kit/guides/bundle-distribution.md。

许可证

MIT——见 LICENSE。发布的 bundle 携带相同的文本，且
scripts/check-shipped-copies.mjs 将两者绑定在一起，因此对其中一方的修改无法悄悄让另一方仍声明旧条款。