# Claude Code VOC 技能包 npm 打包与发布说明

## 当前包名

VOC 技能包当前对外 npm 包名：

```bash
@vocmarket/voc-skill
```

CLI 命令保持不变：

```bash
claude-voc
```

插件安装目录也保持不变：

```text
voc-intelligence
```

这样做的目的：对外包名更短、更适合课程和市场传播；同时不破坏已经沉淀好的 Claude Code 插件目录、MCP server 名称和 skill 入口。

## 用户安装方式

推荐给 VSCode Claude Code 使用工作区安装：

```powershell
npx --yes @vocmarket/voc-skill@latest workspace --smoke
```

工作区安装会写入：

```text
.\.mcp.json
.\.claude\plugins\voc-intelligence
.\.claude\skills\xiaohongshu-trend-intelligence\SKILL.md
.\.claude\skills\douyin-trend-intelligence\SKILL.md
.\.claude\skills\voc-issue-pool\SKILL.md
.\.claude\skills\voc-problem-deep-dive\SKILL.md
.\.claude\skills\voc-content-plan\SKILL.md
.\.claude\skills\voc-speaking-script\SKILL.md
.\.claude\skills\voc-competitor-map\SKILL.md
.\.claude\skills\voc-business-workflow\SKILL.md
```

全局安装：

```powershell
npm install -g @vocmarket/voc-skill
claude-voc install
```

npx 免全局安装：

```powershell
npx --yes @vocmarket/voc-skill@latest install
```

## package.json 要点

```json
{
  "name": "@vocmarket/voc-skill",
  "bin": {
    "claude-voc": "bin/claude-voc.js"
  },
  "publishConfig": {
    "access": "public"
  }
}
```

`files` 必须显式包含：

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

不要发布：

- `.env`
- `.env.local`
- `.npmrc`
- `node_modules/`
- `memory/`
- `outputs/`
- 本地 smoke 临时目录

## 发布前验证

在仓库根目录执行：

```powershell
npm --prefix claude-code/claude-code-voc-intelligence run mcp:smoke
npm --prefix claude-code/claude-code-voc-intelligence run smoke:package
npm run claude-voc:acceptance
npm run claude-voc:build
npm run claude-voc:npm-pack
```

`npm run claude-voc:npm-pack` 会做三类验证：

1. 校验 npm package metadata、CLI 入口和必要文件。
2. 生成 `dist/npm/vocmarket-voc-skill-<version>.tgz`。
3. 在临时目录模拟 npm install、npx install、workspace install，并执行 `--smoke`。

`npm run claude-voc:acceptance` 是更完整的发布前验收，会额外断言 workspace 安装后的：

- `.mcp.json` 已生成
- 8 个 `.claude/skills/*/SKILL.md` 入口已生成
- MCP server 路径是安装后插件目录里的绝对路径
- `npm pack --dry-run` 能看到关键文件

## 正式发布

推荐使用 release 脚本：

```powershell
powershell -ExecutionPolicy Bypass -File release/npm/claude-code-voc-intelligence/publish.ps1
```

也可以直接执行：

```powershell
npm run claude-voc:npm-publish
```

发布脚本会读取以下位置的 token：

```text
release/npm/claude-code-voc-intelligence/.env.local
```

文件内容格式：

```text
NPM_TOKEN=你的 npm automation token
```

也支持环境变量：

```powershell
$env:NPM_TOKEN="你的 npm automation token"
```

不要提交 `.env.local`、npm token、VOC session token、模型 API key 或任何真实用户凭证。

## 发布后验证

确认 npm latest：

```powershell
npm view @vocmarket/voc-skill name version dist-tags.latest --registry=https://registry.npmjs.org/
```

线上安装 smoke：

```powershell
$test = Join-Path $env:TEMP ("vocmarket-online-smoke-" + [guid]::NewGuid())
New-Item -ItemType Directory -Path $test | Out-Null
Push-Location $test
npm exec --yes --package @vocmarket/voc-skill@latest -- claude-voc workspace --smoke
Pop-Location
```

## npm 发布假失败处理

有时 `npm publish` 已经返回成功，例如：

```text
+ @vocmarket/voc-skill@0.3.15
```

但脚本紧接着执行 `npm view` 时，registry 还没同步完成，会短暂返回 404。

处理方式：

1. 等 20-60 秒后重新执行：

```powershell
npm view @vocmarket/voc-skill@0.3.15 version --registry=https://registry.npmjs.org/
```

2. 如果返回版本号，说明发布已经成功，不要重复发布同一个版本。
3. 如果持续 404，再检查 npm 组织权限、token 权限和包名 scope。

当前发布脚本已经把后置校验等待次数从 6 次增加到 12 次，减少这种假失败。

## 当前发布记录

- 2026-06-05：已发布 `@vocmarket/voc-skill@0.3.15`。
- `npm view @vocmarket/voc-skill name version dist-tags.latest` 返回 `0.3.15`。
- 线上 `npm exec --yes --package @vocmarket/voc-skill@latest -- claude-voc workspace --smoke` 已通过。
- 旧包 `@gangvy/claude-code-voc-intelligence@*` 已标记为 deprecated，安装旧包时会提示改用 `@vocmarket/voc-skill`。
- 已新增 `npm run claude-voc:acceptance` 一键发布前验收，覆盖包级 smoke、MCP smoke、npm pack dry-run 和 workspace 安装断言。
- 包内包含 8 个 skill、12 个 MCP tools。
- smoke 覆盖 sample report、证据卡、图片缓存、xsec URL 规范化、偏好记忆、no-token 充值提示、祖先 `.env.local` token 读取、抖音搜索入参错误保护、跨行业样例和 MCP tool discovery。

## 后续版本同步

升级版本时同步修改：

- `claude-code/claude-code-voc-intelligence/package.json`
- `claude-code/claude-code-voc-intelligence/package-lock.json`
- `claude-code/claude-code-voc-intelligence/skill-package-manifest.json`
- `claude-code/claude-code-voc-intelligence/.claude-plugin/plugin.json`
- 如涉及 MCP server 或记忆 schema，同步对应版本字段
- `dist/npm/claude-code-voc-npm-package-manifest.json`
- `dist/claude-code-voc-intelligence-suite-manifest.json`
- `release/npm/claude-code-voc-intelligence/README.md`
- `release/npm/claude-code-voc-intelligence/release-checklist.md`

## 体验原则

- 用户侧不要暴露 `profile`、`output`、`collectionMode` 等底层参数。
- 用户用自然语言触发 VOC 采集、问题池、单点深挖、内容计划和口播脚本。
- 第一轮真实采集只输出“初步判断 / 机会假设 / 待校准”，不要包装成最终结论。
- 无 token、余额不足、业务权限未开通时，返回开通/充值引导，不直接暴露底层 403、余额接口或 stack trace。