@aiti-ai/aiti-git-trace 0.0.0-stage → 0.2.12

package/client/src/trace-app.tsx

@@ -0,0 +1,275 @@
+/**
+ * aiti-git-trace · client 入口薄壳（2026-09-13 薄壳拆分）
+ *
+ * 薄壳只做「零/低成本」的事：会话状态接线、工具条入口、徽标、回撤后验横幅，
+ * 以及把重面板（关注路径 / 时间线 / 回撤对话框，~1.2k 行）换成**懒加载包装**：
+ *   - 点工具条 / 徽标 / 横幅按钮 → openPanel 事件 → 薄壳桥（替面板翻 float 状态）
+ *     → 动态 import ./panels → 面板挂载并重放事件数据；
+ *   - 停靠面（rightFileDock / sidebarExplorerDock）→ 面渲染时才加载；
+ *   - forkGate → requestForkDialog（用到才加载，弹窗就绪后照旧走三选项）。
+ * 拆包动机：开页不再为未使用的面板付 ~60KB；panels chunk 由服务端批量包外置为
+ * 相对引用（client-bundle 只在交互时按需拉取）。
+ *
+ * 跨扩展对接点（window）：__aitiGitTraceForkDialog（兼容转调）、__aitiGitTraceBanner。
+ */
+import { useState, useEffect, t } from "./host-shim";
+import { usePresent, openFloat, isSidebarDockState } from "../../../_shared/ext-float-dock";
+import {
+  OPEN_EVENT, TIMELINE_KEY, WATCH_KEY, openPanel,
+  bindSession, getSessionId, fetchOpsCached,
+  btnStyle, chipStyle,
+} from "./common";
+
+// 会话服务接线继续由薄壳承担（entry.tsx 调用；重面板只读同一份模块态）
+export { installSessionService } from "./common";
+
+// ---------- 重面板懒加载桥 ----------
+
+type PanelsModule = {
+  WatchPanelSlot: any; WatchDockLeft: any; WatchDockRight: any;
+  TimelineSlot: any; TimelineDockRight: any; TimelineDockLeft: any;
+  ForkDialogSlot: any;
+  requestForkDialog: (params: any) => Promise<any>;
+};
+
+const panelsNeedSubs = new Set<() => void>();
+let panelsPromise: Promise<PanelsModule> | null = null;
+let panelsReady = false;
+let forkNeeded = false;
+
+function notifyPanelsNeed(): void {
+  for (const cb of [...panelsNeedSubs]) { try { cb(); } catch { /* noop */ } }
+}
+
+/** 加载重面板 chunk（幂等；失败允许重试——下次交互再触发）。 */
+export function loadPanels(): Promise<PanelsModule> {
+  if (!panelsPromise) {
+    panelsPromise = (import("./panels") as Promise<PanelsModule>).then((m) => {
+      panelsReady = true;
+      notifyPanelsNeed();
+      return m;
+    }).catch((e) => {
+      panelsPromise = null;
+      throw e;
+    });
+  }
+  return panelsPromise;
+}
+
+function keyOfKind(kind: string): string {
+  return kind === "timeline" ? TIMELINE_KEY : kind === "watch" ? WATCH_KEY : "aiti-git-trace:" + kind;
+}
+
+/**
+ * open 事件桥：面板监听只在其「面」被渲染时才存在（closed 态没有任何面板组件挂载），
+ * 所以桥不能只看 chunk 是否已加载——必须看该 kind 当前是否有挂载中的面（mountedKinds）：
+ *   - 有面挂载：只翻状态（面板自己的监听会拿 data）；
+ *   - 无面挂载：翻状态 + 暂存 data（面板挂载后 useReplayOpen 重放）+ 触发 chunk 加载。
+ */
+const pendingOpen = new Map<string, any>();
+const mountedKinds = new Map<string, number>();
+function markKindMounted(kind: string, active: boolean): () => void {
+  if (!active) return () => {};
+  mountedKinds.set(kind, (mountedKinds.get(kind) ?? 0) + 1);
+  return () => {
+    const n = (mountedKinds.get(kind) ?? 1) - 1;
+    if (n <= 0) mountedKinds.delete(kind);
+    else mountedKinds.set(kind, n);
+  };
+}
+if (typeof window !== "undefined") {
+  window.addEventListener(OPEN_EVENT, (e: any) => {
+    const d = e?.detail || {};
+    if (!d.kind) return;
+    const kind = String(d.kind);
+    if ((mountedKinds.get(kind) ?? 0) === 0) pendingOpen.set(kind, d.data);
+    openFloat(keyOfKind(kind));
+    void loadPanels().catch(() => { /* 加载失败：面板不可用（等价于从未打开） */ });
+  }, true);
+}
+
+/** enabled 时才加载并取回重面板组件（返回 null 表示尚未就绪）。 */
+function useHeavyComponent(enabled: boolean, which: keyof PanelsModule): any {
+  const [Comp, setComp] = useState<any>(null);
+  useEffect(() => {
+    if (!enabled || Comp) return;
+    let alive = true;
+    void loadPanels().then((m) => { if (alive) setComp(() => (m as any)[which]); }).catch(() => { /* 下次再试 */ });
+    return () => { alive = false; };
+  }, [enabled, which, Comp]);
+  return Comp;
+}
+
+/** 面板挂载后重放「薄壳期捕获的 open 数据」（面板自己的 OPEN_EVENT 监听此刻已注册）。 */
+function useReplayOpen(kind: string, Comp: any): void {
+  useEffect(() => {
+    if (!Comp || !pendingOpen.has(kind)) return;
+    const data = pendingOpen.get(kind);
+    pendingOpen.delete(kind);
+    try { window.dispatchEvent(new CustomEvent(OPEN_EVENT, { detail: { kind, data } })); } catch { /* noop */ }
+  }, [Comp, kind]);
+}
+
+/** 面激活判定（与重面板内部 gate 一致）：float=浮窗态；right=右栏 tab；left=sidebar 族停靠。
+ *  只有「面真的会被渲染」才加载 chunk——例如 dockpref=right-panel 但右栏 tab 未激活时不加载。 */
+function faceActive(face: "float" | "right" | "left", st: string): boolean {
+  if (face === "float") return st === "floating";
+  if (face === "right") return st === "docked:right-panel";
+  return isSidebarDockState(st);
+}
+
+/** 浮动面板包装（dialogs 槽常挂）：浮窗态才加载渲染。 */
+function floatPanel(kind: string, which: keyof PanelsModule) {
+  return function LazyFloatPanel(props?: any) {
+    const presented = usePresent(keyOfKind(kind));
+    const active = faceActive("float", presented);
+    useEffect(() => markKindMounted(kind, active), [kind, active]);
+    const Comp = useHeavyComponent(active, which);
+    useReplayOpen(kind, Comp);
+    return Comp ? <Comp {...(props ?? {})} /> : null;
+  };
+}
+
+/** 停靠面包装：面被宿主渲染 = 用户正在看 → 挂载即加载（仍按状态二次确认）。 */
+function dockFace(kind: string, face: "right" | "left", which: keyof PanelsModule) {
+  return function LazyDockFace(props?: any) {
+    const presented = usePresent(keyOfKind(kind));
+    const active = faceActive(face, presented);
+    useEffect(() => markKindMounted(kind, active), [kind, active]);
+    const Comp = useHeavyComponent(active, which);
+    useReplayOpen(kind, Comp);
+    return Comp ? <Comp {...(props ?? {})} /> : null;
+  };
+}
+
+export const WatchPanelSlot = floatPanel("watch", "WatchPanelSlot");
+export const WatchDockLeft = dockFace("watch", "left", "WatchDockLeft");
+export const WatchDockRight = dockFace("watch", "right", "WatchDockRight");
+export const TimelineSlot = floatPanel("timeline", "TimelineSlot");
+export const TimelineDockRight = dockFace("timeline", "right", "TimelineDockRight");
+export const TimelineDockLeft = dockFace("timeline", "left", "TimelineDockLeft");
+
+/** 回撤对话框包装：forkGate 请求时加载渲染。 */
+export function ForkDialogSlot(): any {
+  const [needed, setNeeded] = useState(forkNeeded);
+  useEffect(() => {
+    if (needed) return;
+    const cb = () => setNeeded(true);
+    panelsNeedSubs.add(cb);
+    return () => { panelsNeedSubs.delete(cb); };
+  }, [needed]);
+  const Comp = useHeavyComponent(needed, "ForkDialogSlot");
+  return Comp ? <Comp /> : null;
+}
+
+/** forkGate 入口（entry.tsx 调用）：用到才加载重面板，弹窗 Promise 语义与原实现一致。 */
+export async function requestForkDialog(params: any): Promise<any> {
+  forkNeeded = true;
+  notifyPanelsNeed();
+  const m = await loadPanels();
+  return m.requestForkDialog(params);
+}
+
+// ---------- 工具条按钮 ----------
+
+const toolbarBtnStyle: any = {
+  display: "flex", alignItems: "center", justifyContent: "center",
+  width: 36, height: 36, padding: 0, background: "none",
+  borderRight: "1px solid var(--border)", color: "var(--text-muted)",
+  cursor: "pointer", flexShrink: 0, fontSize: 16, lineHeight: 1, transition: "color 0.12s",
+};
+const svgProps = { width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true } as any;
+
+// 工具条按钮（⎇ 关注路径 / ⎇ 时间线）：纯静态组件，与 config/git-review 等扩展按钮同款注册方式。
+// feature 门控（trace.watchUI / trace.timelineUI，默认关）由宿主统一处理：registerItems 条目带 feature，
+// 关 → 宿主过滤不渲染（顶栏行/⋯菜单/自定义面板都不进，extman 变更实时生效）——扩展无需自己注册/注销或在组件内门控。
+
+export function WatchToolbarButton(props?: any) { bindSession(props);
+  return (
+    <button style={toolbarBtnStyle} title={t("gt.watch.title")} onClick={() => openPanel("watch")}>
+      <svg {...svgProps}><line x1="6" x2="6" y1="3" y2="15" /><circle cx="18" cy="6" r="3" /><circle cx="6" cy="18" r="3" /><path d="M18 9a9 9 0 0 1-9 9" /></svg>
+    </button>
+  );
+}
+
+export function TimelineToolbarButton(props?: any) { bindSession(props);
+  return (
+    <button style={toolbarBtnStyle} title={t("gt.timeline.title")} onClick={() => openPanel("timeline", { sessionId: getSessionId() })}>
+      <svg {...svgProps}><circle cx="12" cy="12" r="10" /><polyline points="12 6 12 12 16 14" /></svg>
+    </button>
+  );
+}
+
+// composerTools 插槽入口（输入框下方控制行，与压缩/导入同排；32×32 图标按钮与原生兄弟一致）——时间线主入口
+export function TimelineComposerButton(props?: any) { bindSession(props);
+  const sid = props?.sessionId || getSessionId(); // composerTools extra 直传 sessionId（chatInputTop 同款）
+  return (
+    <button
+      title={t("gt.timeline.title")}
+      aria-label={t("gt.timeline.title")}
+      onClick={() => openPanel("timeline", { sessionId: sid })}
+      style={{
+        display: "flex", alignItems: "center", justifyContent: "center", gap: 5,
+        width: 32, height: 32, padding: 0,
+        background: "none", border: "none", borderRadius: 9,
+        color: "var(--text-muted)", cursor: "pointer",
+        transition: "background 0.12s, color 0.12s",
+      }}
+      onMouseEnter={(e: any) => { e.currentTarget.style.background = "var(--bg-hover)"; e.currentTarget.style.color = "var(--text)"; }}
+      onMouseLeave={(e: any) => { e.currentTarget.style.background = "none"; e.currentTarget.style.color = "var(--text-muted)"; }}
+    >
+      <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden>
+        <circle cx="12" cy="12" r="10" />
+        <polyline points="12 6 12 12 16 14" />
+      </svg>
+    </button>
+  );
+}
+
+// ---------- 回撤后验横幅（§5.4 兜底） ----------
+
+export function BannerSlot(): any {
+  const [info, setInfo] = useState<any>(null);
+  useEffect(() => {
+    (window as any).__aitiGitTraceBanner = (i: any) => setInfo(i || null);
+    return () => { try { delete (window as any).__aitiGitTraceBanner; } catch {} };
+  }, []);
+  if (!info) return null;
+  return (
+    <div style={{ margin: "6px 12px", padding: "6px 12px", borderRadius: 8, border: "1px solid #d4a72c", color: "#9a6700", background: "var(--bg-panel)", display: "flex", gap: 10, alignItems: "center" }}>
+      <span>{String(t("gt.banner.text")).replace("{n}", String(info.count ?? "?"))}</span>
+      <button style={btnStyle} onClick={() => openPanel("timeline", { sessionId: info.sessionId })}>{t("gt.timeline.title")}</button>
+      <button style={btnStyle} onClick={() => setInfo(null)}>{t("gt.common.close")}</button>
+    </div>
+  );
+}
+
+// ---------- 用户消息徽标 ----------
+
+// 取数走 common.fetchOpsCached 共享缓存（§11.3 性能审计合并：此前徽标独立一份 TTL 缓存，
+// 与 footer 各拉一次 /ops；现单缓存 + ETag 再校验，live 失效走 invalidateOpsCache）
+
+export function MessageBadge(props?: any): any {
+  bindSession(props);
+  const entryId = String(props?.entryId || "");
+  const [ops, setOps] = useState<any[] | null>(null);
+  useEffect(() => {
+    if (!entryId) return;
+    let dead = false;
+    const sid = getSessionId();
+    if (!sid) return;
+    fetchOpsCached(sid).then((list) => { if (!dead) setOps(list); });
+    return () => { dead = true; };
+  }, [entryId]);
+  if (!entryId || ops === null) return null;
+  // 与时间线增量口径一致：纯基线 op（before=null）/无变更 op 不计入徽标
+  const hasDelta = (row: any) => (row.leaks || []).length > 0
+    || (row.stores || []).some((s: any) => s.before && (s.files ? (s.files.M || 0) + (s.files.A || 0) + (s.files.D || 0) : 0) > 0);
+  const mine = ops.filter((row: any) => (row.entryId === entryId || row.userEntryId === entryId) && hasDelta(row));
+  if (mine.length === 0) return null; // 该消息无被追踪操作：不渲染（避免噪音）
+  return (
+    // 场景 3：徽标带 entryId 打开 → 总览自动过滤到该轮
+    <button style={chipStyle} title={"aiti-git-trace：" + mine.length + " 个被追踪操作（点击看时间线）"}
+      onClick={() => openPanel("timeline", { sessionId: getSessionId(), entryId })}>⎇ {mine.length}</button>
+  );
+}

package/client/src/trace-files-row.pure.ts

@@ -0,0 +1,88 @@
+/**
+ * aiti-git-trace · assistantMessageFooter 数据面（纯函数，无依赖可直测）
+ * （方案 docs/aiti-git-trace-message-files-ext-plan.md §3.3）
+ *
+ * 输入 = 台账 ops 行（带外事实源，pi-git-trace 落盘）+ 宿主插槽 extra 的
+ * assistantEntryIds（整轮 assistant entry id 集合）。输出 = 本轮 trace 捕捉的
+ * 变更文件聚合；渲染前由组件与宿主 writtenFiles（write/edit 口径）求差集。
+ */
+
+/** 台账行（pi-git-trace/src/types.ts LedgerRow 的消费侧子集；宽松结构防漂移） */
+export interface LedgerRowLike {
+  entryId?: string;
+  userEntryId?: string;
+  stores?: Array<{
+    root?: string;
+    before?: string | null;
+    files?: { M?: number; A?: number; D?: number; skipped?: number };
+    paths?: string[];
+    pathsTruncated?: boolean;
+  }>;
+  leaks?: unknown[];
+  [k: string]: unknown;
+}
+
+/** 增量口径（与时间线/徽标一致）：纯基线 op（无 before）且无 leaks 不算变更。 */
+export function rowHasDelta(row: LedgerRowLike): boolean {
+  return (row.leaks || []).length > 0
+    || (row.stores || []).some((s) => Boolean(s.before)
+      && (s.files ? (s.files.M || 0) + (s.files.A || 0) + (s.files.D || 0) : 0) > 0);
+}
+
+/** 台账 paths 是仓相对路径 → 拼仓库根成绝对路径（已是绝对形态则原样）。 */
+export function toAbsPath(root: string | undefined, rel: string): string {
+  if (!rel) return "";
+  if (/^([a-zA-Z]:[\\/]|\/)/.test(rel)) return rel;
+  if (!root) return rel;
+  const sep = root.endsWith("/") || root.endsWith("\\") ? "" : "/";
+  return root + sep + rel;
+}
+
+export interface TraceTurnFiles {
+  /** 绝对路径（跨 store/跨 op 去重，首见序）。 */
+  absPaths: string[];
+  /** 任一 store 触发台账 paths 上限截断。 */
+  truncated: boolean;
+  /** 贡献文件的有增量 op 行数（title 展示用）。 */
+  ops: number;
+}
+
+/**
+ * 按整轮 assistant entry id 集合聚合台账 → 本轮 trace 捕捉的变更文件。
+ * 关联键 = row.entryId（携带该工具调用的 assistant/toolCall entry）。
+ * 无命中行 / 命中行全无增量 → null（渲染层整行不画）。
+ */
+export function aggregateTraceTurnFiles(
+  rows: LedgerRowLike[] | null | undefined,
+  assistantEntryIds: string[],
+): TraceTurnFiles | null {
+  const idSet = new Set((assistantEntryIds || []).map(String).filter(Boolean));
+  if (idSet.size === 0) return null;
+  const seen = new Set<string>();
+  const absPaths: string[] = [];
+  let truncated = false;
+  let ops = 0;
+  for (const row of rows || []) {
+    if (!idSet.has(String(row.entryId || ""))) continue;
+    if (!rowHasDelta(row)) continue;
+    ops++;
+    for (const s of row.stores || []) {
+      if (s?.pathsTruncated) truncated = true;
+      for (const p of s?.paths || []) {
+        const abs = toAbsPath(s?.root, String(p));
+        if (!abs || seen.has(abs)) continue;
+        seen.add(abs);
+        absPaths.push(abs);
+      }
+    }
+  }
+  if (absPaths.length === 0) return null;
+  return { absPaths, truncated, ops };
+}
+
+/** 路径归一（分隔符/尾斜杠）后的差集：trace 有、宿主 writtenFiles 没有的文件。 */
+export function diffAgainstWritten(absPaths: string[], writtenFiles: string[]): string[] {
+  const norm = (p: string) => String(p || "").replace(/\\/g, "/").replace(/\/+$/, "");
+  const written = new Set((writtenFiles || []).map(norm));
+  return (absPaths || []).filter((p) => !written.has(norm(p)));
+}

package/client/src/trace-files-row.tsx

@@ -0,0 +1,110 @@
+/**
+ * aiti-git-trace · assistantMessageFooter 变更文件行
+ * （方案 docs/aiti-git-trace-message-files-ext-plan.md §3.3/§3.4）
+ *
+ * 宿主在 assistant 消息「改动的文件」chips 之后挂 assistantMessageFooter 插槽：
+ * turn 最终回答渲染点 extra 带整轮 assistantEntryIds + 宿主推导的 writtenFiles
+ * （write/edit 口径）；普通 assistant 消息渲染点只有自身 entryId（消息级兜底）。
+ * 本组件把台账 ops 按这些 entryId 聚合、与 writtenFiles 求差集，只补 write/edit
+ * 之外的变更文件（bash 等），避免与宿主「改动的文件」重复；差集为空整行不画。
+ *
+ * 数据面：与徽标共用 common.fetchOpsCached 单缓存（§11.3 性能审计合并，TTL 4s + ETag
+ * 再校验）；挂载时拉取非轮询（严禁 setInterval）。live 轮次的最后几条 op 常在 TTL
+ * 窗口内落账——refcount 共享一条 SSE /events（本扩展自有通道，panels.tsx 同款），
+ * op 事件 → invalidateOpsCache 清缓存 + 800ms trailing 防抖通知挂载行重取（事件驱动，
+ * 连接零挂载即断）。
+ */
+import { useState, useEffect, apiUrl, t } from "./host-shim";
+import { bindSession, getSessionId, openPanel, chipStyle, EXT_API, fetchOpsCached, invalidateOpsCache } from "./common";
+import { aggregateTraceTurnFiles, diffAgainstWritten } from "./trace-files-row.pure";
+
+// ---------- 台账 op 事件 → 失效重取（refcount 共享 SSE；事件驱动非轮询） ----------
+
+const MAX_CHIPS = 8;
+const OP_DEBOUNCE_MS = 800; // panels.tsx 时间线同款：busy 轮 op 连爆不逐条重取
+
+const opSubs = new Set<(sid: string) => void>();
+let opEs: EventSource | null = null;
+let opDebounce: ReturnType<typeof setTimeout> | null = null;
+
+function subscribeOps(cb: (sid: string) => void): () => void {
+  opSubs.add(cb);
+  if (!opEs) {
+    try {
+      opEs = new EventSource(apiUrl(EXT_API + "/events"));
+      opEs.addEventListener("op", (e: any) => {
+        let sid = "";
+        try { sid = String(JSON.parse(String(e?.data || "{}"))?.sessionId || ""); } catch { return; }
+        if (!sid) return;
+        invalidateOpsCache(sid);
+        if (opDebounce) clearTimeout(opDebounce);
+        opDebounce = setTimeout(() => {
+          opDebounce = null;
+          for (const fn of [...opSubs]) { try { fn(sid); } catch { /* noop */ } }
+        }, OP_DEBOUNCE_MS);
+      });
+    } catch { opEs = null; /* EventSource 不可用：退化为挂载时取数，仅失实时化 */ }
+  }
+  return () => {
+    opSubs.delete(cb);
+    if (opSubs.size === 0) {
+      if (opEs) { try { opEs.close(); } catch { /* ignore */ } opEs = null; }
+      if (opDebounce) { clearTimeout(opDebounce); opDebounce = null; }
+    }
+  };
+}
+
+export function TraceFilesRow(props?: any): any {
+  bindSession(props);
+  // turn 粒度优先（assistantEntryIds）；缺省降级消息粒度（自身 entryId，§3.4 兜底）
+  const ids: string[] = Array.isArray(props?.assistantEntryIds) && props.assistantEntryIds.length
+    ? props.assistantEntryIds.map(String).filter(Boolean)
+    : props?.entryId ? [String(props.entryId)] : [];
+  const writtenFiles: string[] = Array.isArray(props?.writtenFiles)
+    ? props.writtenFiles.map(String).filter(Boolean)
+    : [];
+  const sessionId = String(props?.sessionId || "") || getSessionId();
+  const idKey = ids.join("|");
+  const [ops, setOps] = useState<any[] | null>(null);
+  const [expanded, setExpanded] = useState(false);
+  useEffect(() => {
+    if (!idKey || !sessionId) return;
+    let dead = false;
+    const refetch = () => { fetchOpsCached(sessionId).then((list) => { if (!dead) setOps(list); }); };
+    refetch();
+    const dispose = subscribeOps((sid) => { if (sid === sessionId) refetch(); });
+    return () => { dead = true; dispose(); };
+  }, [idKey, sessionId]);
+  if (!idKey || ops === null) return null;
+  const info = aggregateTraceTurnFiles(ops, ids);
+  if (!info) return null;
+  const extra = diffAgainstWritten(info.absPaths, writtenFiles);
+  if (extra.length === 0) return null;
+  const shown = expanded ? extra : extra.slice(0, MAX_CHIPS);
+  const hidden = extra.length - shown.length;
+  return (
+    <div style={{ display: "flex", flexWrap: "wrap", gap: 4, alignItems: "center", marginTop: -2 }}>
+      <span aria-hidden title={t("gt.footer.title", { n: info.ops })}
+        style={{ fontSize: 11, color: "var(--text-dim)", cursor: "default" }}>⎇</span>
+      {shown.map((p: string) => (
+        <button key={p}
+          style={{ ...chipStyle, maxWidth: 260, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}
+          title={p}
+          onClick={() => openPanel("timeline", { sessionId, view: "file", file: p })}>
+          {p.split("/").pop() || p}
+        </button>
+      ))}
+      {hidden > 0 && (
+        <button style={chipStyle} title={t("gt.footer.title", { n: info.ops })}
+          onClick={() => setExpanded(true)}>{t("gt.footer.more", { n: hidden })}</button>
+      )}
+      {expanded && extra.length > MAX_CHIPS && (
+        <button style={chipStyle} onClick={() => setExpanded(false)}>{t("gt.footer.collapse")}</button>
+      )}
+      {info.truncated && (
+        <span title={t("gt.footer.truncated")} aria-label={t("gt.footer.truncated")}
+          style={{ fontSize: 11, color: "var(--text-dim)", cursor: "default" }}>…</span>
+      )}
+    </div>
+  );
+}

package/client/src/version-mention.ts

@@ -0,0 +1,90 @@
+/**
+ * 版本引用文本构造（docs/aiti-git-trace-timeline-file-actions-plan.md §3）。
+ *
+ * 纯函数：无 React、无宿主 ctx 依赖，可直 node:test 单测。
+ * buildAtText（@ token 格式：空格加引号、目录尾斜杠）复用 _shared/new-session-cwd
+ * （与 aiti-doc-center / 宿主 buildAtMentionText 同源）。
+ */
+import { buildAtText } from "../../../_shared/new-session-cwd.ts";
+
+export interface VersionMentionInput {
+  /** 相对 root 的路径（@ token 用；buildAtText 决定引号格式） */
+  path: string;
+  /** 原仓 root（绝对路径，构造边路仓 gitDir=<root>/.aiti-trace） */
+  root: string;
+  /** before commit（完整 hash；可空=首触无基线） */
+  base?: string | null;
+  /** after commit（完整 hash；可空=loose 工作区无 commit） */
+  target?: string | null;
+  /** 行号（行级引用用；文件级引用不传） */
+  line?: number | null;
+  /** 行类型（决定行号归属 + 标注） */
+  lineKind?: "new" | "old" | "context" | "hunk" | "other";
+}
+
+const SHORT = (h?: string | null): string => (h ? String(h).slice(0, 7) : "");
+const trimSlash = (p: string): string => String(p || "").replace(/\/+$/, "");
+
+/**
+ * 构造带版本信息的引用文本：@ token（纯路径，宿主可点击解析）+ 附文（边路仓 git 命令）。
+ *
+ * 关键：after commit 在边路仓 .aiti-trace 里，原工作区仓没有此 commit——AI 在原仓跑 git show
+ * 会扑空。故附文给出指向边路仓的完整命令（--git-dir=<root>/.aiti-trace --work-tree=<root>），
+ * AI 直接复制可执行，能 show/diff 出历史版本。
+ */
+export function buildVersionMention(inp: VersionMentionInput): string {
+  const at = buildAtText(inp.path);
+  const root = trimSlash(inp.root);
+  const gitDir = `${root}/.aiti-trace`;
+  const target = inp.target || null;
+  const base = inp.base || null;
+  if (!target) {
+    return at + `（⏱ 时间线工作区版本，无边路 commit；可能非当前文件）`;
+  }
+  const parts: string[] = [`after=${SHORT(target)}`];
+  if (base && base !== target) parts.push(`base=${SHORT(base)}`);
+  if (inp.line != null) {
+    const kindTag = inp.lineKind === "old" ? "(旧文件)" : inp.lineKind === "new" ? "(新文件)" : "";
+    parts.push(`行${inp.line}${kindTag}`);
+  }
+  const showCmd = `git --git-dir=${gitDir} --work-tree=${root} show ${target}:${inp.path}`;
+  const diffCmd = (base && base !== target)
+    ? `\n或查看区间 diff：\ngit --git-dir=${gitDir} --work-tree=${root} diff ${base}..${target} -- ${inp.path}`
+    : "";
+  return at + `\n（⏱ 时间线历史版本 ${parts.join(" ")}；非当前文件，边路仓查看：\n${showCmd}${diffCmd}）`;
+}
+
+export interface DiffLineInfo {
+  line: number | null;
+  lineKind: "new" | "old" | "context" | "hunk" | "other";
+}
+
+/**
+ * 从 unified diff 行列表 + 点击索引，推算行号信息。
+ * 解析 `@@ -a,b +c,d @@` hunk 头 + 行前缀（+/−/空）累加。
+ * hunk 头之前的行（diff --git / index 等）→ other。
+ */
+export function resolveDiffLineInfo(lines: string[], index: number): DiffLineInfo {
+  let newLine = 0, oldLine = 0, inHunk = false;
+  for (let i = 0; i <= index && i < lines.length; i++) {
+    const ln = lines[i] || "";
+    const m = ln.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (m) {
+      oldLine = parseInt(m[1], 10);
+      newLine = parseInt(m[3], 10);
+      inHunk = true;
+      if (i === index) return { line: null, lineKind: "hunk" };
+      continue;
+    }
+    if (!inHunk) continue;
+    if (i === index) {
+      if (ln.startsWith("+")) return { line: newLine, lineKind: "new" };
+      if (ln.startsWith("-")) return { line: oldLine, lineKind: "old" };
+      return { line: newLine, lineKind: "context" };
+    }
+    if (ln.startsWith("+")) newLine++;
+    else if (ln.startsWith("-")) oldLine++;
+    else { newLine++; oldLine++; }
+  }
+  return { line: null, lineKind: "other" };
+}

package/deploy-commit.mjs

@@ -0,0 +1,52 @@
+/**
+ * deploy 脚本共享「部署状态 commit」助手（pi-web-ext 各扩展 tools/deploy.mjs 统一用）。
+ *
+ * 背景（2026-08-30 排障，session 0cc6ad47 op264）：重复部署同内容时
+ * `git add -A && git commit` 以 "nothing to commit" exit 1，而 stdio:"ignore" 吞掉
+ * stderr，输出「提交失败（忽略）：Command failed: …」假报警（msg-smart 实证）；
+ * 另有 --allow-empty 族每次部署都造空 commit 噪音。本助手统一三态语义：
+ *   committed → 有暂存变更，已提交
+ *   clean     → 无变更，跳过（不算失败）
+ *   failed    → git 真失败（带 stderr 首行，不阻断部署——部署本体永远优先）
+ *
+ * 用法：
+ *   import { deployCommit } from "../../_shared/deploy-commit.mjs";
+ *   deployCommit({ repo: extRepo, name: "aiti-msg-smart", paths: ["aiti-msg-smart"],
+ *                  log: (m) => console.log("[deploy] " + m) });
+ *
+ * 红线：本助手永不 throw、不触碰部署产物路径之外的任何东西；只对 <repo> 做
+ * add/diff/commit（默认 --no-verify，extRepo 无 hooks，防未来误挂）。
+ */
+import { execFileSync } from "node:child_process";
+
+export function deployCommit({ repo, name, paths = null, extraMsg = "", ident = false, log = console.log }) {
+  const git = (args) =>
+    execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  const firstLine = (s) => String(s || "").trim().split("\n")[0];
+  try {
+    // 暂存：默认只收本扩展子目录（与 add <ext> 行为对齐；避免把别的扩展的
+    // 未提交改动卷进本扩展的部署 commit）；paths=null 时退回 add -A 全仓。
+    git(["add", ...(paths && paths.length ? ["--", ...paths] : ["-A"])]);
+    let dirty;
+    try {
+      git(["diff", "--cached", "--quiet"]);
+      dirty = false; // exit 0 = 暂存区与 HEAD 一致
+    } catch (e) {
+      if (e.status !== 1) throw e; // 1 = 有变更；其他才是真错误
+      dirty = true;
+    }
+    if (!dirty) {
+      log("扩展仓库无变化（跳过提交）");
+      return { status: "clean" };
+    }
+    const stamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+    const msg = `[deploy] ${name} · ${stamp}${extraMsg ? " · " + extraMsg : ""}`;
+    git([...(ident ? ["-c", "user.name=deploy", "-c", "user.email=deploy@local"] : []), "commit", "--no-verify", "-m", msg]);
+    log("扩展仓库已提交：" + msg);
+    return { status: "committed", msg };
+  } catch (e) {
+    const reason = firstLine(e.stderr) || firstLine(e.message) || "git error";
+    log("提交失败（忽略，不影响部署）：" + reason);
+    return { status: "failed", reason };
+  }
+}