Skip to content

fix(anchor): 锚点纳入版本载体,随发布自动刷新 - #118

Merged
Kucell merged 2 commits into
mainfrom
fix/anchor-version-carrier
Oct 23, 2026
Merged

Kucell merged 2 commits into
mainfrom
fix/anchor-version-carrier

Conversation

@Kucell

@Kucell Kucell commented Oct 23, 2026

Copy link
Copy Markdown
Owner

背景

docs/cortex-agent/anchor.md 停在 v1.13.0,而当前版本是 1.15.6。

更关键的是没有任何机制会更新它:锚点正文里写着「重跑 cortex-agent export-anchor 即可刷新」,但这不成立——exportAnchor 只在文件缺失时自动生成,文件已存在时只输出到 stdout,不碰磁盘。于是锚点每发一版就陈旧一版,而它恰恰是给外部 AI 工具读的「本项目由 cortex-agent 管理,版本 X」的唯一声明。

核对结论:该文件与生成器输出逐字节相同,只有第 2 行的版本号一处不同(1790 字节 vs 1790 字节,20 行 vs 20 行)——纯生成物,漂移点唯一。

变更

1. 锚点成为第 5 个版本载体(lib/release/version-carriers.js)

  • 载体注册表新增 kind: "text" 的生成型载体:锚点的版本在正文里,唯一正确的做法是用模板重新渲染,而不是就地打补丁。
  • 版本 bump(local-publish-validate --bump)会重新渲染锚点 → 发包 PR 白名单由载体注册表派生,自动放行该路径(ALLOWED 由 7 项变 8 项)。
  • buildAnchor 支持 version 覆盖:bump 渲染的是即将发布的版本,而不是进程启动时 require 缓存下来的旧版本。

2. export-anchor --write(lib/commands/anchor.js)

显式刷新项目内锚点;默认仍是只读导出(stdout),保持本仓「默认只读、写入需显式」的约定。锚点模板里的刷新指引同步改为 cortex-agent export-anchor --write。

3. 发布一致性门禁新增一条(tests/release/release-version-consistency.test.js)

仓库内锚点必须与生成器输出逐字节一致——模板一改、版本一 bump,没刷新就直接变红。

4. 锚点内容同步刷新到 v1.15.6

影响与边界

  • 不改门禁脚本本身;verify-approved-release.cjs 的 ALLOWED 仍由载体注册表派生,新增路径自动生效
  • 锚点模板只存在于 lib/anchor/anchor.js(框架代码),L1 模板与治理仓都没有副本 → 不涉及 L1/L3 同步
  • export-anchor 不带 --write 时的行为完全不变(含「文件缺失时自动生成」)
  • --help 路径在参数解析阶段即返回,不写盘
  • 已发布到 npm 的 1.15.6 及更早版本内容不变(锚点不进 npm 包,files 未包含 docs/)

验证

  • node --test tests/release/*.test.js tests/commands/anchor.test.js tests/anchor/anchor.test.js tests/cli/cli-contract.test.js → 67/67
  • npm run test:m040 → 278/278
  • node scripts/m040/architecture-guard.js → PASS
  • node scripts/check-template-parity.js → PASS
  • 真实仓库树上 syncVersion(root, 当前版本) → changed: [] missing: [](幂等,无多余改写)
  • 载体夹具断言:bump 后锚点等于 buildAnchor({version:"2.0.0"}).body(重新渲染,而非字符串替换)

cortex-agent added 2 commits October 23, 2026 13:34
docs/cortex-agent/anchor.md 停在 v1.13.0,且没有任何机制会更新它:文件里
写的「重跑 cortex-agent export-anchor 即可刷新」并不成立——该命令在文件
已存在时只输出到 stdout,只有文件缺失时才会自动生成。

- 锚点成为版本载体注册表里的第 5 个载体:版本 bump 会用锚点模板重新渲染
  它,发包 PR 白名单由载体注册表派生,因此自动放行该路径。
- 载体注册表新增 kind:"text" 的生成型载体:锚点的版本在正文里,只能重新
  渲染,不能就地打补丁。
- buildAnchor 支持 version 覆盖,bump 渲染的是即将发布的版本,而不是进程
  启动时 require 缓存下来的旧版本。
- export-anchor 新增 --write 显式刷新项目内锚点;默认仍是只读导出。
- 发布一致性门禁新增:仓库内锚点必须与生成器输出逐字节一致。

锚点内容同步刷新到 v1.15.6,模板里的刷新指引改为 export-anchor --write。
@Kucell
Kucell merged commit 5312ef0 into main Oct 23, 2026
9 checks passed
@Kucell
Kucell deleted the fix/anchor-version-carrier branch October 23, 2026 05:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant