@bachi/pi-coder 1.0.0

package/extensions/read-path-collapse.ts

@@ -0,0 +1,474 @@
+/**
+ * read-path-collapse — read 工具调用标题行的路径压缩：**永远一行**，超宽时用 `…` 前缀
+ * 表示被省略的前缀，把**文件名尾部**显示完整。
+ *
+ * 要解决的问题：pi 内置 read 的标题行是 `read <路径>:<行号>`，路径由 pi-tui 的
+ * `Text`（`wrapTextWithAnsi`）折行 —— 那是**贪心词折行**，装不进当前行剩余空间的词会被
+ * **整块挑到下一行**再去断。长路径是一整个「词」（中间没有空格），于是实测 79 列终端上
+ *
+ *     read
+ *     ~/.pi/agent/npm/node_modules/@earendil-works/pi-coding-agent/dist/core/extensions/loader.js:62-116
+ *
+ * 会渲成 `read` 单独一行（首行只有 4 列、行尾白白空着七十多列）+ 路径从中间断成两截。
+ * 和 `bash-command-collapse.ts` 里 `$ cp <78 列路径>` 那个「提前折行」是同一个根因，
+ * 只是 bash 那边选择 break-all 硬折行（命令正文要尽量完整可见），这里选择**压缩到一行**：
+ * 路径的信息量集中在**尾部**（文件名 + 最后几级目录），前面的 `~/.pi/agent/npm/...`
+ * 那串前缀谁都知道，宁可省掉前缀也不要占两行。
+ *
+ * ## 结果形态
+ *
+ *     Read …@earendil-works/pi-coding-agent/dist/core/extensions/loader.js:62-116
+ *
+ * - `Read ` 前缀（`toolTitle` 色 + 粗体）与 `:62-116` 行号区间（`warning` 色）原样保留；
+ * - 路径用 `text` 色（与 `tool-diff.ts` 的 `Edit <path>` 同一约定），**不是 pi 内置的
+ *   `accent`**：pi 的 `renderToolPath()` 给路径上的是 `accent`，而标题行是「动词 + 路径」
+ *   并排 —— 只要皮肤的 `accent` 与 `toolTitle` 取同一个调色板色（catppuccin 的 mauve），
+ *   两段就完全同色、看不出层次。所以**装得下的短路径也换色**（见 `recolorToolPath`）；
+ * - 路径从**尾部**往前装：一级一级目录往左加，装到恰好放不下为止，前面补一个 `…`；
+ * - 装得下时（短路径）**结构完全不动 pi 的原始渲染**（只把路径颜色从 `accent` 换成 `text`），包括
+ *   OSC 8 可点击超链接；
+ * - 极窄终端下连最后一级目录都装不下时，按 grapheme 从右往左硬截（emoji / 组合字符
+ *   不会被切成两半，CJK 按 2 列计）。
+ *
+ * ## 工具名首字母大写（`Read`）
+ *
+ * pi 内置 read 渲染器写的是小写 `read`，本扩展显示成 `Read` —— 与 `tool-diff.ts` 的
+ * `Edit` / `Write` 同一约定（仿 Claude Code 的工具标题观感），**只改显示形态**：注册名、
+ * 路由、session 记录里的原文都不动。三种动词形态（`read <路径>:<行号>` /
+ * `read docs <标签>` / `read resource <标签>`）与压缩后自绘的标题都覆盖；`[skill] <目录名>`
+ * 形态里没有这个词，原样保留。替换只发生在**动词段**内、且只动**第一行**
+ * （`capitalizeReadVerb` / `capitalizeReadTitle`），读一个名字里带 `read` 的文件、或折到行首的
+ * `read ` 片段都不会被误改。`/read-collapse off` 只关长路径压缩，工具名照样大写。
+ *
+ * ## 只在需要压缩时才接管渲染（不重写整个 renderCall）
+ *
+ * 做法是**后处理** pi 渲好的组件：先委托内置 `readRenderers.renderCall` 拿到那个 `Text`，
+ * 在 `render(width)` 里渲染它；**≤ 1 行就原样返回**（pi 的配色、`~` 缩写、OSC 8 超链接、
+ * `[skill]` / `read docs` / `read resource` 紧凑形态、`(ctrl+o to expand)` 提示全部保留），
+ * **> 1 行才自己重建一行压缩标题**。这样短路径（绝大多数 read）走的还是 pi 的原生渲染，
+ * 本扩展不引入任何行为差异；只有真正超宽的那部分才换成压缩形态。
+ *
+ * 两个必须注意的坑：
+ *   1. **`lastComponent` 必须传内层 `Text`，不能传我们自己的 wrapper** —— 内置 read.js 是
+ *      `context.lastComponent ?? new Text("", 0, 0)` 然后 `setText()`；pi 会把上一次
+ *      renderCall 的返回值（我们的 wrapper）当 lastComponent 传回来，wrapper 没有 setText，
+ *      于是 renderCall 抛异常，而 `updateDisplay()` 的 try/catch 会**静默退回**
+ *      `createCallFallback()` —— 标题只剩一个光秃秃的 `read`，路径全丢。所以内层组件存在
+ *      `context.state.innerText` 里跨次复用（与 `bash-command-collapse.ts` 的
+ *      `state.innerComponent` 同一套做法）。
+ *   2. **OSC 8 超链接的开关不能读我们自己那份 pi-tui 的 `getCapabilities()`** —— 扩展
+ *      import 到的 pi-tui 是 loader alias 指向的 npm/dist 副本，pi 运行时（bundle）调的
+ *      `setCapabilityOverrides(settings)` 只改 bundle 那份的缓存，副本按环境变量自己检测，
+ *      两边可能不一致（终端不支持 OSC 8 时副本却判 true → 链接文本被吞）。所以改成
+ *      **从 pi 渲出来的标题里探测**：pi 的标题串里出现 `\x1b]8;;` 就说明它启用了超链接，
+ *      我们再用 pi-tui 的 `hyperlink()`（纯字符串拼接函数，不查能力）复刻同一个 URL。
+ *
+ * ## 紧凑形态（`[skill]` / `read docs` / `read resource`）
+ *
+ * pi 对 SKILL.md、pi 自己的 README/docs/examples、AGENTS.md/CLAUDE.md 这几类文件不显示
+ * 完整路径，而是显示 `[skill] <目录名>` / `read docs <相对标签>` / `read resource <相对路径>`
+ * （`getCompactReadClassification`，模块私有）。这些标签通常很短，但 `read resource` 的
+ * 标签是**相对 cwd 的路径**，一样可能超宽。所以压缩分支把这三种形态一并复刻
+ * （`getReadmePath()` 是包根导出的，docs 判定与 pi 同源），压缩的只是标签本身，前缀与
+ * `(ctrl+o to expand)` 提示保留。
+ *
+ * 提示行里的键名**绝不能 import pi 的 `keyHint` / `keyText`**：实测 `keyHint` 抛
+ * `Theme not initialized`（读的是 npm/dist 副本自己的 theme 单例，pi 只初始化了 bundle 那份）、
+ * `keyText` 返回空串（副本的 keybindings 表是空的），而 renderCall 抛异常会被 pi 静默 catch
+ * 退回 fallback。所以从 `~/.pi/agent/keybindings.json` 读 `app.tools.expand`，读不到用默认
+ * `ctrl+o`（与 `bash-command-collapse.ts` 的 `expandKeyText()` 同一套做法）。
+ * 终端窄到给标签留不出 `MIN_LABEL_WIDTH` 列时，先丢掉提示行再算一遍预算 —— 提示是说明性的，
+ * 文件名更重要。
+ *
+ * ## 展开态（ctrl+o）
+ *
+ * `context.expanded` 为 true 时 pi 不做紧凑形态判定（一律走完整路径），本扩展同样只在
+ * 超宽时压缩，规则完全一致 —— 折叠态与展开态的折行规则必须一致，否则展开态又会提前折行。
+ * 注意展开态**不影响文件内容**的显示（那是 renderResult 的事，本扩展不碰 renderResult）。
+ *
+ * 纯显示层：发给模型的 tool call 参数、session 记录里的原文、read 的执行逻辑完全不变
+ * （`execute` / `parameters` / `description` / `promptSnippet` / `promptGuidelines` /
+ * `constrainedSampling` 全部由 `{ ...base }` 从 `createReadToolDefinition()` 原样继承）。
+ *
+ * 用法：
+ *   /read-collapse          查看当前状态
+ *   /read-collapse off      关闭压缩（回到 pi 的贪心折行，长路径占两行）
+ *   /read-collapse on       打开压缩（默认）
+ *   PI_READ_COLLAPSE=off    启动时就关闭
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createReadToolDefinition, getReadmePath } from "@earendil-works/pi-coding-agent";
+import { hyperlink, Text, visibleWidth } from "@earendil-works/pi-tui";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** 省略前缀的标记。1 列宽，`visibleWidth` 量出来就是 1。 */
+const ELLIPSIS = "…";
+/** 紧凑形态下给标签留的最少列数，低于它就丢掉 `(ctrl+o to expand)` 提示再算一遍预算。 */
+const MIN_LABEL_WIDTH = 12;
+/** pi 判定为「紧凑形态」的资源文件名（照抄 read.js 的 COMPACT_RESOURCE_FILE_NAMES）。 */
+const COMPACT_RESOURCE_FILE_NAMES = new Set(["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
+
+/** grapheme 分段器（pi-tui 没导出它自己的实例，本地建一个；Node 内置 Intl.Segmenter）。 */
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** pi 的 agent 目录（`PI_CODING_AGENT_DIR` 可覆盖，否则 `~/.pi/agent`）。 */
+function resolveAgentDir(): string {
+	const envDir = process.env.PI_CODING_AGENT_DIR;
+	return envDir ? (envDir.startsWith("~") ? join(homedir(), envDir.slice(1)) : envDir) : join(homedir(), ".pi", "agent");
+}
+
+/**
+ * `app.tools.expand` 的键名文本（默认 `ctrl+o`）。
+ *
+ * 不能用 pi 导出的 `keyText` / `keyHint`，理由见文件头「紧凑形态」一节。
+ */
+function expandKeyText(): string {
+	try {
+		const parsed = JSON.parse(readFileSync(join(resolveAgentDir(), "keybindings.json"), "utf8"));
+		const bound = parsed?.["app.tools.expand"];
+		const keys = Array.isArray(bound) ? bound : [bound];
+		const text = keys.filter((k: unknown): k is string => typeof k === "string" && k.trim() !== "").join("/");
+		if (text) return text;
+	} catch {
+		// 没配置文件 / 解析失败 / 没绑这个键，都用默认值
+	}
+	return "ctrl+o";
+}
+
+/** pi 的 `str()`：string 原样，null/undefined → ""，其它类型 → null（= invalid arg）。 */
+function strArg(value: unknown): string | null {
+	if (typeof value === "string") return value;
+	if (value == null) return "";
+	return null;
+}
+
+/** pi 的 `shortenPath()`：`$HOME` 前缀换成 `~`（注意 pi 用的是裸 startsWith，不要求分隔符）。 */
+function shortenPath(path: string): string {
+	const home = homedir();
+	if (home && path.startsWith(home)) return `~${path.slice(home.length)}`;
+	return path;
+}
+
+/**
+ * 复刻 `resolveToCwd()` 里我们用得上的那部分：剥 `@` 前缀、展开 `~`、相对 cwd 解析。
+ * pi 还会归一 Unicode 空格（macOS 截图文件名那些窄不换行空格），这里跳过 ——
+ * 它只影响文件名里带特殊空格的路径，且我们只用它来算 OSC 8 的 URL 与紧凑形态判定。
+ */
+function resolveAgainstCwd(rawPath: string, cwd: string): string {
+	let normalized = rawPath;
+	if (normalized.startsWith("@")) normalized = normalized.slice(1);
+	if (normalized === "~") return homedir();
+	if (normalized.startsWith("~/")) return join(homedir(), normalized.slice(2));
+	return isAbsolute(normalized) ? resolvePath(normalized) : resolvePath(cwd, normalized);
+}
+
+/** pi 的 `getCwdRelativePath()`：cwd 内返回相对路径，否则 undefined。 */
+function cwdRelativePath(filePath: string, cwd: string): string | undefined {
+	const resolvedCwd = resolvePath(cwd);
+	const resolved = resolvePath(filePath, resolvedCwd);
+	const rel = relative(resolvedCwd, resolved);
+	const inside = rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+	return inside ? rel || "." : undefined;
+}
+
+/** pi 的 `formatPathRelativeToCwdOrAbsolute()`：cwd 内给相对路径，否则绝对路径，一律 posix 分隔符。 */
+function pathRelativeToCwdOrAbsolute(filePath: string, cwd: string): string {
+	const absolutePath = resolvePath(filePath, cwd);
+	return (cwdRelativePath(absolutePath, cwd) ?? absolutePath).split(sep).join("/");
+}
+
+/** pi 的 `getPiDocsClassification()`：pi 包内的 README.md / docs/** / examples/**。 */
+function piDocsLabel(absolutePath: string): string | undefined {
+	try {
+		const packageRoot = dirname(getReadmePath());
+		const rel = relative(resolvePath(packageRoot), resolvePath(absolutePath));
+		if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+		const label = rel.split(sep).join("/");
+		if (label === "README.md" || label.startsWith("docs/") || label.startsWith("examples/")) return label;
+	} catch {
+		// getReadmePath() 抛了就放弃 docs 判定（回落到完整路径形态）
+	}
+	return undefined;
+}
+
+interface CompactClassification {
+	kind: "skill" | "docs" | "resource";
+	label: string;
+}
+
+/** 复刻 pi 的 `getCompactReadClassification()`（模块私有，只能照抄）。 */
+function getCompactClassification(args: any, cwd: string): CompactClassification | undefined {
+	const rawPath = strArg(args?.path);
+	if (!rawPath) return undefined;
+	const absolutePath = resolveAgainstCwd(rawPath, cwd);
+	const fileName = basename(absolutePath);
+	if (fileName === "SKILL.md") return { kind: "skill", label: basename(dirname(absolutePath)) || fileName };
+	const docsLabel = piDocsLabel(absolutePath);
+	if (docsLabel) return { kind: "docs", label: docsLabel };
+	if (COMPACT_RESOURCE_FILE_NAMES.has(fileName)) return { kind: "resource", label: pathRelativeToCwdOrAbsolute(absolutePath, cwd) };
+	return undefined;
+}
+
+/** pi 的 `formatReadLineRange()`：`:62-116`（warning 色），offset/limit 都没给就返回 ""。 */
+function formatReadLineRange(args: any, theme: any): string {
+	if (args?.offset === undefined && args?.limit === undefined) return "";
+	const startLine = args.offset ?? 1;
+	const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
+	return theme.fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+}
+
+/**
+ * 按 grapheme 从**右**往左取，取到装满预算为止。
+ * 用于极窄终端下连最后一级目录都装不下的兜底 —— 按列硬切会把 emoji / 组合字符切成两半，
+ * 宽字符（CJK 等，2 列）装不进剩下的 1 列时就在它前面停（留 1 列空白），一个 grapheme 不可分。
+ */
+function tailGraphemes(text: string, budget: number): string {
+	if (budget <= 0) return "";
+	let out = "";
+	let used = 0;
+	for (const { segment } of [...graphemeSegmenter.segment(text)].reverse()) {
+		const w = visibleWidth(segment);
+		if (used + w > budget) break;
+		out = segment + out;
+		used += w;
+	}
+	return out;
+}
+
+/**
+ * 路径压缩：装得下就原样返回；装不下就从**尾部**往前一级一级加目录，前面补 `…`。
+ *
+ * 刻意保留尽量多的尾部层级而不是只留文件名：同样的列预算，
+ * `…core/extensions/loader.js` 比 `…loader.js` 更能说明读的是哪个文件（同名文件很常见）。
+ */
+function compressTail(text: string, budget: number): string {
+	const width = Math.max(1, Math.floor(budget));
+	if (visibleWidth(text) <= width) return text;
+	const ellipsisWidth = visibleWidth(ELLIPSIS);
+	// macOS / Linux 是 `/`；Windows 的 `~C:\...` 也照办（pi 的 shortenPath 不改分隔符）
+	const separator = text.includes("/") ? "/" : "\\";
+	const segments = text.split(separator);
+	let tail = "";
+	for (let i = segments.length - 1; i >= 0; i--) {
+		const candidate = tail ? `${segments[i]}${separator}${tail}` : segments[i];
+		if (visibleWidth(candidate) + ellipsisWidth > width) break;
+		tail = candidate;
+	}
+	if (!tail) {
+		// 连最后一级目录都装不下：按 grapheme 从右往左硬截
+		return ELLIPSIS + tailGraphemes(segments[segments.length - 1] ?? "", width - ellipsisWidth);
+	}
+	return ELLIPSIS + tail;
+}
+
+/**
+ * 探测 pi 有没有启用 OSC 8 超链接：看它渲出来的标题串里有没有 `\x1b]8;;`。
+ * 理由见文件头 —— 不能读副本自己的 `getCapabilities()`。
+ * `inner.text` 是 `Text` 的私有字段（TS 层面 private，运行时可读）；拿不到就退回渲染行。
+ */
+function piTitleUsesHyperlink(inner: any, lines: string[]): boolean {
+	const raw = typeof inner?.text === "string" ? inner.text : lines.join("\n");
+	return raw.includes("\x1b]8;;");
+}
+
+/**
+ * 前景色重置序列 —— `theme.fg()` 的每个色段都以它收尾，所以行内第一个它标着**动词段的结束**。
+ */
+const FG_RESET = "\x1b[39m";
+
+/** SGR 序列（`theme.fg()` / `theme.bold()` 发出的那些），只用于量可见文本。 */
+const SGR_SEQUENCE = /\x1b\[[0-9;]*m/g;
+
+/**
+ * 把标题行里的动词 `read` 换成大写的 `Read`（详见文件头「工具名首字母大写」一节）。
+ *
+ * 只在**动词段**（行首到第一个 `\x1b[39m`，与 `recolorToolPath` 同一套定位）里动手，并在
+ * 剥掉 SGR 后要求这段可见文本恰好是 `read` 或以 `read ` 开头：
+ *   - `read <路径>` / `read docs <标签>` / `read resource <标签>` 命中；
+ *   - `[skill] <目录名>` 的动词段是 `[skill]`，不含这个词，原样返回；
+ *   - 颜色被关掉（没有 ANSI）时动词段退化成整行，同一条件仍能把 `readme.md` 这类
+ *     以 `read` 开头却没有空格的续行排除在外；命中时行内第一个 `read` 必然是动词本身。
+ */
+function capitalizeReadVerb(line: string): string {
+	const verbEnd = line.indexOf(FG_RESET);
+	const head = verbEnd === -1 ? line : line.slice(0, verbEnd);
+	const visible = head.replace(SGR_SEQUENCE, "");
+	if (visible !== "read" && !visible.startsWith("read ")) return line;
+	const at = head.indexOf("read");
+	return head.slice(0, at) + "Read" + line.slice(at + "read".length);
+}
+
+/**
+ * 标题行数组的入口：**只动第一行**。动词只可能出现在第一行；续行全是路径 / 标签，
+ * 那里以 `read ` 开头的片段（带空格的目录名 / 文件名被折到行首）不能被误改成大写。
+ */
+function capitalizeReadTitle(lines: string[]): string[] {
+	if (lines.length === 0) return lines;
+	const [first, ...rest] = lines;
+	return [capitalizeReadVerb(first), ...rest];
+}
+
+/**
+ * 把 pi 渲染出来的标题行里的**路径**颜色从 `accent` 换成 `text`。
+ *
+ * 为什么是**替换 SGR** 而不是自己重建整行：这一支（装得下的短路径）刻意保留 pi 的原生
+ * 渲染 —— 折行、OSC 8 超链接、`[skill]` / `read docs` / `read resource` 紧凑形态、
+ * `(ctrl+o to expand)` 提示全都由 pi 自己决定，本扩展只改一个颜色。pi 的 read 标题里
+ * `accent` 只用在路径上（`renderToolPath()`）或紧凑形态的标签上（`formatCompactReadCall`
+ * 的 docs / resource 分支），`skill` 形态的标签走 `customMessageText`，不受影响。
+ *
+ * **只换动词之后那一段**：动词（`read`）是整行的第一个色段，第一个 `\x1b[39m` 就是它的
+ * 结尾；后面的 `accent` 才是路径。这一步不是耍小聪明 —— 皮肤把 `accent` 与 `toolTitle` 设成
+ * 同一个调色板色时（上游 catppuccin 的 mauve 就是）整行直接替换会把动词一起换成 `text`，
+ * 两段仍旧同色，正好就是本扩展要消掉的那个症状。
+ *
+ * 两个色相同时（皮肤把 `accent` 和 `text` 设成同一个色）直接原样返回，不做无谓改写 ——
+ * `getFgAnsi` 拿到的就是 pi 自己会发的那个序列（truecolor / 256 色两种模式都对得上）。
+ */
+function recolorToolPath(line: string, theme: any): string {
+	const accent = theme.getFgAnsi("accent");
+	const text = theme.getFgAnsi("text");
+	if (!accent || accent === text) return line;
+	const verbEnd = line.indexOf(FG_RESET);
+	if (verbEnd === -1) return line.split(accent).join(text);
+	const cut = verbEnd + FG_RESET.length;
+	return line.slice(0, cut) + line.slice(cut).split(accent).join(text);
+}
+
+/** 压缩后的完整路径形态：`read …<尾部路径>:<行号>`。 */
+function compressedPathTitle(args: any, theme: any, cwd: string, budget: number, hyperlinksEnabled: boolean): string {
+	const prefix = `${theme.fg("toolTitle", theme.bold("Read"))} `;
+	const range = formatReadLineRange(args, theme);
+	const rawPath = strArg(args?.path);
+	// 与 pi 的 renderToolPath 对齐：null → `[invalid arg]`，空串 → `...`（toolOutput 色）
+	if (rawPath === null) return `${prefix}${theme.fg("error", "[invalid arg]")}${range}`;
+	if (!rawPath) return `${prefix}${theme.fg("toolOutput", "...")}${range}`;
+	const styled = theme.fg("text", compressTail(shortenPath(rawPath), budget - visibleWidth(prefix) - visibleWidth(range)));
+	const display = hyperlinksEnabled ? hyperlink(styled, pathToFileURL(resolveAgainstCwd(rawPath, cwd)).href) : styled;
+	return prefix + display + range;
+}
+
+/** 压缩后的紧凑形态：`[skill] …<标签>` / `read docs …<标签>` / `read resource …<标签>`。 */
+function compressedCompactTitle(
+	classification: CompactClassification,
+	args: any,
+	theme: any,
+	budget: number,
+	hyperlinksEnabled: boolean,
+	cwd: string,
+): string {
+	const range = formatReadLineRange(args, theme);
+	const hint = theme.fg("dim", ` (${expandKeyText()} to expand)`);
+	const isSkill = classification.kind === "skill";
+	const prefix = isSkill
+		? theme.fg("customMessageLabel", "\x1b[1m[skill]\x1b[22m ")
+		: `${theme.fg("toolTitle", theme.bold(`Read ${classification.kind}`))} `;
+	// 先带提示算预算；窄到给标签留不出 MIN_LABEL_WIDTH 列就丢掉提示再算一遍
+	let suffix = hint;
+	let labelBudget = budget - visibleWidth(prefix) - visibleWidth(range) - visibleWidth(hint);
+	if (labelBudget < MIN_LABEL_WIDTH) {
+		suffix = "";
+		labelBudget = budget - visibleWidth(prefix) - visibleWidth(range);
+	}
+	const styled = theme.fg(isSkill ? "customMessageText" : "text", compressTail(classification.label, labelBudget));
+	// docs / resource 的标签是包内路径，同样给超链接（skill 的标签是目录名，不是路径，不给）
+	const display =
+		hyperlinksEnabled && !isSkill
+			? hyperlink(styled, pathToFileURL(resolveAgainstCwd(classification.label, cwd)).href)
+			: styled;
+	return prefix + display + range + suffix;
+}
+
+/**
+ * 包一层组件：pi 渲出来 ≤ 1 行就原样返回，> 1 行才换成压缩标题。
+ * 压缩结果按宽度缓存 —— `render(width)` 每帧都调，终端 resize 时自动重算。
+ */
+function createCollapsedCallComponent(
+	inner: any,
+	options: { args: any; theme: any; cwd: string; expanded: boolean; isEnabled: () => boolean },
+) {
+	const cache = new Map<number, string[]>();
+	return {
+		render(width: number): string[] {
+			const lines: string[] = inner.render(width);
+			// 关闭开关 → 回到 pi 的原生渲染（含路径颜色，见 `/read-collapse off`）；工具名照旧大写
+			if (!options.isEnabled()) return capitalizeReadTitle(lines);
+			// 没超宽（短路径，绝大多数 read）→ 只把路径的颜色换成 `text`，其余原样交给 pi
+			if (lines.length <= 1) return capitalizeReadTitle(lines.map((line) => recolorToolPath(line, options.theme)));
+			const fixedWidth = visibleWidth(`${options.theme.fg("toolTitle", options.theme.bold("Read"))} `) + visibleWidth(ELLIPSIS);
+			if (width - fixedWidth < 1) return capitalizeReadTitle(lines);
+			const hit = cache.get(width);
+			if (hit) return hit;
+			const hyperlinksEnabled = piTitleUsesHyperlink(inner, lines);
+			const classification = options.expanded ? undefined : getCompactClassification(options.args, options.cwd);
+			const line = classification
+				? compressedCompactTitle(classification, options.args, options.theme, width, hyperlinksEnabled, options.cwd)
+				: compressedPathTitle(options.args, options.theme, options.cwd, width, hyperlinksEnabled);
+			// 极窄终端兜底：固定部分（前缀 + 行号区间，或紧凑形态的提示行）本身就比整行还宽时，
+			// 压缩后的标题仍然会超宽 —— 那时 pi 自己的折行渲染同样难看，没有更好的选择，直接交回去。
+			if (visibleWidth(line) > width) return capitalizeReadTitle(lines);
+			const out = [line];
+			cache.set(width, out);
+			return out;
+		},
+		invalidate() {
+			cache.clear();
+			inner.invalidate?.();
+		},
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	let enabled = process.env.PI_READ_COLLAPSE?.trim().toLowerCase() !== "off";
+
+	// cwd 只是兜底：内置 execute 用的是 ctx.cwd（每次调用的当前 session cwd），
+	// renderCall 也用 context.cwd，不读这里这个值。
+	const base = createReadToolDefinition(process.cwd());
+
+	const statusText = () => (enabled ? "长路径压缩到一行（`Read …<尾部>:<行号>`），装得下时原样用 pi 的渲染" : "已关闭（回到 pi 的贪心折行，长路径会占两行）");
+
+	pi.registerTool({
+		// 用展开而不是逐字段抄：`description` / `parameters` / `promptSnippet` /
+		// `promptGuidelines` / `constrainedSampling` / `execute` 全部原样继承
+		// （prompt 元数据不会自动继承，必须显式带上）。
+		...base,
+		renderCall(args, theme, context) {
+			const state = context.state;
+			// 关键：传给内置实现的 lastComponent 必须是**内层** Text 而不是我们的 wrapper，
+			// 否则内置 `setText()` 抛异常、pi 静默退回只剩 `read` 的 fallback（见文件头）。
+			const inner = base.renderCall?.(args, theme, { ...context, lastComponent: state.innerText }) ?? new Text("", 0, 0);
+			state.innerText = inner;
+			return createCollapsedCallComponent(inner, {
+				args,
+				theme,
+				cwd: context.cwd,
+				expanded: context.expanded,
+				isEnabled: () => enabled,
+			});
+		},
+	});
+
+	pi.registerCommand("read-collapse", {
+		description: "read 标题行的长路径压缩：off | on",
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+
+			if (arg === "") {
+				ctx.ui.notify(`read 路径压缩：${statusText()}`, "info");
+				return;
+			}
+
+			if (arg !== "off" && arg !== "on") {
+				ctx.ui.notify("用法：/read-collapse off | on", "warning");
+				return;
+			}
+
+			enabled = arg === "on";
+			ctx.ui.notify(`read 路径压缩${enabled ? "已开启" : "已关闭"}，${statusText()}`, "info");
+		},
+	});
+}