@zhushanwen/pi-smart-context 0.1.0

package/src/llm.ts

@@ -0,0 +1,139 @@
+/**
+ * same-model 模式的 LLM 调用（D12 + D13-5 cache-key 一致性）。
+ *
+ * 不走 llm-shared callLLM：其 tools:[] 硬编码会破坏前缀缓存对齐（call.ts:113）。
+ * 此处直接用 completeSimple + getApiKeyAndHeaders，并把 tools schema 与主会话对齐
+ * （deepseek-harness summarizer 同款做法：system + tools + messages 全部复用做缓存对齐）。
+ *
+ * cache-key 一致性约束（D13-5）：除末尾追加的压缩指令 user message 外，
+ * systemPrompt / tools / messages 前缀与主会话完全一致；不设 maxTokens / reasoning 覆盖
+ * （Claude Code 教训：单独设置 maxOutputTokens/thinking 会造成 cache-key mismatch 前缀全 miss）。
+ */
+
+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 } from "@earendil-works/pi-coding-agent";
+
+/** ToolInfo 的宽松形状（Pick<ToolDefinition, "name"|"description"|"parameters"> 即可投影为 pi-ai Tool）。 */
+interface ToolInfoLike {
+	name: string;
+	description: string;
+	parameters: unknown;
+}
+
+/**
+ * ToolInfo → pi-ai Tool 投影：三字段直取。parameters 是 typebox schema（主会话同源对象，
+ * 序列化后与主请求一致——缓存对齐的关键是不改造、原样透传）。
+ */
+export function projectTools(toolInfos: readonly ToolInfoLike[]): LlmTool[] {
+	return toolInfos.map((t) => ({
+		name: t.name,
+		description: t.description,
+		parameters: t.parameters as LlmTool["parameters"],
+	}));
+}
+
+/** completeSimple 返回的宽松形状（消费 stopReason / usage / content text）。 */
+interface SimpleResponseLike {
+	stopReason?: string;
+	usage?: {
+		input?: number;
+		output?: number;
+		cacheRead?: number;
+		cacheWrite?: number;
+		totalTokens?: number;
+	};
+	content: ReadonlyArray<{ type: string; text?: string }>;
+}
+
+/**
+ * same-model 调用结果（判别联合）：成功携带摘要文本与 usage；失败仅携带 error
+ * （调用方走 D7 回退），stopReason 两态均可携带（length 截断 fail-closed / 排查用）。
+ */
+export type SameModelCallResult =
+	| {
+		ok: true;
+		/** 摘要文本（content 内全部 text block 拼接，D13-10 只取 text）。 */
+		text: string;
+		/** provider usage（cacheRead 供 R8 探针验证缓存命中）。 */
+		usage?: SimpleResponseLike["usage"];
+		/** stopReason（length = max-tokens 截断，D13-2 fail-closed 判据）。 */
+		stopReason?: string;
+	}
+	| {
+		ok: false;
+		error: string;
+		stopReason?: string;
+	};
+
+export interface SameModelCallOptions {
+	model: Model<never> | Model<string> | undefined;
+	/** 会话原 system prompt（ctx.getSystemPrompt()——缓存对齐必要条件）。 */
+	systemPrompt: string;
+	/** 完整上下文 messages + 末尾已追加的压缩指令 message。 */
+	messages: Message[];
+	/** 主会话工具投影（缓存对齐）。 */
+	tools: LlmTool[];
+	signal?: AbortSignal;
+	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>;
+	};
+}
+
+/**
+ * content block 的 text 提取（in-guard：联合中 ThinkingContent/ToolCall 无 text 字段）。
+ * 与 llm-shared extractText 刻意不同：不过滤 block type、join 用 "\n"——摘要需保留
+ * 多段换行结构（extractText 过滤 type==="text" 且 join 空格，语义是单段纯文本）。
+ */
+function blockText(block: { type: string; text?: unknown }): string {
+	return typeof block.text === "string" ? block.text : "";
+}
+
+/**
+ * 发起 same-model 压缩调用。失败归一为 {ok:false, error}（调用方走 D7 回退），不抛错。
+ * max-tokens 截断（stopReason === "length"）返回 ok:true + stopReason 由调用方 fail-closed。
+ */
+export async function callSameModelCompaction(
+	ctx: ExtensionContext,
+	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));
+	try {
+		if (!opts.model) {
+			return { ok: false, error: "no current model" };
+		}
+		const auth = await getAuth(opts.model);
+		if (!auth.ok) {
+			return { ok: false, error: auth.error };
+		}
+		const context: LlmContext = {
+			systemPrompt: opts.systemPrompt,
+			messages: opts.messages,
+			tools: opts.tools,
+		};
+		// cache-key 一致性（D13-5）：不设 maxTokens / reasoning / timeoutMs 覆盖——
+		// 任何 cache-key 参数差异都使前缀缓存整体失效
+		const options: SimpleStreamOptions = {
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+			env: auth.env,
+			...(opts.signal ? { signal: opts.signal } : {}),
+			...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
+		};
+		const resp = await call(opts.model, context, options);
+		if (resp.stopReason === "error" || resp.stopReason === "aborted") {
+			const errorText = resp.content.map(blockText).join(" ").trim();
+			return { ok: false, error: errorText || `stopReason=${resp.stopReason}`, stopReason: resp.stopReason };
+		}
+		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) };
+	}
+}

package/src/prompts.ts

@@ -0,0 +1,70 @@
+/**
+ * 压缩 prompt 工程（D13-6/7/8/9/12 + D12 same-model 压缩指令）。
+ *
+ * 全部为纯常量/纯函数。措辞吸收自 Claude Code / Codex / deepseek-harness（附录 B 吸收记录），
+ * 实施期按摘要质量迭代（§5.3-3）。
+ */
+
+/** 落回包裹语（D13-9）：消除压缩后"确认收到摘要"的浪费回合。 */
+export const CHECKPOINT_PREAMBLE =
+	"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.";
+
+/** same-model 压缩指令的结构化模板（D13-7：pi 原生 6 节 + Files and Code + Errors and Fixes）。 */
+const CHECKPOINT_TEMPLATE = `## Goal
+- [the user's original and evolving goals; quote verbatim where the exact wording matters]
+
+## Constraints & Preferences
+- [constraints, conventions, and user preferences in play]
+
+## Progress
+- Done: [completed work with verification status]
+- In Progress: [what was underway at this checkpoint]
+- Blocked: [blocked items and why]
+
+## Key Decisions
+- [decisions made and their rationale]
+
+## Files and Code
+- [exact path: why it matters, key changes or snippets]
+
+## Errors and Fixes
+- [error: how it was resolved, plus any related user feedback/corrections]
+
+## Next Steps
+- [the single next action, directly in line with the most recent request, or "(none)"]
+
+## Critical Context
+- [data, examples, or references needed to continue]`;
+
+/**
+ * same-model 模式的压缩指令 user message（追加在完整上下文末尾，D12）。
+ *
+ * - 首尾 TEXT ONLY 双保险（D13-6，防模型在压缩调用里乱调工具）
+ * - 先验 checkpoint 合并规则（D13-8，输入里已有上次摘要时：不逐字复制、保留仍真、丢弃过时）
+ * - custom_instructions（agent 的重点关注）非空时追加
+ */
+export function buildSameModelInstruction(customInstructions?: string): string {
+	const prior = `If the conversation above already contains a checkpoint summary from an earlier compaction, do NOT copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated checkpoint under the same structure.`;
+	const focus = customInstructions?.trim()
+		? `\n\nAdditional focus from the calling agent (weight these higher):\n${customInstructions.trim()}`
+		: "";
+	return [
+		`CRITICAL: Respond with TEXT ONLY. Do NOT call any tools. This is a compaction request.`,
+		``,
+		`You are now acting as a compaction engine for this AI coding session. Condense the conversation ABOVE into a structured checkpoint that lets the next model turn resume the work with no loss of essential context.`,
+		``,
+		prior,
+		``,
+		`Output EXACTLY the Markdown structure below: keep every section, in order. Use terse bullets, not prose paragraphs. Write "(none)" for an empty section — never drop a section. Preserve exact file paths, commands, error strings, identifiers, numeric values, and function signatures.`,
+		``,
+		CHECKPOINT_TEMPLATE,
+		focus,
+		``,
+		`REMINDER: Respond with TEXT ONLY. Do NOT call any tools. Output only the checkpoint text.`,
+	].join("\n");
+}
+
+/** transcript 回查指针（D13-4）：附在 summary 末尾。 */
+export function buildTranscriptPointer(sessionFilePath: string): string {
+	return `\n\n<transcript-ref>Need details from before this compaction? Read the full session transcript at: ${sessionFilePath}</transcript-ref>`;
+}

package/src/pure.ts

@@ -0,0 +1,311 @@
+/**
+ * 纯函数层：配置 schema / 加载 / 门控判定 / 阈值检查 / 摘要后处理。
+ *
+ * 无副作用（fs 读取经 llm-shared loadConfig 的缓存封装），全部可单测。
+ * 设计文档：docs/extensions/smart-context/design.md（D5 门控矩阵 / D6 阈值保护 / D8 配置 schema）。
+ */
+
+import type { ModelSelector } from "@zhushanwen/pi-llm-shared";
+import { loadConfig } from "@zhushanwen/pi-llm-shared";
+
+// ──────────────────────── 配置 schema（D8） ────────────────────────
+
+/** 单 K 的 token 数（显示格式化用）。 */
+const TOKENS_PER_K = 1_000;
+/** chars/4 的 token 估算口径（对齐 pi estimateTokens 启发式）。 */
+export const CHARS_PER_TOKEN_ESTIMATE = 4;
+/** 提醒阈值最大档数（3 档）。 */
+const MAX_THRESHOLD_TIERS = 3;
+
+/** 3 档提醒阈值默认值（token 绝对数）：200K / 400K / 600K。 */
+const DEFAULT_REMINDER_THRESHOLDS: readonly number[] = [200_000, 400_000, 600_000];
+
+/** smart-context 磁盘配置（<agentDir>/config/smart-context-ext-config.json）。 */
+export interface SmartContextConfig {
+	enabled: boolean;
+	/** 压缩模型 ref；与当前会话模型一致 → same-model 模式（D12）。 */
+	compactModel: ModelSelector;
+	/** 3 档提醒阈值（token 绝对数，升序）。 */
+	reminderThresholds: number[];
+	/** 排除模型列表：完整 provider/modelId 精准等值匹配（D5）。 */
+	excludedModels: string[];
+}
+
+export const DEFAULT_SMART_CONTEXT_CONFIG: SmartContextConfig = {
+	enabled: true,
+	compactModel: { type: "ref", ref: "" },
+	reminderThresholds: [...DEFAULT_REMINDER_THRESHOLDS],
+	excludedModels: [],
+};
+
+/**
+ * 配置 normalize：字段缺失/非法回退默认值（向后兼容，规范要求 deserializeState 同款纪律）。
+ * - reminderThresholds：过滤非正数 → 升序 → 截 3 档；空数组回退默认
+ * - excludedModels：过滤非字符串与不含 "/" 的条目（精准匹配要求完整 provider/modelId）→ 去重
+ * - compactModel：ref 非字符串按空串
+ */
+export function normalizeSmartContextConfig(raw: unknown): SmartContextConfig {
+	const base = DEFAULT_SMART_CONTEXT_CONFIG;
+	if (typeof raw !== "object" || raw === null) return { ...base, reminderThresholds: [...base.reminderThresholds] };
+	const r = raw as Record<string, unknown>;
+
+	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: "" };
+
+	const rawThresholds = Array.isArray(r.reminderThresholds)
+		? r.reminderThresholds
+		: [];
+	const thresholds = rawThresholds
+		.filter((t): t is number => typeof t === "number" && Number.isFinite(t) && t > 0)
+		.sort((a, b) => a - b)
+		.slice(0, MAX_THRESHOLD_TIERS);
+	const reminderThresholds = thresholds.length > 0 ? thresholds : [...base.reminderThresholds];
+
+	const rawExcluded = Array.isArray(r.excludedModels) ? r.excludedModels : [];
+	const excludedModels = [
+		...new Set(
+			rawExcluded.filter((m): m is string => typeof m === "string" && m.includes("/")),
+		),
+	];
+
+	return { enabled, compactModel, reminderThresholds, excludedModels };
+}
+
+/**
+ * 读取配置（llm-shared loadConfig：mtime+size 读时刷新，热重载契约禁止上层缓存）。
+ * 文件不存在/损坏 → 默认值。
+ */
+export function loadSmartContextConfig(): SmartContextConfig {
+	return loadConfig("smart-context", DEFAULT_SMART_CONTEXT_CONFIG, normalizeSmartContextConfig);
+}
+
+// ──────────────────────── 门控判定（D5 矩阵） ────────────────────────
+
+// 当前模型 ID 拼接口径单点在 llm-shared（model-switch 同源消费）
+export { getCurrentModelId } from "@zhushanwen/pi-llm-shared";
+
+/**
+ * 门控是否放行（D5 矩阵第一列）：enabled 且当前模型未精准命中排除列表。
+ * 每次事件回调现场调用（热读配置），不缓存。
+ */
+export function isGatingActive(config: SmartContextConfig, currentModelId: string): boolean {
+	if (!config.enabled) return false;
+	if (currentModelId === "") return false;
+	return !config.excludedModels.includes(currentModelId);
+}
+
+/**
+ * 模式判定（D12）：compactModel.ref 等于当前模型（或未配置 = 跟随当前模型）→ "same-model"；
+ * 否则 "cross-model"。
+ */
+export function pickMode(config: SmartContextConfig, currentModelId: string): "same-model" | "cross-model" {
+	const ref = config.compactModel.ref;
+	if (ref === "" || ref === currentModelId) return "same-model";
+	return "cross-model";
+}
+
+// ──────────────────────── 阈值检查（D3/D6） ────────────────────────
+
+/**
+ * 越档检查：返回本次应提醒的档位（已 fired 的排除；多档合并由调用方组装成一条消息）。
+ * tokens 为 null（压缩后首响应前，R7）→ 空数组（跳过本轮检查）。
+ */
+export function findCrossedThresholds(
+	thresholds: readonly number[],
+	tokens: number | null | undefined,
+	fired: ReadonlySet<number>,
+): number[] {
+	if (typeof tokens !== "number" || !Number.isFinite(tokens)) return [];
+	return thresholds.filter((t) => tokens >= t && !fired.has(t));
+}
+
+/**
+ * 工具最低阈值保护（D6）：返回 null = 放行；返回字符串 = 拒绝原因（含当前用量数据）。
+ * tokens 为 null → 拒绝（"用量未知"，null 窗口期紧随压缩完成，不应再压）。
+ */
+export function checkToolThresholdGuard(
+	thresholds: readonly number[],
+	tokens: number | null | undefined,
+): string | null {
+	const min = Math.min(...thresholds);
+	if (typeof tokens !== "number" || !Number.isFinite(tokens)) {
+		return `当前上下文用量未知（可能刚完成一次压缩），暂不执行压缩。若确有必要，请稍后重试。`;
+	}
+	if (tokens < min) {
+		return `当前上下文 ${formatK(tokens)} tokens，未达第 1 档提醒阈值 ${formatK(min)}，无需压缩。继续你的工作即可。`;
+	}
+	return null;
+}
+
+// ──────────────────────── 摘要后处理（D13 纯函数部分） ────────────────────────
+
+/** token 数格式化为 K 显示（200000 → "200K"；非整数 K 保留一位小数）。 */
+export function formatK(tokens: number): string {
+	const k = tokens / TOKENS_PER_K;
+	return Number.isInteger(k) ? `${k}K` : `${k.toFixed(1)}K`;
+}
+
+/**
+ * 收缩校验（D13-1）：摘要 token 数 ≥ 被压段 token 数 → 不合格（返回 true）。
+ * 估算口径与 pi 一致（chars/4）。
+ */
+export function isSummaryInflated(summaryTokens: number, shadowedTokens: number): boolean {
+	return summaryTokens >= shadowedTokens;
+}
+
+/** chars/4 估算 token（对齐 pi estimateTokens 口径的文本版）。 */
+export function estimateTextTokens(text: string): number {
+	return Math.ceil(text.length / CHARS_PER_TOKEN_ESTIMATE);
+}
+
+/** 降智提示阈值（D13-12）：累计 compaction 次数 ≥2 时提示开新会话。 */
+export const DEGRADATION_HINT_MIN_COMPACTIONS = 2;
+
+/**
+ * fileOps 形状（对齐 pi createFileOps：{read/written/edited: Set<string>}）的宽松结构。
+ * preparation.fileOps 直接传入。
+ */
+export interface FileOpsLike {
+	read: Iterable<string>;
+	written: Iterable<string>;
+	edited: Iterable<string>;
+}
+
+/**
+ * 计算文件清单（对齐 pi computeFileLists 语义：只读 = read − modified；modified = edited ∪ written）。
+ * 返回排序后的两个列表。
+ */
+export function computeFileListsLike(fileOps: FileOpsLike): { readFiles: string[]; modifiedFiles: string[] } {
+	const modified = new Set<string>([...fileOps.edited, ...fileOps.written]);
+	const readFiles = [...fileOps.read].filter((f) => !modified.has(f)).sort();
+	const modifiedFiles = [...modified].sort();
+	return { readFiles, modifiedFiles };
+}
+
+/**
+ * 文件清单追加（D11-2，对齐 pi formatFileOperations 输出格式：XML tags）。
+ */
+export function formatFileOperationsLike(readFiles: readonly string[], modifiedFiles: readonly string[]): string {
+	const sections: string[] = [];
+	if (readFiles.length > 0) {
+		sections.push(`<read-files>\n${readFiles.join("\n")}\n</read-files>`);
+	}
+	if (modifiedFiles.length > 0) {
+		sections.push(`<modified-files>\n${modifiedFiles.join("\n")}\n</modified-files>`);
+	}
+	if (sections.length === 0) return "";
+	return `\n\n${sections.join("\n\n")}`;
+}
+
+/** 文件重注入预算（D13-11）：≤5 文件 / 每文件 5K 字符 / 总 50K 字符。 */
+const REINJECT_MAX_FILES = 5;
+const REINJECT_PER_FILE_CHARS = 5_000;
+const REINJECT_TOTAL_CHARS = 50_000;
+
+/**
+ * 文件重注入选择（D13-11）：从只读文件列表取最近 ≤5 个（Set 保序 = 插入序 ≈ 时间序，
+ * 取尾部即最近），返回选中的路径列表（预算裁剪由调用方读文件时执行）。
+ * keptReadFiles：保留段已出现过的 Read 结果（跳过，避免重复占上下文）。
+ */
+export function pickReinjectFiles(readFiles: readonly string[], keptReadFiles: ReadonlySet<string>): string[] {
+	return readFiles
+		.filter((f) => !keptReadFiles.has(f))
+		.slice(-REINJECT_MAX_FILES);
+}
+
+/**
+ * 组装「Recently read files」节（D13-11）：每文件头 5K 字符 + 截断标记，总 50K 截停。
+ * 文件内容缺失（读失败/空）逐文件跳过。
+ */
+export function buildReinjectSection(contents: ReadonlyArray<{ path: string; content: string }>): string {
+	let total = 0;
+	const parts: string[] = [];
+	for (const { path, content } of contents) {
+		if (content === "") continue;
+		const budgetFile = Math.min(REINJECT_PER_FILE_CHARS, REINJECT_TOTAL_CHARS - total);
+		if (budgetFile <= 0) break;
+		const text = content.length <= budgetFile
+			? content
+			: `${content.slice(0, budgetFile)}\n[... truncated]`;
+		total += text.length;
+		parts.push(`### ${path}\n\`\`\`\n${text}\n\`\`\``);
+	}
+	if (parts.length === 0) return "";
+	return `\n\n<recently-read-files>\n${parts.join("\n\n")}\n</recently-read-files>`;
+}
+
+// ──────────────────────── subagent 识别（R6） ────────────────────────
+
+/**
+ * subagent 子进程检测（D9/R6）：subagent-workflow 无条件注入 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 的宽松形状（降智计数）。 */
+export interface EntryLike {
+	type: string;
+}
+
+/** 累计 compaction 次数（D13-12 判据）。 */
+export function countCompactions(entries: ReadonlyArray<EntryLike>): number {
+	return entries.filter((e) => e.type === "compaction").length;
+}
+
+/**
+ * 保留段已 Read 的文件集合（D13-11 去重：重注入跳过保留段已有的 Read 结果）。
+ * 保留段 = branchEntries 中 firstKeptEntryId 之后的 message entries；从其 toolCall 参数提取 path。
+ */
+export function collectKeptReadFiles(branchEntries: ReadonlyArray<unknown>, firstKeptEntryId: string): Set<string> {
+	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 (!found) {
+			if (e.id === firstKeptEntryId) found = true;
+			continue;
+		}
+		const msg = e.message;
+		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") {
+				kept.add(block.arguments.path);
+			}
+		}
+	}
+	return kept;
+}
+
+/**
+ * 被压段 token 估算（收缩校验分母：仅 messagesToSummarize；turnPrefixMessages 是保留段前缀，
+ * 不属于被压段，不计入）。pi 的 estimateTokens 按 message 内容估算；此处 chars/4 的保守替代：
+ * serialize 后长度 / 4（与 pi 同口径量级，用于"摘要 >= 原文"的粗判已足）。
+ */
+export function estimateShadowedTokens(
+	messagesToSummarize: ReadonlyArray<{ role: string; content?: unknown }>,
+): number {
+	let chars = 0;
+	for (const m of messagesToSummarize) {
+		const content = m.content;
+		if (typeof content === "string") {
+			chars += content.length;
+		} else if (Array.isArray(content)) {
+			for (const b of content as ReadonlyArray<{ type?: string; text?: string }>) {
+				if (typeof b.text === "string") chars += b.text.length;
+			}
+		}
+	}
+	return Math.ceil(chars / CHARS_PER_TOKEN_ESTIMATE);
+}

package/src/reminder.ts

@@ -0,0 +1,73 @@
+/**
+ * 提醒与通知文案构造（D3/D4/D5/D13-12）。
+ *
+ * 全部为纯函数：文案 + 越档判定。注入由 src/index.ts 用 pi.sendUserMessage 执行。
+ * 措辞原则（目标 3）：提醒是数据投递不是指令——给三条件自查清单 + 明确的"可忽略"出口，
+ * 避免 agent 见提醒就压缩。
+ */
+
+import {
+	DEGRADATION_HINT_MIN_COMPACTIONS,
+	formatK,
+} from "./pure.js";
+
+/**
+ * 阈值提醒消息（D3/D4）：越档信息 + 用量数据 + 工具名 + 三条件自查 + 可忽略出口。
+ * 多档同时越过合并为一条（D3 去重规则）。
+ */
+export function buildThresholdReminder(
+	crossedThresholds: readonly number[],
+	tokens: number,
+	contextWindow: number,
+	compactionCount: number,
+): string {
+	const percent = contextWindow > 0 ? ((tokens / contextWindow) * 100).toFixed(1) : "?";
+	const tiers = crossedThresholds
+		.map((t, index) => `${formatK(t)}（第 ${index + 1} 档）`)
+		.join("、");
+	const lines = [
+		`[smart-context 提示] 上下文当前 ${formatK(tokens)} / ${formatK(contextWindow)} tokens（${percent}%），已超过提醒阈值 ${tiers}。`,
+		``,
+		`compact_context 工具可用于压缩上下文。请自行判断是否现在压缩——仅当以下三个条件同时满足时才调用：`,
+		`1. 当前任务的一个阶段已完成并验证（如一批文件改完、测试通过）；`,
+		`2. 后续工作不再依赖将被压缩的早期细节；`,
+		`3. 上下文已超过阈值（本提示即第 3 条的数据依据）。`,
+		``,
+		`若任务仍在进行中、或近期仍需引用早期上下文，忽略本提示继续工作即可（本档位不会重复提醒，压缩后会重置）。`,
+	];
+	if (compactionCount >= DEGRADATION_HINT_MIN_COMPACTIONS) {
+		lines.push(``, buildDegradationHintLine());
+	}
+	return lines.join("\n");
+}
+
+/** 降智提示单行（D13-12，工具结果复用）。 */
+export function buildDegradationHintLine(): string {
+	return `Note: this session has been compacted multiple times; fine-grained details may be lost. If the task allows, consider starting a new session.`;
+}
+
+/** 切换跨界通知（D5）：进入排除 / 恢复可用 两态。 */
+export function buildSwitchNotice(kind: "unavailable" | "available", modelId: string): string {
+	if (kind === "unavailable") {
+		return `[smart-context] 压缩工具暂时不可用：当前模型 ${modelId} 已配置为排除（smart-context excludedModels），本会话将使用 pi 原生压缩行为。`;
+	}
+	return `[smart-context] 压缩工具恢复可用：当前模型 ${modelId} 支持压缩（不在排除列表）。超阈值时将收到提醒。`;
+}
+
+/**
+ * downshift 检测（D5）：新模型窗口更小且当前 tokens 将触线 → 提醒建议先压缩。
+ * 返回 null = 无需提醒。
+ */
+export function buildDownshiftNotice(
+	tokens: number | null | undefined,
+	previousWindow: number | undefined,
+	newWindow: number | undefined,
+): string | null {
+	if (typeof tokens !== "number" || typeof previousWindow !== "number" || typeof newWindow !== "number") {
+		return null;
+	}
+	if (newWindow >= previousWindow) return null;
+	const triggerLine = newWindow - 16_384; // pi 内建触发线（window − reserveTokens 默认值）
+	if (tokens < triggerLine) return null;
+	return `[smart-context] 当前上下文 ${formatK(tokens)} tokens，已接近新模型窗口上限（${formatK(newWindow)}）。建议尽快压缩（调用 compact_context 或 /compact），否则内建自动压缩将在触线时强制执行。`;
+}