dsh-plugin-template

通过 npx 一键创建一个可直接使用的 TypeScript 版 DeepSeek Harness（DSH）插件项目。

基于官方文档《第一个插件》《开发一个工具》《插件配置》《打包与安装插件》设计，模板内置：

• 标准插件结构：name / inject / Config（Schemastery schema）/ apply(ctx, config)
• 一个可直接运行的 greet 工具示例（defineTool + ctx.tools.register）
• 两种加载方式：本地开发覆盖层（绝对路径指向 src/index.ts，Node ≥ 22.6 直接加载 TS）与 dsh.bundle 组合包（构建后安装进 profile）
• 零运行时依赖的脚手架（纯 Node 内置模块），生成的插件项目用 tsc 构建，无额外打包器

使用

# 创建项目（默认包名 dsh-<name>）
npx @4t145/create-dsh-plugin greet

# 自定义包名 / 描述
npx @4t145/create-dsh-plugin greet --package-name my-greet --description "Greeting tools for DSH"

# 作用域包名（目录名取 name 部分）
npx @4t145/create-dsh-plugin @acme/greet

# 跳过依赖安装 / 覆盖已存在目录
npx @4t145/create-dsh-plugin greet --skip-install --force

生成的项目：

greet/
├── src/
│   └── index.ts          # 插件入口（greet 工具示例 + 可配置问候语）
├── cordis.patch.yml      # dsh.bundle 清单的 patch（按包名解析）
├── cordis.dev.patch.yml  # 本地开发覆盖层（已写入 src/index.ts 的绝对路径）
├── tsconfig.json         # 类型检查
├── tsconfig.build.json   # 构建到 lib/
└── package.json          # 含 dsh.bundle 清单 + peerDependencies

生成后立即：

cd greet

# 1) 本地开发（从 deepseek-harness 源码检出运行）
pnpm dsh web --patch "$PWD/cordis.dev.patch.yml"

# 2) 构建
npm run build

# 3) 安装进 profile（作为组合包）
dsh plugin --profile <profile> add .

详见生成项目内的 README.md。

本地开发本脚手架

npm pack                # 打出 4t145-create-dsh-plugin-<version>.tgz
npm exec --package=./4t145-create-dsh-plugin-0.1.0.tgz -- create-dsh-plugin greet
# 或直接运行源码
node bin/index.js greet

发布到 npm（GitHub Actions + Trusted Publishing）

仓库 4t145/dsh-plugin-template 内置 .github/workflows/publish.yml，采用 npm 官方的 Trusted Publishing（OIDC）：CI 不需要任何 npm token，GitHub Actions 通过 OIDC 短期凭证自动认证并发布，同时自动生成 provenance（供应链证明）。

• 推送 v<版本号> 标签（如 v0.1.0）→ CI 先跑 npm test，再自动 npm publish
• 标签必须与 package.json 的 version 一致，否则 CI 报错中止
• 工作流已声明 permissions: id-token: write（OIDC 必需）

一次性配置（首次发布前完成）

1. 首次发布：包必须先存在于 npm 才能配置 trusted publisher。在本机执行（需要 2FA 验证码）：

cd /home/atlas/Github/dsh-plugin-template
npm login        # 如尚未登录
npm publish      # 会要求输入 OTP

2. 添加 trusted publisher：打开 https://www.npmjs.com/package/@4t145/create-dsh-plugin/settings → Trusted publishing 区域：

字段	值
Provider	GitHub Actions
Organization or user	4t145
Repository	dsh-plugin-template
Workflow filename	publish.yml（只填文件名，带扩展名）
Environment name	留空
Allowed actions	npm publish

3. 之后每次发版：npm version patch && git push --follow-tags（或手动打 v<版本> 标签推送），CI 自动发布。

4. （可选，推荐）发布验证通过后，在包设置页把 Publishing access 改为 Require two-factor authentication and disallow tokens，并删除 npm 账户里旧的 token。

手动触发：Actions 页面的 publish workflow → Run workflow（只跑检查，不发布）。

发布到 npm（手动）

npm publish    # 之后即可全局使用 npx @4t145/create-dsh-plugin@latest <name>

注：npm 上已存在同名的非官方包 create-dsh-plugin，本仓库发布为 @4t145/create-dsh-plugin（作用域包）以避免混淆；DeepSeek 官方目前未提供任何脚手架。

端到端测试

npm test   # 脚手架 → npm install → typecheck → build

验证过的加载路径

仓库开发过程中用 @deepseek-ai/dsh@0.1.0-rc.6 实测确认：

1. --patch 覆盖层以绝对路径引用 src/index.ts → Node 类型剥离直接加载（无需构建）
2. --patch 覆盖层引用构建产物 lib/index.js → 正常加载
3. 按包名解析（模拟 profile node_modules 布局）→ 正常加载，patch 中 config 覆盖经 Schemastery 校验后生效

License

MIT