dsh-plugin-scaffold — DSH 插件脚手架

一条命令生成一个零业务功能的 DSH（DeepSeek Harness / Cordis）静态插件开发框架。

• 开箱即全绿 —— host/client 双半、shared contract、构建/安装/调试脚本、双冒烟测试一样不少；
• 最小面自证 —— 唯一的业务是一条 ping RPC：bundle 加载 → Typert 注册 → Gateway 挂载 → Slot 渲染 → RPC 回环；
• 两种发布 —— 纯本地出 tarball 备份搬运，或 --push 一键 Git + CI 自动 npm publish / GitHub Release；
• AI 友好 —— 模板自带 docs/client-modules.md：客户端可注入服务/模块/UI 扩展点速查 + 给 AI 的提示词骨架；
• 零运行时依赖 —— CLI 纯 Node 标准库，tarball 离线可用。

安装

# 从 npm 全局安装
npm i -g dsh-plugin-scaffold
dsh-plugin-scaffold demo-tools

# 或免安装直接用
npx dsh-plugin-scaffold@latest demo-tools

首次发布成功前上面的命令会 404，本地场景用 tarball 等价替代（见发布与备份）。

快速开始

dsh-plugin-scaffold demo-tools   # 1. 生成（TTY 下交互补全缺省项，回车即用推导值）
cd demo-tools                    # 2. 进入项目
npm install                      # 3. 装依赖
npm run install:local            # 4. 构建 + 软链进 ~/.dsh/profiles/web
# 5. 重启 dsh / 刷新 Web GUI → 设置页出现「Demo Tools」→ 点 Ping Host → 显示 RTT

本包（CLI + 模板）
├─ bin/cli.mjs + lib/*       CLI：复制模板 → 替换占位符 → 校验 → 指引
└─ templates/default/       模板项目（占位符待替换）
        │ dsh-plugin-scaffold demo-tools
        ▼
   demo-tools/               生成的项目：npm install 后即可 build/test/install:local

用法（三种等价入口）

# A. 直接 node 执行（最常用）
node <本包路径>/bin/cli.mjs demo-tools

# B. npm link 之后获得全局命令
npm link          # 在本包目录执行一次
dsh-plugin-scaffold demo-tools

# C. tarball 携带（备份 / 换机 / 给别人；CLI 零依赖，离线可用）
npm pack          # 得到 dsh-plugin-scaffold-x.y.z.tgz
npm exec --yes ./dsh-plugin-scaffold-x.y.z.tgz -- demo-tools

参数

dsh-plugin-scaffold <project-name> [options]

  --dir <path>         生成目标父目录（默认：当前工作目录）
  --template <path>    模板目录（默认：<CLI 包>/templates/default）
  --id <plugin-id>     覆盖自动推导的插件 ID
  --service-key <key>  覆盖自动推导的 SERVICE_KEY
  --desc <text>        一句话描述
  --author <text>      作者（默认 wqy8593521）
  --pm <npm|pnpm>      只影响「下一步」提示文案（默认 npm）
  --install            生成后立即安装依赖
  --force              目标目录已存在且非空时覆盖
  -h / --version

占位符与推导规则

| Token | 含义 | 推导（缺省） | |-------|------|--------------| | {{PLUGIN_ID}} | 包名 / loader entry id | 输入转 kebab-case，无 dsh- 前缀则补（demo → dsh-demo） | | {{SERVICE_KEY}} | Typert 服务键 | 去 dsh- 前缀后 camelCase（dsh-demo-tools → demoTools） | | {{DISPLAY_NAME}} | 人读名称 | ID 转空格分隔 Title Case（Demo Tools） | | {{DESCRIPTION}} | 一句话描述 | 「DISPLAY_NAME — DSH 静态插件（脚手架生成）」 | | {{AUTHOR}} | 作者 | --author / 交互，默认 wqy8593521 | | {{SCAFFOLD_VERSION}} | 模板版本 | 本包版本号（写入生成项目的 scaffoldVersion 字段） | | {{YEAR}} | 版权年份 | 生成当年（LICENSE 用） |

替换只针对文本文件（二进制原样拷贝）；替换后全树扫描，发现残留占位符即报错并回滚删除目标目录。

生成项目的常用命令

| 命令 | 作用 | |---|---| | npm run build / typecheck / test | 构建、类型检查、双冒烟测试（开箱全绿） | | npm run install:local | 构建并软链进 DSH Profile（联调） | | npm run uninstall:local | 从 Profile 移除（移动/删除项目前先执行，防悬空软链） | | npm run run:host | 纯 Host 半调试（不起 GUI） | | npm run release | 本地发版：验证 → 版本递增 → CHANGELOG → tarball |

改业务落点与客户端能力速查见模板内 docs/client-modules.md （两层 inject 契约、平台种子模块、UI 扩展点地图、常见坑、给 AI 的提示词骨架）。

分发约束

设计口径：脚手架与生成动作保持完全本地；对外发布是开发者的显式行为。

1. 脚手架本体与模板的 package.json 不含 repository / bugs / homepage； CLI 生成时不执行 git init、不写入任何远程仓库 URL；
2. 生成项目默认零 Git 痕迹；开发者选择发布时自行 git init + 配远端， 然后 npm run release -- --push 触发 CI 自动 publish 与 GitHub Release；
3. 本包（脚手架自身）README 带 npm/GitHub 徽章；生成项目 README 保持 无仓库链接、只写本地用法——两条边界互不影响；
4. .npmignore 收紧（模式锚定到包根），tarball 只含 bin/ lib/ templates/ README.md LICENSE。

打包细节（npm 的两个坑，已规避）

• 模板不带 .npmignore：npm pack 会把子目录里的 .npmignore 也当作规则应用， 导致脚手架自身 tarball 里 templates/default 的源码被剪掉。生成项目改用 files 白名单达成同样意图。
• .gitignore 以无点 gitignore 携带：npm 永远排除包内的 .gitignore 文件本身； CLI 复制后把它重命名回 .gitignore。

发布与备份

npm run release               # 验证（全量语法检查 + 真实生成自证）→ 版本递增 → CHANGELOG → release/*.tgz
npm run release -- minor --note "xxx" --note "yyy"
npm run release-remote        # = release --push：commit/tag/push 触发 CI 自动 npm publish + GitHub Release
npm pack                      # 只打包不升版（旧方式，仍可用）

验证失败中止且零改动；打包失败自动回滚版本号与 CHANGELOG。tarball 即离线备份/ 搬运载体：拷贝到任意机器后 npm i -g ./dsh-plugin-scaffold-x.y.z.tgz 即可用。

升级策略

• 模板版本 = 本包版本（语义化：骨架结构 minor，占位符/参数 patch）；
• 每个生成项目在 package.json 记录 scaffoldVersion，模板升级后人工 diff 回移（v1 不自动化）；
• 骨架变化记录在本包 CHANGELOG.md。

License

MIT © wqy8593521