@zhushanwen/pi-smart-context 0.1.0 → 0.1.2

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "@zhushanwen/pi-smart-context",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
-    "role": "universal"
+    "role": "universal",
+    "startupConfig": [
+      {
+        "path": "config/smart-context-ext-config.json",
+        "content": {
+          "enabled": true,
+          "compactModel": {
+            "type": "ref",
+            "ref": ""
+          },
+          "reminderThresholds": [
+            200000,
+            400000,
+            600000
+          ],
+          "excludedModels": []
+        }
+      }
+    ]
   },
   "pi": {
     "extensions": [
@@ -18,8 +36,8 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.2.2",
-    "@zhushanwen/pi-llm-shared": "0.4.0"
+    "@zhushanwen/pi-extension-logger": "0.3.1",
+    "@zhushanwen/pi-llm-shared": "0.4.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -32,8 +50,8 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-ai": "^0.84.4",
     "typebox": "*"
   },
   "peerDependenciesMeta": {

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

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

package/src/compact-handler.ts

@@ -10,7 +10,7 @@
  */
 
 import { buildSessionContext, compact as nativeCompact, convertToLlm } from "@earendil-works/pi-coding-agent";
-import type { CompactionResult } from "@earendil-works/pi-coding-agent";
+import type { CompactionResult, SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createLogger } from "@zhushanwen/pi-extension-logger";
 import { resolveModel } from "@zhushanwen/pi-llm-shared";
@@ -95,17 +95,30 @@ export interface SmartContextDetails {
 	mode: "same-model" | "cross-model";
 }
 
+/** sessionManager 上会话文件字段/方法的宽松形状（D13-4，消费侧可选链兜底）。 */
+interface SessionManagerSessionFileLike {
+	getSessionFile?: () => string | undefined;
+	sessionFile?: string;
+}
+
+/**
+ * sessionManager 会话文件访问形状的运行时守卫（D13-4）：
+ * 只收窄到对象（字段存在性/类型由消费侧可选链 + ?? 兜底，与原语义一致）。
+ */
+function isSessionManagerSessionFileLike(sm: unknown): sm is SessionManagerSessionFileLike {
+	return typeof sm === "object" && sm !== null;
+}
+
 /**
  * session 文件路径（transcript 回查指针用，D13-4）：从 sessionManager 推导。
  * getSessionFile 若不可得则返回空串（指针省略，不失败）。
  */
 function getSessionFilePath(ctx: ExtensionContext): string {
-	const sm = ctx.sessionManager as unknown as {
-		getSessionFile?: () => string | undefined;
-		sessionFile?: string;
-	};
+	// 经 unknown 再守卫：sessionFile 是 sessionManager 的类型未暴露字段（宽于其声明）
+	const sm: unknown = ctx.sessionManager;
+	const accessor = isSessionManagerSessionFileLike(sm) ? sm : undefined;
 	try {
-		return sm.getSessionFile?.() ?? sm.sessionFile ?? "";
+		return accessor?.getSessionFile?.() ?? accessor?.sessionFile ?? "";
 	} catch {
 		return "";
 	}
@@ -165,7 +178,7 @@ async function generateSameMode(
 	}
 	// AgentMessage[]（含 bash/custom 等扩展消息）→ 标准 Message[]（与主会话请求同源转换，
 	// convertToLlm 是 pi host 默认实现——同样的输入产生同样的输出，前缀缓存对齐的前提）
-	const fullMessages = convertToLlm(buildSessionContext(event.branchEntries as never).messages);
+	const fullMessages = convertToLlm(buildSessionContext(event.branchEntries as SessionEntry[]).messages);
 	const instructionMessage = {
 		role: "user" as const,
 		content: [{ type: "text" as const, text: buildSameModelInstruction(event.customInstructions) }],
@@ -237,9 +250,11 @@ async function generateCrossMode(
 			Object.entries(auth.headers).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
 		)
 		: undefined;
+	// preparation：BeforeCompactLikeEvent 的宽松形状是 nativeCompact 入参（CompactionPreparation，
+	// 含 settings 等未消费字段）的结构子集——运行时是 pi 原生事件对象，此处单层收窄断言
 	const result = await nativeCompact(
-		event.preparation as never,
-		model as never,
+		event.preparation as Parameters<typeof nativeCompact>[0],
+		model,
 		auth.apiKey,
 		headers,
 		event.customInstructions,

package/src/llm.ts

@@ -79,8 +79,8 @@ export interface SameModelCallOptions {
 	sessionId?: string;
 	/** 工具投影与 LLM 调用的依赖注入（单测 mock 点）。 */
 	deps?: {
-		getApiKeyAndHeaders?: (model: unknown) => Promise<{ ok: true; apiKey?: string; headers?: Record<string, string>; env?: Record<string, string> } | { ok: false; error: string }>;
-		call?: (model: unknown, context: LlmContext, options: SimpleStreamOptions) => Promise<SimpleResponseLike>;
+		getApiKeyAndHeaders?: (model: Model<never> | Model<string>) => Promise<{ ok: true; apiKey?: string; headers?: Record<string, string>; env?: Record<string, string> } | { ok: false; error: string }>;
+		call?: (model: Model<never> | Model<string>, context: LlmContext, options: SimpleStreamOptions) => Promise<SimpleResponseLike>;
 	};
 }
 
@@ -102,8 +102,8 @@ export async function callSameModelCompaction(
 	opts: SameModelCallOptions,
 ): Promise<SameModelCallResult> {
 	const deps = opts.deps ?? {};
-	const getAuth = deps.getApiKeyAndHeaders ?? ((m: unknown) => ctx.modelRegistry.getApiKeyAndHeaders(m as never));
-	const call = deps.call ?? ((m: unknown, c: LlmContext, o: SimpleStreamOptions) => completeSimple(m as never, c, o));
+	const getAuth = deps.getApiKeyAndHeaders ?? ((m: Model<never> | Model<string>) => ctx.modelRegistry.getApiKeyAndHeaders(m));
+	const call = deps.call ?? ((m: Model<never> | Model<string>, c: LlmContext, o: SimpleStreamOptions) => completeSimple(m, c, o));
 	try {
 		if (!opts.model) {
 			return { ok: false, error: "no current model" };

package/src/pure.ts

@@ -18,7 +18,14 @@ export const CHARS_PER_TOKEN_ESTIMATE = 4;
 const MAX_THRESHOLD_TIERS = 3;
 
 /** 3 档提醒阈值默认值（token 绝对数）：200K / 400K / 600K。 */
-const DEFAULT_REMINDER_THRESHOLDS: readonly number[] = [200_000, 400_000, 600_000];
+const DEFAULT_REMINDER_THRESHOLD_TIER_1_TOKENS = 200_000;
+const DEFAULT_REMINDER_THRESHOLD_TIER_2_TOKENS = 400_000;
+const DEFAULT_REMINDER_THRESHOLD_TIER_3_TOKENS = 600_000;
+const DEFAULT_REMINDER_THRESHOLDS: readonly number[] = [
+	DEFAULT_REMINDER_THRESHOLD_TIER_1_TOKENS,
+	DEFAULT_REMINDER_THRESHOLD_TIER_2_TOKENS,
+	DEFAULT_REMINDER_THRESHOLD_TIER_3_TOKENS,
+];
 
 /** smart-context 磁盘配置（<agentDir>/config/smart-context-ext-config.json）。 */
 export interface SmartContextConfig {
@@ -88,7 +95,7 @@ export function loadSmartContextConfig(): SmartContextConfig {
 
 // ──────────────────────── 门控判定（D5 矩阵） ────────────────────────
 
-// 当前模型 ID 拼接口径单点在 llm-shared（model-switch 同源消费）
+// 当前模型 ID 拼接口径单点在 llm-shared
 export { getCurrentModelId } from "@zhushanwen/pi-llm-shared";
 
 /**
@@ -263,6 +270,11 @@ 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。
@@ -271,16 +283,18 @@ export function collectKeptReadFiles(branchEntries: ReadonlyArray<unknown>, firs
 	const kept = new Set<string>();
 	let found = false;
 	for (const entry of branchEntries) {
-		const e = entry as { id?: string; message?: { role?: string; content?: unknown } };
+		if (!isRecord(entry)) continue;
 		if (!found) {
-			if (e.id === firstKeptEntryId) found = true;
+			if (entry.id === firstKeptEntryId) found = true;
 			continue;
 		}
-		const msg = e.message;
+		const msg = isRecord(entry.message) ? entry.message : undefined;
 		if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
-		for (const block of msg.content as ReadonlyArray<{ type?: string; name?: string; arguments?: { path?: unknown } }>) {
-			if (block.type === "toolCall" && block.name === "read" &&
-				block.arguments && typeof block.arguments.path === "string") {
+		for (const block of msg.content) {
+			if (
+				isRecord(block) && block.type === "toolCall" && block.name === "read" &&
+				isRecord(block.arguments) && typeof block.arguments.path === "string"
+			) {
 				kept.add(block.arguments.path);
 			}
 		}

package/src/reminder.ts

@@ -11,6 +11,11 @@ import {
 	formatK,
 } from "./pure.js";
 
+/** 百分比换算基数（tokens/contextWindow 比例 → 百分数显示）。 */
+const PERCENT_SCALE = 100;
+/** pi 内建自动压缩触发线的 reserveTokens 默认值（window − 16K）。 */
+const PI_DEFAULT_RESERVE_TOKENS = 16_384;
+
 /**
  * 阈值提醒消息（D3/D4）：越档信息 + 用量数据 + 工具名 + 三条件自查 + 可忽略出口。
  * 多档同时越过合并为一条（D3 去重规则）。
@@ -21,7 +26,7 @@ export function buildThresholdReminder(
 	contextWindow: number,
 	compactionCount: number,
 ): string {
-	const percent = contextWindow > 0 ? ((tokens / contextWindow) * 100).toFixed(1) : "?";
+	const percent = contextWindow > 0 ? ((tokens / contextWindow) * PERCENT_SCALE).toFixed(1) : "?";
 	const tiers = crossedThresholds
 		.map((t, index) => `${formatK(t)}（第 ${index + 1} 档）`)
 		.join("、");
@@ -67,7 +72,7 @@ export function buildDownshiftNotice(
 		return null;
 	}
 	if (newWindow >= previousWindow) return null;
-	const triggerLine = newWindow - 16_384; // pi 内建触发线（window − reserveTokens 默认值）
+	const triggerLine = newWindow - PI_DEFAULT_RESERVE_TOKENS; // pi 内建触发线（window − reserveTokens 默认值）
 	if (tokens < triggerLine) return null;
 	return `[smart-context] 当前上下文 ${formatK(tokens)} tokens，已接近新模型窗口上限（${formatK(newWindow)}）。建议尽快压缩（调用 compact_context 或 /compact），否则内建自动压缩将在触线时强制执行。`;
 }

package/src/tool.ts

@@ -65,11 +65,16 @@ 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 = result as { tokensBefore?: unknown; estimatedTokensAfter?: unknown; usage?: unknown; details?: unknown };
-	const usage = (r.usage ?? null) as { input?: unknown; output?: unknown; cacheRead?: unknown } | null;
-	const details = (r.details ?? null) as { engine?: unknown; mode?: unknown } | null;
+	const r: Record<string, unknown> = isRecord(result) ? result : {};
+	const usage = isRecord(r.usage) ? r.usage : null;
+	const details = isRecord(r.details) ? r.details : null;
 	const num = (v: unknown) => (typeof v === "number" ? v : undefined);
 	const str = (v: unknown) => (typeof v === "string" ? v : undefined);
 	return {
@@ -82,7 +87,7 @@ function toCompactionResultLike(result: unknown): CompactionResultLike {
 				cacheRead: num(usage.cacheRead),
 			}
 			: undefined,
-		details: details && typeof details === "object"
+		details: details
 			? {
 				engine: str(details.engine),
 				mode: str(details.mode),