claude-mem 三发布分支策略：main / core-dev / community-edge 的规划、落地与源码运行指南

本篇技术文章基于 claude-mem 仓库中的分支策略规划文档 plans/2026-07-05-three-release-branches.md，完整还原该项目如何把三个一次性 PR 升级为三条长期发布线（stable / core-dev / community-edge）：包括四条发布线对照表、变更流向设计、四个执行阶段（建分支、写文档、接导航与 README、终验）的具体命令与验证方式，并结合 package.json 中的真实 npm scripts 与 scripts/sync-marketplace.cjs 源码，讲清 npm run build-and-sync 如何在本地把非稳定分支装进 Claude Code 插件市场并重启 worker。读完你能掌握一条"单维护者、低仪式"的多发布线 Git 策略的完整落地路径，以及从源码运行 claude-mem 非稳定分支的可复制命令链。

一、规划背景：为什么需要三条长期发布线

claude-mem 是运行在 Claude Code 等 Agent 之上的持久记忆系统，安装形态是 npx claude-mem 发布的 npm 包。规划文档开头明确了它的 Owner 与目标：

Owner: solo maintainer。Goal: turn the three plan PRs into three permanent release lines, document the strategy in one place, and give clone/run instructions for the non-stable lines.

也就是说，仓库里同时存在三个"计划型 PR"，它们原本都是朝着 main 合入的一次性 PR；维护者决定不合入 main，而是把其中两个 PR 的内容沉淀为两条永久分支，再加上 main 本身，构成三条长期发布线。这个决策针对的是典型的单维护者（solo maintainer）仓库治理问题：既要有稳定的对外发布面，又要有承载"根因级可靠性修复"和"社区集成前沿"的试验田，且不能引入 CI 门禁、强制评审等重流程（规划原文明确 "No gates, no required reviewers — solo maintainer discretion"）。

三条线对照表（规划的 source of truth）

规划文档给出的核心表格是整篇文章的主干：

Line	Branch	For	Published to npm?
Stable	main	Everyone. The npx claude-mem install.	Yes（唯一发布线）
Core Dev	core-dev	Maintainer + testers wanting root-cause fixes	No — run from source
Community Edge	community-edge	Bleeding edge, integrated community PRs	No — run from source

这张表定义了各条线的服务对象和分发方式，后面所有阶段（建分支、写文档、README 提示）都是围绕它展开的。

二、规划时已核实的事实基线（Facts, verified 2026-07-05）

规划文档在动手前记录了一批"已核实事实"，这是执行类文档的重要部分，它让后续阶段的所有命令都有据可依：

• PR #3141 plan/stable-working-build @ f6c7f51 — base main，是 STABLE 的落点；
• PR #3143 plan/root-cause-holistic-fixes @ c81acee — 将成为 core-dev 分支；
• PR #3142 plan/community-bleeding-edge @ a20d1ac — 将成为 community-edge 分支；
• 当时 origin 上尚不存在 core-dev / community-edge 分支；
• 文档侧：docs/public/*.mdx，导航位于 docs/public/docs.json 的 "Configuration & Development" 分组（规划时约在第 79 行）；
• README 贡献章节约在第 374 行；
• 非稳定线的运行路径 = clone + git checkout <branch> + npm install + npm run build-and-sync。

其中"非稳定线运行路径"这条事实可以直接在 package.json 中验证：build-and-sync 是一个真实存在的 script，其定义为：

"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"

可见 build-and-sync 恰好串联了三步：构建产物 → 同步到本地插件市场 → 重启市场 worker，与规划文档中"builds + syncs to local marketplace + restarts worker"的注释完全对应。而规划文档特别要求"不得虚构 npm script，只允许引用真实存在的 build-and-sync、release、release:patch|minor|major"，这些脚本在 package.json 中均可一一对应找到（"release": "np"、"release:patch": "np patch --no-cleanup" 等）。

三、Phase 0 决策点：两个 PR 的命运

执行前规划文档提出了一个关键决策：PR #3143 和 #3142 本是"合入 main"的 PR，但现在它们的内容将变成永久分支，合入就失去意义，两个 PR 因此冗余。

规划给出的推荐方案是：从 PR head 创建分支，推送后关闭这两个 PR，并附一条重定向评论——"Promoted to long-lived branch core-dev / community-edge; this is now a permanent release line, not a merge-to-main."；同时保持 PR #3141（stable landing）打开或按原计划合入。这一步体现了发布线策略中"PR 与分支各司其职"的边界：stable 走 PR 合入流程，edge 线走分支常驻流程。

四、Phase 1：创建并推送两条 edge 分支

规划的 Phase 1 给出了精确到 SHA 的命令：

# 1. 从 PR #3143 head 创建 core-dev
git branch core-dev c81acee39a771848bd30ee26e3c52ec26d713cd1
git push origin core-dev

# 2. 从 PR #3142 head 创建 community-edge
git branch community-edge a20d1ac44144d4749acfd68faceda2794f3187f0
git push origin community-edge

# 3.（按前述决策）关闭 #3143 和 #3142，附重定向评论

验证方式也写明：

git ls-remote --heads origin | grep -E 'core-dev|community-edge'

确认两个 ref 都在期望的 SHA 上。这条验证命令的意义在于：分支策略一旦发布，"分支存在于远端且指向正确 commit"就是对外承诺的锚点，之后所有从源码运行的操作都以远端 ref 为准。

五、Phase 2：编写分支策略文档 branches.mdx

Phase 2 要求创建 docs/public/branches.mdx，并逐节规定了文档骨架（"copy this structure, don't invent"）：

1. Frontmatter：title: "Release Branches" 加一行 description；
2. "The three lines"：即上文三线对照表；
3. "How changes flow"：规划原文的流向是——三条线都从 main 起步，main 向前（forward-merge） 到 core-dev 与 community-edge 保持其新鲜度；经过验证的修复通过普通 PR 向后（promote back down） 回到 main。一句话流向、零流程仪式；
4. "Which one should I use?"：普通使用选 stable；想提前测试根因级可靠性修复选 core-dev；要最新社区集成且能接受粗糙边缘选 community-edge；
5. "Run a non-stable line locally"：给出 clone → checkout → npm install → npm run build-and-sync 的命令块，并注明"只有 main 发布到 npm，所以 npx claude-mem@latest 永远等于 stable"；回到 stable 的方法是 git checkout main && npm run build-and-sync；
6. "Releasing"（维护者视角）：发布（npm run release、tag、publish）只从 main 发起，edge 线永远从源码运行、永不发布。

这一阶段最终在仓库中落地的成品即 docs/public/branches.mdx。对照规划可以看到两点演进：其一，成品文档把"变更如何流动"改写为向上晋升的表述——"New runtime work enters as a PR to core-dev or community-edge, not main"，流向为 community-edge -> core-dev -> main，即运行时代码不再直接落 main，而是从 edge 逐级向上晋升；规划稿中"main 前向合并 + 修复向后晋升"的描述是初始设计，仓库中的最终文档以成品为准。其二，成品文档还补充了两处规划中未展开的实操细节：

• 纯文档类变更可以放在 updates/docs 分支暂存，就绪后合入 main，该分支不是运行时发布线；
• "Published Versions"一节区分了 GitHub release/tag 与 npm publish 两件事：GitHub tag 只是让源码归档可见，真正让 npx claude-mem@<version> 可解析的是 npm publish；未来若引入 npm channel，应使用 core-dev、community-edge 之类的 dist-tags，在那之前非稳定分支一律从源码运行。

六、非稳定线从源码运行的机制：build-and-sync 拆解

规划文档反复强调的运行命令是 npm run build-and-sync，它为什么能让"checkout 某分支"这件事真正生效？结合仓库源码可以看清完整链路。

6.1 sync-marketplace：把当前分支镜像进插件市场

scripts/sync-marketplace.cjs 的核心逻辑是把仓库根目录镜像（mirror）到本机 Claude Code 的插件市场目录 ~/.claude/plugins/marketplaces/thedotmack，再镜像 plugin/ 到版本缓存目录 ~/.claude/plugins/cache/thedotmack/claude-mem/<version>，两处各执行一次 bun install。由于镜像的源就是当前 checkout 出的分支，插件运行目录里的代码随之变成该分支的代码——这就是"从源码运行某条线"的落点。

脚本里还有一段与分支策略直接相关的防护逻辑（scripts/sync-marketplace.cjs、L72-L83）：它读取已安装市场目录中的 git 分支名，如果已安装插件处于非 main 分支（即 beta 线），直接 sync-marketplace 会拒绝并退出，提示三个选项：在 worker 端口对应的 UI 中更新 beta、先切回 stable 再同步、或显式使用 npm run sync-marketplace:force 强制覆盖。这段"防误覆盖"检查与规划中"edge 线与 stable 共存于同一台机器"的场景完全对应——同一台机器既跑 stable 又跑 edge 线时，必须防止 stable 的同步动作把 beta 代码冲掉。

镜像时排除的条目由 scripts/sync-marketplace.cjs 的 BASE_EXCLUDES 加上 .gitignore 行共同构成（node_modules、lockfile、/workers 等），保证同步的是可直接运行的插件产物而非整个仓库。

6.2 restart-marketplace-worker：让运行中的插件切到新分支

scripts/restart-marketplace-worker.cjs 很短：确认市场目录存在（否则提示"先跑 npm run sync-marketplace"），然后在 ~/.claude/plugins/marketplaces/thedotmack 下执行 npm run worker:restart。对应 package.json 中的 "worker:restart": "bun plugin/scripts/worker-service.cjs restart"。worker 是 claude-mem 的常驻后台进程（负责转录监听、上下文生成等），重启后加载的正是刚同步过去的分支代码，"checkout 分支 → 运行该分支"的闭环至此完成。

6.3 完整的非稳定线运行命令

综合规划与 docs/public/branches.mdx，可复制的命令序列为：

git clone https://gitcode.com/GitHub_Trending/cl/claude-mem.git
cd claude-mem
git checkout core-dev          # 或 community-edge
npm install
npm run build-and-sync          # 构建 + 同步到本地插件市场 + 重启 worker

回到 stable：

git checkout main
npm run build-and-sync
# 或直接重装已发布构建
npx claude-mem@latest install

运行环境前提（以 package.json 的 engines 与 docs/public/branches.mdx 为准）：Node >=20.12.0、Bun >=1.0.0（sync-marketplace 在目标目录中执行的是 bun install），且本机已有 Claude Code 插件市场安装基础，否则 restart-marketplace-worker 会因市场目录缺失而报错退出。

七、Phase 3：接入文档导航与 README

Phase 3 要求在两处暴露分支策略的入口：

1. docs/public/docs.json：在 "Configuration & Development" 分组的 pages 数组中（"development" 之后）加入 "branches"，并保持 JSON 合法。当前仓库中该分组页面数组已包含 "development" 后的 "branches" 条目（docs/public/docs.json），与规划一致；
2. README 贡献章节：加一行指向 Release Branches 文档的说明。仓库中的 README.md 实际上有两处对应内容：一是文档索引中的 "Release Branches — Stable, core-dev, and community-edge branch flow"（README.md），二是贡献章节中的 "Claude-Mem ships from three branches: main (stable), core-dev, and community-edge. Only main is published to npm; the others are run from source."（README.md）。

验证方式同样具体：node -e "JSON.parse(require('fs').readFileSync('docs/public/docs.json','utf8'))" 能干净退出，README 链接可正常渲染。

八、Phase 4：终验清单与红线

规划的收尾是一份可勾选的验证清单：

• 两条分支已推送且 SHA 正确（git ls-remote 验证）；
• docs.json 可解析；
• branches.mdx 存在且已进导航；
• README 已更新；
• （若已决策）#3143、#3142 已附重定向评论关闭，#3141 状态未变；
• 红线：不要手改 CHANGELOG——CHANGELOG.md 是自动生成的（package.json 中有 "changelog:generate": "node scripts/generate-changelog.js"，发布流程末尾会重新生成）。

这条红线在仓库中可以得到旁证：CHANGELOG.md 中存在社区 edge 线的独立版本记录，如 ## [13.10.3-community-edge.0] - 2026-07-09（"Community edge release for integrated batches 4-9"），以及 13.10.2 条目中 "New Release Branches guide (main / core-dev / community-edge) with instructions for running the non-stable lines locally" 的文档变更记录。这说明规划落地后，edge 线的发布确实以"独立 changelog 条目 + 源码运行"的形态存在，与"edge 线永不发布 npm、只从源码运行"的策略吻合。

九、策略要点小结

从这份规划文档与其落地痕迹可以提炼出几条对单维护者项目有直接参考价值的做法：

1. PR 升格为分支是低成本的多线发布手段：不引入 release 分支保护规则、不打 CI 门禁，靠"分支名 + npm 是否发布"两个维度区分发布线；
2. 对外承诺只有一行：npx claude-mem@latest 恒等于 main，其余一切 edge 体验都通过"checkout + build-and-sync"自助完成，用户的回退成本是一条命令（git checkout main && npm run build-and-sync）；
3. 工具链把策略写进了代码：scripts/sync-marketplace.cjs 中"已装 beta 分支时拒绝非 force 同步"的检查，把"stable 与 edge 线不能互相覆盖"这条规则做成了运行时护栏，而不是仅停留在文档约定；
4. 每阶段都有机器可验证的验收命令（git ls-remote 过滤、JSON.parse 校验、导航条目存在性），使"策略文档"可被审计而不是只靠叙述。

需要说明的适用边界：上述分支流向、PR 编号与 SHA 均出自 2026-07-05 的规划快照，其中"main 前向合并到 edge 线"的初始设计在最终发布的 docs/public/branches.mdx 中已演进为"edge → core-dev → main 向上晋升"的表述；引用该策略时，请以仓库中的 branches.mdx 为现行文档、以 package.json 的 scripts 为可执行事实。