Эхлэл Бүгдийг харах Тусламж
Нэвтрэх
18307996893
/
openclaw-voc-skill
2
2
Салаа 0
Файлууд Асуудлууд 0 Хуулах хүсэлтүүд 0 Мэдлэгийн сан
Мод: e8d9ccfbfd
Салаанууд Тагууд
openclaw-voc-sk...
/
claude-code
/
claude-code-voc-intelligence
/
docs
/
npm-packaging-notes.md

npm-packaging-notes.md 6.1 KB
Түүх Анхны өгөгдөл

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

当前包名

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

@vocmarket/voc-skill

CLI 命令保持不变：

claude-voc

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

voc-intelligence

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

用户安装方式

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

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

工作区安装会写入：

.\.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

全局安装：

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

npx 免全局安装：

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

package.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 临时目录

发布前验证

在仓库根目录执行：

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 -ExecutionPolicy Bypass -File release/npm/claude-code-voc-intelligence/publish.ps1

也可以直接执行：

npm run claude-voc:npm-publish

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

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

文件内容格式：

NPM_TOKEN=你的 npm automation token

也支持环境变量：

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

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

发布后验证

确认 npm latest：

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

线上安装 smoke：

$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 已经返回成功，例如：

+ @vocmarket/voc-skill@0.3.15

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

处理方式：

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

    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。