[ranxianglei]

Why

Community feedback (awesome-dsh-plugin discussion #5795) shows users mis-model compaction timing on large-window + heavy-boot + local-model setups. The key fact the docs lacked:

Compaction does not trigger on absolute window position — it triggers on growth intervals. By default the first soft compaction fires 50k tokens past the boot content (nudgeGrowthTokens, flat and window-independent). So the absolute position of the first compaction ≈ boot + 50k:

• boot 30k–50k (dsh default) → first compaction ~80k–100k;
• boot 100k–150k (heavy tool/skill stack) → first compaction likely waits until ~200k;
• growth step raised to 100k → boot + 100k.

The 75% maxContextLimit forced line is only a backstop, applied over the effective window (output reserve min(max_tokens, outputHeadroomMaxPct × window), 25% cap by default, subtracted first): typically small reserve → forced line ≈190k on a 262k window; a request carrying max_tokens = 131072 → reserve 65,536 → forced line ≈147k.

After the first compaction the cadence stays growth-based (+50k per incremental compaction); on local models each is a full re-prefill — the "kept compacting, task took 2–3×" experience.

What this adds

• CONFIGURATION.md / CONFIGURATION.zh-CN.md: ### Why the first compaction waits until 200k / ### 为什么第一次压缩要到 200k 才触发？ — growth-gate mechanics, boot+50k arithmetic, backstop math, then remedy angles: earlier token saving (lower nudgeGrowthTokens / maxContextLimit), fewer compactions (raise the step), leaner boot (promptPack: "lean"), and measure first via /acp or the web UI.
• README.md / README.zh-CN.md: one FAQ entry each cross-linking the worked example.

Docs-only — no code or config changes.

[github-actions]

📦 Built Package Artifact

Branch: 2026-10-06_compaction-timing-docs (803a03c)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2296-pr.2225.310d34e

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-pr2225.tgz
npm install -g package

---

Install instructions are refreshed on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,开始处理。已核对代码与文档现状:

• 算例复核通过:reserveOutputHeadroom(src/util.ts)确为 min(max_tokens, cap×window)、cap 默认 0.25;kernel 默认 maxContextLimitPct=0.75、growthFloor==growthCap==50000(tests/golden/wire-contract/kernel.json 钉死)→ 262,144 + max_tokens 131,072 → 有效窗口 196,608 → 75% 线落在 ≈147k(≈全窗口 56%)。✓
• 注意:[docs][website] 配置文档单一事实源：从声明式 schema 生成 CONFIGURATION.md 与网站 /docs/（一步到位） #2107 之后 CONFIGURATION.md 的参数索引是 YAML 种子生成的,但叙述性章节(如 Soft target with elastic headroom)仍是手写静态内容——本 issue 的新章节按静态内容直接写入两个 CONFIGURATION 文件,不动种子。
• 顺带发现:相邻的 Soft target 章节里"自适应步长 = clamp(window×5%, 20k, 50k)"一行与当前内核常量矛盾(fix: merge all system/developer messages into one leading message (SGLang #377) #379/探索是否可以集成进sglang，以做到透明管理 #380 之后已是固定 50k),与本 issue 新章节直接冲突,将作为独立标注提交顺手修正并在 PR 中披露。

计划:新章节(中英)+ README 双语 FAQ 条目 → PR(Closes #2225)→ 回复七问结论。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 完成。**PR: https://github.com/ranxianglei/billion-context/pull/2226**（分支 2026-10-06_docs-large-window-compaction，Closes #2225）

结构化结论（七问）

1. 是什么问题：文档缺口——两个默认值（输出预留 + 固定 50k 增长步长）的相互作用没有任何叙述性解释，社区在大窗口+本地模型场景反复报告"不到 200k 就压缩""一直压缩、慢 2–3 倍"却无处可查。
2. 什么原因导致的：不是 bug，是算术不可见：有效窗口 = 窗口 − min(max_tokens, 0.25×窗口) → 262,144 + 131,072 → 196,608，默认 75% 强制线落在 ≈147k（全窗口的 56%）；叠加固定 50k 增长步长，重型启动（100k–150k 预填充）在长任务里撞 2–4 次增量压缩，本地模型每次都是完整重预填充。
3. 怎么修复的：纯文档。CONFIGURATION.md/.zh-CN.md 在 Soft target 节前新增 Why compaction starts earlier than expected on large windows（大窗口下压缩为何比预期更早更频繁地触发）：算例表 + 两条成因 + 有序对策（先 /acp/Web UI 实测 → 调高 compress.nudgeGrowthTokens 至 100k+ → promptPack: "lean" 精简启动）；两个 README 各加一条交叉链接 FAQ。
4. 是否有回归问题：无。无代码/配置/默认值改动。所有文档断言逐条对源码复核过：reserveOutputHeadroom（src/util.ts）、DEFAULT_OUTPUT_HEADROOM_MAX_PCT=0.25、kernel maxContextLimitPct=0.75、growthFloor==growthCap==50000（golden 钉死 tests/golden/wire-contract/kernel.json:1630-1632）、增长门 max(20k, 0.45×step)=22.5k 与 T1 需 ≥50k 可压缩质量（kernel/src/compress.ts:1721-1724, 1817）。node tools/gen-config-docs.mjs generate 改后零 diff（新内容是标记块外手写叙述，种子未动）。披露一处顺手小修（独立标注 commit）：相邻 Soft-target 章节残留 fix: merge all system/developer messages into one leading message (SGLang #377) #379/探索是否可以集成进sglang，以做到透明管理 #380 之前的旧公式"自适应步长 clamp(window×5%, 20k, 50k)、地板随窗口 20k/22.5k"，与现行常量及新章节直接矛盾——已改为"任意窗口固定 50k 步长；增长门 max(20k, 0.45×步长)≈22.5k；T1 另需 ≥1 步长可压缩质量"。这是文档向现实对齐（实际行为自 fix: merge all system/developer messages into one leading message (SGLang #377) #379/探索是否可以集成进sglang，以做到透明管理 #380 起就是固定 50k），不是行为漂移。
5. 是否破坏缓存：不涉及——未触碰任何运行时路径。
6. 是否改了设计方向：不涉及——纯解释性文档，架构/边界/数据流零变化。
7. 是否引入了新的配置：不涉及——只引用既有键（compress.nudgeGrowthTokens、compress.promptPack、outputHeadroomMaxPct），无新 env/config/默认值。

diff：4 文件 +65/−2，每行都与本 issue 相关。判定：可合并（docs-only，CI 全局把关）。

[ranxianglei]

[bot] 🏷 Closing as superseded by #2226.

Duplicate screening result: same scope — the same two community symptoms (large-window + local-model compacting early / repeatedly), the same four files, the same section placement. #2226 carries this PR's content in a more complete form (worked-example table, ordered remedies, validation notes) plus the pass-by correction of the stale pre-#379/#380 growth-step formula in the Soft-target section, and its body explicitly declares Closes #2225.

Merging this PR first would leave #2226 stale and conflicting on the very sections it extends. Everything here survives in #2226 — nothing is lost by closing.