dsh-compact-relay 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,32 @@
 
 （暂无新改动）
 
+## 0.3.4（2026-10-24，判断机制修复 + 小 bug）
+
+### 判断机制（BUG-010：适合压缩的节点几乎不触发）
+
+- **问题与证据**：扫了 427 个真实会话（36,813 次工具调用）——0.3.1 上线后 `mark_stage` 工具调用 **0 次**，`plugin:compact-relay/compress-hint` 记录全库仅 **1 条**（0.3.0 开发期测试）；而工具 schema 在当前会话日志出现 43 次，说明工具确实进了模型上下文，只是模型从不调用。
+- **根因**：工具描述写「系统会告诉你当前容量」，但系统从未告诉模型任何容量 → 「超过最小线 / 还没到压缩线」两条条件无法判断；描述末尾「不要凑数触发」进一步抑制调用。
+- **修复**：新增 `systemPrompt` 动态 context（`core/compress-cue.js` + `adapters/prompt.js`）——容量进入可压缩区间时主动告诉模型当前容量与区间（5% 桶取整并在显示时 clamp 到区间下限，避免「约 30%（区间 33.6%–40%）」自相矛盾；刚记过 hint 且差 <10 个百分点时抑制；异常静默跳过——`systemPrompt` 是 DSH 0.2.x 核心根服务，缺服务时插件不激活）；`dsh/state-hub.js` 无论有无 SSE 订阅者都维护最新状态缓存（`latestState`）供同步读取。
+- **工具**：`mark_stage` 改名 `mark_compress_point`，重写描述（完成明确任务/阶段且认为可安全压旧历史时调用；工具自己返回容量并判断；太低/到线拒绝且不改历史；不确定可调用）；记录/拒绝文案同步，不再有「系统会告诉你」的假承诺。
+- **清理**：删除 0.3.1 遗留死代码 `lib/core/stage.js` + `lib/actions/stage.js`（无任何引用）。
+- **测试**：新增 `test/compress-cue.mjs`（区间边界/5% 桶/动态最小线/hint 抑制 + 状态缓存无订阅者更新/防抖/卸载清理/异常安全 + prompt 适配降级）；`test/plugin-load.mjs` 的 fake host 增加 `systemPrompt` 替身并断言 context 注册、区间内文案、区间外空串、异常安全。
+
+### 小 bug
+
+- **BUG-005 交接单详情纯文本**：新增 `core/markdown-lite.js` 轻量 Markdown 解析（标题/段落/有序无序列表/粗体/行内代码/代码块/分隔线；零依赖、**不生成 HTML**、无 XSS 面），client `16-markdown.js` 构建时内联同一源码并在交接单详情面板渲染；512KB/白名单/只读约束不变。新增 `test/markdown-lite.mjs`。
+- **BUG-006 交接单列表只显示最近 20 份**：列表端点返回 `total`；客户端底部显示「共 N 份（显示最近 20）」并提供「加载更多」（limit 提到 50），无更多时隐藏按钮。
+- **BUG-004**：交接失败提示带原因保持已修状态，真机抽查待一次真实 `/handoff`（本次未动真实历史）。
+- 测试基线：smoke 53/53、handoff 35/35、plugin-load 14/14、contract 17/17、compact-log PASS、compress-cue PASS、markdown-lite PASS。
+
+## 0.3.3（2026-10-20，跨平台补丁版）
+
+- **Windows 适配**：完整的测试套件（smoke 53 / handoff 35 / plugin-load 13 / contract 17 / compact-log）已在 Windows 11 + Node 24.22 实测全部通过。
+- **测试跨平台修复**：`handoff` 的「目录不可写」用例改用「普通文件当父目录」制造 ENOTDIR（Windows 没有 `/dev/null` 语义）；`contract` 的交接目录断言按 `path.resolve` 比较（Windows 上 `/tmp` 会被解析为 `C:\tmp`）。
+- **构建脚本**：`scripts/build-client.mjs` 忽略隐藏文件与 macOS 资源分叉（`._*`），拷贝/打包后的源码在 Windows 上也能通过 `--check`。
+- **文档**：README（中英）与 DEVELOPMENT 注明测试需要 Node 22.15+（`node:module.registerHooks`）；TUTORIAL 常见问题补充「headless / QQ 桥接链路不加载指示灯与命令」；ROADMAP 明确不做桥接链路接管。
+- 运行时功能与 0.3.2 一致。
+
 ## 0.3.2（2026-10-20，补丁版，行为无变化，仅设置页文案与链接）
 
 - 设置页「帮助」区新增 npm 包页面外链（https://www.npmjs.com/package/dsh-compact-relay）；「使用教程」「反馈 / 提 bug」两条外链指向的 GitHub 地址已确认可用。

package/README.en.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/dsh-compact-relay?label=npm&color=cb3837)](https://www.npmjs.com/package/dsh-compact-relay)
 [![DSH](https://img.shields.io/badge/DSH-0.2.x-4d6bfe)](https://www.deepseek.com/harness/)
 [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
-[![version](https://img.shields.io/badge/version-0.3.2-blue)](CHANGELOG.md)
+[![version](https://img.shields.io/badge/version-0.3.4-blue)](CHANGELOG.md)
 
 </div>
 
@@ -32,6 +32,8 @@ The plugin mounts beside the existing composer. Default parameters are tuned for
 
 The ring is colored in segments according to the compression-assessment logic: the suggested compression point determined by the model or configured threshold, the positions of pinned messages, and the DSH native auto-compaction line (80% by default). When occupancy crosses the native auto-compaction line, the ring flashes red.
 
+When occupancy enters the compressible band (between the minimum compression line and the compression line), the plugin proactively tells the model the current occupancy and band through a dynamic system-prompt context, so it can decide whether to record a compression node after finishing a natural milestone (since 0.3.4; before that the model could not see occupancy, so the condition was not actionable).
+
 Hovering over the ring displays exact values: capacity used, cumulative compaction count, current suggestion, compression point, native auto-compaction line, and the number of pinned messages.
 
 ### 2. Preview-then-confirm compaction
@@ -58,7 +60,7 @@ Running `/pin` marks messages that must be preserved during compaction. Pinned m
 | Blue arc | The normal capacity zone is full |
 | Amber arc | The compression point has been passed; compaction is suitable |
 | Red arc | The handoff threshold has been passed; switching to a new session is recommended |
-| Ring notch | Suggested compression point (determined by model assessment or the configured threshold) |
+| Ring notch | Suggested compression point (the system proactively prompts the model to assess inside the compressible band; shown after the model records one or the compression line is reached) |
 | Violet tick | DSH native auto-compaction line (reads `compaction-basic.thresholdRatio`, 80% by default) |
 | Magenta blocks | Distribution of pinned messages in the history |
 | Full-ring red flash | The native auto-compaction line has been crossed; DSH native auto-compaction is imminent |
@@ -67,7 +69,7 @@ Running `/pin` marks messages that must be preserved during compaction. Pinned m
 
 ## Installation
 
-**Requirements**: DSH Desktop or `dsh web` 0.2.x (tested on 0.2.1-rc.2), Node.js 22+.
+**Requirements**: DSH Desktop or `dsh web` 0.2.x (tested on 0.2.1-rc.2), Node.js 22+ (the plugin uses the runtime bundled with DSH). Running the source test suite requires Node **22.15+** (the harness uses `node:module.registerHooks`). The suite is verified on macOS and Windows 11 (Node 24.22).
 
 ```sh
 dsh plugin --profile desktop add dsh-compact-relay
@@ -118,11 +120,13 @@ The first time a session is opened, the ring plays a brief highlight animation w
 - **Does not modify prompts or model replies**: history is replaced only when the user explicitly confirms a compaction or runs a handoff.
 - **Summary quality depends on the underlying model**: summaries use a structured nine-section template with format validation and a single retry, but output quality remains limited by the selected model.
 - **Local storage only**: plugin state is stored in `~/.dsh/compact-relay.json` and handoff documents in `~/.dsh/handoffs/`; no external data is synchronized.
+- **Tied to the desktop composer**: the ring indicator, `/bc` and `/handoff` depend on the DSH composer and slash-command system. They are not loaded in headless sessions or in bridge links such as QQ/WeChat, where `/bc` is treated as an ordinary message. That is a limitation of the bridge link, not a plugin failure.
 - **UI language limitation**: the current UI is Simplified Chinese only; an English UI is planned with no fixed schedule.
+- **Prerequisite for the model hint**: the compressible-band hint relies on the DSH 0.2.x root service `systemPrompt` (same as plugins such as memory). It is a heuristic prompt and does not guarantee the model records a compression node every time, but the condition is now actionable instead of unobservable.
 
 ## Version and license
 
-- **Current version**: 0.3.1 (first public release), tested on macOS against DSH 0.2.1-rc.2 and using only public DSH exports. See [CHANGELOG.md](CHANGELOG.md) for changes, [ROADMAP.md](ROADMAP.md) for plans and known limitations, and [DEVELOPMENT.md](https://github.com/cfanzx/dsh-compact-relay/blob/main/DEVELOPMENT.md) for build and release workflows.
+- **Current version**: 0.3.4 (0.3.1 was the first public release; 0.3.2 fixed settings links and contact details; 0.3.3 added Windows support; 0.3.4 fixes the compression-point judgment mechanism and adds handoff Markdown rendering plus list load-more). Tested on macOS (DSH 0.2.1-rc.2) and Windows 11 (Node 24.22), using only public DSH exports. See [CHANGELOG.md](CHANGELOG.md) for changes, [ROADMAP.md](ROADMAP.md) for plans and known limitations, and [DEVELOPMENT.md](https://github.com/cfanzx/dsh-compact-relay/blob/main/DEVELOPMENT.md) for build and release workflows.
 - **License**: [MIT](LICENSE). Feedback and Pull Requests are welcome via [GitHub Issues](https://github.com/cfanzx/dsh-compact-relay/issues).
 
 ## Credits

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/dsh-compact-relay?label=npm&color=cb3837)](https://www.npmjs.com/package/dsh-compact-relay)
 [![DSH](https://img.shields.io/badge/DSH-0.2.x-4d6bfe)](https://www.deepseek.com/harness/)
 [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
-[![version](https://img.shields.io/badge/version-0.3.2-blue)](CHANGELOG.md)
+[![version](https://img.shields.io/badge/version-0.3.4-blue)](CHANGELOG.md)
 
 </div>
 
@@ -32,6 +32,8 @@
 
 指示环按压缩评估逻辑分段显色，分别标识模型或阈值判定的建议压缩点、已锁定消息位置，以及 DSH 原生自动压缩线（默认 80%）。当上下文占用越过原生自动压缩线时，整环呈红色闪烁告警。
 
+上下文进入「可压缩区间」（最小压缩线到压缩线之间）时，插件会在系统提示里主动告诉模型当前容量与区间，模型据此判断「刚完成一个自然节点」时是否记录压缩节点（0.3.4 起；此前模型看不到容量，判断条件不可执行）。
+
 鼠标悬停可查看详细数值：已用容量、累计压缩次数、当前操作建议、压缩判断点、原生自动压缩线及已锁定消息数量。
 
 ### 2. 预览与确认压缩
@@ -58,7 +60,7 @@
 | 蓝色弧 | 常规容量区间已满 |
 | 琥珀色弧 | 已越过压缩判断点，适合执行压缩 |
 | 红色弧 | 已越过交接阈值，建议切换新会话 |
-| 环形缺口 | 建议压缩点（由模型评估或配置阈值决定） |
+| 环形缺口 | 建议压缩点（系统在可压缩区间主动提示模型判断；模型记录或到达压缩线时自动出现） |
 | 紫色刻度 | DSH 原生自动压缩线（读取 `compaction-basic.thresholdRatio`，默认 80%） |
 | 品红色块 | 已锁定消息在历史记录中的分布位置 |
 | 整环红色闪烁 | 已越过原生自动压缩线，即将触发 DSH 原生自动压缩 |
@@ -67,7 +69,7 @@
 
 ## 安装
 
-**环境要求**：DSH 桌面版或 `dsh web` 0.2.x（已于 0.2.1-rc.2 测试通过），Node.js 22+。
+**环境要求**：DSH 桌面版或 `dsh web` 0.2.x（已于 0.2.1-rc.2 测试通过），Node.js 22+（插件跟随 DSH 自带运行时）。若要在源码里跑测试，需要 Node **22.15+**（测试脚手架用到 `node:module.registerHooks`）。测试已在 macOS 与 Windows 11（Node 24.22）实测全部通过。
 
 ```sh
 dsh plugin --profile desktop add dsh-compact-relay
@@ -118,11 +120,13 @@ dsh plugin --profile desktop add github:cfanzx/dsh-compact-relay
 - **不篡改提示词与模型回复**：插件仅在用户明确确认压缩或执行交接时替换对应历史记录。
 - **摘要质量取决于底层模型**：摘要生成采用九段式结构化模板并包含格式校验与单次重试机制，但最终产出质量仍受限于所选模型的能力。
 - **纯本地存储**：插件状态保存于 `~/.dsh/compact-relay.json`，交接文档保存于 `~/.dsh/handoffs/`，无任何外部数据同步。
+- **依附桌面输入框**：环形指示器、`/bc`、`/handoff` 依附 DSH 的输入框与斜杠命令；headless 会话或 QQ / 微信等桥接链路不会加载它们，在这些链路里发 `/bc` 会被当成普通消息——这是桥接链路的能力边界，不是插件故障。
 - **界面语言限制**：当前版本用户界面仅提供简体中文，英文界面已列入后续计划（排期未定）。
+- **模型判断提示的前置**：可压缩区间的动态提示依赖 DSH 0.2.x 的根服务 `systemPrompt`（与 memory 等插件同款）；它是启发式提示，不保证模型每次都会记录压缩节点，但条件从「不可判断」变成「可判断」。
 
 ## 版本状态与开源许可
 
-- **当前版本**：0.3.1（首个公开版本），已于 macOS 环境下基于 DSH 0.2.1-rc.2 完成测试，仅调用 DSH 公开导出接口。变更记录详见 [CHANGELOG.md](CHANGELOG.md)，后续规划与已知限制详见 [ROADMAP.md](ROADMAP.md)，构建与发布流程详见 [DEVELOPMENT.md](https://github.com/cfanzx/dsh-compact-relay/blob/main/DEVELOPMENT.md)。
+- **当前版本**：0.3.4（0.3.1 为首个公开版本；0.3.2 修正设置页链接与联系方式；0.3.3 完成 Windows 适配；0.3.4 修复「适合压缩的节点几乎不触发」的判断机制，并补交接单 Markdown 渲染与列表加载更多）。已在 macOS（DSH 0.2.1-rc.2）与 Windows 11（Node 24.22）完成测试，仅调用 DSH 公开导出接口。变更记录详见 [CHANGELOG.md](CHANGELOG.md)，后续规划与已知限制详见 [ROADMAP.md](ROADMAP.md)，构建与发布流程详见 [DEVELOPMENT.md](https://github.com/cfanzx/dsh-compact-relay/blob/main/DEVELOPMENT.md)。
 - **开源许可**：采用 [MIT](LICENSE) 许可证，欢迎通过 [GitHub Issues](https://github.com/cfanzx/dsh-compact-relay/issues) 与 Pull Requests 提交反馈。
 
 ## 参考与致谢

package/ROADMAP.md

@@ -1,6 +1,6 @@
 # 压缩接力 · 目标与路线图
 
-> 版本基准：0.3.1（2026-10-20）｜状态：0.3 发布准备中
+> 版本基准：0.3.4（2026-10-24）｜状态：0.3 已发布（npm + GitHub），0.3.4 发布中
 > 维护方式：每次发布前更新"当前状态"与勾选进度；方向变化必须同时改本文件和 memory 项目页。
 
 ## 一、最终目标（North Star）
@@ -72,6 +72,27 @@
 
 验收：多天项目不用回忆"上次做到哪"，直接继续。
 
+### 评审建议的落位（2026-10-20 小潇拍板）
+
+> 来源：2026-10-20 首条外部评审（Gemini）+ 小潇讨论。拍板结论：先收尾发布闭环（市场 PR / 陌生人安装验证 / soak），再进 0.4 首批。
+
+**0.4 首批（已确认，四项）**
+1. **压缩预览里的「建议锁定」提示**：预览时高亮「包含关键决策 / 报错堆栈 / 明确要求别改」的消息，提示用户先 `/pin` 再压；只提示，不自动锁（不替用户做主）。
+2. **设置页一行「累计压缩 X 次 / 腾出 Y tokens」**：不做独立成本面板（见 §四），只做一行正反馈数字。
+3. **交接预览可编辑**：只允许改「下一步计划 / 约束条件」两段；程序生成的段落不可改（防编造），改完再确认切换。
+4. **接力链元数据补全**：A5 记录已存在，补全 parent/child、第几次、时间线字段，为 0.5 的接力链视图铺路（视图本身仍留 0.5）。
+
+**低优先（0.4 观察，有数据再动）**
+- **阶段边界「只读提示」**：识别「子任务收尾」的对话边界，在缺口旁只读标注「可能处于阶段收尾」，暂不改变压缩范围；误判风险大，先只提示。
+- **场景化交接模板**：等 3+ 真实用户提同一诉求再做。
+- **简化模式（降低认知负荷）**：可选开关，暂不排期。
+
+**研究项（先探边界，不做承诺）**
+- **DSH 公开消息钩子**：确认宿主是否提供官方钩子可供桥接链路做文本级提醒；没有就维持 §四「不接管 headless/桥接链路」。dcr 目前只用 `ctx.on('session/event')` 观察事件，不修改模型回复。
+
+**维持观察**
+- **i18n（英文界面）**：README 已有英文版；界面英文等 0.5 再评估。
+
 ### 1.0 上下文生命周期自动化（远期）
 
 - 自动化等级：建议 → 一键确认 → 在 Step 边界自动执行（可配置）。
@@ -82,6 +103,7 @@
 验收：用户不再主动想"上下文会不会满"。
 
 ## 四、明确切掉 / 不做
+- **不接管 headless / 桥接链路**：指示灯与 `/bc`、`/handoff` 依附 DSH 输入框和命令系统；headless 会话、QQ / 微信桥接里不加载（那里发 `/bc` 会被当成普通消息）。只保证插件加载不报错、不额外烧模型调用。
 
 | 方向 | 原因 |
 |---|---|
@@ -119,7 +141,12 @@
 ## 七、当前状态 / 下一步
 
 - ✅ 0.3.1 发布包已就绪：版本号 / CHANGELOG / README 安装段 / .gitignore / npm `files` 收窄 / 文件权限归一；测试基线 smoke 50、handoff 35、plugin-load 13、contract 17、compact-log PASS。
+- ✅ 0.3.1 已发布：npm `dsh-compact-relay@0.3.1` + GitHub tag/Release；0.3.2 补设置页链接与联系方式；0.3.3 完成 Windows 适配（Win11 + Node 24.22 全测试通过）。
+- ✅ 0.3.4 判断机制修复（BUG-010：`mark_compress_point` + systemPrompt 可压缩区间提示 + 状态缓存；427 会话数据佐证旧工具 0 调用）+ BUG-005/BUG-006 小 bug；npm latest 待本次发布。
 - ✅ 真实压缩 e2e：`test/e2e/real-compact.mjs`（真实模型 + 真实压缩事务 + `maxSummaries=1` 合并旧摘要分支）6 项断言通过。
 - ✅ P3-01～14（13 修/1 确认无需修）+ BUG-004 + P2-T1 已收口。
-- ⏳ 待一次重启复核：state 帧单调 `revision` 真机下发；待一次真交接复核：交接成功文案。
-- ⏳ 发布动作（待拍板）：GitHub 账号/仓库名 → 填 `repository`/`homepage`/`bugs` 与 `links`、发布渠道（npm / GitHub / 插件市场）。
+- ⏳ 市场收录 PR：仓库满 1 天（2026-10-21 19:09 后）提，yml 与说明已备。
+- ⏳ 陌生人安装路径验证（npm 安装 → 重启 → 设置/指示灯）—— 发布后第一次外部用户安装时一并确认。
+- ⏳ 真实长会话 soak（至少 3 条真实任务，含压缩→交接→继续）—— 建议下一批功能开发时顺带跑（dogfooding）。
+- ⏳ 与其他上下文插件共存测试（dsh-auto-handoff / hypercompact 等）—— 等市场收录后有用户反馈再做。
+- ⏳ 真机复核残留：交接成功文案（0.3.1 起文案已改，待一次真交接确认）。

package/TUTORIAL.md

@@ -17,7 +17,7 @@
 | 警示红（原生线） | 80% 处的 DSH 原生自动压缩线（紫色径向刻度）；越过 80% 后整环红色闪烁 | 再往前 DSH 会自己压历史，先压缩或交接 |
 | 品红（锁定色） | 这里锁了一条重要消息（按它在对话里的位置显示，可多个） | 知道「我锁的东西在哪」 |
 
-**断点**（环上的小缺口）=「我判断这里适合压缩」的位置：模型判断（上下文超过最小压缩线、还没到压缩线、正到自然节点）或到压缩线时自动出现；压缩后环变短，断点自然消失。
+**断点**（环上的小缺口）=「我判断这里适合压缩」的位置：上下文进入可压缩区间（最小压缩线到压缩线之间）时，系统会主动在提示里告诉模型当前容量，模型判断「刚完成一个自然节点」时**可能**会记录一个压缩节点；到了压缩线也会自动出现。压缩后环变短，断点自然消失。
 
 把鼠标放到指示灯上，会显示具体数字：`会话容量已用 xx.x%（xxxK / 1.00M），已压缩 n 次｜建议压缩 / 建议交接 / 正常｜压缩判断点 x%｜原生自动压缩线 80%｜已锁定 n 条`。
 
@@ -58,8 +58,9 @@
 - **压缩到一半取消了**：历史不会变、锁会释放；已发出的模型请求可能仍计费。
 - **换模型后阈值变了**：阈值按窗口比例算，小窗口模型会自动变小，这是预期。
 - **设置保存了但没变**：设置栏保存即时生效；改代码或 profile 配置才需要重启 DSH。
+- **在 headless / QQ 桥上发 `/bc` 没反应**：指示灯和 `/bc`、`/handoff` 依附桌面输入框与斜杠命令，headless 会话和 QQ / 微信桥接链路不会加载它们，`/bc` 会被当成普通消息。插件本身不报错、也不额外烧模型调用；要在电脑上开 DSH 桌面版才能用。
 
 ## 5. 更多
 
 - 安装、完整说明见仓库 `README.md`；设计文档见 `ARCHITECTURE.md`。
-- 遇到 bug / 想提改进：到仓库 Issues 提一条（设置页「帮助」区的「反馈」入口建好后会直接打开）。
+- 遇到 bug / 想提改进：到仓库 Issues 提一条（设置页「帮助」区的「反馈 / 提 bug」入口会直接打开）；也可以发邮件到 cfanzx@136.com。

package/lib/actions/better-compact.js

@@ -19,13 +19,13 @@ import { actionError } from '../core/errors.js';
 import { livePinnedSeqs } from '../dsh/session-view.js';
 import { compactionPolicy } from '../core/policy.js';
 import { SUMMARY_INSTRUCTION } from '../core/prompts.js';
+import { sumShadowedTokens, tokenOf } from '../core/tokens.js';
 import { selectCompactableRange } from '../dsh/select-range.js';
-import { replaceRangeWithSummary } from '../dsh/compact-transaction.js';
-import { runIdle } from '../dsh/idle.js';
 import { measurePressure } from '../dsh/pressure.js';
 import { countSummaries } from '../dsh/session-view.js';
-import { summarize } from '../dsh/summarizer.js';
+import { runCompaction } from './compact-run.js';
 import { withLock } from './lock.js';
+import { beginInflight, cancelErrorOf, combinedSignal, finishInflight } from './support.js';
 
 /** 范围小于这个 token 数时，摘要大概率比原文大：预览阶段就提示、前端据此禁用确认（0.3.1）。 */
 const MIN_MEANINGFUL_TOKENS = 800;
@@ -55,11 +55,6 @@ function planIdOf(range) {
     .slice(0, 16);
 }
 
-function rememberPreviewPlan(sessionId, plan) {
-  if (typeof sessionId !== 'string' || sessionId.length === 0) return;
-  previewPlans.set(sessionId, { ...plan, expiresAt: Date.now() + PREVIEW_TTL_MS });
-}
-
 /**
  * 取出并消费一次预览计划；过期/不存在返回 null。
  * @param {string|undefined} sessionId
@@ -86,13 +81,6 @@ export function clearPreviewPlans() {
   previewPlans.clear();
 }
 
-function shadowedTokensOf(nodes, shadowedSeqs) {
-  const wanted = new Set(shadowedSeqs);
-  return nodes
-    .filter((node) => wanted.has(node.seq))
-    .reduce((sum, node) => sum + (node.heuristicTokens ?? node.tokens ?? 0), 0);
-}
-
 /**
  * 算一遍「这次能压什么」—— 预览与正式执行共用，保证两边口径一致。
  * @param {{ctx:object, cfg:object, engine:object}} deps
@@ -112,12 +100,17 @@ async function planCompact(deps, agent) {
     nodes,
     engine: deps.engine,
     cfg: deps.cfg,
-    tokenOf: (node) => node.heuristicTokens ?? node.tokens ?? 0,
+    tokenOf,
   });
 
   return { measured, nodes, summaries, allowMergeOldSummaries, range, pinned, planId: range === null ? null : planIdOf(range) };
 }
 
+function rememberPreviewPlan(sessionId, plan) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return;
+  previewPlans.set(sessionId, { ...plan, expiresAt: Date.now() + PREVIEW_TTL_MS });
+}
+
 /**
  * 没有可压范围时给用户的解释——被钉住挡住时要指出来，否则用户不知道去 /unpin。
  * @param {number[]|undefined} pinned
@@ -156,38 +149,18 @@ export async function betterCompactLocked(deps, { agent, signal, commandId, expe
     };
   }
 
-  const freshRange = { ...range, shadowedTokenCount: shadowedTokensOf(nodes, range.shadowedSeqs) };
-  const flush =
-    typeof deps.ctx.sessions?.flush === 'function' ? () => deps.ctx.sessions.flush(session) : undefined;
-  const estimateMessage =
-    typeof deps.ctx?.tokenMeter?.estimateMessage === 'function'
-      ? (message) => deps.ctx.tokenMeter.estimateMessage(message)
-      : undefined;
+  const freshRange = { ...range, shadowedTokenCount: sumShadowedTokens(nodes, range.shadowedSeqs) };
 
-  const outcome = await runIdle(agent, (idleSignal) => {
-    const combined = signal === undefined ? idleSignal : AbortSignal.any([signal, idleSignal]);
-    return replaceRangeWithSummary({
-      session,
-      range: freshRange,
-      engine: deps.engine,
-      signal: combined,
-      sourceCommandId: commandId,
-      estimateMessage,
-      summarize: ({ shadowedSeqs, signal: innerSignal }) =>
-        summarize({
-          ctx: deps.ctx,
-          engine: deps.engine,
-          agent,
-          shadowedSeqs,
-          endSeq: freshRange.endSeq,
-          instruction: SUMMARY_INSTRUCTION,
-          maxTokens: deps.cfg.summary.maxTokens,
-          inputTokens: plan.measured.tokens,
-          timeoutMs: deps.cfg.timeouts?.llmMs,
-          signal: innerSignal,
-        }),
-      flush,
-    });
+  const outcome = await runCompaction(deps, {
+    agent,
+    session,
+    range: freshRange,
+    instruction: SUMMARY_INSTRUCTION,
+    signal,
+    commandId,
+    inputTokens: plan.measured.tokens,
+    // 正式精压继承配置超时（/bctest 不传、保持 llm-call 的 180s 默认）。
+    timeoutMs: deps.cfg.timeouts?.llmMs,
   });
 
   const note = allowMergeOldSummaries
@@ -227,7 +200,7 @@ export async function previewBetterCompact(deps, { agent } = {}) {
     };
   }
 
-  const shadowedTokenCount = shadowedTokensOf(nodes, range.shadowedSeqs);
+  const shadowedTokenCount = sumShadowedTokens(nodes, range.shadowedSeqs);
   rememberPreviewPlan(agent.id, {
     planId,
     startSeq: range.startSeq,
@@ -283,12 +256,6 @@ export function cancelBetterCompact(deps, { agent } = {}) {
     : { ok: false, cancelled: false, kind: null, message: '当前没有正在进行的压缩/交接任务。' };
 }
 
-function combinedSignal(a, b) {
-  if (a === undefined) return b;
-  if (b === undefined) return a;
-  return AbortSignal.any([a, b]);
-}
-
 /**
  * 压缩动作入口：带每会话单飞锁 + 可取消登记。
  * @param {{ctx:object, cfg:object, lock:object, engine:object, inflight?:object}} deps
@@ -297,30 +264,15 @@ function combinedSignal(a, b) {
 export async function betterCompact(deps, input) {
   if (input?.agent === undefined || input?.agent === null) throw actionError('nosession', '没有活动会话');
   const agent = input.agent;
-  const controller =
-    deps.inflight !== undefined && typeof deps.inflight.begin === 'function'
-      ? deps.inflight.begin(agent.id, 'compact')
-      : null;
+  const controller = beginInflight(deps, agent.id, 'compact');
   const signal = combinedSignal(controller?.signal, input.signal);
 
   try {
     return await withLock(deps.lock, agent.id, () => betterCompactLocked(deps, { ...input, signal }));
   } catch (error) {
     // 取消 → 统一成 cancelled 文案（宿主 HTTP 层据此回「历史没改」）。
-    // P2-1：commit/persistence 表示历史可能已改或落盘状态不明，绝不能谎报「历史没改」。
-    if (
-      signal !== undefined &&
-      signal.aborted &&
-      error?.code !== 'cancelled' &&
-      error?.code !== 'commit' &&
-      error?.code !== 'persistence'
-    ) {
-      throw actionError('cancelled', '已取消，会话记录没有改动。', error);
-    }
-    throw error;
+    throw cancelErrorOf(error, signal, '已取消，会话记录没有改动。');
   } finally {
-    if (controller !== null && typeof deps.inflight.finish === 'function') {
-      deps.inflight.finish(agent.id, controller);
-    }
+    finishInflight(deps, agent.id, controller);
   }
 }

package/lib/actions/compact-run.js

@@ -0,0 +1,76 @@
+/**
+ * 压缩执行流程 —— 正式精压（actions/better-compact.js）与实验动作 /bctest
+ * （actions/test-compact.js）共用的那一段「idle 准入 → 替换事务 → 调摘要」。
+ *
+ * 两个动作的差异只在**怎么选段、用什么摘要指令、要不要六段校验、超时从哪来**；
+ * 真正改历史的执行路径必须完全同一条（否则 /bctest 就不是「小范围真事务」了）：
+ *   1. 从 deps.ctx 取 flush / tokenMeter.estimateMessage（宿主能力，可选）；
+ *   2. runIdle(agent, ...) 里跑事务（手动压缩的 idle 准入 / 与自动压缩互斥）；
+ *   3. 用户取消信号与 idle 信号合并；
+ *   4. replaceRangeWithSummary：summarize 回放前缀（cache 对齐）+ 替换历史 + 成对 start/end。
+ *
+ * 超时不在本函数内部读 cfg：由调用方传 `timeoutMs`。正式精压传 cfg.timeouts.llmMs
+ * （原有行为），/bctest 不传 → summarize 用 llm-call 的 180s 默认（同样保持原行为）。
+ *
+ * 以前这 20+ 行在 better-compact.js 与 test-compact.js 里逐字重复（含 summarize
+ * 参数的拼装），改一处漏一处就会让 /bctest 与正式压缩行为分叉。
+ */
+import { replaceRangeWithSummary } from '../dsh/compact-transaction.js';
+import { runIdle } from '../dsh/idle.js';
+import { summarize } from '../dsh/summarizer.js';
+import { combinedSignal } from './support.js';
+
+/**
+ * 执行一次压缩替换事务。
+ * @param {{ctx:object, cfg:object, engine:object}} deps
+ * @param {object} input
+ * @param {object} input.agent
+ * @param {object} input.session
+ * @param {{startSeq:number, endSeq:number, shadowedSeqs:number[], shadowedTokenCount:number}} input.range
+ * @param {string} input.instruction 摘要指令（正式版 SUMMARY_INSTRUCTION / 实验版 TEST_INSTRUCTION）
+ * @param {string[]} [input.requiredSections] 摘要结构校验的小节；省略=默认六段，[]=不校验（/bctest）
+ * @param {AbortSignal} [input.signal]
+ * @param {string} [input.commandId]
+ * @param {number} [input.inputTokens] 调用前预算预检的输入 token 估算（可选）
+ * @param {number} [input.timeoutMs] 单次模型调用超时；**由调用方决定**（省略 = llm-call 的 180s 默认）
+ * @returns {Promise<{compactionId:string, startSeq:number, summarySeq:number, endSeq:number, shadowedSeqs:number[], shadowedTokenCount:number}>}
+ */
+export async function runCompaction(
+  deps,
+  { agent, session, range, instruction, requiredSections, signal, commandId, inputTokens, timeoutMs },
+) {
+  const flush =
+    typeof deps.ctx.sessions?.flush === 'function' ? () => deps.ctx.sessions.flush(session) : undefined;
+  const estimateMessage =
+    typeof deps.ctx?.tokenMeter?.estimateMessage === 'function'
+      ? (message) => deps.ctx.tokenMeter.estimateMessage(message)
+      : undefined;
+
+  return runIdle(agent, (idleSignal) => {
+    const combined = combinedSignal(signal, idleSignal);
+    return replaceRangeWithSummary({
+      session,
+      range,
+      engine: deps.engine,
+      signal: combined,
+      sourceCommandId: commandId,
+      estimateMessage,
+      summarize: ({ shadowedSeqs, signal: innerSignal }) =>
+        summarize({
+          ctx: deps.ctx,
+          engine: deps.engine,
+          agent,
+          shadowedSeqs,
+          endSeq: range.endSeq,
+          instruction,
+          requiredSections,
+          maxTokens: deps.cfg.summary.maxTokens,
+          inputTokens,
+          // 超时由调用方传：正式精压传 cfg.timeouts.llmMs（原行为），/bctest 不传 → 180s 默认。
+          timeoutMs,
+          signal: innerSignal,
+        }),
+      flush,
+    });
+  });
+}

package/lib/actions/compress-hint.js

@@ -1,8 +1,11 @@
 /**
- * 「这里适合压缩」判断（0.3.1）。
+ * 「这里适合压缩」判断（0.3.1；0.3.4 工具改名 mark_compress_point）。
  *
- * 模型工具 `mark_stage` 在这里落一条 plugin record；环上把它画成断点1。
+ * 模型工具 `mark_compress_point` 在这里落一条 plugin record；环上把它画成断点1。
  * 用户手动入口已删除（作者 2026-10-20 拍板：判断由模型/阈值自动完成）。
+ *
+ * 服务端仍复核区间：太低（压缩不划算）/已经到压缩线都拒绝，不改历史。
+ * 返回文案是给模型看的，措辞要和工具描述一致（0.3.4 起不再说「系统会告诉你」）。
  */
 import { COMPRESS_HINT_RECORD_TYPE } from '../core/compress-hint.js';
 import { compressionMinRatio } from '../core/policy.js';
@@ -17,11 +20,11 @@ import { measurePressure } from '../dsh/pressure.js';
 export async function markCompressHint(deps, { agent } = {}) {
   const session = agent?.session;
   if (session === null || session === undefined) {
-    return { ok: false, ratio: 0, at: 0, reason: 'no-session', message: '没有活动会话，无法记录判断' };
+    return { ok: false, ratio: 0, at: 0, reason: 'no-session', message: '没有活动会话，无法记录压缩节点' };
   }
   const measured = await measurePressure(deps.ctx, agent, { windowFallback: deps.cfg.contextWindowFallback }).catch(() => null);
   if (measured === null || typeof measured.ratio !== 'number') {
-    return { ok: false, ratio: 0, at: 0, reason: 'no-pressure', message: '拿不到当前容量，先别记录' };
+    return { ok: false, ratio: 0, at: 0, reason: 'no-pressure', message: '拿不到当前上下文容量，先别记录压缩节点' };
   }
   const ratio = measured.ratio;
   const window = measured.window;
@@ -34,7 +37,9 @@ export async function markCompressHint(deps, { agent } = {}) {
       ratio,
       at: Date.now(),
       reason: 'below-min',
-      message: `当前容量 ${percent(ratio)} 还没到最小压缩线 ${percent(minRatio)}——这个位置压缩不划算，不用记录，继续做你的工作`,
+      message:
+        `当前容量 ${percent(ratio)} 还没到最小压缩线 ${percent(minRatio)}——现在压缩旧历史不划算，` +
+        '没有记录压缩节点，继续做你的工作',
     };
   }
   if (ratio >= compactRatio) {
@@ -43,7 +48,9 @@ export async function markCompressHint(deps, { agent } = {}) {
       ratio,
       at: Date.now(),
       reason: 'already-over',
-      message: `当前容量 ${percent(ratio)} 已经到压缩线了——直接建议用户压缩就行，不用再记录判断点`,
+      message:
+        `当前容量 ${percent(ratio)} 已经到压缩线 ${percent(compactRatio)} 了——` +
+        '直接建议用户压缩旧会话即可，不用再记录压缩节点',
     };
   }
   const at = Date.now();
@@ -53,6 +60,8 @@ export async function markCompressHint(deps, { agent } = {}) {
     ratio,
     at,
     seq,
-    message: `已记录「适合压缩」判断：当前 ${percent(ratio)}（在最小线和压缩线之间）。用户会在环上看到一个断点`,
+    message:
+      `已记录压缩节点：当前容量 ${percent(ratio)}（在最小线 ${percent(minRatio)} 和压缩线 ${percent(compactRatio)} 之间）。` +
+      '用户会在指示灯环上看到一个断点；可以继续工作，或建议用户压缩旧会话',
   };
 }

package/lib/actions/handoff-docs.js

@@ -3,17 +3,23 @@
  *
  * HTTP 只关心「列最近 N 份 / 读一篇的 JSON」，目录白名单/防穿越/大小上限
  * 全部留在 dsh/handoff-files.js。
+ *
+ * 0.3.4（BUG-006）：列表额外返回 `total`（全量份数），客户端据此显示
+ * 「共 N 份（显示最近 20）」并用「加载更多」把 limit 提到 50。
  */
-import { listHandoffFiles, readHandoffFile } from '../dsh/handoff-files.js';
+import { countHandoffFiles, listHandoffFiles, readHandoffFile } from '../dsh/handoff-files.js';
 
 /**
  * @param {{cfg:{handoffDir:string}}} deps
  * @param {{limit?:number}} [options]
+ * @returns {{dir:string, items:object[], total:number}}
  */
 export function listHandoffDocs(deps, { limit = 20 } = {}) {
+  const dir = deps.cfg.handoffDir;
   return {
-    dir: deps.cfg.handoffDir,
-    items: listHandoffFiles(deps.cfg.handoffDir, { limit }),
+    dir,
+    items: listHandoffFiles(dir, { limit }),
+    total: countHandoffFiles(dir),
   };
 }
 

package/lib/actions/handoff.js

@@ -31,6 +31,7 @@ import { surfaceMessages } from '../dsh/prefix.js';
 import { handoffTitlePlanOf, createHandoffSession, sourceTitleOf } from '../dsh/sessions.js';
 import { writeRelayRecord } from '../dsh/relay.js';
 import { withLock } from './lock.js';
+import { beginInflight, cancelErrorOf, combinedSignal, finishInflight } from './support.js';
 
 /**
  * 压缩阶段：能压就压，压不了就带着原因往下走。
@@ -87,16 +88,8 @@ export async function handoff(deps, { agent, signal, commandId }) {
 
   return withLock(deps.lock, agent.id, async () => {
     // P1-4：交接登记进 inflight，client 的取消按钮才能真正 abort 模型调用。
-    const controller =
-      deps.inflight !== undefined && typeof deps.inflight.begin === 'function'
-        ? deps.inflight.begin(agent.id, 'handoff')
-        : null;
-    const combined =
-      controller?.signal === undefined
-        ? signal
-        : signal === undefined
-          ? controller.signal
-          : AbortSignal.any([controller.signal, signal]);
+    const controller = beginInflight(deps, agent.id, 'handoff');
+    const combined = combinedSignal(controller?.signal, signal);
 
     try {
       // P2-2：先做可失败的 preflight（目录可写），再动历史（压缩）。
@@ -242,19 +235,9 @@ export async function handoff(deps, { agent, signal, commandId }) {
       };
     } catch (error) {
       // 取消统一收口；已提交/落盘状态不明的错误不许谎报「没改」。
-      if (
-        combined?.aborted === true &&
-        error?.code !== 'cancelled' &&
-        error?.code !== 'commit' &&
-        error?.code !== 'persistence'
-      ) {
-        throw actionError('cancelled', '已取消交接；已完成的压缩不会回滚。', error);
-      }
-      throw error;
+      throw cancelErrorOf(error, combined, '已取消交接；已完成的压缩不会回滚。');
     } finally {
-      if (controller !== null && typeof deps.inflight.finish === 'function') {
-        deps.inflight.finish(agent.id, controller);
-      }
+      finishInflight(deps, agent.id, controller);
     }
   });
 }

package/lib/actions/settings.js

@@ -12,6 +12,7 @@
  */
 import { resolveConfig } from '../config.js';
 import { paletteForBothSchemes } from '../core/colors.js';
+import { isPlainObject } from '../core/object.js';
 import { readNativeCompaction } from '../dsh/native-compaction.js';
 import { filterSettingsPatch, publicConfigOf } from '../core/config-schema.js';
 import {
@@ -24,10 +25,6 @@ import {
 
 export { defaultSettingsPath } from '../dsh/settings-file.js';
 
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /** 深合并普通对象；数组/标量直接覆盖。 */
 function deepMerge(base, patch) {
   if (!isPlainObject(base) || !isPlainObject(patch)) return patch;

package/lib/actions/state.js

@@ -6,6 +6,7 @@
  */
 import { paletteForBothSchemes } from '../core/colors.js';
 import { adviceFor, ratioOf, thresholdsForWindow } from '../core/policy.js';
+import { tokenOf } from '../core/tokens.js';
 import { measurePressure } from '../dsh/pressure.js';
 import { selectCompactableRange } from '../dsh/select-range.js';
 import { compressHint as compressHintOf, countSummaries, lastCheckpointSurfaceSeq, livePinnedSeqs, liveSessionOf, pickAgent, surfaceSeqs } from '../dsh/session-view.js';
@@ -75,7 +76,7 @@ export async function readState(deps, { sessionId, agent } = {}) {
         nodes: measured.nodes.filter((node) => Number.isInteger(node?.seq)),
         engine: deps.engine,
         cfg: deps.cfg,
-        tokenOf: (node) => node.heuristicTokens ?? node.tokens ?? 0,
+        tokenOf,
       });
       compactRange =
         compactRange === null