@liuxincuit/pi-compact-tools 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuxincuit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# compact-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+覆盖内置的 `read` / `bash` / `edit` / `write` 四个工具，换成自绘的紧凑渲染；顺带给 bash 注入默认超时与 `.env` 环境。
+
+## 安装
+
+```bash
+pi install npm:@liuxincuit/pi-compact-tools
+```
+
+`@earendil-works/pi-coding-agent`、`@earendil-works/pi-tui` 由 pi 宿主提供，不需要额外安装。
+装完 `/reload` 后生效。
+
+注意它不只改渲染，还会改 bash 的行为：默认 120 秒超时、注入 `~/.pi/agent/.env`、移除代理变量。细节与理由见下节。
+
+从源码调试时用本地路径安装（在仓库根执行）：
+
+```bash
+pi install ./packages/compact-tools
+```
+
+## 做什么
+
+- **紧凑渲染**：四个工具改为 `renderShell: "self"`，自绘调用行与结果行。成功命令无输出时折叠成一行，失败或展开时才铺开全文。执行期间用 spinner + 耗时提示（按 `toolCallId` 分别计状态，并发工具互不干扰）。
+- **技能读取折叠**：路径末段是 `SKILL.md` 时（pi 把技能当普通文件读，只能靠文件名认），未展开渲染成单行 `│ [skill] <父目录名>  (ctrl+o to expand)`，颜色跟随成功/失败；展开后退回 `read <路径>`，保留文件位置。普通文件不受影响，仍是原来的两行 `read <路径>` + `↳ loaded N lines`。判定只看文件名、不校验目录：任何叫 `SKILL.md` 的文件都这样显示。
+- **ANSI 清洗**：剥掉工具输出里的背景色 SGR 参数，保留前景色，避免主题色串到整个终端。
+- **bash 默认超时**：LLM 没传 `timeout` 时按 `DEFAULT_BASH_TIMEOUT_SECONDS`（120 秒）执行，防止 `find` 全盘搜索之类的长驻命令无限阻塞。
+- **bash 环境注入**：从 `~/.pi/agent/.env` 读 `KEY=VALUE` 注入 bash 环境，同时移除 `HTTP_PROXY` / `HTTPS_PROXY` / `http_proxy` / `https_proxy` / `all_proxy`。
+
+## 配置
+
+| 项 | 位置 | 说明 |
+|---|---|---|
+| 环境变量 | `~/.pi/agent/.env` | `KEY=VALUE`，支持 `#` 注释、空行、单双引号；文件不存在时不改动 env |
+| 默认超时 | 源码导出的 `DEFAULT_BASH_TIMEOUT_SECONDS` | 改动需编辑源码后 `/reload` |
+
+## 调试
+
+改完必须 `/reload`。
+
+技能折叠：让模型读一个 `SKILL.md`（如本仓库的 `skills/supermap-jira/SKILL.md`），未展开应是单行 `│ [skill] supermap-jira  (ctrl+o to expand)`；按 expand 键后首行退回 `│ read <绝对路径>` 并铺开正文。读不存在的技能文件时整行转红，不出现展开提示。读普通文件应保持 `│ read <路径>` + `  ↳ loaded N lines` 两行。
+
+bash 超时：不传 `timeout` 跑 `sleep 200`，应在 120 秒时中断，且错误消息里附带默认超时的说明——用来区分“LLM 自己设的超时”和“扩展注入的默认超时”。LLM 显式传入的 `timeout` 原样透传，并保持 pi 原生的错误格式。
+
+## 陷阱
+
+**超时改不动 `spawnHook`。** `spawnHook` 只能改 `command` / `cwd` / `env`，注入默认超时得整体包装 `operations`（`createLocalBashOperations()` 保持原生行为）。
+
+**技能折叠的判定分散在两处，必须同步改。** `getDetail` 把标题行换成 `[skill] <名字>` 并挂展开提示，`getSummary` 对同一路径返回 `undefined` 省掉第二行摘要；两处共用 `skillNameFromPath`。只改一处会出现“只有名字没提示”或“提示重复两遍”。展开提示只在终态挂：`isPartial` 为真（参数流式、执行中、结果流式）不挂，`isError` 为真（没内容可展开）也不挂。
+
+**`getDetail` 的第三个参数是 pi 的渲染上下文。** `expanded` / `isPartial` / `isError` / `cwd` 都在里面，技能折叠靠它判断；返回值多出的 `label` 字段可覆盖工具默认名，其余渲染分支照用。
+
+**`renderCall` 与 `renderResult` 有明确分工。** 只在参数流式期间出调用行（那时还没有 partial result，`renderResult` 不会被调，否则模型产出参数时界面整段空白）；执行开始或已有结果时让 `renderResult` 独占，包括 `/reload` 重放历史的情况——那时不会再发 `tool_execution_start`。
+
+**要主动发一次空 partial。** `renderResult` 只在有 result 时被调用，read/edit/write 这类不产生流式输出的工具执行期间会整行不可见，所以 `execute` 开头手动 `onUpdate({ content: [], details: undefined })`。
+
+**覆盖的是工具名而非实现细节**：`name` / `description` / `parameters` 全部沿用内置工具的定义，只替换渲染与执行包装。改完必须 `/reload` 才生效。

package/index.ts

@@ -0,0 +1,567 @@
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Container, Text } from "@earendil-works/pi-tui";
+import {
+	createBashTool,
+	createEditTool,
+	createLocalBashOperations,
+	createReadTool,
+	createWriteTool,
+	formatSize,
+	keyHint,
+	type BashOperations,
+} from "@earendil-works/pi-coding-agent";
+
+const BORDER = "\u2502 "; // │
+
+const ENV_FILE = join(homedir(), ".pi", "agent", ".env");
+
+/** 解析 KEY=VALUE 格式，支持 # 注释、空行、引号；文件不存在或为空返回 {} */
+function parseEnvFile(file: string): Record<string, string> {
+	const out: Record<string, string> = {};
+	if (!existsSync(file)) return out;
+	for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+		const t = line.trim();
+		if (!t || t.startsWith("#")) continue;
+		const eq = t.indexOf("=");
+		if (eq <= 0) continue;
+		const key = t.slice(0, eq).trim();
+		let value = t.slice(eq + 1).trim();
+		if (
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))
+		) {
+			value = value.slice(1, -1);
+		}
+		out[key] = value;
+	}
+	return out;
+}
+
+/** bash 工具专属环境：移除代理变量并注入 ~/.pi/agent/.env；无 .env 时不改变 env */
+function bashEnvHook({ command, cwd, env }: { command: string; cwd: string; env: Record<string, string> }) {
+	if (!existsSync(ENV_FILE)) return { command, cwd, env };
+	const clean = { ...env };
+	for (const key of ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy", "all_proxy"]) {
+		delete clean[key];
+	}
+	Object.assign(clean, parseEnvFile(ENV_FILE));
+	return { command, cwd, env: clean };
+}
+
+/**
+ * bash 默认超时：LLM 未显式传 timeout 时按默认时长执行，防止 find 全盘搜索
+ * 之类的长驻命令无限阻塞；LLM 显式传入的 timeout 原样透传并保持 pi 原生
+ * 错误格式，只有默认注入触发的超时消息附加说明。
+ */
+export const DEFAULT_BASH_TIMEOUT_SECONDS = 120;
+
+export function createBashTimeoutOps(
+	base: BashOperations,
+	defaultTimeoutSeconds = DEFAULT_BASH_TIMEOUT_SECONDS,
+): BashOperations {
+	return {
+		exec: async (command, cwd, options) => {
+			const injected = options.timeout === undefined;
+			const timeout = injected ? defaultTimeoutSeconds : options.timeout;
+			try {
+				return await base.exec(command, cwd, { ...options, timeout });
+			} catch (err) {
+				// pi 层把 "timeout:<n>" 错误渲染为 "Command timed out after <n> seconds"，
+				// 在 <n> 后附带默认超时说明，让 LLM 区分自己设的超时和默认超时。
+				if (injected && err instanceof Error && err.message.startsWith("timeout:")) {
+					throw new Error(
+						`timeout:${defaultTimeoutSeconds} (default timeout; no explicit timeout was provided)`,
+					);
+				}
+				throw err;
+			}
+		},
+	};
+}
+
+const SPINNER_CHARS = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 200;
+
+interface SpinnerState {
+	frame: number;
+	start: number;
+	timer?: ReturnType<typeof setInterval>;
+}
+
+// Per-tool-call spinner state; keyed by toolCallId so concurrent tools spin independently.
+const spinnerStates = new Map<string, SpinnerState>();
+
+const MAX_TITLE_LEN = 100;
+const MAX_CONTENT_LINE_LEN = 80;
+
+// Commands whose successful completion normally produces no output.
+const QUIET_COMMAND_PREFIXES = [
+	"cd", "mkdir", "rmdir", "rm", "mv", "cp", "touch", "chmod", "chown",
+	"git add", "git checkout", "git switch", "git restore", "git reset", "git clean",
+	"npm install", "pnpm install", "yarn install", "bun install",
+	"pip install", "poetry install", "cargo fetch", "go mod tidy",
+] as const;
+
+function formatElapsed(ms: number): string {
+	const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+	if (totalSeconds < 60) return `${totalSeconds}s`;
+	const totalMinutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	if (totalMinutes < 60) return `${totalMinutes}m ${seconds}s`;
+	return `${Math.floor(totalMinutes / 60)}h ${totalMinutes % 60}m`;
+}
+
+function getOrCreateSpinnerState(toolCallId: string): SpinnerState {
+	let state = spinnerStates.get(toolCallId);
+	if (!state) {
+		state = { frame: 0, start: Date.now() };
+		spinnerStates.set(toolCallId, state);
+	}
+	return state;
+}
+
+function stopSpinner(toolCallId: string | undefined): void {
+	if (!toolCallId) return;
+	const state = spinnerStates.get(toolCallId);
+	if (!state) return;
+	if (state.timer) clearInterval(state.timer);
+	spinnerStates.delete(toolCallId);
+}
+
+function titleLine(
+	label: string,
+	detail: string,
+	t: any,
+	color: string,
+	parts?: Array<{ text: string; color?: string }>,
+): string {
+	const border = t.fg(color, t.bold(BORDER));
+	const suffix = (parts ?? []).map((p) => " " + t.fg(p.color ?? "muted", p.text)).join("");
+	if (color === "error") {
+		return border + t.fg(color, t.bold(label + " ")) + t.fg(color, detail) + suffix;
+	}
+	return border + t.fg(color, t.bold(label + " ")) + detail + suffix;
+}
+
+function addBorder(text: string, t: any, color?: string): string {
+	const borderColor = color ? t.fg(color, BORDER) : t.fg("border", BORDER);
+	return text.split("\n").map((l: string) => borderColor + l).join("\n");
+}
+
+function truncateDetail(detail: string): string {
+	const firstLine = detail.split("\n")[0] || "";
+	if (firstLine.length <= MAX_TITLE_LEN) return firstLine;
+	return firstLine.slice(0, MAX_TITLE_LEN - 1) + "…";
+}
+
+/** Ensure every line in text is at most maxLen characters, hard-break if needed */
+function hardWrap(text: string, maxLen: number): string {
+	return text.split("\n").map((line) => {
+		if (line.length <= maxLen) return line;
+		const chunks: string[] = [];
+		for (let i = 0; i < line.length; i += maxLen) {
+			chunks.push(line.slice(i, i + maxLen));
+		}
+		return chunks.join("\n");
+	}).join("\n");
+}
+
+function splitLines(text: string): string[] {
+	if (!text) return [];
+	return text.replace(/\r/g, "").split("\n").map((line) => line.replace(/\t/g, "    "));
+}
+
+function trimTrailingEmptyLines(lines: string[]): string[] {
+	const next = [...lines];
+	while (next.length > 0 && next[next.length - 1]?.trim().length === 0) {
+		next.pop();
+	}
+	return next;
+}
+
+function collapseConsecutiveEmptyLines(lines: string[], maxAllowed: number): string[] {
+	if (maxAllowed <= 0) {
+		return lines.filter((line) => line.trim().length > 0);
+	}
+	const compacted: string[] = [];
+	let consecutiveEmpty = 0;
+	for (const line of lines) {
+		if (line.trim().length === 0) {
+			consecutiveEmpty++;
+			if (consecutiveEmpty > maxAllowed) continue;
+		} else {
+			consecutiveEmpty = 0;
+		}
+		compacted.push(line);
+	}
+	return compacted;
+}
+
+function prepareOutputLines(text: string, expanded: boolean): string[] {
+	const lines = trimTrailingEmptyLines(splitLines(text));
+	return expanded ? lines : collapseConsecutiveEmptyLines(lines, 1);
+}
+
+function countNonEmptyLines(lines: string[]): number {
+	return lines.filter((line) => line.trim().length > 0).length;
+}
+
+function pluralize(count: number, singular: string, plural = `${singular}s`): string {
+	return count === 1 ? singular : plural;
+}
+
+function shortenPath(inputPath: string | undefined): string {
+	if (!inputPath) return "";
+	const home = homedir();
+	return inputPath.startsWith(home) ? `~${inputPath.slice(home.length)}` : inputPath;
+}
+
+/**
+ * 末段为 SKILL.md 时返回技能名（父目录名）。pi 把技能当普通文件读，
+ * 只能靠文件名区分，路径里没有别的线索；不叫 SKILL.md 的文件一律不算技能。
+ */
+function skillNameFromPath(inputPath: unknown): string | undefined {
+	if (typeof inputPath !== "string" || !inputPath) return undefined;
+	const segments = inputPath.replace(/\\/g, "/").split("/").filter((s) => s.length > 0);
+	if (segments[segments.length - 1] !== "SKILL.md") return undefined;
+	return segments[segments.length - 2] || "skill";
+}
+
+function extractTextOutput(result: any): string {
+	const blocks = Array.isArray(result?.content) ? result.content : [];
+	return blocks
+		.filter((block: any) => block?.type === "text" && typeof block.text === "string")
+		.map((block: any) => block.text)
+		.join("\n");
+}
+
+function toRecord(value: unknown): Record<string, any> {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {};
+}
+
+// --- ANSI sanitization (adapted from pi-tool-display, MIT) ---
+// Strip background SGR parameters from raw tool output so themed output
+// does not get background-color artifacts, while foreground colors survive.
+
+const ANSI_SGR_PATTERN = /\x1b\[([0-9;]*)m/g;
+const STYLE_RESET_PARAMS = [39, 22, 23, 24, 25, 27, 28, 29, 59] as const;
+
+function expandSgrReset(param: number): readonly number[] | undefined {
+	return param === 0 ? STYLE_RESET_PARAMS : undefined;
+}
+
+function toSgrParams(rawParams: string): number[] {
+	if (!rawParams.trim()) return [0];
+	return rawParams
+		.split(";")
+		.map((token) => Number.parseInt(token, 10))
+		.filter((value) => Number.isFinite(value));
+}
+
+function readSgrColorSequence(params: readonly number[], index: number): number[] | undefined {
+	const param = params[index];
+	if (param !== 38 && param !== 48) return undefined;
+	const colorMode = params[index + 1];
+	if (colorMode === 5) {
+		const colorValue = params[index + 2];
+		return typeof colorValue === "number" && Number.isFinite(colorValue) ? [param, colorMode, colorValue] : undefined;
+	}
+	if (colorMode === 2) {
+		const [red, green, blue] = [params[index + 2], params[index + 3], params[index + 4]];
+		return [red, green, blue].every((v) => typeof v === "number" && Number.isFinite(v))
+			? [param, colorMode, red, green, blue]
+			: undefined;
+	}
+	return undefined;
+}
+
+function stripBackgroundSgrParams(params: readonly number[]): number[] {
+	const sanitized: number[] = [];
+	for (let index = 0; index < params.length; index++) {
+		const param = params[index] ?? 0;
+		if (param === 0) {
+			sanitized.push(...(expandSgrReset(param) ?? []));
+			continue;
+		}
+		if (param === 49 || (param >= 40 && param <= 47) || (param >= 100 && param <= 107)) {
+			continue;
+		}
+		if (param === 38 || param === 48) {
+			const sequence = readSgrColorSequence(params, index);
+			if (sequence) {
+				if (param === 38) sanitized.push(...sequence);
+				index += sequence.length - 1;
+				continue;
+			}
+			const advance = params[index + 1] === 5 ? 2 : params[index + 1] === 2 ? 4 : 0;
+			if (advance > 0) {
+				index += advance;
+				if (param === 38) sanitized.push(param);
+				continue;
+			}
+		}
+		sanitized.push(param);
+	}
+	return sanitized;
+}
+
+function sanitizeAnsiForThemedOutput(text: string): string {
+	if (!text || !text.includes("\x1b[")) return text;
+	return text.replace(ANSI_SGR_PATTERN, (_sequence, rawParams: string) => {
+		const parsed = toSgrParams(rawParams);
+		if (parsed.length === 0) return "";
+		const sanitized = stripBackgroundSgrParams(parsed);
+		if (sanitized.length === 0) return "";
+		return `\x1b[${sanitized.join(";")}m`;
+	});
+}
+
+function isLikelyQuietCommand(command: string | undefined): boolean {
+	if (!command) return false;
+	const normalized = command.trim().toLowerCase();
+	const primarySegment = normalized
+		.split(/&&|\|\||;/)
+		.map((segment) => segment.trim())
+		.find((segment) => segment.length > 0);
+	if (!primarySegment) return false;
+	for (const prefix of QUIET_COMMAND_PREFIXES) {
+		if (primarySegment === prefix || primarySegment.startsWith(`${prefix} `)) return true;
+	}
+	return false;
+}
+
+function countTextLines(value: unknown): number {
+	return typeof value === "string" ? splitLines(value).length : 0;
+}
+
+function countEditLines(args: any): number {
+	const record = toRecord(args);
+	const edits = Array.isArray(record.edits) ? record.edits : [];
+	if (edits.length > 0) {
+		return edits.reduce<number>((total, edit) => total + countTextLines(toRecord(edit).newText), 0);
+	}
+	return countTextLines(record.newText);
+}
+
+function countWriteContentLines(value: unknown): number {
+	if (typeof value !== "string") return 0;
+	const lines = value.replace(/\r/g, "").split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.length;
+}
+
+function getWriteContentSizeBytes(value: unknown): number {
+	return typeof value === "string" ? Buffer.byteLength(value, "utf8") : 0;
+}
+
+function expandHint(): string {
+	return keyHint("app.tools.expand", "to expand");
+}
+
+function isToolError(r: any, c: any): boolean {
+	return c?.isError === true || r?.isError === true;
+}
+
+function isTruncated(r: any): boolean {
+	return toRecord(toRecord(r?.details).truncation).truncated === true;
+}
+
+/** Partial (in-progress) header: spinner + elapsed while executing, streamed text on expansion. */
+function renderPartialText(
+	label: string,
+	detail: string,
+	parts: Array<{ text: string; color?: string }> | undefined,
+	t: any,
+	c: any,
+): Text {
+	const text = c?.lastComponent instanceof Text ? c.lastComponent : new Text("", 0, 0);
+	const toolCallId = typeof c?.toolCallId === "string" ? c.toolCallId : undefined;
+	const animating = toolCallId !== undefined && c?.executionStarted === true;
+
+	const build = () => {
+		let spinnerAndElapsed = "";
+		if (animating && toolCallId !== undefined) {
+			const state = getOrCreateSpinnerState(toolCallId);
+			spinnerAndElapsed = t.fg("warning", SPINNER_CHARS[state.frame]) + " " + t.fg("muted", "· " + formatElapsed(Date.now() - state.start)) + " ";
+		}
+		const suffix = (parts ?? []).map((p) => " " + t.fg(p.color ?? "muted", p.text)).join("");
+		const det = detail ? truncateDetail(detail) : "";
+		text.setText(t.fg("dim", BORDER) + spinnerAndElapsed + t.bold(label + " ") + det + suffix);
+	};
+
+	if (animating && toolCallId !== undefined) {
+		const state = getOrCreateSpinnerState(toolCallId);
+		if (!state.timer && typeof c?.invalidate === "function") {
+			state.timer = setInterval(() => {
+				if (spinnerStates.get(toolCallId) !== state) {
+					clearInterval(state.timer);
+					return;
+				}
+				state.frame = (state.frame + 1) % SPINNER_CHARS.length;
+				build();
+				c.invalidate();
+			}, SPINNER_INTERVAL_MS);
+		}
+	}
+
+	build();
+	return text;
+}
+
+export default function (pi: any) {
+	const cwd = process.cwd();
+
+	// label 是工具的默认名；getDetail 可以按参数与渲染状态覆盖它（技能读取要显示成 [skill] <名字>）
+	type ToolDetail = { label?: string; detail: string; parts?: Array<{ text: string; color?: string }> };
+
+	function registerTool(
+		tool: any,
+		label: string,
+		getDetail: (a: any, t: any, c: any) => ToolDetail,
+		getSummary?: (r: any, o: any, t: any, a: any, isError: boolean) => string | undefined,
+	) {
+		pi.registerTool({
+			name: tool.name, label: tool.name,
+			description: tool.description,
+			parameters: tool.parameters,
+			renderShell: "self",
+			async execute(toolCallId: string, ...args: any[]) {
+				// renderResult 只在有 result 时被调用，不主动发一次空 partial 的话，
+				// 不产生流式输出的工具（read/edit/write）执行期间整行不可见。
+				// 内置 bash 工具在自己的 execute 开头做同样的事。
+				const onUpdate = args[2];
+				if (typeof onUpdate === "function") {
+					onUpdate({ content: [], details: undefined });
+				}
+				try {
+					return await tool.execute(toolCallId, ...args);
+				} finally {
+					stopSpinner(toolCallId);
+				}
+			},
+			renderCall(a: any, t: any, c: any) {
+				// 只在参数流式期间出调用行：那时还没有 partial result，renderResult 不会被调，
+				// 否则模型产出参数时界面整段空白。执行开始或已有 result 时让 renderResult 独占，
+				// 也包括 /reload 重放历史（那时不会再发 tool_execution_start）。
+				if (c?.executionStarted || !c?.isPartial) return new Container();
+				const { label: customLabel, detail, parts } = getDetail(a || {}, t, c);
+				const text = c?.lastComponent instanceof Text ? c.lastComponent : new Text("", 0, 0);
+				const suffix = (parts ?? []).map((p) => " " + t.fg(p.color ?? "muted", p.text)).join("");
+				text.setText(
+					t.fg("dim", BORDER) + t.bold((customLabel ?? label) + " ") + (detail ? truncateDetail(detail) : "") + suffix,
+				);
+				return text;
+			},
+			renderResult(r: any, o: any, t: any, c: any) {
+				const { label: customLabel, detail, parts } = getDetail(c?.args || {}, t, c);
+				const shownLabel = customLabel ?? label;
+				const err = isToolError(r, c);
+				// Partial (in-progress): spinner + any streamed text
+				if (o.isPartial) {
+					const streamed = r.content?.filter((x: any) => x?.type === "text").map((x: any) => x.text).join("") || "";
+					if (!o.expanded || (!detail && !streamed)) {
+						return renderPartialText(shownLabel, detail, parts, t, c);
+					}
+					const lines = [];
+					if (detail) {
+						lines.push(addBorder(t.bold(shownLabel + " ") + hardWrap(detail, MAX_CONTENT_LINE_LEN), t, "dim"));
+					}
+					if (streamed) {
+						lines.push(addBorder(sanitizeAnsiForThemedOutput(streamed), t, "dim"));
+					}
+					return new Text(lines.join("\n"), 0, 0);
+				}
+				stopSpinner(c?.toolCallId); // ensure no timer survives a cancelled call
+				const tailParts: Array<{ text: string; color?: string }> = [...(parts ?? [])];
+				if (isTruncated(r)) tailParts.push({ text: "• truncated", color: "warning" });
+				const color = err ? "error" : "success";
+				if (!o.expanded) {
+					const title = titleLine(shownLabel, truncateDetail(detail), t, color, tailParts);
+					const summary = getSummary?.(r, o, t, c?.args || {}, err);
+					if (summary) {
+						return new Text(title + "\n" + t.fg("muted", "  " + summary), 0, 0);
+					}
+					return new Text(title, 0, 0);
+				}
+				// Expanded: full detail + output, all lines use state color (dim/success/error)
+				const contentLines = [];
+				if (detail) {
+					contentLines.push(addBorder(t.bold(shownLabel + " ") + hardWrap(detail, MAX_CONTENT_LINE_LEN), t, color));
+				}
+				const partsText = r.content?.filter((c: any) => c?.type === "text").map((c: any) => c.text) || [];
+				if (r.details?.diff) partsText.push(r.details.diff);
+				for (const p of partsText) {
+					contentLines.push(addBorder(prepareOutputLines(sanitizeAnsiForThemedOutput(p), o.expanded).join("\n"), t, color));
+				}
+				return new Text(contentLines.join("\n"), 0, 0);
+			},
+		});
+	}
+
+	registerTool(createReadTool(cwd), "read", (a, _t, c) => {
+		const rawPath = typeof a.path === "string" ? a.path : "";
+		const offset = typeof a.offset === "number" ? a.offset : undefined;
+		const limit = typeof a.limit === "number" ? a.limit : undefined;
+		let range: string | undefined;
+		if (offset !== undefined || limit !== undefined) {
+			const from = offset ?? 1;
+			const to = limit !== undefined ? from + limit - 1 : undefined;
+			range = to !== undefined ? `:${from}-${to}` : `:${from}`;
+		}
+		const skill = skillNameFromPath(rawPath);
+		// 技能折叠成单行 [skill] <名字>，第二行摘要由 getSummary 一起省掉。展开后退回 read + 路径，
+		// 保留文件位置信息。展开提示只挂终态：参数流式、执行中、结果流式都不显示；
+		// 出错时没有内容可展开，也不显示。行范围照旧沿用警告色显示。
+		if (skill && c?.expanded !== true) {
+			const finalState = c?.isPartial !== true && c?.isError !== true;
+			const parts = [
+				...(range ? [{ text: range }] : []),
+				...(finalState ? [{ text: `(${expandHint()})` }] : []),
+			];
+			return { label: `[skill] ${skill}`, detail: "", parts: parts.length > 0 ? parts : undefined };
+		}
+		return { detail: shortenPath(rawPath), parts: range ? [{ text: range }] : undefined };
+	}, (r, o, t, _a, _err) => {
+		if (_err) return undefined;
+		// 技能的展开提示已经在标题行里，不再出第二行摘要
+		if (skillNameFromPath(_a?.path)) return undefined;
+		const lineCount = prepareOutputLines(extractTextOutput(r), true).length;
+		if (lineCount === 0) return "↳ (empty)";
+		return `↳ loaded ${lineCount} ${pluralize(lineCount, "line")} · ${expandHint()}`;
+	});
+
+	registerTool(createBashTool(cwd, {
+		spawnHook: bashEnvHook,
+		operations: createBashTimeoutOps(createLocalBashOperations()),
+	}), "$", (a) => {
+		return { detail: a.command || "" };
+	}, (r, o, t, a, err) => {
+		if (err) return "↳ command failed";
+		const lines = prepareOutputLines(extractTextOutput(r), false);
+		if (lines.length === 0) {
+			return isLikelyQuietCommand(toRecord(a).command)
+				? "↳ command completed (no output)"
+				: "↳ (no output)";
+		}
+		const count = countNonEmptyLines(lines);
+		return `↳ ${count} ${pluralize(count, "line")} returned · ${expandHint()}`;
+	});
+
+	registerTool(createEditTool(cwd), "edit", (a) => {
+		const lineCount = countEditLines(a);
+		const parts = lineCount > 0 ? [{ text: `(${lineCount} ${pluralize(lineCount, "line")})` }] : undefined;
+		return { detail: shortenPath(a.path || ""), parts };
+	});
+
+	registerTool(createWriteTool(cwd), "write", (a) => {
+		const content = typeof a.content === "string" ? a.content : undefined;
+		let parts;
+		if (content !== undefined) {
+			const lineCount = countWriteContentLines(content);
+			parts = [{ text: `(${lineCount} ${pluralize(lineCount, "line")} • ${formatSize(getWriteContentSizeBytes(content))})` }];
+		}
+		return { detail: shortenPath(a.path || ""), parts };
+	});
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@liuxincuit/pi-compact-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "覆盖内置 read/bash/edit/write，提供紧凑渲染与默认超时",
+  "keywords": [
+    "pi-package",
+    "renderer",
+    "compact",
+    "tui"
+  ],
+  "license": "MIT",
+  "author": "liuxincuit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liuxincuit/pi-packages.git",
+    "directory": "packages/compact-tools"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}