openclaw-voc-skill/claude-code-voc-intelligence/docs/npm-packaging-notes.md

Claude Code VOC 技能包 npm 打包经验

目标

同一个技能包同时支持两种交付：

• 链接下载 zip：适合不会 npm 的客户，解压后执行 node install.js。
• npm/npx 安装：适合教学、远程交付和批量升级。

推荐命令：

npm install -g @gangvy/claude-code-voc-intelligence
claude-voc install

免全局安装：

npx @gangvy/claude-code-voc-intelligence install

关键设计

npx 下载的包可能在临时缓存里，不能直接让 Claude Code 长期加载这个临时目录。

所以 claude-voc install 会把包复制到固定目录：

~/.claude/plugins/voc-intelligence

然后在该目录安装运行依赖，并输出：

claude --plugin-dir "<安装目录>"

这样全局安装和 npx 安装的结果一致，后续也便于升级。

package.json 要点

• npm 包名使用 scoped package：@gangvy/claude-code-voc-intelligence

• CLI 入口：

  {
  "bin": {
  "claude-voc": "bin/claude-voc.js"
  }
  }
  

• files 必须显式包含：

  • .claude-plugin/
  • .mcp.json
  • bin/
  • skills/
  • mcp/
  • memory-templates/
  • docs/
  • install.js
  • skill-package-manifest.json

验证命令

根目录执行：

npm run claude-voc:npm-pack

这个命令会做三件事：

1. 校验 npm package metadata 和 CLI 入口。
2. 生成 dist/npm/*.tgz。
3. 在临时目录里模拟 npm 安装，并执行 claude-voc install --smoke。

发布命令：

npm run claude-voc:npm-publish

发布前需要完成 npm login，或在 CI/部署环境配置 npm token。

注意点

• zip 包和 npm 包共用同一套源码，但验证脚本分开。
• npm 包不要发布 node_modules/、memory/、outputs/、.env。
• install.js 不强依赖 package-lock.json，因为 npm publish 后 package-lock 不一定随包安装。
• 用户侧不要暴露 profile、output、collectionMode 这类参数；安装完成后仍然用自然语言启动。