claude-mem 多清单版本发布工作流：从 version-bump Skill 到 npm 人工交接的全流程解读

本篇文章面向需要为 claude-mem（一个以 Claude Code 插件为分发核心、同时发布到 Codex / OpenClaw 等多个生态的记忆持久化系统）执行发布任务的开发者与 AI Agent。文章以 plugin/skills/version-bump/SKILL.md 为骨架，完整还原"版本号抬升 → 构建同步 → 打标签 → GitHub Release → 重新生成 CHANGELOG → npm 人工交接 → 发布后验证与通知"的十三步发布流水线，并结合仓库内的构建脚本与一致性测试解释每一步背后的源码依据。读完本文，你将掌握如何在多清单、多生态的插件仓库中安全、可审计地完成一次语义化版本发布，并理解为何 npm publish 必须作为最终交给人类维护者的唯一动作。

一、这个 Skill 解决什么问题：版本号被散落在八个清单文件里

claude-mem 不是一个只带 package.json 的普通 npm 包：它同时以 Claude Code 插件、Codex 插件、OpenClaw 插件三种形态分发，且同一形态又区分"仓库根目录清单"与"随 npm 包捆绑的运行时清单"。这意味着同一个版本字符串 X.Y.Z 会同时出现在八个 JSON 文件中。任何一处漏改，都会造成"npm 上显示的版本与 marketplace 清单不一致""插件更新提示错误版本"等难以排查的发布事故。

version-bump Skill 的核心价值，就是把这一高度重复、易错、步骤繁多（构建、同步本地 marketplace、重启 worker、清队列、打标签、发 Release、重写 CHANGELOG、发布后核验）的流程，编码成一份 Agent 可逐步执行的确定性 SOP，并在边界处明确划线：npm 发布必须留给持有凭证 / 2FA 的人类维护者。

该 Skill 位于 plugin/skills/ 下，与 mem-search、babysit、smart-explore 等同属 claude-mem 为 Agent 预置的"工作技能"目录（详见 plugin/skills），说明 claude-mem 不只把记忆注入会话，还把自身发布这类仓库运维动作也沉淀为可复用技能。

二、先认清"八个版本文件"各自扮演的角色

SKILL.md 明确列出每一处携带版本字符串的路径。下面结合仓库现状逐一说明其用途（当前仓库所有清单版本均为 13.24.0，可作为核对参考）：

相对路径	角色定位	仓库现状核对
package.json	npm / npx 分发的主版本源，npx claude-mem@X.Y.Z 即从此解析；同时也是其余清单的"单一事实来源"	根目录 package.json "version": "13.24.0"
plugin/package.json	随包捆绑的插件运行时依赖清单（private，含 zod、tree-sitter 系列等运行时依赖）	plugin/package.json "version": "13.24.0"
.claude-plugin/marketplace.json	Claude Code 本地 marketplace 索引，版本位于 plugins[0].version（claude-mem 条目）	.claude-plugin/marketplace.json plugins[0].version = "13.24.0"；注意同文件还含 cowork 插件条目 0.1.3，发布 claude-mem 主版本时只改 plugins[0]
.claude-plugin/plugin.json	仓库根目录的顶层 Claude-plugin 清单	.claude-plugin/plugin.json
plugin/.claude-plugin/plugin.json	随 npm 包捆绑（被发布）的 Claude-plugin 清单	plugin/.claude-plugin/plugin.json
.codex-plugin/plugin.json	Codex 插件清单（仓库根目录）	.codex-plugin/plugin.json
plugin/.codex-plugin/plugin.json	随包捆绑的 Codex 插件清单	plugin/.codex-plugin/plugin.json
openclaw/openclaw.plugin.json	OpenClaw 插件清单	openclaw/openclaw.plugin.json

SKILL.md 给出的覆盖检查方式是两条 git grep：

# 编辑前：确认旧版本只存在于这八个文件中
git grep -l "\"version\": \"<OLD>\""

# 编辑后：确认新版本在八个文件中全部命中
git grep -n "\"version\": \"<NEW>\""
git grep -n "\"version\": \"<OLD>\""   # 期望零命中

值得说明的细节：

• 不要把 marketplace.json 当成普通 JSON 一把梭地全局替换：SKILL 明确指出版本在 plugins[0].version，因为该 marketplace 同时托管 claude-mem 与 claude-mem-cowork 两个插件（当前 cowork 版本为 0.1.3），全局替换会误伤 cowork 条目。
• SKILL 特别提醒：若自文档更新后新增了清单，需同步扩充此列表。事实上从 scripts/sync-plugin-manifests.js 可见，仓库还额外维护了 claude-mem-cursor/.cursor-plugin/plugin.json 与 claude-mem-grok-bot/.cursor-plugin/plugin.json 两个 Cursor 插件的清单，它们由同一脚本负责把根 package.json 的 version 同步过去——发布流程如遇到 Cursor 相关变更，也属于需要核对的范围。

三、完整发布工作流逐段拆解

SKILL.md 将流程编排为 13 步，核心纪律有两条（文档以粗体标注）：动工前先规划并写好详细 Release Notes；结束时工作树必须干净、无任何未提交未推送内容（以最终 git status 验证）。

1. 发布准备：判定语义化版本类型与确认仓库身份

发布前先判定变更属于哪一档语义化版本：

• PATCH：bug 修复；
• MINOR：新增功能；
• MAJOR：破坏性变更。

同时用 git remote -v 确认仓库 owner/name（后续 gh release create、changelog 拉取 GitHub API 都依赖它）。SKILL 还要求先完成 1~2 步的"范围核对"，即上文第一节的 git grep，确保没有遗漏新引入的清单。

2. 抬升版本号（唯一一步"手工编辑 JSON"）

在第一节列出的八个路径上同步递增版本字符串。注意一个反向约束：不要手动碰 CHANGELOG.md——它是脚本从 GitHub Releases 重新生成的产物（见第 5 步），手动编辑会被覆盖。

3. 用 build-and-sync 而不是 npm run build 做发布验证

这是本 Skill 最容易踩坑、也最有工程味道的一步。SKILL 明确警告：不要为了做发布验证而使用裸 npm run build，因为它可能让本地 marketplace / worker 与发布产物失步。

看根目录 package.json 的脚本定义即可理解这一警告的由来：

"build": "node scripts/sync-plugin-manifests.js && node scripts/build-hooks.js && node scripts/gen-plugin-lockfile.cjs",
"build-and-sync": "npm run build && npm run sync-marketplace && node scripts/restart-marketplace-worker.cjs",
"sync-marketplace": "node scripts/sync-marketplace.cjs"

build-and-sync 实际上是三段链路：

1. npm run build：先由 scripts/sync-plugin-manifests.js 从根 package.json 读取 name / version / description / homepage / repository / license / keywords / author 等字段，同步写入 Codex 与 Claude 的根目录 + 捆绑两份清单（共 4 个 JSON），再执行 hooks 构建与插件 lockfile 生成；
2. npm run sync-marketplace：由 scripts/sync-marketplace.cjs 读取 plugin/.claude-plugin/plugin.json 的版本（见其 getPluginVersion()），把本地安装的 marketplace（~/.claude/plugins/marketplaces/thedotmack）镜像为仓库当前状态，并处理 beta 分支守卫与 gitignore 排除规则；
3. node scripts/restart-marketplace-worker.cjs：重启本地的 claude-mem worker 并清空待处理队列，让本地安装立即吃到新版本。

因此发布验证请始终执行：

npm run build-and-sync

4. 提交、打标签、推送

git add -A && git commit -m "chore: bump version to X.Y.Z"
git tag -a vX.Y.Z -m "Version X.Y.Z"
git push origin main && git push origin vX.Y.Z

此处刻意使用 git add -A：因为 build-and-sync 会改动构建产物与本地同步文件，SKILL 的纪律是连构建产物一起提交，不允许工作树残留任何未提交内容。

5. 创建 GitHub Release 并重新生成 CHANGELOG

先基于第 1 步写好的发布说明创建 Release：

gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES"

随后重新生成 CHANGELOG（不要手动编辑它）：

npm run changelog:generate

该命令实际运行 scripts/generate-changelog.js，实现细节印证了"CHANGELOG 是派生产物"的定位：它通过 gh release list --limit 1000 --json tagName,publishedAt,name 拉取全部 Releases，再对每个 tag 用 gh release view <tag> --json body --jq '.body' 取正文，清洗掉"Generated with Claude Code"尾部水印后，按 Keep a Changelog 格式（含固定文件头，见 CHANGELOG.md 头部）重写整个 CHANGELOG.md。仓库中的 plugin/skills/version-bump/scripts/generate_changelog.js 则是一个更轻量的从 stdin 读取 JSON 生成 changelog 的辅助实现，可用于无 GitHub CLI 的受限环境。

改完 CHANGELOG.md 后需再次提交并推送（SKILL 第 9 步"Sync changelog"）。

6. 发布前审计（pre-handoff audit）

正式把 npm 发布交给人之前，Agent 必须逐项确认：

• release commit、tag、GitHub Release、changelog 均已推送；
• release worktree 无 pending tracked 变更；
• 构建依赖齐全——因为 prepublishOnly 会在发布时重建包。

若此时 npm view claude-mem@X.Y.Z version 已能解析到目标版本，说明此前已发布过，可跳过交接直接进入发布后检查。

7. 最终人工交接：npm publish 是唯一的"人要做的事"

SKILL 在此画出了全流程最严格的职责边界，原话值得逐字理解：

Do not stop in the middle of the workflow for npm. Finish every agent-owned preparation above first, then make this the final human-required action.

• 人类维护者的凭证 / 2FA 是必需的；
• Agent 绝不运行 npm publish，也绝不运行会触发发布的 np 或 npm run release:*（根 package.json 中确实定义了 "release": "np"、"release:patch"、"release:minor"、"release:major" 四条由 np 驱动的命令，全部属于 Agent 禁手）；
• Agent 只需给出精确的 release worktree 路径和这一条命令，作为唯一请求动作：

npm publish   # run by the HUMAN — prepublishOnly rebuilds the package

prepublishOnly 钩子同样定义在 package.json："prepublishOnly": "npm run build && node scripts/check-postinstall-allowlist.js"，即发布前自动重建并把一次构建 + postinstall 白名单检查兜住，降低"人发布的是旧产物"的风险。

交接后 Agent 应等待确认，且不得再要求人类执行任何其他发布步骤。

8. 发布后验证与 Discord 通知

人类确认发布成功后，Agent 依次执行：

# 同时验证精确版本号与 latest dist-tag
npm view claude-mem@X.Y.Z version
npm view claude-mem version

若发布触发的重建改动了 tracked artifacts，再跑一次 npm run build-and-sync、审查结果并提交推送合法变更。随后才执行 Discord 通知——且必须等到 npm 验证通过之后：

cd ~/Scripts/claude-mem/ && npm run discord:notify vX.Y.Z

这条命令对应 package.json 的 "discord:notify": "node scripts/discord-release-notify.js"。从 scripts/discord-release-notify.js 源码看，通知脚本会解析存放 webhook 的 .env（键名 DISCORD_UPDATES_WEBHOOK），并通过 gh release view <version> --json body --jq '.body' 拉取 Release 正文作为通知内容——因此 SKILL 强调"必须先有 npm 验证、且即使 release worktree 没有本地 .env 也要执行"，因为 webhook 密钥存放于维护者的 ~/Scripts/claude-mem/ 环境而非仓库内。

9. 收尾

git status   # 工作树必须干净，所有内容已推送

自最终人工交接之后，只允许自动化验证、通知与清理动作发生。

四、Checklist：Agent 自检清单的完整语义

SKILL 末尾的 checklist 把"验证点"与"责任边界"分成两类，翻译过来即：

版本一致性类

• 八个配置文件版本一致；
• 对旧版本字符串的 git grep 零命中；
• npm run build-and-sync 成功。

发布物落库类

• Git tag 已创建并推送；
• GitHub Release 已创建且含 notes；
• CHANGELOG.md 已更新并推送。

职责边界与收尾类

• 发布前审计通过，无任何 Agent 可自主完成的发布准备残留；
• npm 发布已作为最终人工必要动作交接（Agent 未运行 npm publish）；
• 人类发布后，精确版本号与 latest 均验证通过；
• Discord 通知仅在 npm 验证之后、且从 ~/Scripts/claude-mem/ 执行；
• git status 干净。

这份 checklist 的价值不在于"勾选动作"，而在于把最容易在长流程中遗漏的核验动作（发布后二次 npm view、通知时序）和权限边界（Agent 禁跑 publish）显式化为可勾选项。

五、从源码看这套纪律为什么成立

claude-mem 之所以在 SKILL 中反复强调"版本一致性 + 全量构建同步 + npm 人工兜底"，底层有两层源码支撑：

其一，"清单自动同步"机制只覆盖了一部分文件，其余仍需人工抬版本。 scripts/sync-plugin-manifests.js 会在每次 npm run build 时把根 package.json 的版本写入 Codex/Claude/Cursor 共 6 个清单，但它不写 plugin/package.json、.claude-plugin/marketplace.json 与 openclaw/openclaw.plugin.json。也就是说 build 并非全自动完成抬版本，SKILL 第 1 步的"人工同步八个文件 + git grep 兜底"依然是流程的源头。

其二，测试层把"版本一致"固化为回归防线。 tests/infrastructure/version-consistency.test.ts 逐项断言根 package.json 与 plugin/package.json、plugin/.claude-plugin/plugin.json、.claude-plugin/marketplace.json（claude-mem 条目）等清单的版本完全相等、格式符合 ^\d+\.\d+\.\d+$ 的 semver 形态，甚至验证构建产物 worker-service.cjs 中注入了对应版本字符串（见其中"should have version injected into built worker-service.cjs"用例）。这解释了为什么 SKILL 要求"连构建产物一起提交"：版本号不仅活在 JSON 清单里，还会被 scripts/build-hooks.js 注入到运行时构建产物中，任何单点不一致都可能让线上 worker 自报版本与 marketplace 清单脱节。

六、核心结论：把"可自动化的"自动化，把"需要信任的"留给人类

回顾整个 version-bump 工作流，其设计哲学可以浓缩为三点，也值得任何做多生态分发插件的项目借鉴：

1. 版本单一事实来源 + 多清单扩散：根 package.json 是源头，构建脚本自动扩散到捆绑清单，SKILL 负责覆盖脚本覆盖不到的三处（plugin/package.json、marketplace.json、OpenClaw 清单），再用 git grep 与 version-consistency 测试形成双保险；
2. 发布验证必须以 build-and-sync 为唯一入口：裸 npm run build 只完成产物构建，sync-marketplace 与 restart-marketplace-worker 才保证本地安装环境与发布内容同步，避免"版本已发布但本地 marketplace 仍旧版"的割裂状态；
3. npm publish 是硬性的人工交接点：凭证 / 2FA 属于人类信任边界，Agent 完成全部可自主执行的准备（抬版本、构建、tag、Release、changelog、审计）后，把 npm publish 作为唯一请求动作交给维护者，再在确认后完成 npm view 双校验与 Discord 通知收尾。整条流水线的状态机在 plugin/skills/version-bump/SKILL.md 中有完整、可直接执行的版本，配合 package.json、scripts 目录下的真实实现与 tests/infrastructure/version-consistency.test.ts，即可在当前仓库内完整复现一次受控发布。