Repository navigation
docs(rfc): add Stage-then-Swap next_command prefetch contract to history working-set RFC - #9148
loopx-agent wants to merge 1 commit into
Conversation
…ory working-set RFC Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
Reviewer: model_agent Antigravity Google Deepmind (self_reported)
Reviewed exact head: 67065545b0e250864f521acd25a43ab59cf7caf5
动机 / Motivation
受长程上下文回收与 EpochReset 影响的控制面维护者、可控采样栈运行时以及不透明 CLI 宿主接入方在设计 M1 与 M2 上下文折叠切片时会遇到这一衔接缺口。
改前在历史回收后模型只能凭摘要空手重启并额外消耗一轮模型往返重读状态,或因过早总结丢失行号与失败细节而反复重读;改后通过先执行后回收的 Stage-then-Swap 原语在单次迁移内用已核验回执与确定性命令观测替换散乱探索后缀,且在失败、超时、超限或净收益为负时原子回退为 KeepRaw。
双语 RFC 正式确立五条可审计的 Stage-then-Swap 规范不变量、两条宿主对齐承载形态、新增验收项 A13、开放决定 D8 与固定文献索引,且不改变默认关闭状态与运行时代码。
本 PR 不修改任何运行时、CLI 或控制面实现代码,不批准 §12 的开放实施选择,也不声称已完成 A13 运行时基准测试或改变默认关闭策略。
FoldAndPrefetch 与 EpochReset prefetch_command 的运行时接入、沙箱准入边界 D8 的维护者拍板以及 A13 的重放与延迟开销实测仍需在后续 M1 与 M2 实施 PR 中完成。
改动思路 / Approach
本 PR 没有为上下文预取另起一份平行文档,而是直接演进既有的 history-working-set-context-policy-v0(关联 #8450 与 #4391 T02 / M1-B),将“弹性回收”与“下一阶段工作视图装载”收口为单次原子状态迁移:
-
两类与宿主对齐的承载形式: 对
DSH/Pi/ 自管 Agent Loop 这类可控采样栈宿主,定义连续尾部FoldAndPrefetch(仅弹出[since_anchor..now]后缀,维持父前缀字节恒定以保住 KV-cache,增量 prefill 只需覆盖$\mu + \text{Obs}(\text{next_cmd})$ );对codex-cli/ Claude Code 等不透明外部 CLI 宿主,则通过turn_driver在 Turn 收尾 /EpochReset边界预执行有界的prefetch_command/context-read --select并直接注入下一 epoch 的初始 prompt。 -
能力与权限边界严格分离: 在 §5.3 中明确
HistoryViewPolicy.propose()依然是纯粹的声明式插件接口,严禁注入可执行命令;只有 Agent 显式发起或随 Turn 收尾提交的请求才可进入运行时沙箱与decision_capture/ Turn journal 审计路径。
| 维度 | 纯上下文回收 / 文字过渡 | 新增 Stage-then-Swap next_command 契约 |
|---|---|---|
| 唤醒连续性 | 空手重启,多耗一轮读指令或文字摘要失真返工 | 单次迁移直接呈现 |
| 原子性与回退 | 无命令预算与净收益门控 | 先执行后回收;超时、溢出、失败或净收益为负时回退 KeepRaw
|
| 失败防遮蔽 | 存在挑好结果盖住既有红灯风险 | 运行时确定性将退码、未消解失败计数与 source_ref 写入 |
| 重放幂等性 | 恢复流程易二次执行命令 | 写入 decision_capture / journal,重放直接回填且保持 tool 信任级别 |
当前 PR 边界刻意止步于静态规范修订(Proposal 成熟度且默认关闭),将 FoldAndPrefetch 具体沙箱白名单与运行时执行切片留给后续受 D8 与 A13 约束的 M1/M2 PR。
具体改动 / Changes
关键内容讲解
本次对照改动前已接收的基准规范 docs/architecture/rfcs/history-working-set-context-policy-v0.md (修订基线提交 5eb6b24 )检验各既定条目,并在中英文镜像各精确增改 +36 / -6 行(共 2 文件 +72 / -12 行):
-
§5.1 新增 Stage-then-Swap 契约与五条不变量: 给出状态迁移形式化定义
$Q \mathbin{|} B_{\text{old}} \rightarrow Q \mathbin{|} \mu \mathbin{|} \text{Obs}(\text{next_cmd})$ ,明确五条硬约束:(1) 先执行后回收(timeout_ms、max_output_bytes及含重定基回本阈值的净 token 门控$\Delta_{\min}$ );(2) 前缀 KV-cache 局部性(禁止中段抽删,区分尾部FoldAndPrefetch与EpochReset预取);(3) 权限与重放幂等(沙箱与幂等只读约束、journal 固化、tool信任级别);(4) 推理项与工具配对完整性(整体规约闭合后缀[since_anchor..reclaim_call]防止半边孤立,B_old保留于source_ref+sha256);(5) 防粉饰太平头(由控制面确定性注入既有验证退码与未消解门禁统计)。 -
§5.3 与 §9.1 / §11 / §12 / 附录 B–C 同步对齐: 在 §5.3 划清 Agent 显式预取与被动
HistoryViewPolicy插件的职责界线;在 §9.1 新增A13验收行,将全量运行时/模型验收范围扩展至A1–A13;在 §11M0与附录 B 同步登记D1–D8并新增2026-11-21提案修订说明;在 §12 新增D8(优先开放quota context-read --select指针与沙箱只读工作区探针);在附录 C 补充[SP1]/[SP2]固定 Spine 参考文献。 -
基线准则映射(相对基线 5eb6b24 ):
- M0 (RFC 评审阶段边界与开放决定治理)-> implemented:中英文规范、所有者分工、回退口与新增 D8 / A13 同步落地且双语与术语校验通过。
- A2 (基于
source_ref与sha256无损保留原始历史以便按需展开)-> deferred:本纯文档 PR 已在 §5.1(4) 与 A13 中重申并固化该契约要求,实际持久化与展开验证随后续 M1/M2 代码切片交付。 - A7 (崩溃恢复与重放幂等性,不重跑副作用命令)-> deferred:本纯文档 PR 已要求
Obs(next_command)不可变落入decision_capture/ Turn journal,运行时回填回归测试随后续 M1/M2turn_driver切片交付。
对主干的风险 / Risks
- 零阻断性缺陷(No blocking finding): 本次变动完全限定在
docs/architecture/rfcs/history-working-set-context-policy-v0.md与.zh-CN.md,不改动任何运行时代码、schema 定义、配置文件或默认策略开关;若需回退只需 revert 单个提交67065545b0e250864f521acd25a43ab59cf7caf5。 - 负向防线核查: 已验证三条关键负向约束均有清晰文档契约落脚点:被动的
HistoryViewPolicy插件被 §5.3 明确禁止发命令;next_command失败、超时、溢出或净收益为负按 §5.1(1) 原地回退KeepRaw;既有红灯事实由 §5.1(5) 运行时确定性头保真,防止“选一条成功命令洗白历史失败”。 - 本地验证摘要(exact head
67065545b0e250864f521acd25a43ab59cf7caf5):uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD-> PASS(双语逐节对称校验通过)python3 examples/semantic-vocabulary-drift-smoke.py-> PASS(语义词表无漂移)loopx check --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.md --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md-> PASS(errors=0, warnings=0, checks=5)loopx canary premerge --from-git-diff --git-diff-base origin/main-> PASS(selected=11, failures=0,含cqr_a2de25392311ef1dc1c7)
我的整体评价 / Verdict
- Long-horizon 影响(improved): 将业界与架构讨论中的
reclaim + next_command思路精准沉淀为带有先执行后回收、KV-cache 前缀局部性、工具配对约束与防粉饰太平头的 RFC 规范契约,有效降低了后续长程上下文运行时落地时的语义返工与缓存击穿风险。 - User experience(not_applicable): 本 PR 仅涉及 Proposal 阶段双语 RFC 规范文档修改,未改动任何 UI、CLI 或飞书终端交互表面。
- 代码体量与兼容评估: 全量仅 +72 / -12 行文档修订,完整复用原有 RFC 状态模型与边界(
necessary;未新增运行时兼容分支)。 - 残余风险: D8 的命令准入边界以及 A13 的真实回放幂等、KV-cache 命中收益和端到端成本控制均尚未有运行时代码实现,后续仍须按
M1/M2切片逐一用独立反例测试验证。
英文简短结论:
English verdict: APPROVE — bounded Proposal-maturity bilingual RFC refinement specifying atomic Stage-then-Swap next_command reclamation with explicit sandbox, KV-cache locality, replay idempotency, and anti-whitewashing gates (0 runtime changes).
Summary
Refines the bilingual History Working-Set & Context Policy RFC (English, 中文) in
Proposalmaturity (default-off, zero runtime changes) to formalize atomic Stage-then-Swap context reclamation with next-step command hydration (reclaim + next_command/FoldAndPrefetch/EpochResetprefetch):Stage-then-Swap):Next(μ, d)).next_commandfirst under explicittimeout_ms/max_output_byteslimits and commit only if net token savings clearKeepRawon failure, overflow, or negative gain.[since_anchor..now]keeping parent prefixDSH/Pi/ managed loop), andturn_driver-boundedprefetch_command/context-read --selectinjection atEpochReseton opaque CLI hosts (codex-cli/ Claude Code).HistoryViewPolicyplugins), sandbox/lease-gated, restricted by default to idempotent reads/probes, recorded immutably indecision_capture/ journal so replay restores output without re-executingnext_command, and kept attooltrust level.[since_anchor..reclaim_call]into a well-formed pair without orphan splits while preserving rawsource_ref+sha256(A2).source_ref) intoA13), §11 (M0), §12 (D8), Appendix B & C:HistoryViewPolicyin§5.3; adds acceptance criterionA13and open decisionD8(admission scope:quota context-read --selectpointers + sandboxed read-only workspace probes first); updatesA1–A13andD1–D8ranges across§11and Appendices A–C; adds fixed Spine / SpineCodex references ([SP1]/[SP2]).Verification
uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD-> passed (RFC bilingual diff check passed.)python3 examples/semantic-vocabulary-drift-smoke.py-> passed (semantic-vocabulary-drift-smoke: ok)loopx check --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.md --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md-> passed (errors=0, warnings=0, checks=5)loopx canary premerge --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance-> passed (selected=11, failures=0, including Change Quality Receiptcqr_a2de25392311ef1dc1c7)python3 scripts/generate_rfc_status_index.py --checkfails on unmodifiedorigin/maindue to a pre-existing dated heading inmonorepo-distribution-split-v0.{md,zh-CN.md}(unrelated to this PR; zero index/heading findings onhistory-working-set-context-policy-v0*).Related: #8450, #4391