@yinan_chen/pi-claude-code-ui 0.0.0-stage → 0.2.0

package/src/skill-block-recollapse.ts

@@ -0,0 +1,362 @@
+/**
+ * skill-block-recollapse — 把展开的 skill 全文折回 `/skill:名字 参数`
+ *
+ * 覆盖四处 pi 没做折叠的地方：
+ *   A. `/tree` 回溯 / `/fork` 后回填到「输入框」的文本
+ *   B. `/tree` 列表里每一行的「预览文本」
+ *   C. `/fork` 的「Fork from Message」候选列表
+ *   D. `/resume` 会话列表里的首条消息摘要
+ *
+ * 上游已有两个同诉求 issue 被关（no-action）：#4995（/tree、/fork 回填）、#7424（/resume
+ * 列表）。维护者的立场是「core 保持最小，这类需求用 extension 解决」，本文件就是那个 extension。
+ *
+ * ── 问题 ──────────────────────────────────────────────────────────────────
+ * `/skill:foo bar` 在提交时被 AgentSession._expandSkillCommand() 展开成
+ *     <skill name="foo" location="/abs/SKILL.md">\n...SKILL.md 全文...\n</skill>\n\nbar
+ * 并以「展开后的全文」写入 session。聊天区显示成 `[skill] foo` 只是显示层的糖：
+ * TUI 用 parseSkillBlock() 识别这段文本后换成 SkillInvocationMessageComponent 折叠渲染。
+ *
+ * 但 `/tree` 回溯（AgentSession.navigateTree）用
+ *     editorText = contentText(targetEntry.message.content, "")
+ * 把「原始展开全文」回填输入框，没做反向折叠 —— 于是输入框里出现一整篇 SKILL.md。
+ * `/fork` 走 runtimeHost.fork() → editor.setText(result.selectedText) 是同一个毛病。
+ *
+ * 同理 `/tree` 列表：TreeList.getEntryDisplayText() → extractContent() 只是把 text block
+ * 拼起来再截断 200 字符，于是一行预览就是 `user: <skill name="herdr" location=…> # Herdr …`。
+ * `/fork` 的候选列表更直接：UserMessageList.render() 拿 item.text 把\n换空格就上屏。
+ *
+ * ── 修法 A：输入框 ────────────────────────────────────────────────────────
+ * 事件后补：session_tree（/tree 回溯）与 session_start（/fork、/clone 会开新 session）
+ * 触发后，等 TUI 把文本写进编辑器，再读回来；命中 skill block 就改写成
+ *     /skill:<name>[ <userMessage>]
+ * 光标随 setEditorText 落到末尾，可以直接继续敲参数或回车重发。
+ *
+ * ── 修法 B：tree 预览 ─────────────────────────────────────────────────────
+ * TreeList 类没有导出，但 TreeSelectorComponent 导出了，且它在构造函数里 new 了一个 TreeList
+ * 并用 getTreeList() 暴露。所以造一个空的探针实例 → 取到 TreeList.prototype → 包一层
+ * extractContent()：先用 extractFullContent() 拿未截断的全文（原实现先截 200 字符，skill
+ * 块的 ^…$ 锚定正则会失配），命中就返回 `[skill] <name>`，与聊天区的折叠渲染一致。
+ *
+ * 原型补丁对 TUI 之后 new 出来的所有 TreeList 生效（bundle 内部 new 的是模块局部绑定，
+ * 替换导出符号没用，但它们共享同一个 prototype）。副作用：tree 内搜索（Type to search）
+ * 对 skill 正文不再命中 —— 但原实现已经只索引前 200 字符，实际损失接近于零，而技能名仍可搜。
+ *
+ * ── 修法 C：fork 候选列表 ───────────────────────────────────────────────
+ * 同样的探针手法：UserMessageSelectorComponent 导出了，getMessageList() 拿到内部的
+ * UserMessageList → prototype。包一层 render()：上屏前把 this.messages 里命中 skill block
+ * 的 text 就地改写成 `[skill] <name>`。
+ * 就地改写是安全的：这个数组是 TUI 每次打开选择器时 `.map(m => ({id, text}))` 现造的副本，
+ * 而 onSelect 只用 id，真正回填编辑器的 selectedText 另走 runtimeHost.fork(entryId)。
+ *
+ * ── 修法 D：/resume 列表 ───────────────────────────────────────────────
+ * SessionList.render() 用 `session.name ?? session.firstMessage`，而 firstMessage 是
+ * buildSessionInfo() 直接取的首条 user 消息全文（未截断）。这里不走探针，而是直接包
+ * SessionManager.list / listAll 两个静态方法：调用方写的是 `SessionManager.list(…)`，
+ * 属性查找落在同一个类对象上，所以静态方法补丁能穿过模块局部绑定（这也是它比
+ * 替换导出符号可靠的原因）。包返回值足够的前提已变：0.86.0 起 --resume 改为渐进式
+ * 加载，onProgress 新增第三参 partialSessions（会话对象）直接流给 SessionSelector
+ * 渐进上屏（session-selector.js onProgress 分支），不经此补丁——加载过程中 skill
+ * 会话首消息会短暂闪现全文；resolve 后 SessionList.setSessions 用折叠过的最终列表
+ * 替换，最终显示仍折叠（一南 2026-09-20 目测验收）。若要消除闪烁，需把补丁扩展到
+ * onProgress 第三参。
+ *
+ * ── 时序 ──────────────────────────────────────────────────────────────────
+ * 事件在 navigateTree/fork 内部 await emit，TUI 的 editor.setText 在其返回后同步执行，
+ * 所以 setTimeout(0) 的宏任务天然排在写入之后。但 fork 路径要跨 session 重建 TUI，
+ * 时序没有保证，故用一串递增延迟轮询（0/16/50/120/250ms），命中即停。
+ *
+ * ── 安全性 ────────────────────────────────────────────────────────────────
+ * 只在编辑器内容「整体严格匹配」skill block 时才改写（parseSkillBlock 的正则带 ^…$ 锚定）。
+ * 用户自己手打的普通文本、粘贴的代码、含 <skill> 片段的说明文字都不会被动到。
+ * 用户若在补偿窗口内抢先改了内容，正则自然失配，本扩展直接放手。
+ */
+
+import {
+  parseSkillBlock,
+  SessionManager,
+  TreeSelectorComponent,
+  UserMessageSelectorComponent,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+// 只取纯常量/纯函数导出：pi-runtime 模块级零副作用，import 本身不触发 chunk 扫描
+// （扫描仅在 getPiRuntime() 被调用时发生），版本核对因此不付扫描成本。
+import { resolvePkgRoot, VERIFIED_PI_VERSION } from "./pi-runtime.ts";
+
+/** TUI 写入编辑器与本扩展读取之间的补偿轮询点（毫秒）。命中即停。 */
+const RETRY_DELAYS_MS = [0, 16, 50, 120, 250];
+
+/** 原实现 extractContent() 的截断长度，补丁保持一致。 */
+const TREE_PREVIEW_MAX_CHARS = 200;
+
+/** 原型补丁的幂等标记，避免 /reload 后反复套娃。 */
+const TREE_PATCHED = Symbol.for("skill-block-recollapse:treeListPatched");
+const FORK_PATCHED = Symbol.for("skill-block-recollapse:userMessageListPatched");
+const RESUME_PATCHED = Symbol.for("skill-block-recollapse:sessionListPatched");
+
+/** 三处列表补丁的安装结果：false = 未装上（留待事件重试），session_start 据此做一次性有声降级。 */
+const patchInstalled = { tree: false, fork: false, resume: false };
+
+/** 有声降级幂等标记：挂 globalThis（Symbol.for），/reload 重载模块后同一进程不再重弹。 */
+const DEGRADED_NOTIFIED = Symbol.for("skill-block-recollapse:degradedNotified");
+
+/** 补丁失败点 → 用户可感知的折叠点名称（对应文件头 B/C/D 三个列表覆盖点；A 是事件后补，不走补丁）。 */
+const PATCH_LABELS: Record<keyof typeof patchInstalled, string> = {
+  tree: "/tree 列表预览",
+  fork: "/fork 候选列表",
+  resume: "/resume 列表",
+};
+
+/** 当前 pi 版本（懒读一次，进程内复用）；取自 pi 包根 package.json，与 _shared 同源避免硬编码漂移。 */
+let piVersionMemo: string | undefined;
+function currentPiVersion(): string {
+  if (piVersionMemo === undefined) {
+    try {
+      piVersionMemo = String(JSON.parse(readFileSync(join(resolvePkgRoot(), "package.json"), "utf8")).version ?? "");
+    } catch {
+      piVersionMemo = "";
+    }
+  }
+  return piVersionMemo;
+}
+
+/**
+ * 有声降级（每进程一次）：补丁目标是 pi 私有 API，升级改名时只会静默 return false，
+ * 折叠功能无声消失。这里把「未装上」与「pi 版本 ≠ 逐版验证值」变成一条看得见的
+ * warning，明确告知对应点已回退原生显示，而不是让用户以为扩展坏了。
+ */
+function notifyDegradedOnce(ctx: ExtensionContext): void {
+  if (!ctx.hasUI) return;
+  const g = globalThis as any;
+  if (g[DEGRADED_NOTIFIED]) return;
+
+  const parts: string[] = [];
+  const failed = (Object.keys(patchInstalled) as (keyof typeof patchInstalled)[]).filter((k) => !patchInstalled[k]);
+  if (failed.length) parts.push(`${failed.map((k) => PATCH_LABELS[k]).join("、")}补丁未装上，已回退原生显示`);
+  const version = currentPiVersion();
+  // 版本比对警告默认静默（一南 2026-10-04：不想每次 pi 升级都提示）；PI_PATCH_VERSION_WARN=1 可临时启用。
+  // 真正的退化警告（上面的 failed 补丁未装上）不受此开关影响，出问题仍会提示。
+  if (version && version !== VERIFIED_PI_VERSION && (process.env.PI_PATCH_VERSION_WARN || "").trim() !== "")
+    parts.push(`pi ${version} ≠ 已验证 ${VERIFIED_PI_VERSION}，列表折叠未逐版核验`);
+  if (!parts.length) return;
+
+  try {
+    ctx.ui.notify(`skill-block-recollapse: ${parts.join("；")}`, "warning");
+    g[DEGRADED_NOTIFIED] = true; // notify 成功才记账；UI 未就绪抛错时留给下个 session_start 重试
+  } catch {
+    /* 静默 */
+  }
+}
+
+/** 把展开的 skill block 还原成斜杠命令；不是 skill block 返回 null。 */
+function collapseToSlashCommand(text: string): string | null {
+  const block = parseSkillBlock(text);
+  if (!block) return null;
+  return block.userMessage ? `/skill:${block.name} ${block.userMessage}` : `/skill:${block.name}`;
+}
+
+/**
+ * 列表类界面统一的单行标签：`[skill] name — 参数首行`（无参数则 `[skill] name`）。
+ * 聊天区折叠行只显示 `[skill] name`（pi 原生），列表预览多带参数首行是有意为之——列表里没有展开
+ * 的机会，参数是区分两次同名调用的唯一线索；sticky-first-message 的吸附泡用同一格式。
+ * 截断按可见宽度（不会切断代理对/组合字），与原实现的 200 字符上限对齐。
+ */
+function collapseToPreviewLabel(text: string): string | null {
+  const block = parseSkillBlock(text);
+  if (!block) return null;
+  const msg = (block.userMessage ?? "").split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+  const label = msg ? `[skill] ${block.name} — ${msg}` : `[skill] ${block.name}`;
+  return truncateToWidth(label, TREE_PREVIEW_MAX_CHARS, "…");
+}
+
+/**
+ * 给 TreeList.prototype.extractContent 套一层 skill 折叠。只做一次。
+ * @returns 是否已处于「已打好补丁」状态
+ */
+function patchTreePreview(): boolean {
+  let proto: Record<string | symbol, unknown>;
+  try {
+    // 空 tree 会让构造函数排一个 setTimeout(onCancel, 100)，传 noop 即可；探针实例不入任何容器，
+    // 构造完就丢，只为了拿 TreeList.prototype。那个定时器拿不到句柄，构造期间临时包一层
+    // setTimeout 给它 unref，别让探针把进程退出钉住 100ms。
+    const origSetTimeout = globalThis.setTimeout;
+    let probe: unknown;
+    try {
+      (globalThis as any).setTimeout = (fn: any, ms?: any, ...args: any[]) => {
+        const h = origSetTimeout(fn, ms, ...args);
+        (h as any)?.unref?.();
+        return h;
+      };
+      probe = new TreeSelectorComponent([], null, 20, () => {}, () => {});
+    } finally {
+      globalThis.setTimeout = origSetTimeout;
+    }
+    proto = Object.getPrototypeOf((probe as unknown as { getTreeList(): object }).getTreeList());
+  } catch {
+    // 主题/键位尚未初始化等情况：这次不打，下个事件再试。
+    return false;
+  }
+  if (proto[TREE_PATCHED]) return true;
+
+  const original = proto.extractContent as (content: unknown) => string;
+  const full = proto.extractFullContent as (content: unknown) => string;
+  if (typeof original !== "function" || typeof full !== "function") return false;
+
+  proto.extractContent = function patchedExtractContent(this: unknown, content: unknown): string {
+    let label: string | null = null;
+    try {
+      label = collapseToPreviewLabel(full.call(this, content));
+    } catch {
+      label = null;
+    }
+    return label ?? original.call(this, content);
+  };
+  proto[TREE_PATCHED] = true;
+  return true;
+}
+
+/**
+ * 给 UserMessageList.prototype.render 套一层 skill 折叠（/fork 的候选列表）。只做一次。
+ * @returns 是否已处于「已打好补丁」状态
+ */
+function patchForkPreview(): boolean {
+  let proto: Record<string | symbol, unknown>;
+  try {
+    const probe = new UserMessageSelectorComponent([], () => {}, () => {});
+    proto = Object.getPrototypeOf((probe as unknown as { getMessageList(): object }).getMessageList());
+  } catch {
+    return false;
+  }
+  if (proto[FORK_PATCHED]) return true;
+
+  const original = proto.render as (width: number) => string[];
+  if (typeof original !== "function") return false;
+
+  proto.render = function patchedRender(this: { messages?: { text?: string }[] }, width: number): string[] {
+    try {
+      for (const item of this.messages ?? []) {
+        if (typeof item?.text !== "string") continue;
+        const label = collapseToPreviewLabel(item.text);
+        // 写回副本对象；onSelect 只用 id，不影响 fork 结果。就地改写的安全性依赖
+        // pi 0.86.0 interactive-mode.js:4400 打开选择器时 `userMessages.map(m => ({id, text}))`
+        // 现造副本的实现细节——升级 pi 时必须核验该调用点仍在造副本，否则会污染源消息。
+        if (label) item.text = label;
+      }
+    } catch {
+      /* 折叠失败不能阻断渲染 */
+    }
+    return original.call(this, width);
+  };
+  proto[FORK_PATCHED] = true;
+  return true;
+}
+
+/**
+ * 给 SessionManager.list / listAll 套一层 skill 折叠（/resume 列表）。只做一次。
+ *
+ * ⚠️ 全局副作用：这是类静态方法补丁，进程内所有调用方（不只 /resume 的 SessionList）拿到的
+ * SessionInfo.firstMessage 都会被改写成 `[skill] name — …`。目前 pi 内只有 /resume 列表读这个字段；
+ * 若将来有全文搜索/去重/摘要等功能依赖 firstMessage 原文，在这里排查。改的是本次扫描现造的快照，
+ * 不回写 .jsonl。可用 PI_SKILL_RECOLLAPSE_RESUME=0 关闭这一处。
+ * @returns 是否已处于「已打好补丁」状态
+ */
+function patchResumePreview(): boolean {
+  if ((process.env.PI_SKILL_RECOLLAPSE_RESUME || "").trim() === "0") return true;
+  const cls = SessionManager as unknown as Record<string | symbol, unknown>;
+  if (cls[RESUME_PATCHED]) return true;
+
+  let wrapped = 0;
+  for (const name of ["list", "listAll"]) {
+    const original = cls[name];
+    if (typeof original !== "function") continue;
+    const fn = original as (...args: unknown[]) => Promise<{ firstMessage?: string }[]>;
+    cls[name] = function patchedList(this: unknown, ...args: unknown[]) {
+      return Promise.resolve(fn.apply(this, args)).then((sessions) => {
+        if (!Array.isArray(sessions)) return sessions;
+        for (const session of sessions) {
+          if (typeof session?.firstMessage !== "string") continue;
+          const label = collapseToPreviewLabel(session.firstMessage);
+          // 改的是本次列表扫描现造的 SessionInfo 快照，不回写任何 .jsonl。
+          if (label) session.firstMessage = label;
+        }
+        return sessions;
+      });
+    };
+    wrapped++;
+  }
+  if (wrapped === 0) return false;
+
+  cls[RESUME_PATCHED] = true;
+  return true;
+}
+
+export default function (pi: ExtensionAPI) {
+  /**
+   * 计划一次「读回编辑器 → 命中则折叠」的补偿。
+   * @param ctx 事件上下文，仅用 ctx.ui 的编辑器读写
+   */
+  function scheduleRecollapse(ctx: ExtensionContext): void {
+    // 只有 TUI 有真正的输入框；print / json / rpc 模式直接跳过。
+    if (ctx.mode !== "tui") return;
+
+    let settled = false;
+
+    function attempt(): void {
+      if (settled) return;
+      let current: string;
+      try {
+        current = ctx.ui.getEditorText();
+      } catch {
+        // 编辑器暂不可用（/fork 跨 session 重建中途、自定义 editor 尚未就位）：只跳过本次，
+        // 后续 16/50/120/250ms 的补偿点继续尝试；不能在这里 settled。
+        return;
+      }
+      const collapsed = collapseToSlashCommand(current);
+      if (collapsed === null) return; // 还没写入，或本来就不是 skill block
+      settled = true;
+      try {
+        ctx.ui.setEditorText(collapsed);
+      } catch {
+        /* 写入失败不影响会话，静默 */
+      }
+    }
+
+    for (const delay of RETRY_DELAYS_MS) {
+      // 别让补偿定时器把进程钉住（退出时 pi 不必等它）。
+      (setTimeout(attempt, delay) as unknown as { unref?: () => void }).unref?.();
+    }
+  }
+
+  // 即刻尝试一次：/reload 后不用等下一个事件，当场就能开 /tree、/fork 看到折叠效果。
+  // 非 TUI（主题未初始化）会安静失败返回 false，留给 session_start 重试。
+  patchInstalled.tree = patchTreePreview();
+  patchInstalled.fork = patchForkPreview();
+  // 不依赖主题/TUI，开机就能打上（首次 /resume 可能早于任何事件）。
+  patchInstalled.resume = patchResumePreview();
+
+  /** 打三个列表预览补丁；失败则留待下次事件重试。 */
+  function ensurePreviewsPatched(ctx: ExtensionContext): void {
+    if (ctx.mode !== "tui") return;
+    if (!patchInstalled.tree) patchInstalled.tree = patchTreePreview();
+    if (!patchInstalled.fork) patchInstalled.fork = patchForkPreview();
+    if (!patchInstalled.resume) patchInstalled.resume = patchResumePreview();
+  }
+
+  // /tree 回溯到某条 user 消息 → navigateTree 返回 editorText 后回填
+  pi.on("session_tree", async (_event, ctx) => {
+    ensurePreviewsPatched(ctx);
+    scheduleRecollapse(ctx);
+  });
+
+  // /fork、/clone、resume：新 session 起来后 TUI 才 setText(selectedText)
+  // 同时这里是打预览补丁最早的可靠时机（主题已初始化）。
+  pi.on("session_start", async (_event, ctx) => {
+    ensurePreviewsPatched(ctx);
+    // 补丁仍未装上/版本不符 → 一次性有声降级（幂等标记在 globalThis，reload 不会重弹）。
+    notifyDegradedOnce(ctx);
+    scheduleRecollapse(ctx);
+  });
+}