@bachi/pi-coder 1.0.0 → 1.1.0

package/extensions/mcp/tools.ts

@@ -0,0 +1,339 @@
+/**
+ * tools.ts — MCP 工具 → pi 工具的纯映射层：命名、schema、结果内容、截断。
+ *
+ * 纯逻辑，不 import pi / 不 spawn 进程，所以 `node --test` 直接跑。pi 的注册动作全在 index.ts，
+ * 这里只回答「这个名字怎么拼」「这段内容怎么给模型」。
+ *
+ * 命名采用 Claude Code 的 `mcp__<server>__<tool>`：用户的 skill 与权限规则都是按这个形状写的，
+ * 换一套前缀只会让两边对不上。（pi-mcp-adapter 默认是 `<server>_<tool>`，我们在 `mcp__` 上
+ * 更贴 Claude Code 的习惯。）
+ *
+ * 结果映射的两个必须遵守的约束：
+ *   - pi 的 tool content 只认 `{type:"text"}` 与 `{type:"image", data, mimeType}`；
+ *     MCP 的 `resource` / `resource_link` / `audio` 都得降级成文本说明，不能原样塞进去。
+ *   - 工具输出必须截断：MCP 服务端（尤其是把整个 JSON 一次吐出来的实现）很容易给出
+ *     超过上下文的体积。截断上限沿用 pi 内建工具的 50KB / 2000 行。
+ */
+
+/** MCP 的 image 内容块 → pi 的 ImageContent 形状。 */
+export interface PiTextContent {
+	type: "text";
+	text: string;
+}
+
+export interface PiImageContent {
+	type: "image";
+	data: string;
+	mimeType: string;
+}
+
+export type PiToolContent = PiTextContent | PiImageContent;
+
+/** 工具名上限：Anthropic / OpenAI 的 tool 名都是 64 字符。 */
+export const MAX_TOOL_NAME_LENGTH = 64;
+
+/** 与 pi 内建工具一致的截断上限。 */
+export const DEFAULT_MAX_BYTES = 50 * 1024;
+export const DEFAULT_MAX_LINES = 2000;
+
+export const MCP_TOOL_PREFIX = "mcp__";
+export const TOOL_PREFIX_SEPARATOR = "__";
+
+export interface McpToolDescriptor {
+	name: string;
+	description?: string;
+	inputSchema?: unknown;
+	annotations?: Record<string, unknown>;
+}
+
+/**
+ * `mcp__<server>__<tool>`，非法字符替换成 `_`。
+ *
+ * 超过 64 字符时截断工具名并接一个 6 位哈希后缀：名字要能被模型原样回传，截断后的
+ * 冲突（两个长工具名截到同一段）靠哈希区分。哈希是 FNV-1a，只为消歧，不做安全用途。
+ */
+export function piToolName(serverName: string, toolName: string): string {
+	const server = sanitizeSegment(serverName);
+	const tool = sanitizeSegment(toolName);
+	const full = `${MCP_TOOL_PREFIX}${server}${TOOL_PREFIX_SEPARATOR}${tool}`;
+	if (full.length <= MAX_TOOL_NAME_LENGTH) return full;
+
+	const hash = fnv1a(`${serverName}\u0000${toolName}`);
+	const budget = MAX_TOOL_NAME_LENGTH - MCP_TOOL_PREFIX.length - server.length - TOOL_PREFIX_SEPARATOR.length - hash.length - 1;
+	const head = tool.slice(0, Math.max(budget, 8));
+	return `${MCP_TOOL_PREFIX}${server}${TOOL_PREFIX_SEPARATOR}${head}_${hash}`;
+}
+
+function sanitizeSegment(value: string): string {
+	const sanitized = value.replace(/[^A-Za-z0-9_-]/g, "_");
+	return sanitized === "" ? "_" : sanitized;
+}
+
+function fnv1a(value: string): string {
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash.toString(16).padStart(8, "0").slice(0, 6);
+}
+
+/**
+ * 归一化 MCP 的 inputSchema，保证是一个合法的 `type: "object"` JSON Schema。
+ *
+ * 现实里的服务端会给出各种形状：缺 schema、`{}`、`{"properties": ...}` 没写 type、
+ * 甚至直接是 `null`。pi 用这个 schema 校验参数，形状不对会让整次调用在下发前就失败 ——
+ * 兜底成「无参数对象」最坏只是模型看不到参数提示，比调用被拒好。
+ */
+export function normalizeInputSchema(schema: unknown): Record<string, unknown> {
+	const empty: Record<string, unknown> = { type: "object", properties: {} };
+	if (typeof schema !== "object" || schema === null || Array.isArray(schema)) return empty;
+	const record = schema as Record<string, unknown>;
+	const type = record.type;
+	if (type !== undefined && type !== "object") return empty;
+	return {
+		type: "object",
+		properties:
+			typeof record.properties === "object" && record.properties !== null && !Array.isArray(record.properties)
+				? record.properties
+				: {},
+		...(Array.isArray(record.required) ? { required: record.required } : {}),
+		// 其余 JSON Schema 关键字（$defs / additionalProperties / oneOf ...）原样保留。
+		...Object.fromEntries(
+			Object.entries(record).filter(([key]) => !["type", "properties", "required"].includes(key)),
+		),
+	};
+}
+
+/** 给模型的工具描述：原文 + 注解提示（只读/破坏性）。 */
+export function toolDescription(serverName: string, tool: McpToolDescriptor): string {
+	const parts: string[] = [];
+	if (tool.description?.trim()) parts.push(tool.description.trim());
+	const hints = annotationHints(tool.annotations);
+	const header = `MCP 工具（server: ${serverName}）${hints ? ` ${hints}` : ""}`;
+	parts.push(header);
+	return parts.join("\n\n");
+}
+
+function annotationHints(annotations: Record<string, unknown> | undefined): string {
+	if (!annotations) return "";
+	const hints: string[] = [];
+	if (annotations.readOnlyHint === true) hints.push("只读");
+	if (annotations.destructiveHint === true) hints.push("可能破坏数据");
+	if (annotations.idempotentHint === true) hints.push("幂等");
+	if (annotations.openWorldHint === true) hints.push("访问外部世界");
+	return hints.length > 0 ? `[${hints.join(" / ")}]` : "";
+}
+
+/** 系统提示里的一行摘要（pi 的 `Available tools` 段）。 */
+export function toolPromptSnippet(description: string | undefined): string | undefined {
+	if (!description?.trim()) return undefined;
+	const flat = description.replace(/\s+/g, " ").trim();
+	return flat.length <= 100 ? flat : `${truncateAtWord(flat, 100)}…`;
+}
+
+function truncateAtWord(value: string, max: number): string {
+	if (value.length <= max) return value;
+	const slice = value.slice(0, max);
+	const space = slice.lastIndexOf(" ");
+	// CJK 里没有空格：切不到词就硬切，别把整段都丢掉。
+	return space > max * 0.6 ? slice.slice(0, space) : slice;
+}
+
+export interface ContentMappingResult {
+	content: PiToolContent[];
+	/** 给 LLM 看的纯文本（文本块拼接；含图片时的占位说明）。 */
+	text: string;
+	/** 无法直传、被降级成文本说明的内容块（音频、二进制 resource 等）。 */
+	notes: string[];
+}
+
+/**
+ * MCP `tools/call` 的 content 数组 → pi 的 content 数组。
+ *
+ * 认得的形状：text / image / resource / resource_link。
+ * 认不得的一律降级成一行文本说明 —— 宁可让模型看到「这里有个不支持的 X」，
+ * 也不要静默丢掉内容（模型会以为自己没看到东西）。
+ */
+export function mcpContentToPiContent(content: unknown[]): ContentMappingResult {
+	const blocks: PiToolContent[] = [];
+	const notes: string[] = [];
+	const texts: string[] = [];
+
+	for (const raw of content) {
+		if (typeof raw !== "object" || raw === null) {
+			if (raw !== undefined && raw !== null) {
+				const text = stringifyUnknown(raw);
+				texts.push(text);
+				blocks.push({ type: "text", text });
+			}
+			continue;
+		}
+		const block = raw as Record<string, unknown>;
+		switch (block.type) {
+			case "text": {
+				const text = typeof block.text === "string" ? block.text : stringifyUnknown(block);
+				texts.push(text);
+				blocks.push({ type: "text", text });
+				break;
+			}
+			case "image": {
+				const image = toImageBlock(block);
+				if (image) {
+					blocks.push(image);
+					texts.push(`[图片 ${image.mimeType}]`);
+				} else {
+					const note = "[图片缺少 data/mimeType，无法传给模型]";
+					notes.push(note);
+					texts.push(note);
+					blocks.push({ type: "text", text: note });
+				}
+				break;
+			}
+			case "audio": {
+				const note = `[音频内容（${typeof block.mimeType === "string" ? block.mimeType : "未知类型"}）无法直接传给模型]`;
+				notes.push(note);
+				texts.push(note);
+				blocks.push({ type: "text", text: note });
+				break;
+			}
+			case "resource": {
+				const mapped = resourceToContent(block.resource);
+				notes.push(...mapped.notes);
+				texts.push(mapped.text);
+				blocks.push(...mapped.content);
+				break;
+			}
+			case "resource_link": {
+				const uri = typeof block.uri === "string" ? block.uri : "(无 uri)";
+				const name = typeof block.name === "string" ? block.name : undefined;
+				const note = `[资源链接${name ? ` ${name}` : ""}: ${uri}]`;
+				notes.push(note);
+				texts.push(note);
+				blocks.push({ type: "text", text: note });
+				break;
+			}
+			default: {
+				const note = `[不支持的 MCP 内容块 ${String(block.type)}: ${stringifyUnknown(block).slice(0, 200)}]`;
+				notes.push(note);
+				texts.push(note);
+				blocks.push({ type: "text", text: note });
+				break;
+			}
+		}
+	}
+
+	return { content: blocks, text: texts.join("\n"), notes };
+}
+
+function resourceToContent(rawResource: unknown): { content: PiToolContent[]; text: string; notes: string[] } {
+	if (typeof rawResource !== "object" || rawResource === null) {
+		const note = "[无效的 MCP resource 内容块]";
+		return { content: [{ type: "text", text: note }], text: note, notes: [note] };
+	}
+	const resource = rawResource as Record<string, unknown>;
+	const uri = typeof resource.uri === "string" ? resource.uri : "(无 uri)";
+	const mimeType = typeof resource.mimeType === "string" ? resource.mimeType : undefined;
+
+	if (typeof resource.text === "string") {
+		return {
+			content: [{ type: "text", text: resource.text }],
+			text: resource.text,
+			notes: [],
+		};
+	}
+	if (typeof resource.blob === "string") {
+		const image = mimeType?.startsWith("image/")
+			? toImageBlock({ data: resource.blob, mimeType })
+			: undefined;
+		if (image) {
+			return { content: [image], text: `[图片 ${mimeType}]`, notes: [] };
+		}
+		const note = `[二进制资源 ${uri}（${mimeType ?? "未知类型"}，${formatBytes(Math.floor((resource.blob.length * 3) / 4))}）未传给模型]`;
+		return { content: [{ type: "text", text: note }], text: note, notes: [note] };
+	}
+	const note = `[资源 ${uri} 没有 text/blob 内容]`;
+	return { content: [{ type: "text", text: note }], text: note, notes: [note] };
+}
+
+function toImageBlock(block: Record<string, unknown>): PiImageContent | undefined {
+	const data = typeof block.data === "string" ? block.data : undefined;
+	const mimeType = typeof block.mimeType === "string" ? block.mimeType : undefined;
+	if (!data || !mimeType) return undefined;
+	return { type: "image", data, mimeType };
+}
+
+function stringifyUnknown(value: unknown): string {
+	if (typeof value === "string") return value;
+	try {
+		const json = JSON.stringify(value);
+		return json === undefined ? String(value) : json;
+	} catch {
+		return String(value);
+	}
+}
+
+export interface TruncateOptions {
+	maxBytes?: number;
+	maxLines?: number;
+}
+
+export interface TruncateResult {
+	text: string;
+	truncated: boolean;
+	totalBytes: number;
+	totalLines: number;
+}
+
+/**
+ * 头截断：保留前 N 行 / 前 N 字节。
+ *
+ * 头截断而不是尾截断：MCP 工具返回的常见形态是一段 JSON 或一段列表，开头大概率是元信息
+ * （消息数、分页游标、schema 名），比结尾更有价值。
+ */
+export function truncateText(text: string, options: TruncateOptions = {}): TruncateResult {
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const totalBytes = Buffer.byteLength(text, "utf8");
+	const totalLines = countLines(text);
+
+	if (totalBytes <= maxBytes && totalLines <= maxLines) {
+		return { text, truncated: false, totalBytes, totalLines };
+	}
+
+	let head = text;
+	if (totalLines > maxLines) {
+		const lines = text.split("\n", maxLines);
+		head = lines.join("\n");
+	}
+	if (Buffer.byteLength(head, "utf8") > maxBytes) {
+		head = Buffer.from(head, "utf8").subarray(0, maxBytes).toString("utf8");
+		// 截在多字节字符中间时尾部会留一个替换字符，去掉它。
+		if (head.endsWith("\uFFFD")) head = head.slice(0, -1);
+	}
+
+	const keptBytes = Buffer.byteLength(head, "utf8");
+	return {
+		text:
+			`${head}\n\n[输出已截断：保留 ${formatBytes(keptBytes)} / ${totalBytes} 字节，` +
+			`${countLines(head)} / ${totalLines} 行。需要完整内容请缩小查询范围（时间区间 / limit / 关键词）后重试。]`,
+		truncated: true,
+		totalBytes,
+		totalLines,
+	};
+}
+
+function countLines(text: string): number {
+	if (text === "") return 0;
+	let lines = 1;
+	for (let index = 0; index < text.length; index += 1) {
+		if (text.charCodeAt(index) === 10) lines += 1;
+	}
+	return lines;
+}
+
+export function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/extensions/statusline/footer-suppress.test.ts

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	FOOTER_SUPPRESS_KEY,
+	FOOTER_SUPPRESS_MAX_AGE_MS,
+	releaseFooterSuppressor,
+	suppressBuiltInFooter,
+} from "./footer-suppress.ts";
+
+/** 仿 pi 的 `FooterComponent`：render 是原型方法，实例自己不带 render。 */
+class FakeFooter {
+	/** 真原版被调用的次数（断言「屏蔽期间一帧都没出真内容」用）。 */
+	originalRenders = 0;
+
+	render(width: number): string[] {
+		this.originalRenders += 1;
+		return [`pi-default#${width}`, `stats#${width}`];
+	}
+}
+
+function recordOf(): unknown {
+	return (FakeFooter.prototype as { [FOOTER_SUPPRESS_KEY]?: unknown })[FOOTER_SUPPRESS_KEY];
+}
+
+test("屏蔽期间内置 footer 渲染 0 行，解除后恢复原渲染", () => {
+	const footer = new FakeFooter();
+	const release = suppressBuiltInFooter(FakeFooter);
+	assert.equal(typeof release, "function");
+
+	assert.deepEqual(footer.render(80), []);
+	assert.deepEqual(footer.render(40), []);
+	// 屏蔽期间真原版一次都没跑 → 屏幕上不会出现默认状态行。
+	assert.equal(footer.originalRenders, 0);
+
+	release();
+	assert.deepEqual(footer.render(80), ["pi-default#80", "stats#80"]);
+	assert.equal(footer.originalRenders, 1);
+});
+
+test("解除后不留接管记录，且幂等", () => {
+	const release = suppressBuiltInFooter(FakeFooter)!;
+	release();
+	assert.equal(recordOf(), undefined);
+	assert.equal(releaseFooterSuppressor(FakeFooter), false);
+
+	// 重复解除不再改动任何东西（原型方法还是那个真原版）。
+	const before = FakeFooter.prototype.render;
+	release();
+	release();
+	assert.equal(FakeFooter.prototype.render, before);
+	assert.deepEqual(new FakeFooter().render(5), ["pi-default#5", "stats#5"]);
+});
+
+test("重复接管先交还上一次，不叠 wrapper", () => {
+	const footer = new FakeFooter();
+	const releaseFirst = suppressBuiltInFooter(FakeFooter)!;
+	assert.deepEqual(footer.render(10), []);
+
+	// 模拟 `/reload`：模块重新求值 → 新实例再打一次。
+	const releaseSecond = suppressBuiltInFooter(FakeFooter)!;
+	assert.deepEqual(footer.render(10), []);
+	assert.equal(footer.originalRenders, 0);
+
+	// 只解第二次：若还叠着第一层 wrapper，这里会继续出空行。
+	releaseSecond();
+	assert.deepEqual(footer.render(10), ["pi-default#10", "stats#10"]);
+	assert.equal(footer.originalRenders, 1);
+
+	releaseFirst();
+	assert.deepEqual(footer.render(10), ["pi-default#10", "stats#10"]);
+});
+
+test("releaseFooterSuppressor 能解除别的扩展实例留下的接管", () => {
+	suppressBuiltInFooter(FakeFooter);
+	assert.equal(new FakeFooter().render(7).length, 0);
+
+	assert.equal(releaseFooterSuppressor(FakeFooter), true);
+	assert.equal(releaseFooterSuppressor(FakeFooter), false);
+	assert.deepEqual(new FakeFooter().render(7), ["pi-default#7", "stats#7"]);
+});
+
+test("超时后自愈：交还原渲染并清掉接管记录", () => {
+	let clock = 1000;
+	const footer = new FakeFooter();
+	suppressBuiltInFooter(FakeFooter, { maxAgeMs: 500, now: () => clock });
+	assert.deepEqual(footer.render(9), []);
+
+	// 还没到点：仍然屏蔽。
+	clock = 1500;
+	assert.deepEqual(footer.render(9), []);
+
+	// 过点：自动交还，后面几帧都走真原版。
+	clock = 1501;
+	assert.deepEqual(footer.render(9), ["pi-default#9", "stats#9"]);
+	assert.equal(recordOf(), undefined);
+	assert.deepEqual(footer.render(9), ["pi-default#9", "stats#9"]);
+});
+
+test("默认兜底时长能盖住慢启动（`mcp` 握手 20s 上限），且是个正数", () => {
+	assert.ok(FOOTER_SUPPRESS_MAX_AGE_MS >= 25_000);
+});
+
+test("形状不对时什么都不做（pi 改了结构 / 传错东西）", () => {
+	assert.equal(suppressBuiltInFooter(undefined), undefined);
+	assert.equal(suppressBuiltInFooter(null), undefined);
+	assert.equal(suppressBuiltInFooter("FooterComponent"), undefined);
+	assert.equal(suppressBuiltInFooter({}), undefined);
+	assert.equal(suppressBuiltInFooter({ prototype: {} }), undefined);
+	assert.equal(suppressBuiltInFooter({ prototype: { render: "not-a-function" } }), undefined);
+});
+
+test("直接传「带 render 的对象」也能接管（不要求是 class）", () => {
+	const component = {
+		render(width: number): string[] {
+			return [`raw#${width}`];
+		},
+	};
+	const release = suppressBuiltInFooter(component);
+	assert.equal(typeof release, "function");
+	assert.deepEqual(component.render(3), []);
+
+	release();
+	assert.deepEqual(component.render(3), ["raw#3"]);
+	assert.equal(Object.prototype.hasOwnProperty.call(component, "render"), true);
+});
+
+test("原型只读时不抛错，退回原样", () => {
+	class Locked {
+		render(): string[] {
+			return ["locked"];
+		}
+	}
+	Object.defineProperty(Locked.prototype, "render", {
+		configurable: false,
+		writable: false,
+		value: () => ["locked"],
+	});
+
+	assert.equal(suppressBuiltInFooter(Locked), undefined);
+	assert.deepEqual(new Locked().render(), ["locked"]);
+});
+
+test("wrapper 的 this 透传给真原版（实例状态照常读写）", () => {
+	const footer = new FakeFooter();
+	const release = suppressBuiltInFooter(FakeFooter)!;
+	assert.deepEqual(footer.render(80), []);
+	release();
+	assert.deepEqual(footer.render(80), ["pi-default#80", "stats#80"]);
+	assert.equal(footer.originalRenders, 1);
+});

package/extensions/statusline/footer-suppress.ts

@@ -0,0 +1,135 @@
+/**
+ * footer-suppress.ts — 启动窗口内「关掉」pi 内置 footer
+ *
+ * 要解决的问题：pi 起 TUI 的顺序是 `ui.start()`（内置 footer 早已挂在 footer 容器里）→
+ * `ensureTool("fd"/"rg")` → `rebindCurrentSession()` → 才 emit `session_start`
+ * （`interactive-mode.js` 的 `init()`）。扩展拿到 ctx、能 `setFooter()` 只能等到最后一步，
+ * 而 Runner 的 `emit()` 是**串行 await** 每个扩展的 handler，排在 `statusline` 前面的扩展
+ * （本机是 `mcp`，握手要连 MCP server）还会再往后推一点。实测本机冷启动：内置 footer 在
+ * ~480ms 出第一帧，我们的 statusline 到 ~1.2s 才装上 —— 中间那 ~0.7s 底部是 pi 默认状态行
+ * （`~/path` + `0.0%/1.0M (auto) ... deepseek-flash • max`），然后整块换成 `⚡️ ...`。
+ * 用户看到的就是「先默认、后扩展」闪一下。
+ *
+ * 为什么只能在原型上解决：扩展能拿到 TUI 的最早时刻就是 `session_start`；但扩展的**模块求值 /
+ * 工厂**发生在 TUI 创建之前（扩展由 `createAgentSessionServices` → `resourceLoader.reload()`
+ * 加载，InteractiveMode 之后才 new）。所以这里在工厂里就把 `FooterComponent.prototype.render`
+ * 换掉：窗口内内置 footer 渲染 0 行（底部空着等我们的 statusline），而不是先画一个马上要变的
+ * 默认状态行。
+ *
+ * 为什么打得中：bundle 运行时，扩展解析 `@earendil-works/pi-coding-agent` 走 loader 的
+ * `virtualModules`（`dist/bundle/index.js`），与 `interactive-mode.js` 内部用的是同一个类对象
+ * （同一个 chunk）—— 和 `fenceless-code-block` 打 `Markdown.prototype` 是同一个前提；
+ * 万一打不中也只是退回原样（照旧闪一下），不会坏。
+ *
+ * 约束：
+ *   - 只换 `prototype.render`，不碰实例、不碰 pi 内部状态，也不动 children；
+ *   - 幂等且可解除：`/reload` 会重新求值模块，新实例先解开旧实例的接管再打自己的；
+ *   - `maxAgeMs` 兜底：万一我们的 footer 始终没装上（扩展报错、非 TUI 模式），到点自动交还，
+ *     回到 pi 默认行为，不会让底部永远空着；
+ *   - 任何一步抛错都当作「没打上」，绝不把异常漏给宿主。
+ */
+
+/** 挂在 footer 原型上的接管记录键（全局符号注册表：`/reload` 后新扩展实例也能看到旧实例的接管）。 */
+export const FOOTER_SUPPRESS_KEY: symbol = Symbol.for("litellm-any.pi-statusline.footerSuppress");
+
+/**
+ * 兜底时长：正常 `session_start` 远早于它解除，只有交接失败才会走到这里。
+ * 取 30s 是因为我们排在别的扩展后面 —— `Runner.emit()` 串行 await，`mcp`（字母序在前）
+ * 只在握手全部结束后才轮到我们，握手本身的上限就是 20s。
+ */
+export const FOOTER_SUPPRESS_MAX_AGE_MS = 30_000;
+
+/** 本模块用到的 `FooterComponent` 形状（不 import pi，单测直接塞假类）。 */
+export interface FooterClassLike {
+	prototype: { render(width: number): string[] };
+}
+
+interface SuppressRecord {
+	release: () => void;
+}
+
+/**
+ * 接管记录挂在哪：优先 `target.prototype`（真正被改的那个对象），退而求其次用 target 自身。
+ * 传类或传原型都能用；形状对不上返回 undefined（那就什么都不做）。
+ */
+export function suppressTarget(target: unknown): { render(width: number): string[] } | undefined {
+	const kind = typeof target;
+	if (target === null || (kind !== "object" && kind !== "function")) return undefined;
+	for (const candidate of [(target as { prototype?: unknown }).prototype, target]) {
+		if (
+			candidate !== null &&
+			typeof candidate === "object" &&
+			typeof (candidate as { render?: unknown }).render === "function"
+		) {
+			return candidate as { render(width: number): string[] };
+		}
+	}
+	return undefined;
+}
+
+/** 解除 `target` 上现有的接管（可能是别的扩展实例遗留的）。返回是否解掉了什么。 */
+export function releaseFooterSuppressor(target: unknown): boolean {
+	try {
+		const holder = suppressTarget(target) as { [FOOTER_SUPPRESS_KEY]?: SuppressRecord } | undefined;
+		const record = holder?.[FOOTER_SUPPRESS_KEY];
+		if (!record || typeof record.release !== "function") return false;
+		record.release();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * 把 `footerClass.prototype.render` 换成「返回 0 行」，返回解除函数（幂等）。
+ *
+ * 解除（或超过 `maxAgeMs`）后原型恢复原样，渲染透传；重复接管会先交还上一次，不会叠 wrapper。
+ * 形状不对 / 原型只读时返回 undefined（调用方按「没打上」处理，行为退回原样）。
+ */
+export function suppressBuiltInFooter(
+	footerClass: unknown,
+	options: { maxAgeMs?: number; now?: () => number } = {},
+): (() => void) | undefined {
+	const target = suppressTarget(footerClass);
+	if (!target) return undefined;
+	// 先解除已有接管（自己重入 / 上一个扩展实例遗留），拿到的才是真原版。
+	releaseFooterSuppressor(target);
+
+	const originalRender = target.render;
+	const maxAgeMs = options.maxAgeMs ?? FOOTER_SUPPRESS_MAX_AGE_MS;
+	const now = options.now ?? Date.now;
+	const armedAt = now();
+	const hadOwnRender = Object.prototype.hasOwnProperty.call(target, "render");
+	const state: { released: boolean; record?: SuppressRecord } = { released: false };
+
+	const release = (): void => {
+		if (state.released) return;
+		state.released = true;
+		try {
+			const holder = target as { [FOOTER_SUPPRESS_KEY]?: SuppressRecord };
+			if (state.record && holder[FOOTER_SUPPRESS_KEY] === state.record) delete holder[FOOTER_SUPPRESS_KEY];
+			if (hadOwnRender) target.render = originalRender;
+			else delete (target as { render?: unknown }).render;
+		} catch {
+			// 原型只读 / 已被换掉：wrapper 自己会因 released 标志透传，不再屏蔽。
+		}
+	};
+
+	const wrapper = function (this: unknown, width: number): string[] {
+		if (state.released) return originalRender.call(this, width);
+		if (now() - armedAt > maxAgeMs) {
+			release();
+			return originalRender.call(this, width);
+		}
+		return [];
+	};
+
+	try {
+		target.render = wrapper;
+		state.record = { release };
+		(target as { [FOOTER_SUPPRESS_KEY]?: SuppressRecord })[FOOTER_SUPPRESS_KEY] = state.record;
+	} catch {
+		return undefined;
+	}
+	return release;
+}

package/extensions/statusline/index.ts

@@ -31,12 +31,18 @@
  * 清掉所有 `setStatus`，新会话 `session_start` 才让我们重装 —— 中间那几十毫秒会真的出帧，
  * 于是底部「闪」一下。本扩展用 `footer-guard.ts` 在渲染路径上把这段窗口冻住（重放上一帧的
  * 行），原因与约束见那个文件的头注释；关掉它只需把 `PI_STATUSLINE_FREEZE` 设为 `off`。
+ *
+ * 启动那一段（进程刚起来、`session_start` 还没轮到我们）走的是另一条路：`footer-suppress.ts`
+ * 在扩展工厂里就把 `FooterComponent.prototype.render` 换成返回 0 行，内置 statusline 一帧
+ * 都不出现（原因、时机与兜底见那个文件的头注释）。它由 `PI_STATUSLINE_BOOT_SUPPRESS=off` 关闭。
  */
 
+import { FooterComponent as PiFooterComponent } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { readGitDiffStat } from "./git.ts";
 import { findRenderContainer, freezeFooterContainer, releaseFooterGuard } from "./footer-guard.ts";
+import { suppressBuiltInFooter } from "./footer-suppress.ts";
 import {
 	STATUSLINE_KEY,
 	ELLIPSIS,
@@ -47,6 +53,7 @@ import {
 const GIT_POLL_INTERVAL_MS = 30_000;
 const GIT_DEBOUNCE_MS = 400;
 const FROZEN_DISABLED = (process.env.PI_STATUSLINE_FREEZE ?? "").trim().toLowerCase() === "off";
+const BOOT_SUPPRESS_DISABLED = (process.env.PI_STATUSLINE_BOOT_SUPPRESS ?? "").trim().toLowerCase() === "off";
 
 /** footer 容器要的是这个组件对象；只要 render/dispose 形状，便于在守卫里按身份比对。 */
 interface FooterComponent {
@@ -56,6 +63,11 @@ interface FooterComponent {
 }
 
 export default function statusline(pi: ExtensionAPI) {
+	// 工厂在 TUI 创建之前跑，所以这里就能把内置 footer 静音：窗口内它渲染 0 行，
+	// 等下面 `installFooter` 把我们的组件挂上去再交还（见 footer-suppress.ts）。
+	const releaseBuiltInFooter: (() => void) | undefined = BOOT_SUPPRESS_DISABLED
+		? undefined
+		: suppressBuiltInFooter(PiFooterComponent);
 	let generation = 0;
 	let activeTarget: { cwd: string; generation: number } | undefined;
 	let requestRender: (() => void) | undefined;
@@ -155,10 +167,15 @@ export default function statusline(pi: ExtensionAPI) {
 		ctx.ui.setStatus(STATUSLINE_KEY, undefined);
 		if (!activeTarget) {
 			requestRender = undefined;
+			// print / rpc 模式没有 footer，不会有人来装，直接交还内置那只。
+			releaseBuiltInFooter?.();
 			return;
 		}
 		const target = activeTarget;
 
+		// 挂上我们的组件前先交还内置那只：两条语句之间是同一个同步块，出不了帧。
+		// 放在 `setFooter` 之前（而不是之后）是为了万一它抛错也不会让底部空着。
+		releaseBuiltInFooter?.();
 		ctx.ui.setFooter((tui, theme, footerData) => {
 			requestRender = () => tui.requestRender();
 			tuiHandle = tui;