Skip to content

docs(agents): slim AGENTS.md, move procedures to reference/ - #1935

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-02_agents-md-cleanup
Oct 2, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-02_agents-md-cleanup

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 2, 2026 •

Copy link
Copy Markdown
Owner

Closes #1928

是什么

按 issue 要求整理删减 AGENTS.md:清理垃圾内容(如「具体包含哪个测试」这类枚举)、删除大量重复、把启动不必加载的内容挪进新建的 reference/ 文件夹。

拆分原则

硬规则 / 不变量留在每次会话自动加载的 AGENTS.md;流程 · 枚举 · 步骤挪进 reference/(不自动加载)。

AGENTS.md:790 行 → 221 行(−72%)。

新增 reference/(本次会话不加载,用到再查)

文件 承接的原内容
reference/architecture.md 模块地图(原 §2)+「漂移即重生成」提示
reference/testing.md build 命令、本地安装、E2E codex + hermetic-registry 两套(环境变量 / 阶段 / CI 触发文件清单)
reference/release.md release 步骤、one-click 内部机制、acp-kernel 先发、updater no-op 校验协议
reference/git-pr.md 无 gh 开 PR 的 REST 流程、外部贡献者 PR、合并后补充
reference/README.md 索引 +「什么该放这里」的判据

原地去重(不留副本)

关键约束保持(逐条核验)

  • 顶层 §1–§7 编号与标题全部不变 → AUTO-MERGE-GUARDRAILS.md 对 #7-review--auto-merge-discipline 的锚点引用不失效;§7 规则文本仍是唯一操作依据(仅措辞收敛,语义未动)。
  • 16 条关键不变量逐条确认仍在:git 四禁、version 纪律、never-publish、双压缩模式、root-cause-not-symptom、wire-fidelity(tool args byte-exact)、wire-constraint-ledger-only-grows、config-surface owner-gated、acp-kernel exact-pin、id-never-reused、nudge flat 50K、acp-kernel-ships-first、updater-noop-first、single-writer。
  • KDD#2 的 ACP tag 示例原样保留;「源文件用 hex escape」规则仍在。
  • 无悬空链接、无被剥离 tag 残留的空反引号。

影响面

纯文档改动:不改任何代码(未触碰 src/),无行为 / 配置 / wire / 缓存变化,无新增配置项。typecheck / test / build 不受影响。


调和记录(2026-10-03,review 会话)

原分支为 stale-base(切自 012a86a0,落后约 100 提交,GitHub 判 dirty 不可合并)。已 rebase 到最新 master(9c608fc3),完整保留本 PR 的精简结构与去重方案,并把 master 侧文档更新逐条落位(union-of-intent):两条 owner 政策(外部贡献者 PR「fix directly, don't replace」;minor problems「小问题直接修」)、release-notes 强制步骤(#1870,含 one-click dispatch-time 前置检查)、两个新 E2E lane(real-image billing / advisory-rollback)、kernel pin 0.0.100、module map 重新生成(zcode/kimi lane、loop/ 新模块、test 数按当前树实点 414)。单提交 c9a9842e 替换原提交(force-with-lease,仅动本分支);CI 13/13 绿,mergeable_state: clean。AGENTS.md 最终 224 行。KDD#2 的 ACP tag 示例经 hex 级核验确认完好(初判「被剥离」系观察管道显示层假象,已更正)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,这是已完成的工作(PR #1935 @ 1637c144),我不重做,按 review 流程核对。初步结论:方向对、拆分质量高,但分支是 stale-base,当前不可合并——正在做 union-of-intent 调和并推更新提交,先同步发现:

① stale-base(主因,GitHub 已标 dirty/冲突)
分支从 012a86a0 切出,之后 master 前进了约 100 个提交,其中 AGENTS.md 本身有 6+ 个文档提交。按 PR 侧直接合入会静默丢掉以下 master 侧更新:

② PR 自检清单有两条不成立

  • 「KDD#2 的 ACP tag 示例原样保留」→ 实际示例被剥离,只剩模糊描述 + 残留空反引号(AGENTS.md:38 like `` (an opening element…)
  • 「无被剥离 tag 残留的空反引号」→ 同上,正是那条残留

③ 其余核验通过:§1–§7 顶层编号/标题逐字不变(AUTO-MERGE-GUARDRAILS 锚点安全)、16 条关键不变量在文中齐全、diff 只含 AGENTS.md + reference/ 六个文件、纯文档零代码触碰。head 上无任何 CI run(冲突状态下没触发)。

动作:rebase 到最新 master,保留本 PR 的精简结构,把上述 master 侧更新逐条落位(AGENTS.md 政策/步骤/KDD#2 示例恢复 + reference/{architecture,testing,release,git-pr}.md 对应章节),单提交替换后验证可合并性。完成后按七问回复。

@ranxianglei
ranxianglei force-pushed the 2026-10-02_agents-md-cleanup branch from 1637c14 to c9a9842 Compare October 2, 2026 16:18
@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-02_agents-md-cleanup (c9a9842)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1942-pr.1935.1434f20

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1935.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 调和完成,PR 已可合并(head c9a9842e,CI 13/13 全绿,mergeable_state: clean)。先更正我上一条回复里的一个误判,再按七问收尾:

⚠️ 更正:发现②不成立——「KDD#2 示例被剥离、残留空反引号」是我的观察管道假象。hex 级核验(git show <blob> 逐字节)确认 PR 原提交里 <acp tokens="2" type="text">m00001</acp> 示例一直都在(行内字节 60 3c616370…3c2f6163703e 60,前后反引号完整);是我这边的工具输出层把展示文本里格式良好的 XML tag 剥掉了,让我连续几次「看到」空反引号。PR 自检清单两条均为真。教训已记录:涉及 tag 字节的判定必须走 hex/repr,不能信渲染层。


七问

  1. 是什么问题:分支 stale-base(切自 012a86a0,落后 master 约 100 个提交),GitHub 判 dirty/不可合并;若按原 head 直接合入,会静默丢掉 master 侧 9 类文档更新。
  2. 什么原因导致的:分支切出后 master 上又落了 6+ 个 AGENTS.md 文档提交(热文件并发漂移,§7.5 重灾区第 1 类)。PR 内容相对其自身 base 是对的,错在 base 过期——不是拆分方案的问题。
  3. 怎么修复的:rebase 到最新 master(9c608fc3),完整保留本 PR 的精简结构与去重方案,把 master 侧更新按 union-of-intent 逐条落位:
    • 两条 owner 政策:外部贡献者 PR「fix directly, don't replace」(AGENTS.md §4 + git-pr.md)、minor problems「小问题直接修」(§4 第 4 条 + §7.2 新 bullet)
    • release-notes 强制步骤(发版可见性:分级标签的 release 元数据(模型撰写摘要)+ 用户版跨 span 更新说明 + acp_status //acp 面板送达「更新已就绪待重启」(#1577 延伸) #1870):§5 步骤链改为 1–6/人 7/CI 8 + 新增 entry bullet;release.md 插入完整步骤 4、重编号 5–9、one-click 前置检查段
    • 两个新 E2E lane:real-image billing(testing.md 整节 + AGENTS.md 一行)与 advisory-rollback(同 gate 段落 + 双文件命令块 + src/advisory.ts 规则)
    • 事实漂移:kernel pin 0.0.56→0.0.100、module map 重新生成(zcode/kimi lane、loop/ 新增 adapter-google/cache-control/tag-echo-filter、删除已不存在的 compress-loop.ts、test 数 66→414——按当前树实点 .test.ts 计数,master 旧图标的 399 本身也已过期)
      单提交 c9a9842e 替换原提交(force-with-lease,仅动本 PR 自己的分支)。
  4. 是否有回归问题:无。纯文档、零代码触碰。逐项核验过:§1–§7 顶层编号/标题与 master 逐字一致(AUTO-MERGE-GUARDRAILS 锚点安全);16 条关键不变量全部在文;KDD#2 示例 hex 逐字节确认;六文件无空反引号残留、无悬空相对链接;diff 仅 AGENTS.md + reference/ 六个文件(+584/−726);CI 13/13 绿(含全部 real-lane e2e 与双平台 test matrix)。
  5. 是否破坏缓存:不涉及。
  6. 是否改了设计方向:无架构变更。唯一流程性效果即本 PR 的既定目标:长流程不再自动加载(移入 reference/),硬规则/不变量仍每次会话加载——该方向 整理删减agents.md #1928 已拍板。
  7. 是否引入新配置:不涉及。

收工判定:可合并。合并动作按规矩由人来:#1935 (我无权也不能代合并)。

@ranxianglei
ranxianglei merged commit 38a4758 into master Oct 2, 2026
13 checks passed
@ranxianglei
ranxianglei deleted the 2026-10-02_agents-md-cleanup branch October 15, 2026 05:32
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.

整理删减agents.md

1 participant