diff --git a/AGENTS.md b/AGENTS.md index dc8bfc4ab9..857a4b4a60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -463,4 +463,121 @@ after that succeeded was the Windows fix shipped in a follow-up release. - `refactor:` code restructuring - `test:` test changes - `docs:` documentation -- `release:` version bump \ No newline at end of file +- `release:` version bump + +## 7. Review & Auto-Merge Discipline + +> Distilled from a full-history review of AI auto-dev across billion-context / +> billion-context-pi / acp-kernel (#801): 1543 issues+PRs, 3645 comments, +> `devlog/`, and this file's own git history. Goal: ~90% of bugfixes mergeable +> without rework, without drifting off direction. Full cited material: +> `AUTO-MERGE-GUARDRAILS.md`. + +### 7.1 Before You Start + +- **Duplicate screening first.** Search open AND closed issues/PRs for the same + fix before implementing. If one exists, link it; do not start parallel work. +- **One issue = one scope.** Split extra findings into separate issues/PRs. + Never bundle unrelated changes or mass whitespace/reformatting into a fix. +- **Open a PR, never just push a branch.** A bare branch is not a deliverable. + +### 7.2 Review Discipline + +- **Rebase to CURRENT master before claiming mergeable.** Verify against the + live master, not the PR's original base. After rebase, re-run typecheck + + full test suite + build. A stale base is the single biggest cause of + second-round rework (#425 Aug-31 base, #467 43 commits behind, #517). +- **Watch hot-file contention.** `src/server.ts`, the preflight paths, + `src/persist.ts`, and the `src/agent/*` extension types are touched by many + concurrent PRs. If another open PR rewrites the same file/region, expect a + semantic (not textual) conflict — coordinate/sequence, resolve by union of + intent, then prove it by running tests (#517↔#587, #571↔#558). +- **One linear commit, clean diff.** No merge commits or rebases that explode + the diff and bury the real change; no incidental whitespace re-alignment. + Every line must relate to the PR's purpose (#571 "diff-爆炸", #467). +- **Done = evidence, not "should work".** Double-review the code, then actually + run the changed behavior and observe it matches expectation. For fixes that + change context/wire behavior, prefer a real end-to-end A/B against the issue + repro over unit tests alone (#254). +- **Tests must be deterministic.** No assertions that depend on environmental + luck (e.g. assuming a port range is free — Windows' ephemeral range + 49152–65535 collides with fixed picks; request a port via `listen(0)` + instead, #360). + +### 7.3 Correctness Guardrails + +- **Never silently clobber or drop user config.** Any read-modify-write on user + config needs a parse-state guard; reject malformed input loudly (HTTP 400/409) + instead of merging into defaults or dropping fields. Whitelists must be + complete (#155: a missing key silently erased custom compress prompts). +- **Sane defaults & fallbacks.** Fallback values must be reasonable (never a + too-small value that causes thrashing); a static/fallback source must always + lose to a fresher authoritative source when both are cheaply available + (#282: window fallback 200K/min 100K, not 64K; the bundled registry snapshot + must not outrank the live registry). +- **Prefer native stable identifiers.** Use a client's native stable session id + when available (it survives credential/model/provider switches); report + clients that expose none. Do not build identity from derived hashes that + drift on switch (#280). +- **Wire fidelity (host-side duty).** Never alter upstream protocol shape beyond + intended injection: preserve tool_call ids/ordering, SSE structure, and + upstream invariants (e.g. `compaction_trigger` must remain the last input + item, #283/#209). Reason in BOTH compression modes (§6). + - *Kernel-owned split:* the FORMAT CONTRACT of the kernel-emitted ACP + artifacts (the compression tags, block refs, `acp_summary` structure — see + Key Design Decision #2) and the **id-never-reused guarantee** belong to + **acp-kernel**, not this repo (see §2 "Kernel Contract"). This repo only + consumes them faithfully. Codifying the kernel-side spec is a separate + acp-kernel change — deferred; cross-repo work stays manual for now. +- **Symptom ≠ mechanism.** Before attributing a bug to bili's mechanism, verify + against upstream logs — repeated-compression logs may be an upstream rate-limit + retry illusion, not over-compression (#282). +- **Honest output.** Never emit misleading messages for degenerate states + (#155: export claimed "original conversation" for a 0-block session). +- **Logs.** Mask secret values in all logs; separate trace/debug/info; keep + debug-on by default during bug-convergence phases (#247). +- **Docs.** Keep zh/en in sync; place content where the actual reader will see + it; mirror env-var references into CONFIGURATION.md, not just one README + (#571). + +### 7.4 Auto-Merge Gate (this repo only) + +A bugfix may **auto-merge** only if ALL hold: + +1. Single-module scoped fix; no architectural change. +2. A regression test reproduces the original bug and now passes. +3. Green **on the rebased head** (typecheck + full test suite + build). +4. No change to: config schema, persistence format/version, wire protocol / + message shape, or cross-repo dependencies (acp-kernel). +5. Pure `fix:` — no new capability surface (not feat/refactor). +6. Clean diff: no unrelated changes, no mass whitespace/reformat, no generated + or lock-file churn. +7. References its issue via `Fixes #N`. +8. Does NOT touch load-bearing infra: `src/update.ts`, release workflow, CI + publish, the acp-kernel pin, message-ref/id logic, or security (MITM/CA/ + credentials). + +**Must stay human** (any hit): wire/message-shape changes (both modes affected), +config schema or persistence version, cross-repo dependencies, `src/update.ts` +(needs a no-op release first), identity/session-binding logic, feat/refactor/ +architecture, security-related, or any fallback/default-value change (a product +decision). + +> **Scope note:** auto-merge applies to THIS repo only. Cross-repo changes +> (acp-kernel bumps, anything spanning repos) remain manual/human for now. + +### 7.5 Reviewer Focus — the "重灾区" (second-round zones) + +Of 326 analyzed merged PRs, 26 (~7%) needed a second+ human review round. Two +drivers dominate, and they are exactly where auto-merge is unsafe: + +1. **Stale-base / concurrent-file churn** — long-lived branches drift from + fast-moving master and collide with other PRs on hot files. Gate signals: + branch freshness, and whether a touched file is being rewritten by another + open PR. +2. **Incomplete first pass** — the initial fix addresses the reported symptom + but misses an adjacent path/edge case, leaves promised work unfinished, or + needs its approach reconsidered. Gate signal: does the fix cover ALL paths of + the bug, not just the repro? + +These map directly onto §7.2–7.3; a reviewer walks those bullets in order. \ No newline at end of file diff --git a/AUTO-MERGE-GUARDRAILS.md b/AUTO-MERGE-GUARDRAILS.md new file mode 100644 index 0000000000..0175c5a70d --- /dev/null +++ b/AUTO-MERGE-GUARDRAILS.md @@ -0,0 +1,90 @@ +# 自动合并护栏(Auto-Merge Guardrails)— 证据附录 + +> **来源**:[#801](https://github.com/ranxianglei/billion-context/issues/801)「自动合并材料收集」。 +> **方法**:拉取三个仓库(billion-context / billion-context-pi / acp-kernel)**全部 issue + PR + 评论**(共 1543 项、1072 个 PR、3645 条评论),叠加本仓 `devlog/` 31 条迭代记录、`AGENTS.md` 完整 git 演进史、commit 类型分布,交叉比对得出。 +> **目标**:让 ~90% 的 bugfix 可自动合并,同时守住大方向不偏移。 +> **定位(重要)**:规则的**权威文本在 [`AGENTS.md` §7](./AGENTS.md#7-review--auto-merge-discipline) Review & Auto-Merge Discipline**(每次会话自动加载,是唯一操作依据)。本文件只做**证据附录**——保留基线数据、逐条 issue/PR 出处、重灾区数据分析、以及内核 vs 本仓库的归属判断。**凡是规则 / Gate / Checklist 的操作文本,一律以 §7 为准,本文不复述**,避免两处漂移。范围限定:**本次仅改本仓库**,跨仓库改动暂留人工。 + +--- + +## 1. 基线事实(数据说话) + +| 事实 | 数据 | 含义 | +|------|------|------| +| fix 是主战场 | 非合并 commit:`fix:` 360 / `feat:` 117 / `docs:` 99 / `test:` 41 / `refactor:` 24 | bugfix 约占 54%,正是自动合并要覆盖的对象 | +| 没有"被拒绝"的 PR | 三仓 closed-unmerged **全为 0** | 人工要么合并、要么挂着,从不直接否决。风险不在"AI 的东西被否",而在**剩下 ~10% 需返工的会卡住整条流水线** | +| 规则是事后补的 | `AGENTS.md` 每条硬规则几乎都对应一次事故(#377 两种压缩模式、#584 问题必建 issue、version 仅 release 分支、auto-update 改动先发 no-op 版) | 现有 `AGENTS.md` ≈ 已踩坑沉淀;隐性规则现在已并入 §7 | +| AI 工作难从作者区分 | 仅 55 个 PR 带 `ework-agent-pr` 标记;多数早期工作以 ranxianglei PAT 直推 | 判断"AI vs 人工"要靠 `[bot] 🏷` 前缀 + 标记,不能靠 authorship | + +--- + +## 2. 人工确立的规则(每条的真实出处) + +> 规则文本本身见 `AGENTS.md` §7.1–§7.3;这里只给**为什么有这条**的证据。 + +### A. 早已成文(继续守住) +git 安全四禁(禁 force-push master / 禁 merge / 禁 npm publish / 禁打印 PAT)、branch 命名 `YYYY-MM-DD_short-title`、version 仅 `*_release-v*` 分支、发布流程 + no-op 校验、acp-kernel 先于本项目发布、issue 先行 + 问题必报、代码质量(no `as any` / hex escape `\x3c\x3e` / loggerLog)、改请求管线前跑 e2e、两种压缩模式都要想。 + +### B. 隐性规则(现已并入 §7)——逐条出处 +1. **先查重再动手** —— *出处*:#268「这个应该已经存在了一个 pr 修复这个问题 检查下重复」;pi #311/#314 同标题重复 PR。 +2. **rebase 到最新 master 再验证再提** —— 警惕 **rebase 顺序依赖**。*出处*:#249/#221/#155/#479 反复要求基于最新 master 重验。**#479 最典型**:AI 漏了顺序依赖——测试写死 `savedAt=9000/5000/8000`(1970),因另一 PR(#487)先落 master 而失效,人工独立复审才抓到。 +3. **收敛范围,一 issue 一主题** —— *出处*:#247「先收敛 你先只负责本 issue…额外问题我找其他 agents 去做」;#640 兄弟 issue 批一个 PR、关掉被取代的。 +4. **交 PR,不是光推分支** —— *出处*:#282「提交 pr 而不是分支」。 +5. **绝不静默丢/覆盖用户配置** —— *出处*:#155 白名单漏 prompts 键 → web 保存会静默抹掉自定义压缩提示词,改为 malformed 直接 400;`devlog/context-window-fixes`(读失败还往 `{}` 合并 = 静默丢数据)。 +6. **兜底值要合理** —— *出处*:#282「识别失败默认回 20w、最低 10w,别用 64k」;`devlog/context-window-fixes`(静态表压过活注册表 = freshness 层级倒挂)。 +7. **优先用客户端原生稳定标识** —— *出处*:#280「session-id 才是唯一不变、绑定当前会话的…不能拿到的客户端你报告一下」。 +8. **分清症状与机制** —— *出处*:#282「连续压缩」实为上游 429 限流 + 客户端重试刷出的日志假象,并非压缩机制失控。 +9. **输出要诚实** —— *出处*:#155 export 对 0-block 会话打出"下面是原始对话"的文案,要求改成诚实提示。 +10. **完成 = 证据** —— *出处*:#784「review 了吗」;#247「本地双 review 然后实际测试切换 观察是否符合预期」。 +11. **日志:凭证必脱敏 + 分级** —— *出处*:#247(B.1 hdrLog 脱敏、B.3 分级)。 +12. **文档中英同步 + 位置可见** —— *出处*:#698 QQ 群号三项目中英文都加、且别放最后没人看见。 +13. **跨仓顺序** —— *出处*:#772「先发一个内核版本,再发这个版本」「内核已经合并」。 + +--- + +## 3. AI 把握不到的点(审核员重点把关,按出现频率排) + +| # | 类别 | 典型表现 | 为什么 AI 容易漏 | +|---|------|----------|------------------| +| 1 | **交叉/交互效应**(最高危) | rebase 顺序依赖、并发 PR 相互影响、切模型/切 provider 后状态漂移 | AI 偏局部推理,看不到全局时序与并发 | +| 2 | **静默数据丢失路径** | read-modify-write、配置覆盖、持久化版本迁移 | 正常路径测得通,异常/边界路径才丢数据 | +| 3 | **协议/线上保真** | tool_call 的 id/顺序、SSE 结构、compaction_trigger 必须是最后一个 input item(#283) | 改了线格式但本地 mock 上游不严格,CI 也测不出 | +| 4 | **标识与会话稳定性** | 派生 id vs 原生 id、sticky 会话、中途切换 | 单一场景下派生 id 够用,切换场景才暴露 | +| 5 | **默认值/兜底判断** | 不合理 fallback、真值来源优先级 | 属产品判断,AI 易拍脑袋选个"看起来对"的值 | +| 6 | **症状 ≠ 根因** | 日志假象、错误归因 | 表象像 A,其实是 B(见 #282) | +| 7 | **流程卫生** | 范围蔓延、重复劳动、只推分支不开 PR、跨仓顺序 | 单看每个动作都对,组合起来违反流程 | +| 8 | **面向用户的判断** | 文档措辞/语言/位置、诚实性、UX 默认值 | 工程正确 ≠ 用户视角正确 | + +### 3.1 重灾区:二次评论才过的 PR(数据) + +对 455 个已合并 PR 统计"人工评论次数":**229 个 0 次、71 个 1 次、26 个 ≥2 次**——即约 **7%(26/326 有评论者)需要第二轮及以上人工 review 才过**。这些就是"重灾区";其中属 **bugfix**(非 feat)的,才是自动合并真正要防的对象: + +| PR | 主题 | 二次返工原因 | +|----|------|--------------| +| #571 | hold client through long preflight | diff-爆炸(#575 同病)、反复 rebase 冲突(#558/#593)、文档放错节 + env 变量只写英文 README、漏 zh/CONFIGURATION.md | +| #467 | hard backstop plugin-mode overflow | base 落后 43 commits;逐行空格 artifact(1280 off-by-one-space)被挑出 | +| #517 | reject stale snapshots rollback | 与 #587 重写 `src/persist.ts` 同文件冲突,需语义 rebase | +| #425 | uncompressed baseline + clamp negative | base 停在 8/31;上条评论承诺的 openai 拆分口径没做完 | +| #219 | stale context limits + registry-first | 首修漏了"代理网络下 Node fetch 忽略 http(s)_proxy → registry 拉取永久失效";快照从投影扩成全量 | +| #428 | re-voice acp_summary as user | 要求确认回归;方案被推翻、移到原 issue | +| #360 | /acp panel persistent message | 反复冲突;"为啥新搞一个 acp panel?"(方案质疑);Windows 临时端口范围致 flaky 测试(改 `listen(0)`) | +| #254 | preflight-compress on model switch | 需真实 A/B 复现验证(非仅单测) | +| #657 | recover stale shim conversation id | review 才发现残留小问题 | + +**两个主导成因**(操作版见 `AGENTS.md` §7.5): +1. **stale-base / 并发文件踩踏**:长命分支偏离快速演进的 master,或与别的 PR 抢同一热文件(`server.ts` / preflight / `persist.ts` / `agent/*` 类型)。信号:分支新鲜度 + 是否与其它 open PR 改同一文件。 +2. **首遍不完整**:只治了报出来的症状,漏了相邻路径/边界、或承诺了却没做完、或方案要重来。信号:修复是否覆盖该 bug 的**所有**路径,而不只是 repro。 + +--- + +## 附:owner 拍板结论 + 内核 vs 本仓库归属判断 + +**已定**: +1. ✅ 规则与门槛并入 `AGENTS.md` 新增 **§7 Review & Auto-Merge Discipline**(唯一操作文本)。 +2. ✅ 范围限定:**跨仓库改动暂留人工**——自动合并门槛只作用于本仓库;acp-kernel bump / 任何跨仓改动一律人工处理。 +3. 「可自动合并」这套先作为 **reviewer 清单 + AGENTS.md 门槛**;是否再升级为 CI 硬门禁(gate)留待后续单独评估(涉及 CI 改动,属另一件事)。届时以 §7.4 为准。 + +**内核 vs 本仓库归属判断**(owner 指出"还有一条落下了,需判断优先沉淀到内核还是本仓库"): +- 有真正归属歧义的是 **wire / 内核产物保真** 这一条。判定:**格式契约 + id 永不复用保证归 acp-kernel**(它产出并拥有 ACP 压缩标签、block ref、`acp_summary` 结构、ref 空间);**本仓库只保留 host 侧义务**(忠实消费:不重生成 tool_call id/顺序、不裁剪 ref map、两种压缩模式都要想)。 +- 依据:`AGENTS.md` §2「Kernel Contract」早已把 id-never-reused 记为内核契约的 host 视角;§7.3 的 wire-fidelity 项已明确标注此 split。 +- 处置:内核侧的正式 spec **已在 acp-kernel 单独 PR 落地**([acp-kernel#303](https://github.com/ranxianglei/acp-kernel/pull/303),把 ref-id 不可复用 + wire-artifact 格式契约提升为一等不变量);billion-context-pi 对应 PR 为 [pi#457](https://github.com/ranxianglei/billion-context-pi/pull/457)。