@zhushanwen/pi-smart-context 0.3.0 → 0.3.2

package/README.md

@@ -8,15 +8,23 @@
 - **双模式生成接管**（`session_before_compact`，覆盖工具 / `/compact` / 内建 auto 三条路径）：
   - same-model：完整原始上下文 + 会话原 system prompt + tools + 末尾追加压缩指令——前缀缓存全命中，成本≈增量指令+输出，且模型看全量上下文（质量上限最高）
   - cross-model：调用 pi 原生 `compact()` 仅换模型与凭证——split-turn / fileOps / previousSummary 原生组装
-- **3 档阈值提醒**（默认 200K/400K/600K）：`agent_settled` 越档检查，每档一次、多档合并、压缩后重置，followUp 投递；措辞是数据投递不是指令
+- **3 档阈值提醒**（默认 400K/500K/600K）：`agent_settled` 越档检查，每档一次、多档合并、压缩后重置，followUp 投递；措辞是数据投递不是指令
 - **排除模型**（精准 `provider/modelId` 匹配）：工具拒绝 + 不提醒 + 回落 pi 原生生成；切换跨界时注入一条可用性通知，downshift（切小窗模型将触线）时建议先压缩
 - **健壮性**：摘要收缩校验、max-tokens 截断 fail-closed、接管失败 3 次熔断、transcript 回查指针、压缩后最近文件内容重注入（≤5 文件/50K）、多轮压缩降智提示
 - **subagent 进程**自动静默（`PI_SUBAGENT_ROOT_SESSION_ID` 标记）
 
-## 配置
+## 行为门控
+
+| 状态 | 工具 execute | 阈值提醒 | 压缩生成接管 |
+|---|---|---|---|
+| enabled，模型未排除 | 放行（低于最低档阈值时拒绝并返回用量建议） | 生效 | 生效（按双模式判定） |
+| enabled，模型命中排除列表 | 拒绝（返回原因） | 跳过 | 跳过（回落 pi 原生生成） |
+| enabled=false | 拒绝（"可在设置页开启"） | 跳过 | 跳过（回落 pi 原生） |
+| compactModel 未配置/无效 | 放行（same-model 不依赖该配置） | 生效 | same-model 生效；cross-model 回退当前模型，压缩不失败 |
+| 模型切换跨界（model_select） | 常驻不变 | 注入一条可用性变化通知（仅跨界时） | 按新模型即时重判 |
 
-`<agentDir>/config/smart-context-ext-config.json`（读时热加载）。schema 与示例见 `skills/smart-context-ext-config/SKILL.md`。xyz-agent 桌面端在设置页（系统 → 智能上下文压缩）可视化配置。
+行为正确性由 execute / handler 现场校验兜底，每次事件回调重新读配置（热加载，改完下一 turn 生效，无需重启）。
 
-## 设计文档
+## 配置
 
-`docs/extensions/smart-context/design.md`（xyz-agent 仓库）——决策依据、探针记录、验收场景。
+`<agentDir>/config/smart-context-ext-config.json`（读时热加载）。schema 与示例见 `skills/smart-context-ext-config/SKILL.md`。taiji 桌面端在设置页（系统 → 智能上下文压缩）可视化配置。

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@zhushanwen/pi-smart-context",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "main": "index.ts",
-  "xyz-agent": {
+  "taiji": {
     "role": "universal",
     "startupConfig": [
       {
@@ -15,8 +15,8 @@
             "ref": ""
           },
           "reminderThresholds": [
-            200000,
             400000,
+            500000,
             600000
           ],
           "excludedModels": []
@@ -36,9 +36,9 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.6.0",
-    "@zhushanwen/pi-llm-shared": "0.7.0"
+    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/pi-extension-logger": "0.6.1",
+    "@zhushanwen/pi-llm-shared": "0.8.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

package/skills/smart-context-ext-config/SKILL.md

@@ -15,7 +15,7 @@ description: "配置 @zhushanwen/pi-smart-context（智能上下文压缩：agen
 
 ## 配置文件
 
-路径：`<agentDir>/config/smart-context-ext-config.json`（`<agentDir>` = `getAgentDir()`，默认 `~/.pi/agent`，xyz-agent 环境 `~/.xyz-agent/pi/agent`；`PI_CODING_AGENT_DIR` 可覆盖）。
+路径：`<agentDir>/config/smart-context-ext-config.json`（`<agentDir>` = `getAgentDir()`，默认 `~/.pi/agent`，taiji 环境 `~/.taiji/agent`；`PI_CODING_AGENT_DIR` 可覆盖）。
 
 ### Schema
 
@@ -23,7 +23,7 @@ description: "配置 @zhushanwen/pi-smart-context（智能上下文压缩：agen
 |---|---|---|---|
 | `enabled` | boolean | `true` | 总开关 |
 | `compactModel` | `{type:"ref", ref:string}` | `{type:"ref", ref:""}` | 压缩模型（完整 `provider/modelId`）。`ref` 为空 = 跟随当前会话模型（same-model 模式）；等于当前模型同样进 same-model 模式 |
-| `reminderThresholds` | `number[]` | `[200000, 400000, 600000]` | 3 档提醒阈值（token 绝对数，升序） |
+| `reminderThresholds` | `number[]` | `[400000, 500000, 600000]` | 3 档提醒阈值（token 绝对数，升序） |
 | `excludedModels` | `string[]` | `[]` | 排除模型列表，完整 `provider/modelId` 精准等值匹配（如 `"deepseek/deepseek-chat"`），不做前缀匹配 |
 
 ### 配置示例
@@ -32,7 +32,7 @@ description: "配置 @zhushanwen/pi-smart-context（智能上下文压缩：agen
 {
   "enabled": true,
   "compactModel": { "type": "ref", "ref": "xiaomi-token-plan-cn/mimo-v2.5" },
-  "reminderThresholds": [200000, 400000, 600000],
+  "reminderThresholds": [400000, 500000, 600000],
   "excludedModels": ["deepseek/deepseek-chat"]
 }
 ```
@@ -52,5 +52,5 @@ description: "配置 @zhushanwen/pi-smart-context（智能上下文压缩：agen
 - 压缩回退当前模型：`compactModel.ref` 指向的模型不可用（无凭证/已删）——换可用模型或留空
 - 工具调用被拒「已禁用」/「已排除」：检查 `enabled` 与 `excludedModels`
 - 提醒未出现：`getContextUsage().tokens` 在压缩后首个响应前为 null，属正常（下轮恢复）
-- 连续接管失败 3 次后不再接管：本会话熔断保护，查看 `XYZ_AGENT_DEBUG=1` 日志定位失败原因
-- 调试：`XYZ_AGENT_DEBUG=1` 后看 `[smart-context]` 前缀日志（`~/.pi/agent/logs/`）
+- 连续接管失败 3 次后不再接管：本会话熔断保护，查看 `TAIJI_AGENT_DEBUG=1` 日志定位失败原因
+- 调试：`TAIJI_AGENT_DEBUG=1` 后看 `[smart-context]` 前缀日志（`~/.pi/agent/logs/`）

package/src/__tests__/pure.test.ts

@@ -12,7 +12,6 @@ import {
 	formatK,
 	getCurrentModelId,
 	isGatingActive,
-	isSubagentProcess,
 	isSummaryInflated,
 	normalizeSmartContextConfig,
 	pickMode,
@@ -23,7 +22,7 @@ describe("normalizeSmartContextConfig", () => {
 	it("非对象输入回退默认值", () => {
 		const c = normalizeSmartContextConfig(null);
 		expect(c).toEqual(DEFAULT_SMART_CONTEXT_CONFIG);
-		expect(c.reminderThresholds).toEqual([200_000, 400_000, 600_000]);
+		expect(c.reminderThresholds).toEqual([400_000, 500_000, 600_000]);
 	});
 
 	it("阈值过滤非正数并升序、截 3 档；空数组回退默认", () => {
@@ -31,7 +30,7 @@ describe("normalizeSmartContextConfig", () => {
 		expect(c.reminderThresholds).toEqual([100_000, 200_000, 300_000]);
 
 		const c2 = normalizeSmartContextConfig({ reminderThresholds: [] });
-		expect(c2.reminderThresholds).toEqual([200_000, 400_000, 600_000]);
+		expect(c2.reminderThresholds).toEqual([400_000, 500_000, 600_000]);
 	});
 
 	it("excludedModels 只留含 / 的字符串条目并去重（精准匹配要求完整 provider/modelId）", () => {
@@ -173,9 +172,6 @@ describe("estimateShadowedTokens 口径契约（D2：与 pi estimateTokens 同
 	});
 });
 
-describe("subagent 识别（R6）", () => {
-	it("PI_SUBAGENT_ROOT_SESSION_ID 存在即 subagent", () => {
-		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1" })).toBe(true);
-		expect(isSubagentProcess({})).toBe(false);
-	});
-});
+// [HISTORICAL] subagent 识别（R6）用例已随本地实现删除移除——现行谓词收敛于
+// ext-guards isSubagentProcess（ext-simplify-17 D4），三态与「宁缺勿污」钉值见
+// extensions/shared/ext-guards/src/__tests__/predicates.test.ts。

package/src/__tests__/startup-config-declaration.test.ts

@@ -1,5 +1,5 @@
 /**
- * startupConfig 声明守护测试：断言 package.json `xyz-agent.startupConfig` 声明的
+ * startupConfig 声明守护测试：断言 package.json `taiji.startupConfig` 声明的
  * content 与代码 DEFAULT_SMART_CONTEXT_CONFIG 常量深相等，防止两侧任一改动未同步（漂移）。
  * 机制：runtime 启动序列统一 ensure（extension-startup-config.ts），声明即首建内容。
  *
@@ -13,7 +13,7 @@ import { describe, expect, it } from "vitest";
 
 import { DEFAULT_SMART_CONTEXT_CONFIG } from "../pure.js";
 
-/** package.json `xyz-agent.startupConfig` 声明条目的最小形状（守护断言用）。 */
+/** package.json `taiji.startupConfig` 声明条目的最小形状（守护断言用）。 */
 interface StartupConfigEntry {
 	path: string;
 	content: unknown;
@@ -21,11 +21,11 @@ interface StartupConfigEntry {
 
 const pkg = JSON.parse(
 	readFileSync(join(fileURLToPath(import.meta.url), "../../../package.json"), "utf-8"),
-) as { "xyz-agent"?: { startupConfig?: StartupConfigEntry[] } };
+) as { "taiji"?: { startupConfig?: StartupConfigEntry[] } };
 
 describe("startupConfig 声明守护", () => {
 	it("声明 content 与代码 DEFAULT_SMART_CONTEXT_CONFIG 深相等", () => {
-		const entry = pkg["xyz-agent"]?.startupConfig?.find(
+		const entry = pkg["taiji"]?.startupConfig?.find(
 			(e: StartupConfigEntry) => e.path === "config/smart-context-ext-config.json",
 		);
 		expect(entry).toBeDefined();

package/src/__tests__/tool.test.ts

@@ -38,7 +38,7 @@ function makePi(): { pi: ExtensionAPI & { sendUserMessage: ReturnType<typeof vi.
 function makeCtx(compactImpl?: (options: CompactOpts) => void): ExtensionContext {
 	return {
 		model: { provider: "zai", id: "glm" },
-		getContextUsage: () => ({ tokens: 250_000, contextWindow: 1_000_000 }),
+		getContextUsage: () => ({ tokens: 450_000, contextWindow: 1_000_000 }),
 		sessionManager: { getEntries: () => [] },
 		compact: compactImpl ?? ((options: CompactOpts) => {
 			options.onComplete({

package/src/compact-handler.ts

@@ -14,6 +14,7 @@
 import { buildSessionContext, compact as nativeCompact, convertToLlm } from "@earendil-works/pi-coding-agent";
 import type { CompactionResult, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { createLogger } from "@zhushanwen/pi-extension-logger";
 import { resolveModel } from "@zhushanwen/pi-llm-shared";
 import { readFileSync } from "node:fs";
@@ -57,7 +58,7 @@ export function createTakeoverState(): TakeoverState {
 /** 统一 logger（@zhushanwen/pi-extension-logger：debug 文件日志 / warn 走 appendEntry 持久化）。 */
 const logger = createLogger("smart-context");
 
-/** 开发调试日志（XYZ_AGENT_DEBUG=1 时写文件，默认 no-op；logging-conventions 统一通道）。 */
+/** 开发调试日志（TAIJI_AGENT_DEBUG=1 时写文件，默认 no-op；logging-conventions 统一通道）。 */
 export function debugLog(message: string): void {
 	logger.debug(message);
 }
@@ -319,7 +320,7 @@ export function createBeforeCompactHandler(
 			return { compaction: result };
 		} catch (error) {
 			state.failStreak += 1;
-			warnLog("takeover error, falling back to native", { error: error instanceof Error ? error.message : String(error) });
+			warnLog("takeover error, falling back to native", { error: toErrorMessage(error) });
 			return {}; // D7 回退
 		}
 	};

package/src/index.ts

@@ -1,7 +1,6 @@
 /**
  * @zhushanwen/pi-smart-context 入口：事件接线 + 门控。
  *
- * 设计文档：docs/extensions/smart-context/design.md
  * - session_start：session 级闭包状态重建（规范 Session 隔离：fired 档位/熔断计数不跨 session）
  * - subagent 进程（R6）：不注册工具、不提醒（宁缺勿污）
  * - session_before_compact：双模式接管（compact-handler）
@@ -11,7 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { guardStaleCtx, isSubagentProcess, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 import {
@@ -27,7 +26,6 @@ import {
 	findCrossedThresholds,
 	getCurrentModelId,
 	isGatingActive,
-	isSubagentProcess,
 	loadSmartContextConfig,
 	type EntryLike,
 } from "./pure.js";
@@ -63,7 +61,8 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle）
 	setPiHandle(pi);
 
-	// R6：subagent 子进程不注册工具、不提醒（PI_SUBAGENT_ROOT_SESSION_ID 标记）
+	// R6：subagent 子进程不注册工具、不提醒（宁缺勿污；TAIJI_AGENT_SUBAGENT 标记——
+	// ext-guards isSubagentProcess，ext-simplify-17 D4 重锚）
 	if (isSubagentProcess()) {
 		debugLog("subagent process detected, staying inert");
 		return;

package/src/llm.ts

@@ -14,6 +14,7 @@ import { completeSimple } from "@earendil-works/pi-ai/compat";
 import type { Context as LlmContext, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
 import type { Tool as LlmTool, Message, Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 /**
  * ToolInfo → pi-ai Tool 投影：三字段直取。parameters 是 typebox schema（主会话同源对象，
@@ -127,6 +128,6 @@ export async function callSameModelCompaction(
 		const text = resp.content.map(blockText).join("\n").trim();
 		return { ok: true, text, usage: resp.usage, stopReason: resp.stopReason };
 	} catch (error) {
-		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+		return { ok: false, error: toErrorMessage(error) };
 	}
 }

package/src/pure.ts

@@ -2,12 +2,12 @@
  * 纯函数层：配置 schema / 加载 / 门控判定 / 阈值检查 / 摘要后处理。
  *
  * 无副作用（fs 读取经 llm-shared loadConfig 的缓存封装），全部可单测。
- * 设计文档：docs/extensions/smart-context/design.md（D5 门控矩阵 / D6 阈值保护 / D8 配置 schema）。
  */
 
 import { estimateTokens } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "@zhushanwen/pi-ext-guards";
 import type { ModelSelector } from "@zhushanwen/pi-llm-shared";
-import { loadConfig } from "@zhushanwen/pi-llm-shared";
+import { loadConfig, normalizeModelSelector } from "@zhushanwen/pi-llm-shared";
 
 // ──────────────────────── 配置 schema（D8） ────────────────────────
 
@@ -18,9 +18,9 @@ export const CHARS_PER_TOKEN_ESTIMATE = 4;
 /** 提醒阈值最大档数（3 档）。 */
 const MAX_THRESHOLD_TIERS = 3;
 
-/** 3 档提醒阈值默认值（token 绝对数）：200K / 400K / 600K。 */
-const DEFAULT_REMINDER_THRESHOLD_TIER_1_TOKENS = 200_000;
-const DEFAULT_REMINDER_THRESHOLD_TIER_2_TOKENS = 400_000;
+/** 3 档提醒阈值默认值（token 绝对数）：400K / 500K / 600K。 */
+const DEFAULT_REMINDER_THRESHOLD_TIER_1_TOKENS = 400_000;
+const DEFAULT_REMINDER_THRESHOLD_TIER_2_TOKENS = 500_000;
 const DEFAULT_REMINDER_THRESHOLD_TIER_3_TOKENS = 600_000;
 const DEFAULT_REMINDER_THRESHOLDS: readonly number[] = [
 	DEFAULT_REMINDER_THRESHOLD_TIER_1_TOKENS,
@@ -59,13 +59,8 @@ export function normalizeSmartContextConfig(raw: unknown): SmartContextConfig {
 
 	const enabled = typeof r.enabled === "boolean" ? r.enabled : base.enabled;
 
-	const rawModel = typeof r.compactModel === "object" && r.compactModel !== null
-		? (r.compactModel as Record<string, unknown>)
-		: null;
 	const compactModel: ModelSelector =
-		rawModel?.type === "ref" && typeof rawModel.ref === "string"
-			? { type: "ref", ref: rawModel.ref }
-			: { type: "ref", ref: "" };
+		normalizeModelSelector(r.compactModel) ?? { type: "ref", ref: "" };
 
 	const rawThresholds = Array.isArray(r.reminderThresholds)
 		? r.reminderThresholds
@@ -249,16 +244,6 @@ export function buildReinjectSection(contents: ReadonlyArray<{ path: string; con
 	return `\n\n<recently-read-files>\n${parts.join("\n\n")}\n</recently-read-files>`;
 }
 
-// ──────────────────────── subagent 识别（R6） ────────────────────────
-
-/**
- * subagent 子进程检测（D9/R6）：subagent-core session-runner 无条件注入 PI_SUBAGENT_ROOT_SESSION_ID。
- * 命中 → 本进程不注册工具、不提醒（宁缺勿污）。
- */
-export function isSubagentProcess(env: NodeJS.ProcessEnv = process.env): boolean {
-	return env.PI_SUBAGENT_ROOT_SESSION_ID !== undefined;
-}
-
 // ──────────────────────── session entries 统计（D13 纯函数） ────────────────────────
 
 /** sessionManager entries 的宽松形状（降智计数）。 */
@@ -271,11 +256,6 @@ export function countCompactions(entries: ReadonlyArray<EntryLike>): number {
 	return entries.filter((e) => e.type === "compaction").length;
 }
 
-/** unknown 的对象收窄（Record 视图；字段消费再经 typeof / Array.isArray 收窄）。 */
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 /**
  * 保留段已 Read 的文件集合（D13-11 去重：重注入跳过保留段已有的 Read 结果）。
  * 保留段 = branchEntries 中 firstKeptEntryId 之后的 message entries；从其 toolCall 参数提取 path。

package/src/tool.ts

@@ -10,7 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { guardStaleCtx, isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { Type } from "typebox";
 
 import { debugLog } from "./compact-handler.js";
@@ -66,11 +66,6 @@ const TOOL_DESCRIPTION =
 	"2) 后续工作不再依赖将被压缩的早期细节；3) 上下文已超过提醒阈值（你会收到 [smart-context 提示]）。" +
 	"若任一条件不满足，不要调用。";
 
-/** unknown 的对象收窄（Record 视图；字段消费再经 typeof 收窄）。 */
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 /** CompactionResult → 宽松形状的 guard 转换（onComplete 回调参数消费，避免 cast）。 */
 function toCompactionResultLike(result: unknown): CompactionResultLike {
 	const r: Record<string, unknown> = isRecord(result) ? result : {};
@@ -150,8 +145,8 @@ export function registerCompactContextTool(
 			const config = loadSmartContextConfig();
 			if (!gating.active) {
 				const reason = config.enabled
-					? `当前模型 ${gating.modelId} 已配置为排除（smart-context excludedModels），压缩工具不可用。可在 xyz-agent 设置页或 smart-context-ext-config skill 中调整。`
-					: `smart-context 已禁用。可在 xyz-agent 设置页开启，或经 smart-context-ext-config skill 修改配置。`;
+					? `当前模型 ${gating.modelId} 已配置为排除（smart-context excludedModels），压缩工具不可用。可在 taiji 设置页或 smart-context-ext-config skill 中调整。`
+					: `smart-context 已禁用。可在 taiji 设置页开启，或经 smart-context-ext-config skill 修改配置。`;
 				throw new Error(reason);
 			}
 
@@ -190,7 +185,7 @@ export function registerCompactContextTool(
 							: "未知";
 						const showHint = compactionCount + 1 >= DEGRADATION_HINT_MIN_COMPACTIONS;
 						const lines = [
-							`[smart-context] 压缩完成。模式：${resultMode}${fellBack ? "（压缩模型不可用，已回退当前模型——请检查配置：xyz-agent 设置页或 smart-context-ext-config skill）" : ""}。`,
+							`[smart-context] 压缩完成。模式：${resultMode}${fellBack ? "（压缩模型不可用，已回退当前模型——请检查配置：taiji 设置页或 smart-context-ext-config skill）" : ""}。`,
 							`压缩前 ${formatK(result.tokensBefore ?? 0)} tokens → 压缩后约 ${formatK(result.estimatedTokensAfter ?? 0)} tokens；摘要生成成本：${cost}。`,
 							showHint ? buildDegradationHintLine() : "",
 						].filter((l) => l !== "");

package/vitest.config.ts

@@ -1,9 +1,7 @@
-import { defineConfig } from "vitest/config";
+import { taijiTestConfig } from "../../../test-guard/factory.ts"
 
-export default defineConfig({
+export default taijiTestConfig({
   test: {
-    reporters: ["default", "junit"],
-    outputFile: { junit: "./test-results/vitest-junit.xml" },
     include: ["src/__tests__/**/*.test.ts"],
   },
 });