插件开发脚手架 benz-ai-x/dsh-plugin-dev

DSH 插件开发

面向 Codex 与 Claude Code 的 DeepSeek Harness（DSH · Cordis）插件开发 —— 提供开发与兼容性分析的 Skill 以及确定性生成器，附带经审计的基线和真实 Loader/profile 验证。

中文使用手册 · English Quick Guide

version
DSH baseline
Codex
Claude Code
Node
pnpm
License: MIT

中文使用手册

这是什么

dsh-plugin-dev 是供 Codex 和 Claude Code 共用的 DeepSeek Harness（DSH，基于 Cordis）插件开发 Skill。你只需安装一次，然后在任意空目录中描述业务需求，Code Agent 就会判断 DSH 扩展形态、生成项目脚手架，并继续完成业务实现和验证。

本仓库是插件开发工具，不是 DSH 运行时插件。当前确定性生成器支持 Host 侧、面向模型的 Tool 插件；Service、Client、LLM Adapter、Bundle/Profile 和 Agent Team 需求仍可通过 Skill 中的专项指南开发，但尚无确定性模板。

仓库自身采用 TypeScript-first 工具链。生成器、基线管理、上下文校验和安装器的权威源码位于 .mts 文件，严格类型检查后编译到现有 .mjs 公共入口；因此安装后的 Skill 仍可直接由 Node 执行，不要求用户额外安装 tsx。tooling-artifacts.json 将源码、JavaScript 和声明文件的摘要绑定在一起。

核心特性

- 双 Agent 一份 Skill：Codex（$HOME/.agents/skills）与 Claude Code（$HOME/.claude/skills）共享同一份 canonical Skill、参考资料、生成器和模板。
- 项目级兼容性分析：配套 version-compatibility-analysis 每次动态读取上游版本、workspace、依赖与源码契约；分析新版无需先修改代码或版本锁。
- 审计基线双通道：dsh-reference.lock.json 锁定官方 tag/commit/docs 摘要，stable/edge 内容寻址通道加上完整验证与 Registry 闭包证据，升级走可审计的 runbook。
- 双交付模式：source 模式链接本地干净 Harness worktree；registry 模式在闭包 ready 时生成普通精确版本依赖与可发布 manifest。
- 真实验证阶梯：生成项目通过 strict 源校验、类型检查、单元/HMR 测试、真实 Loader 组合、profile add/dump/boot/remove 与打包产物检查。

环境要求

- Node.js ^22.19.0 或 >=24.0.0（与锁定的 Harness 一致）
- pnpm 11
- 验证本仓库或使用 source 交付时，需要与 dsh-reference.lock.json 一致的本地 DeepSeek Harness；tracked/non-ignored 源码需 clean，根目录不得有会被 CLI 加载的 .env，并先执行 pnpm install && pnpm run build。使用已审计为 ready 的 registry 生成模式时，生成项目本身不需要本地 Harness。
- Codex、Claude Code，或两者都安装

如果 Harness 不在默认相对位置，请先设置：

export DSH_HARNESS_BASELINE_ROOT=/path/to/pinned-deepseek-harness

安装

git clone https://github.com/benz-ai-x/dsh-plugin-dev.git
cd dsh-plugin-dev
pnpm install
pnpm context:check:strict
pnpm install:skill

pnpm install:skill 会安全地创建两个用户级链接：

- Codex：$HOME/.agents/skills/dsh-plugin-dev
- Claude Code：$HOME/.claude/skills/dsh-plugin-dev

两个 Agent 始终读取同一份 Skill、参考资料、生成器和模板。安装器不会覆盖同名的无关文件；也可以只安装一个入口：

pnpm install:codex
pnpm install:claude

此安装器仍只安装开发 Skill。版本兼容性 Skill 是本仓库的项目级功能，通过 .agents/skills/、.claude/skills/ 发现，并随 Codex Plugin 分发；不需要额外安装到用户目录。
分析新版 Harness（无需修改代码）

在本项目中向 Codex 发出：

使用 $version-compatibility-analysis 分析本项目与 /path/to/deepseek-harness 的版本依赖兼容性，列出必要修复与验证阻塞。

Claude Code 使用 /version-compatibility-analysis。也可先运行只读证据采集：

pnpm compatibility:analyze --harness-root /path/to/deepseek-harness

基线自动取 dsh-reference.lock.json 的默认通道 commit，候选默认取指定仓库 HEAD；可加 --target TAG_OR_COMMIT、--channel CHANNEL 或 --capability NAME。未知锁格式可由 Agent 读取后传 --base REF --root-package NAME（根节点可重复），不要求修改助手代码。

“自升级”指每轮重新发现当前版本的包目录、依赖、API 和文档证据，不是自动改写 Skill 或升级已审计基线。脚本按各提交 workspace 定义重建声明依赖图，包版本/包名/目录不写死；复杂声明由 Skill 补充只读调查。默认只输出 JSON，不联网、不安装、不改锁；完整兼容性结论仍需源码、运行、迁移及发布证据，exit 0 只代表证据采集完成。

需要自动下载缺失的已发布精确版本包时，明确要求 Skill 下载，或运行：

pnpm compatibility:analyze --harness-root /path/to/deepseek-harness \
--download-missing --download-dir /path/to/compat-npm-cache

目录必须在项目、Harness 和 Skill 之外，父目录已存在，目标为新目录或助手先前创建的缓存；可用 --registry HTTPS_URL 指定源，默认公共 npm。需要本机 npm。它只下载并校验 tarball、复用已验证缓存，不执行脚本或安装依赖。未发布版本无法补齐，范围/私有包保留待处理项；有缺口退出 2，不改发布门槛或基线。详见 下载模式。

当前开发基线：stable 与 edge 均为官方 dsh-v0.1.2-rc.1 （a66e4702047846cdaa10c66c9d3df3951f5ea70d），不再使用 0.1.3-alpha.1。rc.1 的完整 Tool Registry 闭包为 24/24 可用，支持已验证的 source 与 registry 两种交付；此前的 15 个 E404 属于 alpha.1 的历史结果，不是 rc.1 的缺包。
rc.1 的投影缓存恢复改动与历史版本边界见按版本选择的契约。
Registry 不就绪时仍会拒绝 --delivery registry，不会跨版本回退；查询更新后必须重跑同通道验证。详见 验收记录。

分析候选路径采用 --harness-root → DSH_HARNESS_ROOT → 锁中环境变量 → fallback；仓库 strict 校验继续用 DSH_HARNESS_BASELINE_ROOT 指向已审计版本，生成项目使用自己的 DSH_HARNESS_ROOT。分析不依赖旧 worktree 或新版构建产物，但需要 Git 中存在比较的两个提交；缺失基线、解析限制和未查询的 Registry 状态会明确报告。

在空目录创建插件

Codex：

mkdir aaa
cd aaa
codex

使用 $dsh-plugin-dev 创建一个 DSH Tool 插件。
它接收仓库路径，查找超大文件并返回结构化报告。完成实现和验证。

Claude Code：

mkdir aaa
cd aaa
claude

/dsh-plugin-dev 创建一个 DSH Tool 插件。
它接收仓库路径，查找超大文件并返回结构化报告。完成实现和验证。

生成完成后，项目通常可用以下命令独立验证：

pnpm verify

常见问题与限制

- 如果空目录出现 ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND，说明在生成 package.json 前执行了 pnpm。先启动 Codex 或 Claude Code 并调用本 Skill，生成脚手架后再运行 pnpm。
- 生成项目绑定 dsh-reference.lock.json 中审计过的 Harness 版本；源码锁不匹配时会停止，而不会静默套用错误契约。
- 生成器默认使用 source；Harness checkout 移动后，在生成项目内运行 DSH_HARNESS_ROOT=/new/path pnpm context:sync。该命令会改写六个 link: 依赖并刷新 lockfile。
- --delivery registry 仅接受 Registry 闭包为 ready 的基线，生成普通精确版本依赖、dsh-registry.lock.json 和可发布 manifest，不需要 Harness 路径。最终发布仍须用同一个 .tgz 通过干净安装/导入和真实 profile add/dump/boot/remove。

验证本仓库

pnpm build:check
pnpm typecheck
pnpm verify

架构、验收证据、项目交接和后续计划分别见 docs/agent/ARCHITECTURE.md、docs/agent/ACCEPTANCE.md、docs/agent/HANDOFF.md 和 TODO.md；基线升级流程见 docs/agent/BASELINE_UPGRADE.md，产品决策见 docs/decisions/。

英文快速指南

这是什么

dsh-plugin-dev 是一个共享的 DeepSeek Harness（DSH，基于 Cordis）插件开发 Skill，适用于 Codex 和 Claude Code。安装一次后，即可从任意空目录描述业务需求。代码智能体会对 DSH 扩展形态进行分类，生成项目脚手架，并继续完成真实的实现与验证。

本仓库是开发工具，而非 DSH 运行时插件。确定性生成器目前支持 Host 侧、面向模型的 Tool 插件。该 Skill 也会指导 Service、Client、LLM Adapter、Bundle/Profile 和 Agent Team 相关工作，但这些形态的确定性模板仍在路线图中。

本仓库本身以 TypeScript 优先。权威的生成器、基线、上下文和安装器源码使用严格的 .mts；编译会保留现有的无依赖 .mjs 入口路径，因此已安装的 Skill 不需要 tsx。tooling-artifacts.json 绑定源码、JavaScript 和声明文件的摘要。

亮点

- 一个 Skill，两个智能体：Codex（$HOME/.agents/skills）和 Claude Code（$HOME/.claude/skills）读取同一个规范 Skill、引用、生成器和模板。
- 项目兼容性伴侣：重新发现版本、工作区包、依赖和变更的契约；分析新的 Harness 修订版无需版本特定代码或锁文件编辑。
- 经审计的基线通道：dsh-reference.lock.json 固定官方标签、提交和文档摘要；内容寻址的 stable/edge 通道通过可审计的升级运行手册携带完整验证和 Registry 闭包证据。
- 两种交付模式：source 链接一个干净的本地 Harness 工作树；registry 在闭包为 ready 后输出精确的普通依赖版本和可发布的清单。
- 真实的验证阶梯：严格的源码检查、类型检查、单元/HMR 测试、真实 Loader 组合、profile 添加/转储/启动/移除，以及打包产物检查。

要求

- Node.js ^22.19.0 或 >=24.0.0，与固定的 Harness 匹配
- pnpm 11
- 验证本仓库或使用 source 交付需要一份与 dsh-reference.lock.json 匹配的本地 DeepSeek Harness 检出，其已跟踪/非忽略的源码输入干净，没有 CLI 可能加载的根 .env，并已通过 pnpm install && pnpm run build 准备就绪。使用经审计的 ready Registry 交付的生成项目不需要本地 Harness 检出。
- Codex、Claude Code，或两者兼有

如果 Harness 不在默认相对位置，请设置：

export DSH_HARNESS_BASELINE_ROOT=/path/to/pinned-deepseek-harness

安装

git clone https://github.com/benz-ai-x/dsh-plugin-dev.git
cd dsh-plugin-dev
pnpm install
pnpm context:check:strict
pnpm install:skill

pnpm install:skill 会安全地创建两个个人 Skill 链接：

- Codex：$HOME/.agents/skills/dsh-plugin-dev
- Claude Code：$HOME/.claude/skills/dsh-plugin-dev

两个 agent 读取相同的 Skill、references、generator 和 templates。安装器绝不会覆盖无关路径。仅在需要时安装一个集成：

pnpm install:codex
pnpm install:claude

上面的个人安装器仅安装开发 Skill。version-compatibility-analysis 配套项由 Codex 和 Claude Code 在此仓库内发现，并且也包含在打包的 Codex Plugin 中。

分析更新的 Harness

在此项目中调用 $version-compatibility-analysis（Codex）或 /version-compatibility-analysis（Claude Code），或收集只读证据：

pnpm compatibility:analyze --harness-root /path/to/deepseek-harness

基线来自当前项目 lock；候选版本默认使用指定仓库的 HEAD。使用 --target REF 选择另一个修订版本。
工作区定义和依赖根从数据中读取，而不是从发布白名单中读取。未知 lock 格式可以使用显式的 --base REF 和可重复的 --root-package NAME；不支持的声明仍会作为可见的证据缺口保留，供 agent 主导的检查使用。默认情况下，不执行 checkout、fetch、install、lock 更新或 Registry 查询。退出码为零表示已收集证据，而非兼容。

对于明确授权的 tarball 下载，添加 --download-missing --download-dir /path/to/compat-npm-cache。父目录必须存在；请使用项目、Harness 和 Skill 之外的新缓存或之前拥有的缓存。需要本地 npm。Registry 默认使用公共 npm，并可通过 --registry HTTPS_URL 选择。已发布的精确版本会进行完整性校验并复用；不会执行生命周期脚本、依赖安装或审计更新。
未发布的版本无法下载，范围/私有目标仍会推迟处理。部分结果退出码为 2，而不是兼容性或发布结论。
参见 下载模式。

自升级意味着每次刷新分析知识，而不是重写 Skill 或提升为 stable。候选路径优先级为 --harness-root、 DSH_HARNESS_ROOT、lock 的环境变量，然后是它的回退值。固定仓库检查仍使用 DSH_HARNESS_BASELINE_ROOT。两个提交都必须存在于候选 Git 仓库中；不需要旧的基线 worktree。

stable 和 edge 都选择官方 dsh-v0.1.2-rc.1，位于 a66e4702047846cdaa10c66c9d3df3951f5ea70d，不再是 0.1.3-alpha.1。
rc.1 Tool Registry 闭包已就绪，24/24 需求可用；源码和 Registry Tool 交付均已验证。之前的 15 个 E404 属于历史 alpha.1 证据，而非 rc.1。阅读版本特定契约以了解 rc.1 缓存恢复和明确限定范围的历史 API。
Registry 生成仍会拒绝未就绪的 channel，而不会进行跨版本回退。重新检查 Registry 需要新的同通道验证；仅来源证据不能授权发布。

从空目录创建插件

使用 Codex：

mkdir aaa
cd aaa
codex

Use $dsh-plugin-dev to create a DSH Tool plugin that accepts a repository path,
finds oversized files, and returns a structured report. Implement and verify it.

使用 Claude Code：

mkdir aaa
cd aaa
claude

/dsh-plugin-dev Create a DSH Tool plugin that accepts a repository path,
finds oversized files, and returns a structured report. Implement and verify it.

生成后，通常可以独立验证项目：

pnpm verify

故障排查与限制

- 在空目录中出现 ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND 意味着 pnpm 在脚手架创建 package.json 之前就运行了。请先启动 Codex 或 Claude Code 并调用此 Skill；生成后再运行 pnpm。
- 生成的项目被锁定到 dsh-reference.lock.json 中经过审计的 Harness 修订版本。源不匹配会停止生成，而不是静默应用错误的契约。
- 生成默认使用 source。移动 Harness 检出目录后，运行 DSH_HARNESS_ROOT=/new/path pnpm context:sync；它会重写六个 link: 依赖并刷新 lockfile。
- --delivery registry 仅在具有 ready Registry 闭包的基线上被接受。它会生成精确的普通版本、dsh-registry.lock.json，以及不带 Harness 路径的可发布清单。最终发布仍需要使用同一个 .tgz 进行干净的安装/导入以及真实的 profile add/dump/boot/remove。

验证此仓库

pnpm build:check
pnpm typecheck
pnpm verify

有关架构、验收证据、当前交接状态和实时路线图，请参阅架构说明、验收证据、维护者交接、基线升级运行手册、产品决策以及 TODO.md。

发现模型遵循官方 OpenAI Skills、OpenAI Plugins 和 Claude Code Skills 文档。