# Claude Code VOC Intelligence npm 发布包

这个文件夹用于沉淀 `@vocmarket/voc-skill` 的 npm 发布流程。

## 用户安装方式

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

```bash
npx @vocmarket/voc-skill@latest workspace --smoke
```

这种方式会把技能包安装到当前工作区：

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

并同步写入当前工作区的 `.mcp.json` 和 `.claude/skills/xiaohongshu-trend-intelligence/SKILL.md`，方便 Claude Code 插件直接识别 MCP 工具和技能工作流。

全局安装：

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

免全局安装：

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

两种方式都会把技能包安装到：

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

然后按提示用 `claude --plugin-dir` 加载。

## 发布前验证

在仓库根目录执行：

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

这个命令会：

1. 校验 `package.json`、CLI 入口和必要文件。
2. 生成 `dist/npm/vocmarket-voc-skill-<version>.tgz`。
3. 模拟全局安装后的 `claude-voc install --smoke`。
4. 模拟 `npx` 方式的 `claude-voc install --smoke`。
5. 模拟 VSCode Claude Code 推荐的 `claude-voc workspace --smoke`。

完整发布前验收：

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

这个命令会串联包级 smoke、MCP smoke、`npm pack --dry-run`、临时 workspace 安装，并断言 `.mcp.json` 里的 MCP server 路径是安装后插件目录内的绝对路径。

也可以直接运行本目录脚本：

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

## 正式发布

方式一：本机已 `npm login`

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

方式二：使用 token

```powershell
$env:NPM_TOKEN="你的 npm automation token"
powershell -ExecutionPolicy Bypass -File release/npm/claude-code-voc-intelligence/publish.ps1
```

也可以放到本目录的本地文件，不提交 git：

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

内容：

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

`.env.local` 已在仓库 `.gitignore` 中忽略。

发布脚本会先跑完整验证，再执行：

```bash
npm publish <tgz> --access public
```

## 当前发布状态

- 当前 npm latest：`@vocmarket/voc-skill@0.3.15`
- 本地 dist zip/tgz manifest 已重建到 `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` 一键发布前验收，借鉴 `tihao-sop` 的 workspace 安装断言方式。
- 已新增：图文报告资产缓存，证据样本首图默认缓存到 `outputs/<run>/assets/`，Markdown 报告优先引用本地 `assets/...`，JSON 保留原图 URL 与本地路径。
- 已修复：无 VOC token、余额不足或未开通时，不再暴露底层 403/权限/余额报错，统一返回充值链接引导。
- 已优化：小红书/社媒任务优先调用 VOC Skill/MCP，不用 WebSearch 替代；报告证据样本包含原帖链接、首图、原文摘录、高赞评论和“为什么值得看”。
- 已修复：小红书原帖链接优先使用 `mini_program_info.webpage_url` 或带 `xsec_token` 的 `share_info.link`，不再把 `/explore/<noteId>` 作为主链接。

## 发布成功但校验 404 的处理

如果 `npm publish` 已经输出：

```text
+ @vocmarket/voc-skill@版本号
```

但脚本后置 `npm view` 立刻返回 404，通常是 npm registry 同步延迟，不要马上重复发布同一个版本。

建议等待 20-60 秒后执行：

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

如果能返回版本号，说明发布成功。当前发布脚本已延长后置校验等待次数，降低误报概率。

## 后续版本更新

1. 修改技能包代码、文档或 MCP 工具。
2. 升级版本号：
   - `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`
3. 如涉及 MCP server 或记忆 schema，同步更新对应版本字段。
4. 执行 `npm run claude-voc:npm-pack`。
5. 执行 `npm run claude-voc:npm-publish`。

用户升级：

```bash
npm install -g @vocmarket/voc-skill@latest
claude-voc install
```

或：

```bash
npx @vocmarket/voc-skill@latest install
```

VSCode Claude Code 工作区升级：

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