@zhushanwen/pi-smart-context 0.4.4 → 0.5.0

package/src/__tests__/index-compaction-signal.test.ts

@@ -0,0 +1,207 @@
+// src/__tests__/index-compaction-signal.test.ts
+//
+// C1 分界行实时化（feat-compaction-closure）：后台压缩落盘信号在 index.ts 装配点的端到端
+// 回归。信号挂在「落盘成功」事实点（BackgroundPersistCallbacks.onPersisted，携带 entry id），
+// 不在终局回调点——分界行帧的数据源（compactionId）只有落盘现场有。
+//
+// 本文件锁三件事：
+//   ① validated 终局（persist 成功）→ sendMessage 落盘信号恰一条（形态见 notices 单测，
+//      此处锁装配链路真正发出 + 先于完成通知）；
+//   ② 失败终局（生成空结果）→ 无落盘信号（失败通知照旧，不混入信号帧判据）；
+//   ③ 信号投递同步抛错 → 不改写压缩成败（完成通知照常投递，dmg-r1-2 同语义）。
+//
+// 信号→分界行帧的后半段（runtime 分诊合成）由 runtime 包单测覆盖，两端以 extension-protocol
+// 词表常量对齐（值漂移结构性不可能）。
+
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
+// 工具注册短路（本文件只测后台压缩信号链路装配；工具装配由 index-generation.test.ts 覆盖）
+vi.mock("../tool.js", () => ({
+	registerCompactContextTool: vi.fn(),
+}));
+
+// same-model 生成替换（不触网；成功/空结果按用例改写）
+const { callSameModelCompactionMock } = vi.hoisted(() => ({
+	callSameModelCompactionMock: vi.fn(),
+}));
+vi.mock("../llm.js", () => ({
+	callSameModelCompaction: callSameModelCompactionMock,
+	projectTools: (tools: unknown[]) => tools.map((t) => ({ name: (t as { name: string }).name })),
+}));
+
+// 配置冻结（不随本机 ~/.taiji 配置漂移）：默认基底（enabled + 0.9 触发线）
+vi.mock("../pure.js", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("../pure.js")>();
+	return {
+		...actual,
+		loadSmartContextConfig: () => actual.normalizeSmartContextConfig({}),
+	};
+});
+
+import { COMPACTION_ENTRY_APPENDED_SOURCE, SMART_CONTEXT_NOTICE_CUSTOM_TYPE } from "@zhushanwen/extension-protocol";
+
+import smartContextExtension from "../index.js";
+
+/** 最小 fake pi：本文件消费 on / sendMessage / getAllTools（same-mode 生成投影工具清单）。 */
+function createMockPi(): { pi: ExtensionAPI; events: Map<string, (...args: unknown[]) => void>; sendMessage: ReturnType<typeof vi.fn> } {
+	const events = new Map<string, (...args: unknown[]) => void>();
+	const sendMessage = vi.fn();
+	const pi = {
+		registerTool: vi.fn(), registerCommand: vi.fn(),
+		getAllTools: () => [],
+		on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
+		sendMessage,
+	} as unknown as ExtensionAPI;
+	return { pi, events, sendMessage };
+}
+
+const BIG = "x".repeat(30_000);
+
+function makeUserEntry(id: string, parentId: string | null): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp: new Date(0).toISOString(),
+		message: { role: "user", content: BIG, timestamp: 0 },
+	} as SessionEntry;
+}
+
+function makeAssistantEntry(id: string, parentId: string | null): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp: new Date(0).toISOString(),
+		message: {
+			role: "assistant",
+			content: [{ type: "text", text: BIG }],
+			api: "openai-completions",
+			provider: "zai",
+			model: "glm",
+			usage: {
+				input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: 0,
+		},
+	} as SessionEntry;
+}
+
+/** 触发行情上下文（190k/200k > 0.9 线；entries 3 轮足够切出被压段）。 */
+function makeCtx(entries: SessionEntry[], tokens = 190_000): ExtensionContext {
+	return {
+		model: { provider: "zai", id: "glm" },
+		getSystemPrompt: () => "sys",
+		getContextUsage: () => ({ tokens, contextWindow: 200_000, percent: null }),
+		sessionManager: {
+			getSessionId: () => "s1",
+			getSessionFile: () => "/tmp/s1.jsonl",
+			getEntries: () => entries,
+			appendCompaction: vi.fn(() => "entry-persisted"),
+		},
+	} as unknown as ExtensionContext;
+}
+
+function fireSessionStart(mock: ReturnType<typeof createMockPi>, ctx: ExtensionContext): void {
+	mock.events.get("session_start")!({ type: "session_start", reason: "startup" }, ctx);
+}
+
+function settle(mock: ReturnType<typeof createMockPi>, ctx: ExtensionContext): void {
+	mock.events.get("agent_settled")!({ type: "agent_settled" }, ctx);
+}
+
+/** 信号帧判据（details.source 双判据的扩展侧写点）。 */
+function isPersistSignal(call: unknown[]): boolean {
+	const [message] = call as [{ customType?: string; details?: { source?: string } }];
+	return message?.customType === SMART_CONTEXT_NOTICE_CUSTOM_TYPE
+		&& message?.details?.source === COMPACTION_ENTRY_APPENDED_SOURCE;
+}
+
+describe("C1: 后台压缩落盘信号装配（validated 事实点发出）", () => {
+	beforeEach(() => {
+		callSameModelCompactionMock.mockReset();
+	});
+
+	it("persist 成功 → 信号恰一条（compactionId=appendCompaction 返回值）+ 先于完成通知（nextTurn）", async () => {
+		callSameModelCompactionMock.mockResolvedValue({ ok: true, text: "bg summary", usage: { input: 1, output: 2 } });
+		const mock = createMockPi();
+		const entries = [makeUserEntry("e1", null), makeAssistantEntry("e2", "e1"), makeUserEntry("e3", "e2"), makeAssistantEntry("e4", "e3"), makeUserEntry("e5", "e4")];
+		smartContextExtension(mock.pi);
+		const ctx = makeCtx(entries);
+		fireSessionStart(mock, ctx);
+
+		settle(mock, ctx);
+		// 后台任务落盘段全微任务：等信号帧出现（完成通知随后，nextTurn 投递）
+		await vi.waitFor(() => {
+			expect(mock.sendMessage.mock.calls.filter(isPersistSignal)).toHaveLength(1);
+		});
+
+		const signal = mock.sendMessage.mock.calls.find(isPersistSignal)!;
+		const [message, options] = signal as [{ customType: string; content: string; display: boolean; details: { compactionId?: string } }, unknown];
+		expect(message.customType).toBe(SMART_CONTEXT_NOTICE_CUSTOM_TYPE);
+		expect(message.display).toBe(false);
+		expect(message.details.compactionId).toBe("entry-persisted");
+		// 空闲投递：无 deliverAs（pi 立即 append + emit，runtime 即时收 customStart 帧）
+		expect(options).toEqual({ triggerTurn: false });
+		// 完成通知（D6 既有语义）在信号之后照常投递，两条互不替代
+		await vi.waitFor(() => {
+			expect(mock.sendMessage.mock.calls.length).toBeGreaterThanOrEqual(2);
+		});
+		const notice = mock.sendMessage.mock.calls.find((call) => !isPersistSignal(call));
+		expect(notice).toBeDefined();
+		expect((notice as [{ details?: { source?: string } }])[0].details?.source).toBe("compact-complete");
+	});
+
+	it("生成空结果（empty 终局）→ 无落盘信号（失败通知照旧）", async () => {
+		callSameModelCompactionMock.mockResolvedValue({ ok: false, text: "", error: "boom" });
+		const mock = createMockPi();
+		const entries = [makeUserEntry("e1", null), makeAssistantEntry("e2", "e1"), makeUserEntry("e3", "e2"), makeAssistantEntry("e4", "e3"), makeUserEntry("e5", "e4")];
+		smartContextExtension(mock.pi);
+		const ctx = makeCtx(entries);
+		fireSessionStart(mock, ctx);
+
+		settle(mock, ctx);
+		await vi.waitFor(() => {
+			expect(mock.sendMessage.mock.calls.length).toBeGreaterThanOrEqual(1);
+		});
+
+		expect(mock.sendMessage.mock.calls.filter(isPersistSignal)).toHaveLength(0);
+		const only = mock.sendMessage.mock.calls[0] as [{ details?: { source?: string } }];
+		expect(only[0].details?.source).toBe("compact-failed");
+	});
+
+	it("信号投递同步抛错 → 不改写压缩成败（完成通知照常投递）", async () => {
+		callSameModelCompactionMock.mockResolvedValue({ ok: true, text: "bg summary", usage: { input: 1, output: 2 } });
+		const mock = createMockPi();
+		const entries = [makeUserEntry("e1", null), makeAssistantEntry("e2", "e1"), makeUserEntry("e3", "e2"), makeAssistantEntry("e4", "e3"), makeUserEntry("e5", "e4")];
+		smartContextExtension(mock.pi);
+		const ctx = makeCtx(entries);
+		fireSessionStart(mock, ctx);
+		// 信号发送点同步抛错：onPersisted 在 appendCompaction try 块内，上抛会把已落盘
+		// 的压缩改记失败（递增点③）——内吞后任务应仍走 validated 终局
+		mock.sendMessage.mockImplementation((message: { details?: { source?: string } }) => {
+			if (message?.details?.source === COMPACTION_ENTRY_APPENDED_SOURCE) throw new Error("signal boom");
+		});
+
+		settle(mock, ctx);
+		await vi.waitFor(() => {
+			// 信号抛错被内吞后任务仍走 validated 终局：完成通知照常投递，且不产生失败通知
+			//（error 终局会经递增点③改投 compact-failed——成败事实被信号失败篡改的回归形态）
+			const sources = mock.sendMessage.mock.calls.map((call) => (call[0] as { details?: { source?: string } }).details?.source);
+			expect(sources).toContain("compact-complete");
+			expect(sources).not.toContain("compact-failed");
+		});
+	});
+});

package/src/__tests__/index-generation.test.ts

@@ -1,17 +1,14 @@
 // src/__tests__/index-generation.test.ts
 //
-// G1 装配级测试（crash-resilience D1，参照 scheduler __tests__/index-generation.test.ts 形态）：
-// index.ts 装配点向 registerCompactContextTool 注入的 deps.isCtxStale 必须是 live 绑定
-// wrapper（() => isCtxStale()）——registerCompactContextTool 在 factory 体同步执行，简写
-// 属性 { isCtxStale } 会把该行时刻的初始 () => false 快照进 deps 对象，session_start
-// handler 内的重新赋值不回写已构造对象 → compact onComplete/onError（E1 实锤崩溃点）
-// 检查的前置代际检查恒不生效，stale 分诊 100% 退化为 PS-30 文案兜底。
+// U5 工具接线装配回归：index.ts 注册点向 registerCompactContextTool 注入 deps.background
+// （BackgroundCompactionControls 契约：isActive/start），工具路径与 agent_settled 自动
+// 触发共享同一 session 级互斥容器（RL1）——未注入时工具 execute 在门控与阈值检查后抛
+// 「后台压缩未接线」（fail-fast，tool.test.ts 覆盖），本文件守住注册点真的注入了。
 //
-// 可区分快照 vs live 的唯一拓扑是 factory 重跑（生产主路径：pi 每次 session 替换
-// newSession/fork/switchSession 都重跑 factory 函数体，loader.ts extensionCache 只缓存
-// factory 函数对象）：同闭包内 fire session_start 后本闭包恒是当前代（isCtxStale 读到
-// false，与快照实现值不可区分）；只有第一代 deps 在第二代 session_start 递增模块级
-// sessionGeneration 后必须翻 true——快照实现在此恒 false，正是生产失效路径。
+// 本文件前身是 G1 deps.isCtxStale live 绑定装配回归：compact_context 纯触发化（U4）后
+// 工具不再持有异步回调（旧 ctx.compact onComplete/onError 路径删除），isCtxStale 过渡
+// 字段随 U5 注入 background 一并退役——代际分诊仅剩事件回调内的 guardStaleCtx 消费
+// （闭包内读变量绑定，天然 live），无快照风险点，故该回归对象消亡、本文件改守注入契约。
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -27,11 +24,14 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
 }));
 
 // 装配捕获：mock tool.js，逐次登记 index.ts 传入的 deps（同 scheduler 捕获 runtime 构造第三参）
+interface CapturedDeps {
+	background?: { isActive: () => boolean; start: (ctx: ExtensionContext, customInstructions?: string) => boolean };
+}
 const { registerCompactContextToolCalls } = vi.hoisted(() => ({
-	registerCompactContextToolCalls: [] as Array<{ deps?: { isCtxStale?: () => boolean } }>,
+	registerCompactContextToolCalls: [] as Array<{ deps?: CapturedDeps }>,
 }));
 vi.mock("../tool.js", () => ({
-	registerCompactContextTool: (_pi: unknown, deps?: { isCtxStale?: () => boolean }) => {
+	registerCompactContextTool: (_pi: unknown, deps?: CapturedDeps) => {
 		registerCompactContextToolCalls.push({ deps });
 	},
 }));
@@ -45,61 +45,56 @@ function createMockPi(): {
 } {
 	const events = new Map<string, (...args: unknown[]) => void>();
 	const pi = {
-		registerTool: vi.fn(),
+		registerTool: vi.fn(), registerCommand: vi.fn(),
 		on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
 		sendMessage: vi.fn(),
 	} as unknown as ExtensionAPI;
 	return { pi, events };
 }
 
-/** 触发 session_start（handler 只更新模块级代数与闭包状态，ctx 不被读取）。 */
+/** 触发 session_start（handler 重建 session 级闭包状态，ctx 仅 seed 用——空 entries 安全）。 */
 function fireSessionStart(events: Map<string, (...args: unknown[]) => void>): void {
 	const sessionStart = events.get("session_start");
 	expect(sessionStart).toBeDefined();
 	sessionStart!({ type: "session_start" }, {} as ExtensionContext);
 }
 
-describe("G1: compact 工具 deps.isCtxStale live 绑定（crash-resilience D1 装配回归）", () => {
+describe("U5: 工具注册 background 契约注入（接线残项落地）", () => {
 	beforeEach(() => {
 		registerCompactContextToolCalls.length = 0;
 	});
 
-	it("factory 同步构造 deps：注入的是函数，首个 session_start 前恒 false（安全默认），fire 后本闭包为当前代", () => {
+	it("deps.background 注入且 isActive/start 均为函数；isCtxStale 过渡字段不再传", () => {
 		const { pi, events } = createMockPi();
 		smartContextExtension(pi);
 		expect(registerCompactContextToolCalls).toHaveLength(1);
-		const isCtxStale = registerCompactContextToolCalls[0]!.deps?.isCtxStale;
-		expect(isCtxStale).toBeTypeOf("function");
-
-		// 首个 session_start 前：无 session，恒 false（安全默认）
-		expect(isCtxStale!()).toBe(false);
+		const background = registerCompactContextToolCalls[0]!.deps?.background;
+		expect(background).toBeDefined();
+		expect(background!.isActive).toBeTypeOf("function");
+		expect(background!.start).toBeTypeOf("function");
+		// 过渡字段退役断言：注册点不得再传 isCtxStale（tool.ts deps 已无该字段）
+		expect("isCtxStale" in (registerCompactContextToolCalls[0]!.deps ?? {})).toBe(false);
 
-		// fire 后本闭包被装配为当前代 → false；同闭包重复 fire（rpc-mode bindExtensions
-		// 重调）后仍为当前代。注意：单闭包拓扑内 live wrapper 与快照实现的返回值同为
-		// false、不可区分——快照 vs live 的回归断言在下方 factory 重跑用例。
+		// 互斥查询可用：装配后（未 fire session_start 亦有初始状态容器）无进行中任务
+		expect(background!.isActive()).toBe(false);
+		// fire 后 controls 仍可用（闭包经 getState 读当前代容器，非快照）
 		fireSessionStart(events);
-		expect(isCtxStale!()).toBe(false);
-		fireSessionStart(events);
-		expect(isCtxStale!()).toBe(false);
+		expect(background!.isActive()).toBe(false);
 	});
 
-	it("factory 重跑：第二次 factory + session_start 后，第一代 deps.isCtxStale 翻 true、第二代 false", () => {
-		// 第一代：独立 factory 执行 + session_start 装配
+	it("factory 重跑（session 替换拓扑）：两代各自拿到独立 controls，均读各自代容器", () => {
 		const first = createMockPi();
 		smartContextExtension(first.pi);
 		fireSessionStart(first.events);
-		const firstIsCtxStale = registerCompactContextToolCalls[0]!.deps!.isCtxStale!;
-		expect(firstIsCtxStale()).toBe(false); // 第一代是当前代
-
-		// 第二代：再次独立执行 factory（模拟 newSession/fork/switchSession 的 factory 重跑，
-		// 新闭包；模块级 sessionGeneration 跨 factory 重跑保留）+ session_start
 		const second = createMockPi();
 		smartContextExtension(second.pi);
 		fireSessionStart(second.events);
 
-		// 核心回归断言：第一代 deps 读到第一代闭包重新赋值后的 isCtxStale，感知换代翻
-		// true（快照实现 = 简写属性 { isCtxStale }，在此恒 false——本用例的回归失败点）
-		expect(firstIsCtxStale()).toBe(true);
-		expect(registerCompactContextToolCalls[1]!.deps!.isCtxStale!()).toBe(false); // 第二代是当前代
+		expect(registerCompactContextToolCalls).toHaveLength(2);
+		const firstBackground = registerCompactContextToolCalls[0]!.deps!.background!;
+		const secondBackground = registerCompactContextToolCalls[1]!.deps!.background!;
+		// 两代 controls 各自可调用且空闲（工厂重跑后旧代任务随旧闭包消亡，isActive 恒 false）
+		expect(firstBackground.isActive()).toBe(false);
+		expect(secondBackground.isActive()).toBe(false);
 	});
 });

package/src/__tests__/index-manual-compact-command.test.ts

@@ -0,0 +1,262 @@
+// src/__tests__/index-manual-compact-command.test.ts
+//
+// C2 /compact 后台化（feat-compaction-closure）：`__taiji_compact__` 内部命令（GUI 手动
+// 压缩的扩展侧触发入口）装配与回执契约。runtime 收到 session.compactBackground RPC 后经
+// client.prompt fire-and-forget 发 `/__taiji_compact__ <encoded>`（session-service），本
+// 文件锁命令 handler 的四件事：
+//   ① 启动成功：经后台管理器 startForTool（manual 来源）启动，不投通知（GUI 提示由
+//      runtime reply → renderer toast 承载，不双投）；
+//   ② customInstructions percent 编码可逆：args = encodeURIComponent 原文（含空格/引号），
+//      解码后透传给压缩生成（input.customInstructions）；
+//   ③ busy 幂等：后台任务进行中再触发 → 即时通知通道投递「进行中已并入」回执（口径与
+//      compact_context 工具 busy 回执一致），不重复启动；
+//   ④ 启动失败（门控拒绝 / args 解码失败）：即时通知通道投递失败文案（含原因），不上抛
+//      （重抛只进 pi emitError 日志，通知才是用户可达呈现）。③④ 走即时投递形态
+//      （sendSmartContextImmediateNotice，无 deliverAs）：回执承载用户刚敲的 /compact 的
+//      即时失败事实，nextTurn pending 队列会推迟到下一条用户消息后才可见——失败提示与
+//      触发动作脱钩（renderer 受理 toast 已先行，延迟到达 = 假成功观感）。
+//
+// runtime 侧契约（RPC handler 受理即 reply / session-service fire-and-forget 投递）由
+// runtime 包单测覆盖；两侧以命令名字面量对齐（跨包字符串契约，改名必须同批）。
+
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
+// 工具注册短路（本文件只测手动命令入口；工具装配由 index-generation.test.ts 覆盖）
+vi.mock("../tool.js", () => ({
+	registerCompactContextTool: vi.fn(),
+}));
+
+// same-model 生成替换（不触网；用例经 resolve/reject/挂起控制任务终局与 busy 窗口）
+const { callSameModelCompactionMock } = vi.hoisted(() => ({
+	callSameModelCompactionMock: vi.fn(),
+}));
+vi.mock("../llm.js", () => ({
+	callSameModelCompaction: callSameModelCompactionMock,
+	projectTools: (tools: unknown[]) => tools.map((t) => ({ name: (t as { name: string }).name })),
+}));
+
+// 配置冻结（不随本机 ~/.taiji 配置漂移）：默认基底（enabled + 0.9 触发线）；门控拒绝
+// 用例经 enable(false) 局部改写
+vi.mock("../pure.js", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("../pure.js")>();
+	let enabledOverride: boolean | undefined;
+	return {
+		...actual,
+		loadSmartContextConfig: () => {
+			const base = actual.normalizeSmartContextConfig(
+				enabledOverride === undefined ? {} : { enabled: enabledOverride },
+			);
+			enabledOverride = undefined;
+			return base;
+		},
+		// 门控拒绝用例的写入口（测试内 import 本模块后调用；生产代码不消费）
+		__testSetEnabledOnce: (v: boolean) => {
+			enabledOverride = v;
+		},
+	};
+});
+
+import { SMART_CONTEXT_NOTICE_CUSTOM_TYPE } from "@zhushanwen/extension-protocol";
+
+import smartContextExtension from "../index.js";
+
+type CommandHandler = (args: string, ctx: ExtensionContext) => Promise<void>;
+
+/** 最小 fake pi：捕获 registerCommand 的 handler（本文件被测对象）。 */
+function createMockPi(): {
+	pi: ExtensionAPI;
+	commands: Map<string, CommandHandler>;
+	sendMessage: ReturnType<typeof vi.fn>;
+} {
+	const commands = new Map<string, CommandHandler>();
+	const sendMessage = vi.fn();
+	const pi = {
+		registerTool: vi.fn(),
+		registerCommand: (name: string, reg: { handler: CommandHandler }) => commands.set(name, reg.handler),
+		getAllTools: () => [],
+		on: vi.fn(),
+		sendMessage,
+	} as unknown as ExtensionAPI;
+	return { pi, commands, sendMessage };
+}
+
+// 单条 120k 字符（≈30k tokens）> keepRecentTokens 保留预算（pi 默认 20k）——保证手动
+// 入口（不受触发线约束，低 tokens 也启动）的被压段非空（buildBackgroundPreparation 判据）。
+const BIG = "x".repeat(120_000);
+
+function makeUserEntry(id: string, parentId: string | null): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp: new Date(0).toISOString(),
+		message: { role: "user", content: BIG, timestamp: 0 },
+	} as SessionEntry;
+}
+
+function makeAssistantEntry(id: string, parentId: string | null): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp: new Date(0).toISOString(),
+		message: {
+			role: "assistant",
+			content: [{ type: "text", text: BIG }],
+			api: "openai-completions",
+			provider: "zai",
+			model: "glm",
+			usage: {
+				input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: 0,
+		} as unknown as SessionEntry["message"],
+	} as SessionEntry;
+}
+
+/** 手动入口不受触发线约束（startForTool 跳过 D4 ratio 判定）——低 tokens 上下文即可启动。 */
+function makeCtx(entries: SessionEntry[], tokens: number | null = 1_000): ExtensionContext {
+	return {
+		model: { provider: "zai", id: "glm" },
+		getSystemPrompt: () => "sys",
+		getContextUsage: () => ({ tokens, contextWindow: 200_000, percent: null }),
+		sessionManager: {
+			getSessionId: () => "s1",
+			getSessionFile: () => "/tmp/s1.jsonl",
+			getEntries: () => entries,
+			appendCompaction: vi.fn(() => "entry-persisted"),
+		},
+	} as unknown as ExtensionContext;
+}
+
+/** 三轮可压行情（与 index-compaction-signal 同款最小 entries 集）。 */
+function makeCompressibleEntries(): SessionEntry[] {
+	return [
+		makeUserEntry("e1", null),
+		makeAssistantEntry("e2", "e1"),
+		makeUserEntry("e3", "e2"),
+	];
+}
+
+async function setup(overrides?: { enabled?: boolean }): Promise<{
+	pi: ReturnType<typeof createMockPi>["pi"];
+	handler: CommandHandler;
+	sendMessage: ReturnType<typeof createMockPi>["sendMessage"];
+}> {
+	const mock = createMockPi();
+	smartContextExtension(mock.pi);
+	const handler = mock.commands.get("__taiji_compact__");
+	expect(handler).toBeDefined();
+	if (overrides?.enabled !== undefined) {
+		const pure = await import("../pure.js") as unknown as { __testSetEnabledOnce: (v: boolean) => void };
+		pure.__testSetEnabledOnce(overrides.enabled);
+	}
+	return { pi: mock, handler: handler!, sendMessage: mock.sendMessage };
+}
+
+/** 通知帧判据（notices 单测锁形态，此处锁装配链路真正发出）。 */
+function noticeCalls(sendMessage: ReturnType<typeof vi.fn>): string[] {
+	return sendMessage.mock.calls
+		.filter((c) => (c[0] as { customType?: string }).customType === SMART_CONTEXT_NOTICE_CUSTOM_TYPE)
+		.map((c) => (c[0] as { content: string }).content);
+}
+
+/** 通知投递选项判据：锁 smart-context 通知的投递形态（即时回执 vs nextTurn 通道）。 */
+function noticeOptions(sendMessage: ReturnType<typeof vi.fn>): unknown[] {
+	return sendMessage.mock.calls
+		.filter((c) => (c[0] as { customType?: string }).customType === SMART_CONTEXT_NOTICE_CUSTOM_TYPE)
+		.map((c) => c[1]);
+}
+
+describe("__taiji_compact__ 命令（C2 手动触发入口）", () => {
+	beforeEach(() => {
+		callSameModelCompactionMock.mockReset();
+		callSameModelCompactionMock.mockResolvedValue({
+			summary: "compressed summary",
+			firstKeptEntryId: "e3",
+			tokensBefore: 30_000,
+			estimatedTokensAfter: 1_000,
+		});
+	});
+
+	it("注册为内部命令（__ 双下划线前缀，前端 internal-command-filter 过滤）", async () => {
+		const { pi } = await setup();
+		expect([...pi.commands.keys()]).toEqual(["__taiji_compact__"]);
+	});
+
+	it("空 args 启动成功：不经通知回执（GUI 提示由 runtime reply → renderer 承载）", async () => {
+		const { handler, sendMessage } = await setup();
+		await handler("", makeCtx(makeCompressibleEntries()));
+		// 启动成功不投任何 smart-context 通知
+		expect(noticeCalls(sendMessage)).toHaveLength(0);
+		// 手动入口不受触发线约束（startForTool 语义）：低 tokens 上下文照样启动
+		expect(callSameModelCompactionMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("customInstructions percent 解码透传（含空格/引号可逆，烘进摘要指令消息）", async () => {
+		const { handler } = await setup();
+		const instructions = '保留 关键决策 与 "引号" 内容';
+		await handler(encodeURIComponent(instructions), makeCtx(makeCompressibleEntries()));
+		// 生成入参：callSameModelCompaction(ctx, { messages, ... })——customInstructions 经
+		// buildSameModelInstruction 烘进末条指令消息（Additional focus 段），原文逐字可检索
+		const input = callSameModelCompactionMock.mock.calls[0]?.[1] as {
+			messages: Array<{ content: Array<{ text?: string }> }>;
+		};
+		const lastMessage = input.messages.at(-1);
+		const instructionText = lastMessage?.content.map((p) => p.text ?? "").join("");
+		expect(instructionText).toContain(instructions);
+	});
+
+	it("busy 幂等：任务进行中再触发 → 通知通道投递「进行中已并入」回执，不重复启动", async () => {
+		const { handler, sendMessage } = await setup();
+		// 第一发：生成挂起（任务 active）
+		let release!: (v: unknown) => void;
+		callSameModelCompactionMock.mockImplementationOnce(
+			() => new Promise((resolve) => { release = resolve }),
+		);
+		await handler("", makeCtx(makeCompressibleEntries()));
+		expect(callSameModelCompactionMock).toHaveBeenCalledTimes(1);
+		// 第二发：busy 回执（口径与 compact_context 工具 busy 回执逐字一致）
+		await handler("", makeCtx(makeCompressibleEntries()));
+		const notices = noticeCalls(sendMessage);
+		expect(notices).toHaveLength(1);
+		expect(notices[0]).toContain("后台压缩进行中");
+		expect(notices[0]).toContain("已并入该任务");
+		// busy 回执走即时投递（无 deliverAs，空闲即达不进 nextTurn pending 队列）
+		expect(noticeOptions(sendMessage)[0]).toEqual({ triggerTurn: false });
+		expect(callSameModelCompactionMock).toHaveBeenCalledTimes(1); // 未重复启动
+		release({ summary: "s", firstKeptEntryId: "e3", tokensBefore: 30_000 });
+	});
+
+	it("门控关闭（enabled=false）不拦 manual：手动显式命令 = 用户意志，照常启动（门控只拦 auto/tool）", async () => {
+		const { handler, sendMessage } = await setup({ enabled: false });
+		await handler("", makeCtx(makeCompressibleEntries()));
+		// manual 来源跳过 isGatingActive（与旧 pi 原生手动压缩对齐：旧链不受 smart-context
+		// 开关影响）——enabled=false 时照样启动，无失败通知
+		expect(callSameModelCompactionMock).toHaveBeenCalledTimes(1);
+		expect(noticeCalls(sendMessage)).toHaveLength(0);
+	});
+
+	it("args 解码失败（非法 percent 编码）→ 即时通知通道失败文案（协议异常可操作呈现）", async () => {
+		const { handler, sendMessage } = await setup();
+		await handler("%zz-not-percent", makeCtx(makeCompressibleEntries()));
+		const notices = noticeCalls(sendMessage);
+		expect(notices).toHaveLength(1);
+		expect(notices[0]).toContain("后台压缩未启动");
+		expect(notices[0]).toContain("解码失败");
+		expect(noticeOptions(sendMessage)[0]).toEqual({ triggerTurn: false });
+		expect(callSameModelCompactionMock).not.toHaveBeenCalled();
+	});
+});

package/src/__tests__/index-reminder-delivery.test.ts

@@ -65,7 +65,7 @@ function createMockPi(): MockPi {
 	const sendUserMessage = vi.fn();
 	const appendEntry = vi.fn();
 	const pi = {
-		registerTool: vi.fn(),
+		registerTool: vi.fn(), registerCommand: vi.fn(),
 		on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
 		sendMessage,
 		sendUserMessage,