@bachi/pi-coder 1.0.0

package/extensions/fenceless-code-block/render.ts

@@ -0,0 +1,142 @@
+/**
+ * fenceless-code-block — 纯逻辑：Markdown 代码块去掉围栏
+ *
+ * 去围栏这个观感来自 `itc-steve/pi-theme`（npm `@itc-steve/pi-theme`，MIT），但**只取这一半**：
+ * 上游还给每行铺一块 `toolPendingBg` 底色，本仓库不要底色 —— 代码正文保持 pi 原本的
+ * `mdCodeBlock` 前景色，缩进与补白也照 pi 的老规矩来。按本仓库的习惯重写：pi-tui 的量度 /
+ * 折行函数由调用方注入（本模块不 import pi，`node --test` 能直跑）。
+ *
+ * 效果：` ``` ` 开合围栏（连同 `lang` 标签）不再占行；代码正文按 pi 的缩进铺开，语法着色保留。
+ * 行尾**不补白**：补白本来是给底色铺满整宽用的，而 `Markdown.render()` 无论如何都会把每行补到
+ * 整宽（没有底色时走 `lineWithMargins + " ".repeat(paddingNeeded)` 那条分支），自己再补一遍多余。
+ *
+ * 为什么必须打原型补丁：pi 的扩展 API 里跟 Markdown 有关的只有 `registerMarkdownTransformer`，
+ * 它是**字符串级**的（改完仍交给内置渲染器）。而围栏是内置渲染器自己拼的字面量
+ * （`markdown.js` 的 `case "code"`：`theme.codeBlockBorder("```" + lang)` 与收尾的 `"```"`），
+ * 源文里没有这两个字符，字符串级改不掉。所以只能接管 `Markdown.prototype.renderToken`。
+ *
+ * 补丁为什么打得中（跨模块实例，本机实测过，别凭直觉推断）：
+ *   `pi` 命令跑的是 `dist/bundle/cli.js`（bun 打的 bundle），pi-tui 被**内联**进 chunk，不是
+ *   node_modules 里那份；扩展若拿到 node_modules 那份，补丁就打在另一个类上、毫无效果
+ *   （实测：改外部包的 `Markdown.prototype`，pi 自己的 `AssistantMessageComponent` 渲染同一个
+ *   assistant 消息，围栏照样在）。真正让补丁生效的是 pi 扩展加载器的 virtualModules 分支
+ *   （`core/extensions/loader.js:421`，bundle / 编译二进制走 `{ virtualModules: VIRTUAL_MODULES }`）：
+ *   扩展 import 的 `@earendil-works/pi-tui` 被指向加载器那份 bundle 自己的命名空间，也就是 pi
+ *   渲染时用的同一个类。`index.test.ts` 断言的就是这条端到端链路。
+ *
+ * 每行都必须 ≤ width（含缩进）：`Markdown.render()` 会把 renderToken 返回的**每一行**再交给
+ * `wrapTextWithAnsi(line, contentWidth)`，超宽行会被二次折行 —— 而续行不带缩进，代码块看上去
+ * 会错位。所以这里自己先折行；缩进放不下（比 width 还宽）时丢缩进，保证可用宽度至少 1 列。
+ */
+
+/** 补丁标记：`Symbol.for` 走全局注册表，`/reload`（模块重新求值）后仍认得出这个原型包过了。 */
+const PATCH_KEY = Symbol.for("pi-fenceless-code-block.patched");
+
+/** 终端列宽量度（注入 pi-tui 的 `visibleWidth`）。 */
+export type Measure = (text: string) => number;
+/** 折行（注入 pi-tui 的 `wrapTextWithAnsi`）。 */
+export type Wrap = (text: string, width: number) => string[];
+
+export interface CodeBlockRenderOptions {
+	/** 语言标签（` ```js ` 里的 `js`），只用来交给 `highlight`。 */
+	lang?: string;
+	/** 缩进前缀：pi 的 `MarkdownTheme.codeBlockIndent`（设置项 `markdown.codeBlockIndent`，默认两格）。 */
+	indent?: string;
+	/** 着色：pi 的 `MarkdownTheme.highlightCode`，返回行数与输入一一对应。 */
+	highlight?: (code: string, lang?: string) => string[];
+	/** 没有 `highlightCode` 时的兜底着色，等价于官方渲染器的 else 分支（`theme.codeBlock`）。 */
+	fallbackStyle?: (text: string) => string;
+	measure: Measure;
+	wrap: Wrap;
+}
+
+/** 代码块正文 → 可直接交给 pi 渲染的行：无围栏、按缩进铺开、每行不超过 width。 */
+export function renderCodeBlockLines(code: string, width: number, options: CodeBlockRenderOptions): string[] {
+	const { measure, wrap } = options;
+	const total = Math.max(1, width);
+	const wanted = options.indent ?? DEFAULT_INDENT;
+	// 缩进可能把可用宽度挤成 0（极窄终端）：宁可这一段丢缩进，也不能让行超过 width
+	// （超了会被 Markdown.render() 二次折行，续行丢缩进、看上去错位）。
+	const indent = measure(wanted) < total ? wanted : "";
+	const inner = Math.max(1, total - measure(indent));
+
+	const lines: string[] = [];
+	for (const source of styleCode(code, options)) {
+		// 折行函数对空串可能返回空数组：空行也要占一行，否则代码块中间会塌掉一行。
+		const pieces = wrap(source, inner);
+		for (const piece of pieces.length > 0 ? pieces : [""]) lines.push(indent + piece);
+	}
+	return lines;
+}
+
+const DEFAULT_INDENT = "  ";
+
+/**
+ * 着色优先级：`highlight` 有产出就用它；产出为空（空代码块、高亮器不认这门语言）就退回纯文本
+ * —— 官方渲染器在这种情况下会一行都不画，那样整个代码块会凭空消失。
+ */
+function styleCode(code: string, options: CodeBlockRenderOptions): string[] {
+	const highlighted = options.highlight?.(code, options.lang);
+	if (highlighted && highlighted.length > 0) return highlighted;
+	const plain = code.split("\n");
+	return options.fallbackStyle ? plain.map(options.fallbackStyle) : plain;
+}
+
+/** Markdown 实例上的主题切片（类的"私有"字段在运行时就是普通属性）。 */
+interface MarkdownLike {
+	theme?: {
+		codeBlockIndent?: string;
+		highlightCode?: (code: string, lang?: string) => string[];
+		codeBlock?: (text: string) => string;
+	};
+}
+
+type RenderToken = (
+	this: MarkdownLike,
+	token: unknown,
+	width: number,
+	nextType?: string,
+	styleContext?: unknown,
+) => string[];
+
+export interface FencelessPatchOptions {
+	/** pi-tui 的 `Markdown` 类。扩展侧 import 到的就是 pi 渲染用的那个类，见文件头。 */
+	Markdown: { prototype: Record<string | symbol, unknown> };
+	measure: Measure;
+	wrap: Wrap;
+}
+
+/**
+ * 装上「代码块去围栏」补丁。返回**本次是否真的装了**：`/reload` 之后是 `false`（补丁已在），
+ * 原型的形状不认识（没有 `renderToken`）时也是 `false` 且什么都不做 —— 不猜、不抛，
+ * 宁可这个特性不生效。
+ */
+export function installFencelessCodeBlocks(options: FencelessPatchOptions): boolean {
+	const prototype = options.Markdown.prototype;
+	if (prototype[PATCH_KEY]) return false;
+
+	const original = prototype.renderToken;
+	if (typeof original !== "function") return false;
+	prototype[PATCH_KEY] = true;
+
+	const patched: RenderToken = function (this: MarkdownLike, token, width, nextType, styleContext) {
+		const block = token as { type?: string; text?: string; lang?: string } | null | undefined;
+		// 只接管代码块，其它 token 原样交给内置渲染器（含 blockquote / list 里的嵌套调用）。
+		if (block?.type !== "code") return original.call(this, token, width, nextType, styleContext);
+
+		const theme = this?.theme ?? {};
+		const lines = renderCodeBlockLines(block.text ?? "", width, {
+			lang: block.lang,
+			indent: theme.codeBlockIndent,
+			highlight: theme.highlightCode?.bind(theme),
+			fallbackStyle: theme.codeBlock?.bind(theme),
+			measure: options.measure,
+			wrap: options.wrap,
+		});
+		// 与官方渲染器一致：后面紧跟的不是空行 token 时补一个空行，免得代码块贴着下一段。
+		if (nextType && nextType !== "space") lines.push("");
+		return lines;
+	};
+	prototype.renderToken = patched;
+	return true;
+}

package/extensions/folder-history.ts

@@ -0,0 +1,197 @@
+/**
+ * Folder-based Command History（本地改版，源自 npm:pi-command-history@0.2.0）
+ *
+ * 按工作目录持久化命令历史，跨会话复用。历史文件：~/.pi/folder-history/<path-with-dashes>.jsonl
+ *
+ * 与上游最大的差别：**不再注册任何快捷键**。
+ * 上游用 ctrl+up / ctrl+down，在 macOS 上被系统 Mission Control 抢走（终端收不到），
+ * 而且和 pi 内置的 tui.altScreen.previousPrompt / nextPrompt 撞键（启动时刷 conflict 警告）。
+ *
+ * 现在的做法是把跨 session 的历史注入编辑器自身的 history 列表，于是**原生 ↑ / ↓ 直接跨 session 翻历史**：
+ *   - pi-tui Editor.history 里 history[0] = 最新，索引越大越旧；↑ 在第一视觉行时往旧翻，↓ 往新翻；
+ *   - pi 启动时只把「当前会话」的用户消息灌进 history（renderInitialMessages → populateHistory），
+ *     所以原生 ↑/↓ 原本只能翻当前会话；
+ *   - 我们把旧 session 的记录**追加到 history 数组尾部**（尾部 = 更旧），顺序变成
+ *     [当前会话最新…最旧, 上个会话最新…最旧, 更早…]，↑ 一路往旧翻，↓ 一路往新翻。
+ *
+ * 为什么用「注入 history」而不是注册 up/down 快捷键：扩展快捷键在 CustomEditor.handleInput 的
+ * 最前面被检查（onExtensionShortcut first），注册 "up" 会吃掉多行输入框的光标上移，
+ * 以及所有选择器（模型选择、/resume 列表…）的 ↑/↓ 导航。注入 history 则完全保留原生语义：
+ * 多行 prompt 里 ↑/↓ 照常移动光标，只有光标在第一视觉行（或正在翻历史）时才翻历史。
+ *
+ * 实现要点：ctx.ui.getEditorComponent() 返回的是**工厂函数**（EditorFactory），不是编辑器实例，
+ * 所以拿不到 history 数组 —— 只能包一层工厂，在实例化时注入。
+ * 扩展按文件名顺序加载（folder-history.ts 排在 prompt-editor.ts 之前），prompt-editor 会在
+ * session_start 里 setEditorComponent 覆盖掉我们的工厂，因此这里同步包一次 + setTimeout(0) 再包一次
+ * （此时所有 session_start handler 都已跑完），并用 symbol 标记避免重复嵌套包装。
+ *
+ * 可调环境变量：
+ *   PI_FOLDER_HISTORY_INJECT  注入编辑器 history 的最大条数，默认 100（= pi-tui 内置 history 上限）
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HISTORY_DIR = join(homedir(), ".pi", "folder-history");
+const MAX_HISTORY = 500; // 历史文件里保留的条数上限
+// 注入上限默认 100：pi-tui Editor.addToHistory 在 history 超过 100 条时会 pop 掉最旧的一条，
+// 注入更多只会在后续提交时被逐条裁掉，所以和内置上限保持一致。
+const MAX_INJECT = Number(process.env.PI_FOLDER_HISTORY_INJECT || 100);
+const WRAPPED = Symbol.for("pi.folder-history.wrapped");
+
+function getHistoryFile(cwd: string): string {
+	const name = cwd.replace(/\//g, "-");
+	return join(HISTORY_DIR, `${name}.jsonl`);
+}
+
+/** 返回 oldest-first 的去重历史（按文件里的写入顺序）。 */
+function loadHistory(cwd: string): string[] {
+	const file = getHistoryFile(cwd);
+	if (!existsSync(file)) return [];
+
+	try {
+		const lines = readFileSync(file, "utf-8")
+			.split("\n")
+			.filter((l) => l.trim());
+
+		const entries: string[] = [];
+		for (const line of lines) {
+			try {
+				const entry = JSON.parse(line);
+				if (entry.text && entry.cwd === cwd) {
+					entries.push(entry.text);
+				}
+			} catch {
+				// skip malformed lines
+			}
+		}
+
+		// Deduplicate keeping last occurrence, then trim to max
+		const seen = new Map<string, number>();
+		entries.forEach((text, i) => seen.set(text, i));
+		const unique = [...seen.entries()]
+			.sort((a, b) => a[1] - b[1])
+			.map(([text]) => text);
+
+		return unique.slice(-MAX_HISTORY);
+	} catch {
+		return [];
+	}
+}
+
+function appendHistory(cwd: string, text: string): void {
+	mkdirSync(HISTORY_DIR, { recursive: true });
+	const file = getHistoryFile(cwd);
+	const entry = JSON.stringify({ cwd, text, ts: Date.now() });
+	appendFileSync(file, entry + "\n", "utf-8");
+}
+
+/** 当前会话已有的用户输入（避免 resume 时把同一条记录重复注入成两份）。 */
+function collectSessionTexts(sessionManager: unknown): Set<string> {
+	const texts = new Set<string>();
+	try {
+		const entries = (sessionManager as { getEntries?: () => unknown[] })?.getEntries?.() ?? [];
+		for (const entry of entries as Array<Record<string, any>>) {
+			if (entry?.type !== "message") continue;
+			const message = entry.message;
+			if (message?.role !== "user") continue;
+			const content = message.content;
+			if (typeof content === "string") {
+				const trimmed = content.trim();
+				if (trimmed) texts.add(trimmed);
+			} else if (Array.isArray(content)) {
+				const text = content
+					.filter((block: any) => block?.type === "text" && typeof block.text === "string")
+					.map((block: any) => block.text)
+					.join("\n")
+					.trim();
+				if (text) texts.add(text);
+			}
+		}
+	} catch {
+		// sessionManager shape changed — just skip dedupe
+	}
+	return texts;
+}
+
+/**
+ * 注入到编辑器 history：history[0] = 最新，索引越大越旧，
+ * 所以旧记录追加到**尾部**，且追加顺序必须是 newest-first。
+ */
+function injectIntoEditor(
+	editor: unknown,
+	entriesOldestFirst: string[],
+	exclude: Set<string>,
+): number {
+	if (!editor || typeof editor !== "object") return 0;
+
+	const existing = (editor as { history?: unknown }).history;
+	const injectOldestFirst = entriesOldestFirst.filter(
+		(text) => !exclude.has(text) && !(Array.isArray(existing) && existing.includes(text)),
+	).slice(-MAX_INJECT);
+	if (injectOldestFirst.length === 0) return 0;
+
+	if (!Array.isArray(existing)) {
+		// 兜底：编辑器没有 history 数组时用公开 API 逐条加（oldest-first → 最新的落在 history[0]）
+		const addToHistory = (editor as { addToHistory?: (t: string) => void }).addToHistory;
+		if (typeof addToHistory !== "function") return 0;
+		for (const text of injectOldestFirst) addToHistory.call(editor, text);
+		return injectOldestFirst.length;
+	}
+
+	existing.push(...injectOldestFirst.slice().reverse());
+	return injectOldestFirst.length;
+}
+
+export default function (pi: ExtensionAPI) {
+	let currentCwd = "";
+	let sessionTexts = new Set<string>();
+
+	/** 包一层编辑器工厂，在实例化时注入跨 session 历史。 */
+	function installEditorWrapper(ctx: any): boolean {
+		if (!ctx?.hasUI) return false;
+
+		const previous = ctx.ui.getEditorComponent();
+		if (previous && (previous as any)[WRAPPED]) return false; // 已经是我们的包装，别嵌套
+
+		ctx.ui.setEditorComponent((tui: any, theme: any, keybindings: any) => {
+			const editor = previous
+				? previous(tui, theme, keybindings)
+				: new CustomEditor(tui, theme, keybindings);
+			injectIntoEditor(editor, loadHistory(currentCwd), sessionTexts);
+			return editor;
+		});
+
+		const installed = ctx.ui.getEditorComponent();
+		if (installed) (installed as any)[WRAPPED] = true;
+		return true;
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		currentCwd = ctx.cwd;
+		sessionTexts = collectSessionTexts((ctx as any).sessionManager);
+
+		// 同步包一次；如果别的扩展（如 prompt-editor）之后又覆盖了工厂，
+		// 下面的 macrotask 会在所有 session_start handler 跑完后再包一次。
+		installEditorWrapper(ctx);
+		setTimeout(() => {
+			try {
+				installEditorWrapper(ctx);
+			} catch {
+				// ctx 可能已经因为 reload / 换 session 失效
+			}
+		}, 0);
+	});
+
+	// 只负责持久化：编辑器 history 由 pi 自己在提交时 addToHistory，不要重复加
+	pi.on("input", (event, _ctx) => {
+		const text = event.text?.trim();
+		if (!text || !currentCwd) return;
+
+		appendHistory(currentCwd, text);
+		return { action: "continue" as const };
+	});
+}

package/extensions/init-command.ts

@@ -0,0 +1,163 @@
+/**
+ * /init：仿 Claude Code —— 让模型分析当前仓库，生成或更新「记忆文件」。
+ *
+ * 目标文件的选取（没显式指定时，只看 `ctx.cwd` 这一层）：
+ *   ① 有 `CLAUDE.md` → 更新 `CLAUDE.md`
+ *   ② 否则有 `AGENTS.md` → 更新 `AGENTS.md`
+ *   ③ 两个都没有 → 新建 `AGENTS.md`
+ * 显式指定：`/init <文件.md>`（第一个词以 `.md` 结尾就当路径，其余的当附加要求），
+ * 例如 `/init docs/NOTES.md`、`/init /tmp/foo.md`、`/init 重点写构建和测试`。
+ *
+ * 为什么 CLAUDE.md 优先：这个仓库（以及作者的大部分项目）把 `CLAUDE.md` 当正文、
+ * `AGENTS.md` 只是指向它的符号链接 —— 写 `CLAUDE.md` 才不会在复制/打包时丢内容。
+ * pi 自己两个名字都认（`docs/usage.md` 的 Context Files：从 cwd 逐层向上加载
+ * `AGENTS.md` 或 `CLAUDE.md`，同目录有 `AGENTS.override.md` 时以它为准），所以这个顺序
+ * 只决定「往哪个文件写」，不影响它会不会被加载。
+ *
+ * 扩展自己**不写文件**：只做目标判定 + 把一段提示词当**用户消息**发给模型
+ *（`pi.sendUserMessage`），由模型的 read / write / edit 去落盘。这正是 Claude Code
+ * `/init` 的形态（一条命令 + 一段提示词），好处是用户能在会话里看到模型的产出过程、
+ * 也能中途纠正；扩展不碰文件，就没有「扩展在后台偷偷改仓库」这类意外。
+ *
+ * 三个刻意的决定：
+ *   ① **先 `await ctx.waitForIdle()`** 再判定：agent 正在跑的时候发用户消息要么抛错
+ *      （未指定 `deliverAs`），要么被排成 followUp；而目标文件的判定会因此变旧 ——
+ *      当前回合可能刚创建/删掉 `CLAUDE.md`，那样就会把内容写进错的记忆文件。
+ *      等这轮结束再判定 + 发送，语义最稳（同 `/clear` 先 `waitForIdle` 的理由）。
+ *   ② **只认 cwd 这一层，不向上找父目录**：pi 是逐层加载的，用户在子目录里 `/init`
+ *      想写的就是这个子目录自己的记忆文件；要写别处直接传路径。向上找会让人在子目录里
+ *      一不留神改到仓库根的记忆文件。
+ *   ③ **不注册参数补全**：`/init` 的候选只有两个固定名字，补全的收益抵不上一个额外的
+ *      pi-tui 依赖面；要指定路径就手敲，反正有 `read`/`write` 的相对路径习惯。
+ *
+ * `ctx.hasUI` 为 false（print / json 模式）时不 notify —— 那里没有 UI，提示无处可去；
+ * 命令本身照常把提示词发出去。
+ */
+
+import { statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** 自动判定时的候选顺序：有 `CLAUDE.md` 就写它，否则 `AGENTS.md`。 */
+const CANDIDATES = ["CLAUDE.md", "AGENTS.md"];
+
+/** 两个候选都没有时新建哪个。 */
+const NEW_FILE = "AGENTS.md";
+
+/** `statSync` 跟随符号链接 —— 本仓库就是 `AGENTS.md -> CLAUDE.md`，两个名字都该算“存在”。 */
+function isFile(path: string): boolean {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+interface InitTarget {
+	/** 交给模型落盘的**绝对路径**。 */
+	path: string;
+	/** 提示词里展示用的路径（在项目内用相对路径，否则回落绝对路径）。 */
+	display: string;
+	exists: boolean;
+	/** 用户显式指定的路径（提示词里换一种说法，并提醒别动兄弟文件）。 */
+	explicit: boolean;
+}
+
+/**
+ * 解析 `/init` 的参数：第一个词以 `.md` 结尾就算目标文件，其余文字当附加要求；
+ * 没有这样的词就整串当附加要求（`/init 重点写构建和测试`）。
+ */
+function parseArgs(args: string): { file?: string; extra: string } {
+	const trimmed = args.trim();
+	if (!trimmed) return { extra: "" };
+	const match = /^(\S+\.md)(?:\s+([\s\S]*))?$/i.exec(trimmed);
+	if (!match) return { extra: trimmed };
+	return { file: match[1], extra: (match[2] ?? "").trim() };
+}
+
+/** 项目内显示相对路径（`../x` 这种跳出去的回落绝对路径，免得看不出真写到哪了）。 */
+function displayPath(cwd: string, path: string): string {
+	const rel = relative(cwd, path);
+	return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : path;
+}
+
+function resolveTarget(cwd: string, file: string | undefined): InitTarget {
+	if (file) {
+		const path = isAbsolute(file) ? file : resolve(cwd, file);
+		return { path, display: displayPath(cwd, path), exists: isFile(path), explicit: true };
+	}
+	for (const name of CANDIDATES) {
+		const path = resolve(cwd, name);
+		if (isFile(path)) return { path, display: name, exists: true, explicit: false };
+	}
+	return { path: resolve(cwd, NEW_FILE), display: NEW_FILE, exists: false, explicit: false };
+}
+
+/**
+ * 提示词。要点：
+ *   - 把「文件会被之后的每次会话自动加载」说清楚，模型才知道该写什么（写给下一个 agent）。
+ *   - 明确**只写验证过的事实**（这个仓库的一贯要求：不臆造命令、不猜路径）。
+ *   - 已存在时强调「先 read、保留正确内容、别为重写而重写」，否则模型很容易整篇重写，
+ *     把仓库里那些踩坑记录一把抹掉。
+ *   - 列出「不要写」的清单（通用建议 / 目录树 / README 复述 / 临时信息）—— 这是
+ *     Claude Code 的 /init 提示词里最起作用的那几条，照搬。
+ */
+function buildPrompt(target: InitTarget, cwd: string, extra: string): string {
+	const action = target.exists ? "更新" : "创建";
+	const lines = [
+		`请分析这个代码库，然后${action}记忆文件 \`${target.display}\`（绝对路径：\`${target.path}\`）。`,
+		"",
+		"这个文件会被 pi 在**之后的每次会话**自动加载（从工作目录逐层向上读 `AGENTS.md` / `CLAUDE.md`，同目录下有 `AGENTS.override.md` 时以它为准），读者是「下一次在这个仓库里干活的 agent」。",
+		`项目根目录：\`${cwd}\``,
+		"",
+		target.exists
+			? "该文件**已存在**：先 read 它，再决定改什么 —— 保留仍然正确的内容、删掉与代码不符的、补上缺的。不要为了重写而重写，也不要丢掉已有的踩坑记录。"
+			: "该文件**还不存在**：从零写一份。",
+		"",
+		"先自己探查仓库（README、依赖与构建清单如 package.json / pyproject.toml / Makefile / Cargo.toml、CI 配置、测试目录、主要源码），**只写你验证过的事实**：命令要真的存在、路径要真的对，没把握就不写，不要臆造。",
+		"",
+		"要写进去的（按价值排序）：",
+		"1. **常用命令**：装依赖 / 构建 / 跑测试（含只跑单个测试的写法）/ lint / 格式化 / 本地起服务；注明在哪个目录执行、有哪些前置条件。命令放代码块，能直接复制。",
+		"2. **架构与代码地图**：主要模块各自负责什么、一条典型请求或一次典型构建是怎么流过去的、关键约定与分层、外部依赖、哪些文件是生成物（不要手改）。",
+		"3. **这个仓库特有的坑**：非显然的行为、必须遵守的流程（提交信息格式、需要同时改的几处配置、必须保持同步的镜像文件）、容易踩错的地方。",
+		"",
+		"不要写：",
+		"- 通用开发建议（「写单元测试」「不要提交密钥」「给出清晰的报错」这类谁都知道的话）。",
+		"- 目录树罗列 / 逐文件清单，或把 README 复述一遍。",
+		"- 只跟当前任务有关的临时信息。",
+		"",
+		"写法：",
+		"- 语言与风格跟随该文件现有内容；新文件用中文（除非这仓库的文档清一色是英文）。紧凑，宁缺毋滥。",
+	];
+	if (!target.explicit) {
+		lines.push(
+			"- 如果 `AGENTS.md` 与 `CLAUDE.md` 同时存在、或其中一个是另一个的符号链接，**只改上面指定的这一个**，不要把内容抄进另一个。",
+		);
+	}
+	lines.push(
+		"- 仓库里若有别的 agent 记忆文件（`.cursorrules` / `.cursor/rules/` / `.github/copilot-instructions.md` / `.claude/`），可以读来补漏，但不要改它们。",
+		"- 用 write / edit 工具写到上面那个绝对路径（不要用 bash 的 cat / heredoc 落盘）。",
+		"- 完成后用一两句话说明改了什么。",
+	);
+	if (extra) lines.push("", `这次 /init 的附加要求：${extra}`);
+	return lines.join("\n");
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("init", {
+		description: "分析仓库并生成/更新记忆文件（有 CLAUDE.md 就更新它，否则 AGENTS.md）",
+		handler: async (args, ctx) => {
+			const { file, extra } = parseArgs(args);
+			// 判定必须发生在「发消息」那一刻：agent 正在跑时先等它结束（见文件头 ①）。
+			if (!ctx.isIdle()) {
+				if (ctx.hasUI) ctx.ui.notify("等当前回合结束再开始 /init …", "info");
+				await ctx.waitForIdle();
+			}
+			const target = resolveTarget(ctx.cwd, file);
+			if (ctx.hasUI) {
+				ctx.ui.notify(`${target.exists ? "更新" : "创建"} ${target.display}（${target.path}）…`, "info");
+			}
+			pi.sendUserMessage(buildPrompt(target, ctx.cwd, extra));
+		},
+	});
+}

package/extensions/prompt-editor/bash-prompt.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Tests for bash-prompt.ts — `!` bash 模式的模式判定与「把行首 `!` 从渲染行里摘掉」。
+ *
+ * Run with:  node --test clients/pi/extensions/prompt-editor/bash-prompt.test.ts
+ *
+ * 被测模块不 import pi / pi-tui，用例直接喂 pi-tui Editor 真正会写出来的渲染行字符串
+ * （光标反显 `\x1b[7m!\x1b[0m`、CURSOR_MARKER `\x1b_pi:c\x07`）。
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { BASH_MARKER, dropLeadingBang, resolveBashPrompt } from "./bash-prompt.ts";
+
+const CURSOR_MARKER = "\x1b_pi:c\x07";
+
+describe("resolveBashPrompt", () => {
+	it("普通正文不算 bash 模式", () => {
+		assert.deepEqual(resolveBashPrompt(""), { active: false, hidden: false });
+		assert.deepEqual(resolveBashPrompt("ls -la"), { active: false, hidden: false });
+		assert.deepEqual(resolveBashPrompt("ls!"), { active: false, hidden: false });
+		assert.deepEqual(resolveBashPrompt("/recap"), { active: false, hidden: false });
+	});
+
+	it("字面以 `!` 开头：算 bash 模式，且那个 `!` 要藏起来", () => {
+		assert.deepEqual(resolveBashPrompt("!"), { active: true, hidden: true });
+		assert.deepEqual(resolveBashPrompt("!ls"), { active: true, hidden: true });
+		assert.deepEqual(resolveBashPrompt("! ls -la"), { active: true, hidden: true });
+		assert.deepEqual(resolveBashPrompt("!ls\n-l"), { active: true, hidden: true });
+	});
+
+	it("`!!`（不进上下文的那种）同样只藏第一个 `!`，第二个留在正文里", () => {
+		assert.deepEqual(resolveBashPrompt("!!ls"), { active: true, hidden: true });
+		assert.deepEqual(resolveBashPrompt("!!"), { active: true, hidden: true });
+	});
+
+	it("前导空白 / 换行后跟 `!`：pi 也算 bash 模式，但位置对不上第一列，不藏", () => {
+		assert.deepEqual(resolveBashPrompt(" !ls"), { active: true, hidden: false });
+		assert.deepEqual(resolveBashPrompt("\n!ls"), { active: true, hidden: false });
+		assert.deepEqual(resolveBashPrompt("\t!ls"), { active: true, hidden: false });
+	});
+});
+
+describe("dropLeadingBang", () => {
+	it("摘掉行首的 `!`，其余逐字保留", () => {
+		assert.deepEqual(dropLeadingBang("!ls -la"), { text: "ls -la", dropped: true });
+		assert.deepEqual(dropLeadingBang("!"), { text: "", dropped: true });
+		assert.deepEqual(dropLeadingBang("! ls"), { text: " ls", dropped: true });
+	});
+
+	it("`!!` 只摘一个（第二个 `!` 是 pi 的「不进上下文」标记，要留在正文里看得见）", () => {
+		assert.deepEqual(dropLeadingBang("!!ls"), { text: "!ls", dropped: true });
+	});
+
+	it("没有可摘的 `!` 时原样返回，并且不报 dropped", () => {
+		assert.deepEqual(dropLeadingBang("ls -la"), { text: "ls -la", dropped: false });
+		assert.deepEqual(dropLeadingBang(""), { text: "", dropped: false });
+		assert.deepEqual(dropLeadingBang("ls!"), { text: "ls!", dropped: false });
+	});
+
+	it("光标反显包在 `!` 上时只摘 `!`，转义序列原样留下", () => {
+		// 行首那串零宽序列（`\x1b[7m`）属于 head，整段保留；紧跟其后的 `\x1b[0m` 仍然收尾，
+		// 所以不会把反显漏给行内其余字符。
+		assert.deepEqual(dropLeadingBang("\x1b[7m!\x1b[0mls"), { text: "\x1b[7m\x1b[0mls", dropped: true });
+		assert.deepEqual(dropLeadingBang("\x1b[7m!\x1b[0m"), { text: "\x1b[7m\x1b[0m", dropped: true });
+	});
+
+	it("CURSOR_MARKER 在行首时保留（它不占列）", () => {
+		assert.deepEqual(dropLeadingBang(`${CURSOR_MARKER}!ls`), {
+			text: `${CURSOR_MARKER}ls`,
+			dropped: true,
+		});
+		assert.deepEqual(dropLeadingBang(`${CURSOR_MARKER}\x1b[7m!\x1b[0mls`), {
+			text: `${CURSOR_MARKER}\x1b[7m\x1b[0mls`,
+			dropped: true,
+		});
+		assert.deepEqual(dropLeadingBang(`${CURSOR_MARKER}!`), {
+			text: `${CURSOR_MARKER}`,
+			dropped: true,
+		});
+	});
+
+	it("零宽序列后面不是 `!` 就一个字都不动（防御性）", () => {
+		assert.deepEqual(dropLeadingBang("\x1b[7mls"), { text: "\x1b[7mls", dropped: false });
+		assert.deepEqual(dropLeadingBang(`${CURSOR_MARKER}ls`), {
+			text: `${CURSOR_MARKER}ls`,
+			dropped: false,
+		});
+	});
+
+	it("导出的标记字符就是 Claude Code 的那个 `!`", () => {
+		assert.equal(BASH_MARKER, "!");
+	});
+});

package/extensions/prompt-editor/bash-prompt.ts

@@ -0,0 +1,59 @@
+/**
+ * `!` bash 模式（对齐 Claude Code 的 `!` 命令模式）的纯逻辑：模式判定 + 把渲染行行首那个
+ * `!` 摘掉。正文文本**一个字符都不改** —— pi 的 bash 判定（`interactive-mode.js` 的
+ * `onChange`）、Enter 提交（`text.startsWith("!")`）、↑ 历史、Esc 清空都还走它自己那条链路，
+ * 这里只回答「怎么画」。
+ *
+ * 刻意不 import pi / pi-tui（与 `thinking-collapse/window.ts` 同一条约定），所以
+ * `node --test clients/pi/extensions/prompt-editor/bash-prompt.test.ts` 能直接跑。
+ */
+
+/** Claude Code 的 bash 模式提示符（也是 pi 触发 bash 的那个字符）。 */
+export const BASH_MARKER = "!";
+
+export interface BashPromptState {
+	/**
+	 * gutter 要不要换成 `!`。判定与 pi 自己一字不差：`interactive-mode.js` 的 `onChange` 是
+	 * `text.trimStart().startsWith("!")`，而边框颜色（`updateEditorBorderColor`）用的就是同一个
+	 * 标志 —— 跟着它走，gutter 才不会和输入框颜色打架。
+	 */
+	active: boolean;
+	/**
+	 * 正文第一个字符就是 `!`，渲染时要把这一列从正文里摘掉（提示符已经占了它的位置）。
+	 *
+	 * 前导空白后跟 `!`（`" !ls"`）时 pi 也算 bash 模式，但那个 `!` 不在正文第一列、位置对不上
+	 * gutter，所以照常显示。这只影响这一个边角输入：边框颜色/提示符仍按 pi 的判定走，正文不动。
+	 */
+	hidden: boolean;
+}
+
+export function resolveBashPrompt(text: string): BashPromptState {
+	const active = text.trimStart().startsWith(BASH_MARKER);
+	return { active, hidden: active && text.startsWith(BASH_MARKER) };
+}
+
+export interface LeadingBangDrop {
+	/** 摘掉行首 `!` 之后的行；没有可摘的 `!` 时与输入逐字相同。 */
+	text: string;
+	/** 真的摘掉了一个可见字符（调用方据此把行尾补回一列，保持整行满宽）。 */
+	dropped: boolean;
+}
+
+/**
+ * 行首可能出现的零宽序列，pi-tui 的 Editor 只会给出这两种：
+ *   - CSI（`\x1b[7m` / `\x1b[0m`…）：光标反显那一段；
+ *   - APC 的 CURSOR_MARKER（`\x1b_pi:c\x07`）：硬件光标 / IME 定位用。
+ * 它们都占 0 列，摘 `!` 时要原样留在原位。
+ */
+const LEADING_ZERO_WIDTH = /^(?:\x1b\[[0-9;:?]*[ -/]*[@-~]|\x1b_[^\x07\x1b]*(?:\x07|\x1b\\))*/;
+
+/**
+ * 摘掉渲染行行首那个隐藏的 `!`（只摘第一个可见字符，其前的零宽转义原样保留）。
+ * 只在 `resolveBashPrompt().hidden` 为真、且这一行就是正文第一行（未滚动）时调用。
+ */
+export function dropLeadingBang(line: string): LeadingBangDrop {
+	const head = LEADING_ZERO_WIDTH.exec(line)?.[0] ?? "";
+	const rest = line.slice(head.length);
+	if (!rest.startsWith(BASH_MARKER)) return { text: line, dropped: false };
+	return { text: head + rest.slice(BASH_MARKER.length), dropped: true };
+}