# Claude Code VOC 技能包 npm 打包经验

## 目标

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

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

推荐命令：

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

免全局安装：

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

## 关键设计

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

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

```text
~/.claude/plugins/voc-intelligence
```

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

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

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

## package.json 要点

- npm 包名使用 scoped package：`@gangvy/claude-code-voc-intelligence`
- CLI 入口：

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

- `files` 必须显式包含：
  - `.claude-plugin/`
  - `.mcp.json`
  - `bin/`
  - `skills/`
  - `mcp/`
  - `memory-templates/`
  - `docs/`
  - `install.js`
  - `skill-package-manifest.json`

## 验证命令

根目录执行：

```bash
npm run claude-voc:npm-pack
```

这个命令会做三件事：

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

发布命令：

```bash
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 这类参数；安装完成后仍然用自然语言启动。