@zhushanwen/pi-smart-context 0.4.4 → 0.5.0

package/src/index.ts

@@ -3,33 +3,67 @@
  *
  * - session_start：session 级闭包状态重建（规范 Session 隔离：熔断计数不跨 session）
  *   + fired 档位从 session entries 重建（D15：reload/进程重启同 session 不重复提醒）
+ *   + 会话替换类启动取消进行中后台压缩任务（D3 第一层，new/resume/fork）
  * - subagent 进程（R6）：不注册工具、不提醒（宁缺勿污）
  * - session_before_compact：双模式接管（compact-handler）
- * - session_compact：重置提醒 fired（D3）
- * - agent_settled：越档检查 + marker 持久化（D15）+ nextTurn 投递一次性提醒（D3/D4①）
+ * - session_compact：重置提醒 fired（D3，与后台落盘成功回调共用 resetFiredThresholds）
+ *   + 后台任务被抢先取消（D3 第一层——后台路径自身落盘不发该事件，收到即代表其他压缩
+ *   抢先落盘）
+ * - session_shutdown：后台任务取消（D3 第一层）
+ * - session_tree：仅观测告警（D3 rejected：会话内回退不破坏压缩正确性，不取消）
+ * - agent_settled：后台压缩自动触发（D4：触发线/互斥/门控/独立熔断判定内聚 manager）
+ *   + 越档检查 + marker 持久化（D15）+ nextTurn 投递一次性提醒（D3/D4①）
+ * - registerCompactContextTool：注入 background 契约（U5——工具路径与自动触发共享
+ *   互斥容器；工具纯触发化后无异步回调，isCtxStale 过渡字段退役）
+ * - 后台压缩落盘段 stale ctx 防线（C-pi-17）：manager 的 isCtxStale 注入位由本文件的
+ *   稳定间接层供给，经续段钩子转交 persistBackgroundCompaction——落盘段跨 await 持有
+ *   ctx，session 替换窗口内放弃落盘回报 dropped（会话态失效类放弃，不递增熔断计数）
+ * - 后台任务终局：完成/失败通知经 nextTurn 投递（U5/D6——validated 完成、失败不静默，
+ *   熔断达到阈值并入该条通知；cancelled 事件取消不发）；通知投递失败由 compact-handler
+ *   的 settle 内吞留痕，不改写压缩成败事实
+ * - 后台压缩落盘信号（C1 分界行实时化）：persistBackgroundCompaction 成功的事实点
+ *   （onPersisted 回调）经 sendCompactionPersistSignal 发 custom message（display:false、
+ *   {triggerTurn:false} 无 deliverAs，空闲时立即 append）——taiji runtime 分诊命中后取
+ *   compaction entry 合成对话流分界行帧，分界行不再只能重开可见
  * - model_select：跨界通知 + downshift 提醒（D5/D4①）
  *
  * 通知投递路径（D4①，delivery-ownership-kernel）：四类通知全部经 notices.ts 的
  * sendSmartContextNotice 走 nextTurn（随下一次 prompt 注入、不自起 run）——通知 run 不再
- * 抢占用户消息投递跑道；被压缩掐断的 turn 由 runtime 续跑投递兜底（D4②）。
+ * 抢占用户消息投递跑道。手动触发失败回执（start-failed/busy）走即时投递（见 notices.ts
+ * sendSmartContextImmediateNotice）。后台压缩全程不掐 turn（C2 后手动压缩不经 pi 同步
+ * compact 链，进行中回合不受影响），无「被压缩掐断的 turn」需续跑兜底。
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { guardStaleCtx, isSubagentProcess, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 import {
+	createBackgroundCompactionManager,
+	createBackgroundCompactionState,
 	createBeforeCompactHandler,
 	createTakeoverState,
 	debugLog,
+	persistBackgroundCompaction,
+	type AfterGenerationHook,
+	type BackgroundCompactionState,
 	type TakeoverState,
 } from "./compact-handler.js";
-import { sendSmartContextNotice } from "./notices.js";
+import {
+	sendSmartContextImmediateNotice,
+	sendSmartContextNotice,
+	buildCompactBusyNotice,
+	buildCompactCompleteNotice,
+	buildCompactFailureNotice,
+	buildCompactStartFailureNotice,
+	sendCompactionPersistSignal,
+} from "./notices.js";
 import { buildDownshiftNotice, buildSwitchNotice, buildThresholdReminder } from "./reminder.js";
 import { registerCompactContextTool } from "./tool.js";
 import {
 	countCompactions,
 	deriveFiredThresholds,
+	estimateTextTokens,
 	findCrossedThresholds,
 	FIRED_ENTRY_CUSTOM_TYPE,
 	getCurrentModelId,
@@ -37,10 +71,13 @@ import {
 	loadSmartContextConfig,
 	type EntryLike,
 } from "./pure.js";
+import type { BackgroundTaskSettlement } from "./compact-handler.js";
 
 /** session 级闭包状态（规范：模块级仅工厂函数，状态在 session_start 重建）。 */
 interface SessionState {
 	takeover: TakeoverState;
+	/** 后台压缩任务状态（U2：进行中互斥 + 独立熔断计数）。 */
+	background: BackgroundCompactionState;
 	/** 已提醒档位（token 值为键；session_compact 清空，D3）。 */
 	firedThresholds: Set<number>;
 	/** fired 是否已从 session entries seed 过（D15：每次状态重建恰好 seed 一次）。 */
@@ -49,7 +86,12 @@ interface SessionState {
 
 /** session 级状态唯一构造点（初始态与 session_start 重建同源，新增字段不落两处）。 */
 function createSessionState(): SessionState {
-	return { takeover: createTakeoverState(), firedThresholds: new Set(), firedSeeded: false };
+	return {
+		takeover: createTakeoverState(),
+		background: createBackgroundCompactionState(),
+		firedThresholds: new Set(),
+		firedSeeded: false,
+	};
 }
 
 // G1 代际检测（crash-resilience D1，同 scheduler/src/index.ts 的模块级代数计数器范式）：
@@ -82,8 +124,9 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	let state: SessionState = createSessionState();
 
 	// G1 代际比对闭包（isCtxStale）：session_start 装配本代比对（读实时模块级代数），
-	// 供下方事件回调与 compact 工具回调的 guardStaleCtx 前置检查使用——stale 分诊不依赖
-	// pi 错误文案。首个 session_start 前无 session，恒 false 为安全默认。
+	// 供下方事件回调的 guardStaleCtx 前置检查使用（工具侧消费已随 U4 纯触发化退役——
+	// 见工具注册点注释）——stale 分诊不依赖 pi 错误文案。首个 session_start 前无
+	// session，恒 false 为安全默认。
 	let isCtxStale: () => boolean = () => false;
 
 	/**
@@ -124,7 +167,110 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		}
 	};
 
-	pi.on("session_start", (_event: unknown, ctx: ExtensionContext) => {
+	// ── 后台压缩任务管理（U2：触发判定/互斥/独立熔断/事件取消；U3：续段落盘 + 膨胀段共享读取）──
+	// getState 读当前代容器（state.background），manager 自身跨代存活无需重建。
+	// 落盘续段（U3/D3 第二层/D2/D6）：三项兜底校验 + appendCompaction 直调，落盘成功回调
+	// 清 firedThresholds（D6 档位重置补偿，与 session_compact 监听共用 resetFiredThresholds），
+	// 收缩校验失败回调写共享膨胀段集合（与同步路径同段不重试同源）。续段跨 await 持有 ctx，
+	// 经下方 isCurrentCtxStale 注入位接 C-pi-17 stale 防线（落盘段内 guardStaleCtx 分诊）。
+	const resetFiredThresholds = (): void => {
+		state.firedThresholds.clear();
+	};
+	const backgroundAfterGeneration: AfterGenerationHook = (result, snapshot, ctx, isCtxStale) =>
+		persistBackgroundCompaction(
+			ctx,
+			result,
+			snapshot,
+			{
+				onPersisted: (entryId) => {
+					resetFiredThresholds();
+					debugLog(`fired thresholds reset after background compaction (sessionId=${snapshot.sessionId})`);
+					// C1 分界行实时化：落盘信号挂在「落盘成功」事实点（本回调在 appendCompaction
+					// 成功后的同一同步帧内、guardStaleCtx 之中，非 stale 由外层保证），不在终局
+					// 回调点（settle 已跨 await 且不带 entryId）。发送失败由 sendCompactionPersistSignal
+					// 内吞留痕（上抛会把已落盘的压缩改记失败，见该函数注释）。
+					sendCompactionPersistSignal(pi, entryId);
+				},
+				onInflated: (firstKeptEntryId) => {
+					state.takeover.inflatedSegments.add(firstKeptEntryId);
+				},
+			},
+			isCtxStale,
+		);
+
+	// ── 后台压缩终局通知（U5：D6 补偿的呈现半边）──
+	// 每个终局点恰一条通知（cancelled 事件取消不发——D3 取消非失败）：validated → 完成
+	// 通知（压缩前后 token 数与模式）；inflated/dropped/empty/error → 失败通知不静默，
+	// 熔断达到阈值时文案附加「自动触发已暂停」。压缩后 token 口径：estimatedTokensAfter
+	// （pi 原生可填）优先，缺省按「压缩前 − 被压段 + 摘要」估算（chars/4 口径与收缩校验
+	// 同源）。异步收尾时 session 可能已替换——guardStaleCtx 分诊，stale 静默降级。本回调
+	// 抛错（非 stale 的上抛语义）由 compact-handler 的 settle 内吞留痕：通知失败不得把已
+	// validated 的压缩改记失败并无谓递增熔断计数。
+	const onBackgroundSettled = (settlement: BackgroundTaskSettlement): void => {
+		if (settlement.outcome === "validated") {
+			const result = settlement.result;
+			if (!result) {
+				debugLog(`compact complete settlement missing result (sessionId=${settlement.sessionId})`);
+				return;
+			}
+			const shadowed = settlement.shadowedTokens ?? 0;
+			const tokensAfter =
+				result.estimatedTokensAfter ?? Math.max(0, result.tokensBefore - shadowed + estimateTextTokens(result.summary));
+			const text = buildCompactCompleteNotice({
+				mode: settlement.mode,
+				tokensBefore: result.tokensBefore,
+				tokensAfter,
+			});
+			debugLog(`compact complete notice queued (sessionId=${settlement.sessionId} tokens=${result.tokensBefore}->${tokensAfter})`);
+			guardStaleCtx(() => {
+				sendSmartContextNotice(pi, text, "compact-complete");
+			}, {
+				isCtxStale,
+				label: "smart-context:compact-complete-notice",
+				onStale: (error) => debugLog(`compact complete notice skipped (stale ctx): ${toErrorMessage(error)}`),
+			});
+			return;
+		}
+		const text = buildCompactFailureNotice({
+			outcome: settlement.outcome,
+			droppedReason: settlement.droppedReason,
+			error: settlement.error,
+			failureStreak: settlement.failureStreak,
+			circuitBreakerOpen: settlement.circuitBreakerOpen,
+		});
+		debugLog(`compact failure notice queued (sessionId=${settlement.sessionId} outcome=${settlement.outcome})`);
+		guardStaleCtx(() => {
+			sendSmartContextNotice(pi, text, "compact-failed");
+		}, {
+			isCtxStale,
+			label: "smart-context:compact-failed-notice",
+			onStale: (error) => debugLog(`compact failure notice skipped (stale ctx): ${toErrorMessage(error)}`),
+		});
+	};
+
+	// 代际检查的稳定间接层（C-pi-17 注入位）：isCtxStale 在 session_start 被重赋值（本代
+	// 比对），而 manager 在 factory 体内创建、早于首个 session_start——直接传引用会把初始
+	// 的 () => false 冻结成永不 stale，故经箭头读实时绑定（与事件回调内 isCtxStale 的 live
+	// 读取同语义）。
+	const isCurrentCtxStale = (): boolean => isCtxStale();
+
+	const background = createBackgroundCompactionManager(
+		pi,
+		() => state.background,
+		loadSmartContextConfig,
+		backgroundAfterGeneration,
+		() => state.takeover.inflatedSegments,
+		onBackgroundSettled,
+		isCurrentCtxStale,
+	);
+
+	pi.on("session_start", (event, ctx) => {
+		// D3 第一层（SI4）：new/resume/fork = 会话替换，进行中后台任务立即取消放弃结果
+		// （必须在重建 state 前 abort——否则旧任务失控跑完白花生成费用）；startup/reload
+		// 不取消（startup 时任务不存在；reload 使扩展工厂重跑、内存态自清）
+		if (event.reason === "new" || event.reason === "resume" || event.reason === "fork") {
+			background.cancelActive(`session_start(${event.reason})`);
+		}
 		// 先递增模块级代数再装配：自此同模块环境内所有前代闭包的 isCtxStale 返回 true
 		sessionGeneration += 1;
 		const myGeneration = sessionGeneration;
@@ -133,6 +279,19 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		seedFiredThresholds(ctx);
 	});
 
+	// session_shutdown（D3 第一层）：扩展运行时因退出/reload/会话替换被拆除前到达——有任务即取消
+	pi.on("session_shutdown", (event) => {
+		background.cancelActive(`session_shutdown(${event.reason})`);
+	});
+
+	// session_tree（D3 rejected 论证）：会话内回退不产生语义错位（回退不取消，取消只浪费
+	// 已花生成费用）——仅观测告警
+	pi.on("session_tree", () => {
+		if (state.background.active) {
+			debugLog("session_tree during background compaction: keeping task (rollback does not invalidate snapshot)");
+		}
+	});
+
 	// ── 压缩生成接管（D1/D12）──
 	const beforeCompact = createBeforeCompactHandler(
 		pi,
@@ -141,20 +300,80 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	);
 	pi.on("session_before_compact", beforeCompact);
 
-	// ── 压缩完成：重置提醒档位（D3）──
+	// ── 压缩完成：重置提醒档位（D3）+ 后台任务被抢先取消（D3 第一层）──
+	// 后台路径自身落盘不发 session_compact（UD6：appendCompaction 纯追加无事件），
+	// 收到该事件必是其他压缩（同步接管/手动/原生兜底）抢先落盘；档位清空与后台落盘成功
+	// 回调共用 resetFiredThresholds（D6 补偿共用化）
 	pi.on("session_compact", (_event, _ctx) => {
-		state.firedThresholds.clear();
+		background.cancelActive("session_compact");
+		resetFiredThresholds();
 	});
 
 	// ── 工具注册（常驻，不可用态由 execute 运行时校验拒绝，D5）──
-	// isCtxStale 必须传 live 绑定 wrapper 而非简写属性：本行在 factory 体同步执行，简写
-	// { isCtxStale } 会把此刻的初始 () => false 快照进 deps 对象，上方 session_start
-	// handler 的重新赋值不回写已构造对象 → compact onComplete/onError（E1 实锤崩溃点）
-	// 检查的前置代际检查恒不生效。wrapper 每次调用读闭包当前绑定。
-	registerCompactContextTool(pi, { isCtxStale: () => isCtxStale() });
+	// background 注入（U5 接线残项落地）：isActive/startForTool 与 agent_settled 自动触发
+	// 共享同一 session 级互斥容器（RL1），工具路径跳过触发线与独立熔断（SI5）。
+	// 工具已无异步回调（U4 纯触发化），旧 isCtxStale 过渡字段随注入一并退役——代际
+	// 分诊仅剩事件回调内的 guardStaleCtx 消费（闭包内读变量绑定，天然 live）。
+	registerCompactContextTool(pi, {
+		background: { isActive: background.isActive, start: background.startForTool },
+	});
+
+	// ── 手动触发入口（C2 /compact 后台化）：GUI 手动 /compact 的扩展侧命令 ──
+	// taiji runtime 收到 session.compactBackground RPC 后经 client.prompt fire-and-forget
+	// 发 `/__taiji_compact__ <encoded>`（先例 __taiji_bg_reconcile__，session-service）。
+	// `__` 双下划线前缀 = 内部命令（前端 internal-command-filter 过滤不显示）；命令同步
+	// 执行、不进模型、无 turn（pi agent-session _tryExecuteExtensionCommand）。
+	// args 编码契约（与 runtime 发送侧成对）：runtime 侧 encodeURIComponent(customInstructions)
+	// 后拼在命令名后（percent 编码无空格/换行，args = 首空格后原样余串可逆还原；空串 =
+	// 未携带，pi 切分语义 PS-63 实锚 agent-session.js:1604-1608）。
+	// 回执路径三分：启动成功不发通知（GUI 提示由 runtime reply → renderer toast 承载，
+	// 不双投）；false = 后台任务进行中，幂等回执经即时通知通道投递（口径与 compact_context
+	// 工具 busy 回执一致）；抛错 = 非互斥失败（门控拒绝/探测失败/无可压内容），失败文案经
+	// 即时通知通道投递后不再重抛——重抛只进 pi emitError 日志、用户不可见，通知才是用户
+	// 可达的失败呈现（发送失败由投递函数内吞留痕，与其他通知同语义）。两条回执走即时
+	// 形态（sendSmartContextImmediateNotice）：承载的是用户刚敲的 /compact 的即时失败
+	// 事实，nextTurn 的 pending 队列会把它推迟到用户下一条消息后才可见——失败提示与
+	// 触发动作脱钩，且 renderer 受理 toast（「后台压缩已启动」）已先行，延迟到达 = 假成功
+	// 观感；即时形态空闲即达，与受理 toast 形成「受理≠成功、失败独立可见」的完整回执链。
+	pi.registerCommand("__taiji_compact__", {
+		description:
+			"Internal: start a background compaction on demand (taiji runtime manual /compact trigger; args = encodeURIComponent(customInstructions), empty = none)",
+		handler: async (args: string, _ctx: ExtensionCommandContext) => {
+			let customInstructions: string | undefined;
+			if (args.trim() !== "") {
+				try {
+					customInstructions = decodeURIComponent(args.trim());
+				} catch (error) {
+					debugLog(`__taiji_compact__ args decode failed: ${toErrorMessage(error)}`);
+					sendSmartContextImmediateNotice(
+						pi,
+						buildCompactStartFailureNotice(`压缩指引参数解码失败（预期百分号编码）：${toErrorMessage(error)}`),
+						"compact-start-failed",
+					);
+					return;
+				}
+			}
+			let started = false;
+			try {
+				started = background.startForTool(_ctx, customInstructions, "manual");
+			} catch (error) {
+				debugLog(`__taiji_compact__ start failed: ${toErrorMessage(error)}`);
+				sendSmartContextImmediateNotice(pi, buildCompactStartFailureNotice(toErrorMessage(error)), "compact-start-failed");
+				return;
+			}
+			if (!started) {
+				debugLog("__taiji_compact__ busy: background compaction already running (idempotent receipt)");
+				sendSmartContextImmediateNotice(pi, buildCompactBusyNotice(), "compact-busy");
+			}
+		},
+	});
 
 	// ── 阈值提醒（D3/D4）：agent_settled 越档检查 + marker 持久化 + nextTurn 一次性投递 ──
 	pi.on("agent_settled", (_event, ctx) => {
+		// 后台压缩自动触发（D4）：门控/互斥/独立熔断/触发线/准备数据组装判定全部内聚
+		// maybeStart，与下方提醒链路相互独立（触发即后台执行，不阻塞本回调）
+		background.maybeStart(ctx);
+
 		const config = loadSmartContextConfig();
 		const modelId = getCurrentModelId(ctx.model);
 		if (!isGatingActive(config, modelId)) return;
@@ -163,7 +382,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		seedFiredThresholds(ctx);
 
 		const usage = ctx.getContextUsage();
-		if (!usage) return; // R7：tokens 可能 null（压缩后首响应前）——findCrossedThresholds 容错
+		if (!usage) return; // pi 观察级 R7（旧编号，见 compact-handler.ts 头注消歧）：tokens 可能 null（压缩后首响应前）——findCrossedThresholds 容错
 		const crossed = findCrossedThresholds(config.reminderThresholds, usage.tokens, state.firedThresholds);
 		if (crossed.length === 0) return;
 

package/src/notices.ts

@@ -1,5 +1,6 @@
 /**
- * 通知注入唯一出口（D4①：四类通知 nextTurn 化）。
+ * 通知注入唯一出口（D4①：四类通知 nextTurn 化；C1：后台压缩落盘信号即时 append 化；
+ * C2 复审：手动触发失败回执即时可见化）。
  *
  * 四类通知（压缩结果 onComplete / onError、阈值提醒、model_select 跨界与降档两条）从
  * `sendUserMessage(deliverAs:'steer'|'followUp')` 改为 `sendMessage(deliverAs:'nextTurn',
@@ -8,6 +9,17 @@
  * 消息投递跑道」——故事 C 根因：压缩完成后通知 run 与用户消息同时 prompt()，后到者被 pi 以
  * `Agent is already processing` 拒绝。
  *
+ * 落盘信号（C1 分界行实时化）是第五条投递，走另一形态：`sendMessage({triggerTurn:false})`
+ * 无 deliverAs——空闲时 pi 立即 append 并 emit message_start/end（runtime 即时收到
+ * customStart 帧合成对话流分界行），streaming 窗口内挂回合尾（秒级延迟，接受）。
+ *
+ * 手动触发失败回执（compact-start-failed / compact-busy，C2 `__taiji_compact__` 命令路径）
+ * 走同一即时形态但可见（sendSmartContextImmediateNotice）：nextTurn 的 pending 队列在用户
+ * 下一条消息前不可见，而这两条回执承载的是用户刚敲的 /compact 的即时失败事实——延迟到
+ * 下一条消息才出现 = 失败提示与触发动作脱钩（用户已看到「后台压缩已启动」的受理 toast，
+ * 假成功观感）。即时形态空闲即达（pi sendCustomMessage 空闲分支直接 append+emit），
+ * streaming 中挂回合尾（与 C1 信号同窗接受）。
+ *
  * 语义定性（设计 D4「C-ext-19 合规定性」四类两分）：
  * - 阈值提醒 / model_select 两条 = **提醒语义**（与 scheduler 2026-09-15 逐条处理完毕先例同类：
  *   提醒不承载必须必达的结果）；
@@ -20,14 +32,25 @@
  * 注入——pi 内建 overflow/threshold 自动压缩兜底在场，无人在场时上下文可能持续增长。
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	COMPACTION_ENTRY_APPENDED_SOURCE,
+	SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+} from "@zhushanwen/extension-protocol";
 
-/** 通知的 customType（taiji 侧按此识别 system 消息来源；pi TUI display 恒 true）。 */
-export const SMART_CONTEXT_NOTICE_CUSTOM_TYPE = "smart-context";
+import { debugLog } from "./compact-handler.js";
+import type { DroppedReason } from "./compact-handler.js";
+import { formatK } from "./pure.js";
+
+// customType 单源在 extension-protocol（runtime 分诊同源消费），此处 re-export 保持既有
+// import 路径（本扩展历史消费方）不变
+export { SMART_CONTEXT_NOTICE_CUSTOM_TYPE };
 
 /** 通知来源（进 details.source，排障定位用）。 */
 export type SmartContextNoticeSource =
 	| "compact-complete"
 	| "compact-failed"
+	| "compact-busy"
+	| "compact-start-failed"
 	| "threshold-reminder"
 	| "model-switch"
 	| "model-downshift";
@@ -57,3 +80,166 @@ export function sendSmartContextNotice(
 		{ triggerTurn: false, deliverAs: "nextTurn" },
 	);
 }
+
+/**
+ * 注入一条即时可见的 smart-context 通知（失败回执路径，不自起 run）。
+ *
+ * 与 sendSmartContextNotice 的差别只在投递选项：无 deliverAs + `{triggerTurn:false}`——
+ * pi sendCustomMessage 该形态空闲时直接 `_appendCustomMessage`（立即 append + emit，
+ * 不进 `_pendingNextTurnMessages`），streaming 窗口内挂回合尾（`_pendingCustomMessages`
+ * 回合尾 flush）。消费方是「用户刚敲的命令立刻失败」类回执（compact-start-failed /
+ * compact-busy）：即时事实用即时通道，nextTurn 的「常驻至下一条用户消息」对它是延迟
+ * 而非必达（消息内容与触发动作脱钩）。字段载荷（customType/display/details.source）
+ * 与 nextTurn 形态完全一致——runtime 分诊不区分投递路径。
+ */
+export function sendSmartContextImmediateNotice(
+	pi: Pick<ExtensionAPI, "sendMessage">,
+	text: string,
+	source: SmartContextNoticeSource,
+): void {
+	pi.sendMessage(
+		{
+			customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+			content: text,
+			display: true,
+			details: { source },
+		},
+		{ triggerTurn: false },
+	);
+}
+
+/** 完成通知数据（U5：D6 完成通知的组装输入；token 数为压缩前后口径）。 */
+export interface CompactCompleteNoticeInput {
+	/** 本次压缩的模式（与生成入口判定同源）。 */
+	mode: "same-model" | "cross-model";
+	/** 压缩前上下文 token（触发快照口径）。 */
+	tokensBefore: number;
+	/** 压缩后上下文 token（estimatedTokensAfter 或「保留段 + 摘要」估算，接线层定口径）。 */
+	tokensAfter: number;
+}
+
+/**
+ * 后台压缩完成通知文案（D6：落盘成功后投递，含压缩前后 token 数与模式）。
+ * 「下一条消息起生效」语义登记 GL3/AS3：投影按请求现算，无需用户操作。
+ */
+export function buildCompactCompleteNotice(input: CompactCompleteNoticeInput): string {
+	return (
+		`[smart-context] 后台压缩完成（${input.mode} 模式）：上下文 ` +
+		`${formatK(input.tokensBefore)} → ${formatK(input.tokensAfter)} tokens。` +
+		`下一条消息起将使用压缩后的上下文。`
+	);
+}
+
+/** 失败通知数据（U5：D6 失败通知的组装输入；条件 = 校验放弃/探测失败/生成空结果/异常/熔断）。 */
+export interface CompactFailureNoticeInput {
+	/** 失败终局（dropped 涵盖落盘兜底校验放弃与 appendCompaction 探测失败两类）。 */
+	outcome: "inflated" | "dropped" | "empty" | "error";
+	/**
+	 * outcome=dropped 时的细分原因（compact-handler 透传）：按实际终局分文案——
+	 * preempted / session-mismatch 下上下文已被另一轮压缩或新会话改变，不得声称「上下文保持原样」。
+	 */
+	droppedReason?: DroppedReason;
+	/** outcome=error 时的错误消息。 */
+	error?: string;
+	/** 失败类终局的独立熔断计数（文案展示用）。 */
+	failureStreak?: number;
+	/** 递增后计数达到熔断阈值：自动触发已暂停（工具路径不受影响，SI5）。 */
+	circuitBreakerOpen?: boolean;
+}
+
+/**
+ * 失败原因行（按终局给短语与恢复动作）。「上下文保持原样」不是各终局共同的不变量——
+ * 只对确认未触碰上下文的终局声明（inflated / empty / error / persist-unavailable）；
+ * preempted / session-mismatch 下上下文已被另一轮压缩或新会话改变，文案如实描述发生了什么。
+ */
+function compactFailureReasonLine(input: CompactFailureNoticeInput): string {
+	switch (input.outcome) {
+		case "inflated":
+			return "后台压缩已放弃：生成的摘要未缩小上下文（无净收益），结果未落盘，上下文保持原样。";
+		case "dropped":
+			switch (input.droppedReason) {
+				case "preempted":
+					return "后台压缩已放弃：另一轮压缩已先行落盘，上下文已使用该较新的压缩结果，本次结果未再写入。";
+				case "session-mismatch":
+					return "后台压缩已放弃：生成期间会话已切换，本次结果未落盘；当前会话的上下文不受本次压缩影响。";
+				case "persist-unavailable":
+					return "后台压缩已放弃：会话存储的压缩写入接口不可用，结果未落盘，上下文保持原样。";
+				default:
+					return "后台压缩已放弃：生成期间会话状态已变化，结果未落盘。";
+			}
+		case "empty":
+			return "后台压缩失败：摘要生成未返回结果，上下文保持原样。";
+		case "error":
+			return `后台压缩失败：${input.error ?? "未知错误"}，上下文保持原样。`;
+	}
+}
+
+/**
+ * 后台压缩进行中幂等回执文案（C2 手动触发入口：`__taiji_compact__` 命令在后台任务
+ * 进行中再触发时的用户回执）。口径与 compact_context 工具的 busy 回执逐字一致（同一
+ * 互斥事实，两入口共用一份事实描述）。
+ */
+export function buildCompactBusyNotice(): string {
+	return "后台压缩进行中，本次请求已并入该任务，无需重复触发。压缩在后台进行，你可以继续任何工作；完成后会收到一条结果消息。";
+}
+
+/**
+ * 后台压缩启动失败文案（C2 手动触发入口：`__taiji_compact__` 命令路径的非互斥失败
+ * ——门控拒绝 / appendCompaction 探测失败 / 无可压内容 / 参数解码失败）。reason 透传
+ * startForTool 的抛错文案（自身已含原因与恢复动作，此处只加前缀定位来源）。
+ */
+export function buildCompactStartFailureNotice(reason: string): string {
+	return `[smart-context] 后台压缩未启动：${reason}`;
+}
+
+/**
+ * 后台压缩失败通知文案（D6：失败不静默）。熔断达到阈值时附加一行说明（同一次失败
+ * 只投一条通知，熔断语义并入该条——不重复投递）。
+ */
+export function buildCompactFailureNotice(input: CompactFailureNoticeInput): string {
+	const lines = [`[smart-context] ${compactFailureReasonLine(input)}`];
+	if (input.circuitBreakerOpen) {
+		lines.push(
+			`已连续失败 ${input.failureStreak ?? "?"} 次，本会话自动触发压缩已暂停（compact_context 工具仍可手动调用）。`,
+		);
+	} else if (input.outcome === "empty" || input.outcome === "error") {
+		lines.push("可稍后重试（调用 compact_context），或忽略本轮继续工作。");
+	}
+	return lines.join("\n");
+}
+
+/**
+ * 后台压缩落盘信号（C1 分界行实时化）：落盘成功这个事实点的即时通知。消费方是 taiji
+ * runtime（分诊 customType + details.source 命中后取 compaction entry 合成对话流分界行帧），
+ * 不是用户——content 空串 + display:false（对话流不渲染，details 是信号唯一载荷）。
+ * LLM 上下文路径（实况链）：该 custom_message entry 进 pi 的上下文投影，convertToLlm 将
+ * role:"custom" 无条件转 user 消息（不读 display）——content 空串即映射为空文本 text block，
+ * provider transform 层过滤空 text block（不耗 token、不报错），对模型净效果为零。这是
+ * 空串 content 的结构性无害，不是「不进上下文」的协议保证——content 若非空即对模型可见。
+ * 投递形态 `{triggerTurn:false}` 无 deliverAs：空闲时 pi 立即 append 并 emit
+ * message_start/end（agent-session sendCustomMessage 末段分支），runtime 即时收到 customStart
+ * 帧；streaming 窗口内挂回合尾（秒级延迟，接受并登记）。
+ *
+ * 失败语义（与通知投递失败同款，dmg-r1-2）：同步抛错只 debugLog 留痕、不上抛——调用点
+ * （BackgroundPersistCallbacks.onPersisted）在 persistBackgroundCompaction 的 appendCompaction
+ * try 块内，上抛会把已落盘的压缩改记失败并无谓递增熔断计数（成败事实被信号失败篡改）。
+ * 信号丢失的最坏结果 = 分界行退回「重开会话才可见」的原状，压缩本身不受影响。
+ */
+export function sendCompactionPersistSignal(
+	pi: Pick<ExtensionAPI, "sendMessage">,
+	compactionId: string | undefined,
+): void {
+	try {
+		pi.sendMessage(
+			{
+				customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+				content: "",
+				display: false,
+				details: { source: COMPACTION_ENTRY_APPENDED_SOURCE, compactionId },
+			},
+			{ triggerTurn: false },
+		);
+	} catch (error) {
+		debugLog(`compaction persist signal delivery failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}

package/src/pure.ts

@@ -28,6 +28,9 @@ const DEFAULT_REMINDER_THRESHOLDS: readonly number[] = [
 	DEFAULT_REMINDER_THRESHOLD_TIER_3_TOKENS,
 ];
 
+/** 后台压缩触发线默认值（窗口 90%，用户裁决 2026-10-31；设计 D4）。 */
+export const DEFAULT_AUTO_COMPACT_THRESHOLD_RATIO = 0.9;
+
 /** smart-context 磁盘配置（<agentDir>/config/smart-context-ext-config.json）。 */
 export interface SmartContextConfig {
 	enabled: boolean;
@@ -37,6 +40,11 @@ export interface SmartContextConfig {
 	reminderThresholds: number[];
 	/** 排除模型列表：完整 provider/modelId 精准等值匹配（D5）。 */
 	excludedModels: string[];
+	/**
+	 * 后台压缩触发线：相对当前模型窗口的用量百分比（tokens 越过 ratio×窗口时触发，
+	 * 设计 D4）。与 reminderThresholds 三档提醒是两个独立行为各自配置。
+	 */
+	autoCompactThresholdRatio: number;
 }
 
 export const DEFAULT_SMART_CONTEXT_CONFIG: SmartContextConfig = {
@@ -44,6 +52,7 @@ export const DEFAULT_SMART_CONTEXT_CONFIG: SmartContextConfig = {
 	compactModel: { type: "ref", ref: "" },
 	reminderThresholds: [...DEFAULT_REMINDER_THRESHOLDS],
 	excludedModels: [],
+	autoCompactThresholdRatio: DEFAULT_AUTO_COMPACT_THRESHOLD_RATIO,
 };
 
 /**
@@ -51,6 +60,7 @@ export const DEFAULT_SMART_CONTEXT_CONFIG: SmartContextConfig = {
  * - reminderThresholds：过滤非正数 → 升序 → 截 3 档；空数组回退默认
  * - excludedModels：过滤非字符串与不含 "/" 的条目（精准匹配要求完整 provider/modelId）→ 去重
  * - compactModel：ref 非字符串按空串
+ * - autoCompactThresholdRatio：非有限数回默认 0.9；有限数钳制到 [0, 1]
  */
 export function normalizeSmartContextConfig(raw: unknown): SmartContextConfig {
 	const base = DEFAULT_SMART_CONTEXT_CONFIG;
@@ -78,7 +88,13 @@ export function normalizeSmartContextConfig(raw: unknown): SmartContextConfig {
 		),
 	];
 
-	return { enabled, compactModel, reminderThresholds, excludedModels };
+	const rawRatio = r.autoCompactThresholdRatio;
+	const autoCompactThresholdRatio =
+		typeof rawRatio === "number" && Number.isFinite(rawRatio)
+			? Math.min(1, Math.max(0, rawRatio))
+			: base.autoCompactThresholdRatio;
+
+	return { enabled, compactModel, reminderThresholds, excludedModels, autoCompactThresholdRatio };
 }
 
 /**

package/src/reminder.ts

@@ -7,6 +7,8 @@
  * 避免 agent 见提醒就压缩。
  */
 
+import { DEFAULT_COMPACTION_SETTINGS } from "@earendil-works/pi-coding-agent";
+
 import {
 	DEGRADATION_HINT_MIN_COMPACTIONS,
 	formatK,
@@ -14,8 +16,6 @@ import {
 
 /** 百分比换算基数（tokens/contextWindow 比例 → 百分数显示）。 */
 const PERCENT_SCALE = 100;
-/** pi 内建自动压缩触发线的 reserveTokens 默认值（window − 16K）。 */
-const PI_DEFAULT_RESERVE_TOKENS = 16_384;
 
 /**
  * 阈值提醒消息（D3/D4/D4'）：越档信息 + 工具名 + 三条件自查 + 可忽略出口。
@@ -72,7 +72,8 @@ export function buildDownshiftNotice(
 		return null;
 	}
 	if (newWindow >= previousWindow) return null;
-	const triggerLine = newWindow - PI_DEFAULT_RESERVE_TOKENS; // pi 内建触发线（window − reserveTokens 默认值）
+	// pi 内建自动压缩触发线（window − reserveTokens 默认值，权威值经 pi 包导出直读）
+	const triggerLine = newWindow - DEFAULT_COMPACTION_SETTINGS.reserveTokens;
 	if (tokens < triggerLine) return null;
 	return `[smart-context] 当前上下文 ${formatK(tokens)} tokens，已接近新模型窗口上限（${formatK(newWindow)}）。建议尽快压缩（调用 compact_context 或 /compact），否则内建自动压缩将在触线时强制执行。`;
 }