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

package/check-client.mjs

@@ -0,0 +1,273 @@
+/**
+ * check-client —— 扩展 client .mjs/.js 的 TS 残留 tripwire（零依赖，纯 node）。
+ *
+ * 背景：aiti-plan-review 事故（docs/aiti-ext-client-hardening-plan.md §1）——
+ * `useState<any>(null)` 解析为合法 JS 比较表达式 `useState < any > (null)`，
+ * node --check / TS 解析器 / babel 全不报错，只有运行时才炸。纯语法检查
+ * 原理性无效，只能启发式规则 + 渲染期错误边界兜底。
+ *
+ * 用法：
+ *   CLI    node check-client.mjs <file|dir>...        FAIL → exit 1
+ *   自测   node check-client.mjs --selftest           fixtures 全过 → exit 0
+ *   API    lintClientSource(src) → violations[]       { line, level, rule, text }
+ *          lintPath(path)        → { files, violations }（文件或目录，递归）
+ *          checkClientDir(dir,{log})                 FAIL → throw（deploy 脚本用）
+ *
+ * 词法：规则匹配前先剥离注释/字符串/模板字面量（${} 插值内代码保留检查）——
+ * aiti-editor 的 Monaco TS stub 模板串、JSDoc @return 都是合法内容，不剥全误报。
+ * 已知极限：regex 字面量含引号等 lexer 歧义允许漏报（tripwire 定位非编译器）。
+ *
+ * 豁免：目标行或其上一行含 `check-client:allow` 即跳过该行。
+ * 权威源：本文件；aiti-extman 部署副本由其 tools/deploy.mjs 拷贝（改动两处同步）。
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ── 规则（分级）──────────────────────────────────────────────────────────────
+
+const RULES = [
+  // FAIL：合法 JS 但运行时必炸 / 纯 TS 语法
+  { level: "FAIL", re: /\b(useState|useRef|useMemo|useCallback|useReducer|useImperativeHandle)\s*</, why: "React hook 泛型（运行时必炸）" },
+  // 注：含「any/unknown/string」字样的规则用字符串构 RegExp——本文件自身也
+  // 会被扫，正则字面量里的 (?:any 会被自己命中（词法器不处理 regex 字面量），
+  // 字符串字面量则会被词法遮蔽。
+  { level: "FAIL", re: new RegExp("\\bas\\s+(?:" + "any|unknown|const)\\b"), why: "as 断言" },
+  { level: "FAIL", re: new RegExp(":\\s*(?:" + "any|unknown)\\b"), why: ": any/: unknown 注解" },
+  { level: "FAIL", re: /\b(?:import|export)\s+type\s/, why: "import/export type" },
+  { level: "FAIL", re: /\b(?:interface|enum)\s+[A-Za-z_$]/, why: "interface/enum 声明" },
+  // warn：疑似残留，人工确认，不阻断
+  { level: "warn", re: new RegExp(":\\s*(?:" + "string|number|boolean|void)\\b(?!\\s*[._\\w])"), why: "疑似类型注解" },
+  { level: "warn", re: /\bsatisfies\s/, why: "satisfies" },
+  { level: "warn", re: /\b(?:Record|Partial|Readonly|Omit|Pick)\s*</, why: "TS 工具类型" },
+];
+
+// ── 词法剥离：注释/字符串/模板字面量 → 空格（保留换行，行号不漂移）─────────
+export function stripLiterals(src) {
+  const out = src.split("");
+  const n = src.length;
+  const mask = (from, to) => {
+    for (let k = from; k < to && k < n; k++) if (out[k] !== "\n") out[k] = " ";
+  };
+  let mode = "code";
+  let depth = 0;
+  const stack = []; // 模板 ${ 插值进入时的 brace 深度（支持嵌套模板）
+  let i = 0;
+  while (i < n) {
+    const c = src[i];
+    const d = i + 1 < n ? src[i + 1] : "";
+    if (mode === "code") {
+      if (c === "/" && d === "/") {
+        const j = src.indexOf("\n", i);
+        const end = j === -1 ? n : j;
+        mask(i, end);
+        i = end;
+      } else if (c === "/" && d === "*") {
+        const j = src.indexOf("*/", i + 2);
+        const end = j === -1 ? n : j + 2;
+        mask(i, end);
+        i = end;
+      } else if (c === "'" || c === '"') {
+        let j = i + 1;
+        while (j < n && src[j] !== c && src[j] !== "\n") j += src[j] === "\\" ? 2 : 1;
+        if (j < n && src[j] === c) {
+          mask(i, j + 1);
+          i = j + 1;
+        } else {
+          // 未闭合到行尾 → 可能是 regex 字面量歧义，只遮开引号，按代码继续
+          out[i] = " ";
+          i++;
+        }
+      } else if (c === "`") {
+        mode = "tpl";
+        out[i] = " ";
+        i++;
+      } else if (c === "{") {
+        depth++;
+        i++;
+      } else if (c === "}") {
+        if (stack.length && depth === stack[stack.length - 1]) {
+          stack.pop();
+          mode = "tpl"; // 插值结束回模板
+          out[i] = " ";
+        } else {
+          depth = Math.max(0, depth - 1);
+        }
+        i++;
+      } else i++;
+    } else if (mode === "tpl") {
+      if (c === "\\") {
+        mask(i, Math.min(i + 2, n));
+        i += 2;
+      } else if (c === "`") {
+        mode = "code";
+        out[i] = " ";
+        i++;
+      } else if (c === "$" && d === "{") {
+        stack.push(depth);
+        mode = "code";
+        mask(i, i + 2);
+        i += 2;
+      } else {
+        if (c !== "\n") out[i] = " ";
+        i++;
+      }
+    } else {
+      // 不可达：line/block/字符串均在 code 分支内联处理
+      i++;
+    }
+  }
+  return out.join("");
+}
+
+// ── 单源检查 ────────────────────────────────────────────────────────────────
+export function lintClientSource(src) {
+  const masked = stripLiterals(src);
+  const origLines = src.split("\n");
+  const maskedLines = masked.split("\n");
+  const violations = [];
+  for (let i = 0; i < maskedLines.length; i++) {
+    const prev = i > 0 ? origLines[i - 1] : "";
+    if (origLines[i].includes("check-client:allow") || prev.includes("check-client:allow")) continue;
+    for (const { level, re, why } of RULES) {
+      if (re.test(maskedLines[i])) {
+        violations.push({ line: i + 1, level, rule: why, text: origLines[i].trim().slice(0, 90) });
+      }
+    }
+  }
+  return violations;
+}
+
+// ── 文件/目录检查 ───────────────────────────────────────────────────────────
+const SKIP_DIR = new Set(["node_modules", ".git"]);
+/** 超过此体积视为 vendored bundle（如 Monaco ts.worker，合法含 interface 字样），不查。 */
+const MAX_BYTES = 512 * 1024;
+const isClientFile = (name) => /\.(mjs|js|cjs)$/.test(name) && !/\.min\./.test(name) && !/\.test\./.test(name);
+
+export function lintPath(p, out = { files: 0, violations: [] }) {
+  const st = statSync(p);
+  if (st.isDirectory()) {
+    for (const name of readdirSync(p)) {
+      if (SKIP_DIR.has(name)) continue;
+      lintPath(join(p, name), out);
+    }
+    return out;
+  }
+  const base = p.split("/").pop();
+  if (!isClientFile(base)) return out;
+  if (st.size > MAX_BYTES) return out; // vendored bundle 豁免
+  out.files++;
+  for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  return out;
+}
+
+export function formatViolations(violations) {
+  return violations
+    .map((v) => `  ${v.level} ${v.file}:${v.line} [${v.rule}] ${v.text}`)
+    .join("\n");
+}
+
+/** deploy 脚本用：检查目录，FAIL 抛错（消息含违规清单），warn 只打日志不阻断。 */
+export function checkClientDir(dir, { log = console.log } = {}) {
+  const { files, violations } = lintPath(resolve(dir));
+  const fails = violations.filter((v) => v.level === "FAIL");
+  const warns = violations.filter((v) => v.level === "warn");
+  if (warns.length) log(`[check-client] ${warns.length} 处疑似 TS 残留（不阻断，建议人工确认）：\n${formatViolations(warns)}`);
+  if (fails.length) {
+    throw new Error(
+      `client 检查未通过：${files} 个文件中 ${fails.length} 处 TS 残留（.mjs 里是合法 JS，语法检查不报，运行时必炸）。\n` +
+        formatViolations(fails) +
+        `\n修复或在该行加注释 // check-client:allow 豁免。详见 docs/aiti-ext-client-hardening-plan.md`,
+    );
+  }
+  if (files) log(`[check-client] ${files} 个 client 文件检查通过`);
+  return { files, fails: fails.length, warns: warns.length };
+}
+
+/**
+ * extman 安装用：扫整个扩展目录（含第三方，不遵循 client/ 约定）。
+ * 在 SKIP_DIR 之上额外跳过构建产物/vendored 目录（Monaco ts.worker、语言包等
+ * 合法包含 TS 字样，词法器对 minified 代码不提供保证）；体积上限同上。
+ */
+export function lintExtensionDir(dir) {
+  const out = { files: 0, violations: [] };
+  const walk = (p) => {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p)) {
+        if (SKIP_DIR.has(name) || VENDORED_DIRS.has(name)) continue;
+        walk(join(p, name));
+      }
+      return;
+    }
+    const base = p.split("/").pop();
+    if (!isClientFile(base) || st.size > MAX_BYTES) return;
+    out.files++;
+    for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  };
+  walk(resolve(dir));
+  return out;
+}
+const VENDORED_DIRS = new Set(["vendor", "monaco", "dist", "build", "assets", "static", "bundles", "chunks"]);
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+function selftest() {
+  const MUST_FAIL = [
+    "const [st, setSt] = useState<any>(null);",
+    "const r = useRef<number>(null);",
+    "const x = v as any;",
+    "function f(a: unknown) {}",
+    'import type { Foo } from "./x";',
+    "interface Foo { a: string }",
+    "enum Color { Red }",
+    "const y = v as const;",
+  ];
+  const MUST_WARN = [
+    "const opts = { mode: string };",
+    "x satisfies Y;",
+    "const m: Record<string, any> = {};",
+  ];
+  const MUST_PASS = [
+    'const REACT_TYPE_STUB = `\ndeclare module "react" {\n  export function useState<T>(init: T): [T];\n  export const Fragment: any;\n}\n`;',
+    "/** @return {{chars1: string, chars2: string}} */",
+    "const [s] = useState(null);",
+    "useState<any>(null); // check-client:allow",
+    "// check-client:allow\nuseState<never>(0);",
+    "const cmp = a < b && c > (d);",
+    "if (a // 注释里 as any 不算\n  ) run();",
+  ];
+  let bad = 0;
+  const check = (src, expect, desc) => {
+    const v = lintClientSource(src);
+    const fails = v.filter((x) => x.level === "FAIL");
+    const ok = expect === "FAIL" ? fails.length > 0 : expect === "PASS" ? v.length === 0 : v.length > 0 && fails.length === 0;
+    if (!ok) {
+      bad++;
+      console.log(`SELFTEST FAIL [${desc}] 期望 ${expect}，实际 ${JSON.stringify(v)}`);
+    }
+  };
+  MUST_FAIL.forEach((s) => check(s, "FAIL", s.slice(0, 40)));
+  MUST_WARN.forEach((s) => check(s, "WARN", s.slice(0, 40)));
+  MUST_PASS.forEach((s) => check(s, "PASS", s.replace(/\n/g, "⏎").slice(0, 40)));
+  if (bad) {
+    console.log(`selftest: ${bad} 处未过`);
+    process.exit(1);
+  }
+  console.log("selftest: 全部通过（8 FAIL / 3 WARN / 7 PASS）");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.filename)) {
+  if (process.argv.includes("--selftest")) {
+    selftest();
+  } else if (process.argv.length > 2) {
+    const all = { files: 0, violations: [] };
+    for (const p of process.argv.slice(2)) lintPath(resolve(p), all);
+    const fails = all.violations.filter((v) => v.level === "FAIL");
+    const warns = all.violations.filter((v) => v.level === "warn");
+    if (all.violations.length) console.log(formatViolations(all.violations));
+    console.log(`\n${all.files} 个文件：FAIL=${fails.length} warn=${warns.length}`);
+    process.exit(fails.length ? 1 : 0);
+  } else {
+    console.log("用法：node check-client.mjs <file|dir>... ｜ --selftest");
+    process.exit(2);
+  }
+}

package/client/src/common.ts

@@ -0,0 +1,179 @@
+/**
+ * aiti-git-trace · 共享层（薄壳与重面板共用）
+ *
+ * 拆包契约（2026-09-13 薄壳拆分）：本文件只放两侧都要用的东西——session 状态、
+ * API 小工具、open 事件/浮动键、样式。**不得 import 重面板模块**（panels.tsx 反向依赖本文件）。
+ */
+import { useState, useEffect, apiUrl } from "./host-shim";
+import { usePresent, openFloat, closePanel } from "../../../_shared/ext-float-dock";
+
+export const TIMELINE_KEY = "aiti-git-trace:timeline";
+export const WATCH_KEY = "aiti-git-trace:watch";
+
+// ---------- 小工具 ----------
+
+export const OPEN_EVENT = "aiti-git-trace-open";
+export function openPanel(kind: string, data?: any) {
+  (window as any).dispatchEvent(new CustomEvent(OPEN_EVENT, { detail: { kind, data } }));
+}
+
+/** dock v3：kind → itemKey 映射 + 状态机收口（CustomEvent 只作入口总线，开/关走 openFloat/closePanel）。
+ *  开/关走 openFloat/closePanel；open 态 = 非 closed（浮窗与停靠都算开，effect 数据加载照旧）。
+ *  返回 [open, setOpen, presented]——presented 供渲染分面（floating / docked:<zone>）。 */
+export function useOpenKind(kind: string, onData?: (d: any) => void): [boolean, (v: boolean) => void, string] {
+  const key = kind === "timeline" ? TIMELINE_KEY : kind === "watch" ? WATCH_KEY : "aiti-git-trace:" + kind;
+  const st = usePresent(key);
+  const open = st !== "closed";
+  useEffect(() => {
+    const fn = (e: Event) => {
+      const d = (e as CustomEvent).detail || {};
+      if (d.kind === kind) { onData && onData(d.data); openFloat(key); }
+      else if (d.kind === null) { closePanel(TIMELINE_KEY); closePanel(WATCH_KEY); }
+    };
+    (window as any).addEventListener(OPEN_EVENT, fn);
+    return () => (window as any).removeEventListener(OPEN_EVENT, fn);
+  }, []);
+  const setOpen = (v: boolean) => { if (v) openFloat(key); else closePanel(key); };
+  return [open, setOpen, st];
+}
+
+export const EXT_API = "/api/extensions/aiti-git-trace";
+
+export async function apiGet(path: string): Promise<any> {
+  const r = await fetch(apiUrl(EXT_API + path), { headers: { accept: "application/json" } });
+  return r.json();
+}
+export async function apiPost(path: string, body: any, method = "POST"): Promise<any> {
+  const r = await fetch(apiUrl(EXT_API + path), {
+    method, headers: { "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return r.json();
+}
+
+// ---------- /ops 共享取数（§11.3 性能审计：badge/footer 此前各持独立缓存，每开页重复拉一次） ----------
+const OPS_TTL_MS = 4000;
+
+/** 台账 ops 共享取数（badge/footer 同一缓存）：TTL 内直用；过期带 If-None-Match 再校验
+ *  （服务端台账未变 → 304 零传输续用）；失败保留旧 rows 防闪空。缓存挂 SHARED 单例
+ *  （本模块双实例约束，见 SHARED 注释）。 */
+export function fetchOpsCached(sid: string): Promise<any[]> {
+  if (!sid) return Promise.resolve([]);
+  const now = Date.now();
+  const c = SHARED.opsCache;
+  if (c && c.sid === sid && now - c.at < OPS_TTL_MS) return Promise.resolve(c.rows);
+  if (SHARED.opsInflight && SHARED.opsInflight.sid === sid) return SHARED.opsInflight.promise;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (c && c.sid === sid && c.etag) headers["if-none-match"] = c.etag;
+  const promise = fetch(apiUrl(EXT_API + "/ops?session=" + encodeURIComponent(sid)), { headers })
+    .then(async (r) => {
+      if (r.status === 304 && SHARED.opsCache && SHARED.opsCache.sid === sid) {
+        SHARED.opsCache.at = Date.now();
+        return SHARED.opsCache.rows;
+      }
+      const body = await r.json().catch(() => null);
+      const rows = (body && body.ops) || [];
+      SHARED.opsCache = { sid, at: Date.now(), etag: r.headers.get("etag"), rows };
+      return rows;
+    })
+    .catch(() => (SHARED.opsCache && SHARED.opsCache.sid === sid ? SHARED.opsCache.rows : []));
+  SHARED.opsInflight = { sid, promise };
+  const clearInflight = () => { if (SHARED.opsInflight && SHARED.opsInflight.sid === sid) SHARED.opsInflight = null; };
+  promise.then(clearInflight, clearInflight);
+  return promise;
+}
+
+/** SSE op 事件失效：清指定会话缓存条目（下一次取全量 200）。sid 空 = 全清。 */
+export function invalidateOpsCache(sid?: string): void {
+  if (SHARED.opsCache && (!sid || SHARED.opsCache.sid === sid)) SHARED.opsCache = null;
+}
+
+/** 宿主每次渲染都会下发 currentSession——组件挂载时捕获到模块级，供 getSessionId() 使用 */
+/**
+ * 宿主每次渲染都会下发 currentSession——组件挂载时捕获，供 getSessionId() 使用。
+ *
+ * ⚠ 薄壳拆分后本模块存在两份实例（批量包内联的 shell 副本 + panels chunk 经相对
+ * import 拉起的 entry 文件副本）——可变状态必须挂 globalThis 单例共享，否则
+ * 面板侧读不到会话（会打出无 session 的幻影请求）。
+ */
+const SHARED: {
+  current: { id?: string; cwd?: string; name?: string; firstMessage?: string } | null;
+  svc: { id: string; cwd: string } | null;
+  svcInstalled: boolean;
+  opsCache: { sid: string; at: number; etag: string | null; rows: any[] } | null;
+  opsInflight: { sid: string; promise: Promise<any[]> } | null;
+} = ((globalThis as any).__aitiGitTraceShared ??= { current: null, svc: null, svcInstalled: false, opsCache: null, opsInflight: null });
+
+export function bindSession(props?: any): void {
+  const cs = props?.currentSession;
+  if (cs && (cs.id || cs.cwd || cs.name)) SHARED.current = { id: cs.id, cwd: cs.cwd, name: cs.name, firstMessage: cs.firstMessage };
+}
+
+// ── 统一会话状态服务（pi-web.session，方案 docs/pi-web-session-state-and-perf-plan.md §4）──
+// 仅在 phase=active 时使用 canonical sessionId；**禁止 URL ?session= 未验证兜底**
+//（会话已删除时打出幻影请求）。消费范式：判空降级 + onExtServiceChange 等待。
+function applySessionSnapshot(snap: any): void {
+  SHARED.svc = snap && snap.phase === "active" && snap.sessionId
+    ? { id: String(snap.sessionId), cwd: String(snap.session?.cwd ?? "") }
+    : null;
+}
+/** 挂载统一会话服务订阅（entry.tsx 调用一次；服务缺席时静默降级到 props 通道）。 */
+export function installSessionService(ctx: Record<string, any>): void {
+  if (SHARED.svcInstalled) return;
+  SHARED.svcInstalled = true;
+  const attach = (): boolean => {
+    const svc = ctx.getExtService?.("pi-web.session");
+    if (!svc?.subscribe) return false;
+    svc.subscribe(applySessionSnapshot);
+    return true;
+  };
+  if (!attach()) {
+    ctx.onExtServiceChange?.((key: string, phase: string) => {
+      if (key === "pi-web.session" && phase === "up") attach();
+    });
+  }
+}
+
+export function getSessionId(): string {
+  // 1) 统一服务（active canonical，唯一权威）；2) 插槽 props（已解析值）；3) 不做 URL 兜底
+  if (SHARED.svc?.id) return SHARED.svc.id;
+  if (SHARED.current?.id) return String(SHARED.current.id);
+  return "";
+}
+export function getCwd(): string {
+  return String(SHARED.svc?.cwd || SHARED.current?.cwd || "");
+}
+
+export const panelStyle: any = {
+  position: "fixed", right: 18, top: 64, zIndex: 10050, width: 460, maxWidth: "92vw",
+  maxHeight: "78vh", overflow: "auto", background: "var(--bg-panel)", color: "var(--text)",
+  border: "1px solid var(--border)", borderRadius: 10, padding: 14,
+  boxShadow: "0 8px 32px rgba(0,0,0,.45)", fontSize: 13, lineHeight: 1.5,
+};
+export const btnStyle: any = {
+  cursor: "pointer", borderRadius: 6, border: "1px solid var(--border)",
+  background: "var(--bg-panel)", color: "inherit", padding: "3px 10px", fontSize: 12,
+};
+export const chipStyle: any = { ...btnStyle, padding: "1px 7px", fontSize: 11, opacity: 0.9 };
+export const inputStyle: any = {
+  borderRadius: 6, border: "1px solid var(--border)", background: "var(--bg)",
+  color: "inherit", padding: "4px 8px", fontSize: 12, width: "100%", boxSizing: "border-box",
+};
+/** float 契约滚动层：float 给面板根补 display:flex/column + overflow:hidden，内容区必须自带滚动（docs/aiti-web-ext-float-dialogs.md） */
+export const scrollLayerStyle: any = { flex: 1, minHeight: 0, overflowY: "auto" };
+
+export const badgeStyle = (kind: string): any => ({
+  cursor: "pointer", marginLeft: 6, padding: "0 6px", borderRadius: 8, fontSize: 11,
+  border: "1px solid", ...(kind === "cross" ? { color: "#9a6700", borderColor: "#d4a72c" }
+    : kind === "leak" ? { color: "#cf222e", borderColor: "#f1c1c1" }
+    : { color: "var(--text-dim)", borderColor: "var(--border)" }),
+});
+
+/** 时间格式：今天显示 HH:MM，更早显示日期（文件视图行尾/触达行用） */
+export function fmtTime(ts?: number): string {
+  if (!ts) return "";
+  const d = new Date(ts);
+  return d.toDateString() === new Date().toDateString()
+    ? d.toTimeString().slice(0, 5)
+    : d.toLocaleDateString();
+}

package/client/src/entry.tsx

@@ -0,0 +1,81 @@
+/**
+ * aiti-git-trace · client 入口（JSX + TypeScript + vite 构建）
+ *
+ * 装配（§8.2）：
+ *   - toolbar「⎇ 关注路径」/「⎇ 时间线」
+ *   - dialogs：关注路径面板 / ops 时间线 / 回撤三选项对话框（全局 Promise API）
+ *   - banners：回撤后验横幅（兜底版，window.__aitiGitTraceBanner）
+ *   - userMessageActions：「⎇」徽标（打开时间线）
+ *
+ * 跨扩展对接点（window）：__aitiGitTraceForkDialog（forkGate 未来调用）、__aitiGitTraceBanner（core fork 后调用）
+ */
+import { __setCtx } from "./host-shim";
+import { seedDockDefault, declareDockZones, sidebarZoneOf } from "../../../_shared/ext-float-dock";
+// 薄壳版：面板组件名保持不变（内部是懒加载包装），新增 requestForkDialog（用到才拉重 chunk）
+import { WatchToolbarButton, TimelineToolbarButton, TimelineComposerButton, WatchPanelSlot, WatchDockLeft, WatchDockRight, TimelineSlot, TimelineDockRight, TimelineDockLeft, ForkDialogSlot, BannerSlot, MessageBadge, installSessionService, requestForkDialog } from "./trace-app";
+import { TraceFilesRow } from "./trace-files-row";
+
+export default function register(ctx: Record<string, any>) {
+  __setCtx(ctx);
+  // 统一会话状态服务订阅（pi-web.session）：仅 active 时用 canonical id；服务缺席降级 props 通道。
+  installSessionService(ctx);
+
+  // aiti-float dock v3（P1/P2 批）：时间线默认右栏（用户定调，left⇄right 可切）；关注路径不设 default。
+  // dock 槽注册专用 face 变体（face 参数保证只有激活面渲染，防 dialogs/dock 双实例同渲）
+  seedDockDefault("aiti-git-trace:timeline", "right-panel");
+  // zones 进注册表：TabBar ⇱ 菜单（后台 tab）也能看到 left⇄right 全集（v3.1）
+  declareDockZones("aiti-git-trace:timeline", ["right-panel", sidebarZoneOf("aiti-git-trace:timeline")], "right-panel");
+  declareDockZones("aiti-git-trace:watch", [sidebarZoneOf("aiti-git-trace:watch"), "right-panel"], sidebarZoneOf("aiti-git-trace:watch"));
+  ctx.registerItems?.("rightFileDock", [
+    { id: "timeline", render: TimelineDockRight, meta: { title: "时间线" } },
+    { id: "watch", render: WatchDockRight, meta: { title: "关注路径" } },
+  ]);
+  ctx.registerItems?.("sidebarExplorerDock", [
+    { id: "timeline", render: TimelineDockLeft, meta: { title: "时间线", priority: 3 } },
+    { id: "watch", render: WatchDockLeft, meta: { title: "关注路径", priority: 3 } },
+  ]);
+
+  // 工具条独立入口：静态注册 + feature 门控（默认关）——宿主按 feature 统一显隐（关 → 顶栏行/⋯菜单/自定义面板都不进，
+  // extman 切换实时生效），扩展零门控代码（参照 session-manager / aiti-acp-agent）
+  //   ⎇ 关注路径 → trace.watchUI（入口在时间线面板顶部）
+  //   ⎇ 时间线   → trace.timelineUI（主入口在输入框下方控制行 composerTools 插槽）
+  ctx.registerItems?.("toolbar", [
+    { id: "aiti-git-trace-watch", render: WatchToolbarButton, meta: { label: "关注路径", icon: "icons/git-branch.svg" }, feature: "trace.watchUI" },
+    { id: "aiti-git-trace-timeline", render: TimelineToolbarButton, meta: { label: "时间线", icon: "icons/git-commit-horizontal.svg" }, feature: "trace.timelineUI" },
+  ]);
+  ctx.registerItems?.("composerTools", [
+    { id: "aiti-git-trace-timeline-entry", render: TimelineComposerButton, meta: { label: "时间线" } },
+  ]);
+  ctx.registerItems?.("dialogs", [
+    { id: "aiti-git-trace-watch-dialog", render: WatchPanelSlot },
+    { id: "aiti-git-trace-timeline-dialog", render: TimelineSlot },
+    { id: "aiti-git-trace-fork-dialog", render: ForkDialogSlot },
+  ]);
+  ctx.registerItems?.("banners", [{ id: "aiti-git-trace-banner", render: BannerSlot }]);
+  ctx.registerItems?.("userMessageActions", [{ id: "aiti-git-trace-badge", render: MessageBadge }]);
+  // assistantMessageFooter（2026-09-17）：assistant 消息底部 trace 变更文件行
+  // （方案 docs/aiti-git-trace-message-files-ext-plan.md）。旧宿主无此插槽 →
+  // registerItems 可能抛错/无渲染点，try/catch 静默降级（aiti-ctx-meter 先例）。
+  try {
+    ctx.registerItems?.("assistantMessageFooter", [
+      { id: "aiti-git-trace-footer", render: TraceFilesRow },
+    ]);
+  } catch { /* 旧宿主：无此插槽，静默无 UI */ }
+
+  // §5.4 forkGate：编辑重发/fork 前置门——有被追踪操作时弹回撤三选项；弹窗未就绪/无操作则放行
+  ctx.registerSessionForkGate?.(async (info: any) => {
+    try {
+      // 薄壳拆分：gate 触发时才加载重面板（含三选项对话框）——语义与原 window 全局一致。
+      const r = await requestForkDialog({
+        sessionId: info?.sessionId || "",
+        entryId: info?.entryId || "",
+        // 方案 §3.3：被裁轮次集合（M 及之后全部用户消息 entryId）——优先按它精确圈定区间（含被编辑轮）
+        cutUserEntryIds: Array.isArray(info?.cutUserEntryIds) ? info.cutUserEntryIds.map(String).filter(Boolean) : [],
+      });
+      return !(r && r.action === "cancel"); // rollback/keep 都放行 fork（回滚已先行落地）
+    } catch { return true; }
+  });
+
+  try { console.log("[aiti-git-trace] client 已挂载（关注路径/时间线/回撤对话框/横幅/徽标）"); } catch {}
+  return () => {};
+}

package/client/src/host-shim.ts

@@ -0,0 +1,118 @@
+/**
+ * host-shim —— JSX client bundle 的宿主桥（共享模板通用版）。
+ *
+ * 为什么需要它：浏览器不认识 JSX，扩展 client 要写 JSX 必须经过 esbuild 预编译
+ * （vite lib mode）。esbuild 的 JSX 自动运行时（jsx: "automatic"）会生成
+ * `jsx(type, props)` 调用，默认指向 React。但 pi-web 的扩展 client 不是 React——
+ * 宿主经 register(ctx) 传入的是自己的渲染原语（h / useState / useEffect / apiUrl…）。
+ *
+ * 所以这里用 vite 的 resolve.alias 把 react / react/jsx-runtime 重定向到本 shim：
+ *   组件里 import react 的 hooks → 本 shim 的 createElement/useState/… → 委托 ctx。
+ * 产物里零 React 引用，宿主保持单渲染实例，npm 生态组件（只要用标准 react hooks）
+ * 也能直接打包进来用。
+ *
+ * 使用：entry.tsx 的 register(ctx) 里第一件事调 `__setCtx(ctx)`（任何 JSX 渲染前）。
+ * 需要的字段（apiUrl/t/useRef/useMemo…）按需在这里加一行委托即可。
+ */
+
+// 模块级 ctx（entry.tsx 的 register 时设置；组件渲染时读取）
+let _ctx: Record<string, unknown> | null = null;
+/**
+ * 薄壳拆分后 host-shim 存在多份模块实例（批量包内联的 shell 副本 / panels chunk 自己的
+ * 副本 / panels 经相对 import 拉起的 entry 文件副本）——每份实例的 __setCtx 只写自己的
+ * `_ctx`。把宿主 ctx 同时挂 globalThis，未注入过的副本按需回读，否则它们拿到的 hooks
+ * 全是 undefined（拆包后实测：`v is not a function or its return value is not iterable`）。
+ */
+function getCtx(): Record<string, unknown> | null {
+  if (_ctx) return _ctx;
+  try { return ((globalThis as any).__aitiGitTraceHostCtx as Record<string, unknown>) ?? null; } catch { return null; }
+}
+export function __setCtx(ctx: Record<string, unknown>): void {
+  _ctx = ctx;
+  try { (globalThis as any).__aitiGitTraceHostCtx = ctx; } catch { /* 隐私模式等：忽略 */ }
+}
+
+/** DI 方案 P2：跨扩展客户端服务读取（ctx.getExtService 的 shim 封装；提供方懒加载/缺席 → undefined，消费方必须降级） */
+export function extSvc<T = unknown>(key: string): T | undefined {
+  return (getCtx() as any)?.getExtService?.(key) as T | undefined;
+}
+
+/** DI 方案 P2：注册跨扩展客户端服务（ctx.registerExtService 的 shim 封装；返回 disposer，旧宿主返回 null） */
+export function regSvc(key: string, impl: unknown): (() => void) | null {
+  const c = getCtx() as any;
+  return typeof c?.registerExtService === "function" ? c.registerExtService(key, impl) : null;
+}
+function c<T = (...args: never[]) => unknown>(name: string): T {
+  return (getCtx()?.[name] as T) ?? (() => undefined as never);
+}
+
+// ---------- react 兼容导出（esbuild alias react → 本 shim） ----------
+// React 的 Fragment 类型是 Symbol.for("react.fragment")——传给宿主 h 即生成真 Fragment。
+export const Fragment = (typeof Symbol !== "undefined" && Symbol.for) ? Symbol.for("react.fragment") : 0xacb;
+export function createElement(...args: unknown[]): unknown {
+  return c("h").call(null, ...args);
+}
+// 自动运行时 jsx(type, props, key)——key 是独立第三参；宿主 h() = React.createElement
+// 的第三参是 **children**。直接透传会把 key 当子元素（元素 key 丢失 + key 值覆盖
+// props.children 成为真实内容）。因此必须把 key 合并回 props。
+function mergeKey(args: unknown[]): unknown[] {
+  const [type, props, key, ...rest] = args;
+  if (props && typeof props === "object") {
+    // key 一律合并进 props，createElement 恒收 (type, config) 两参：
+    // 有 key → config.key 由 React 读为元素 key；key 为 undefined/null → 也必须剥掉第三参——
+    // 否则 createElement(type, config, undefined) 按 legacy 语义（第三参=children）用 undefined
+    // 覆盖 props.children，元素内容整体丢失（实证：aiti-editor ⋯ 菜单 key=undefined 的项全部空白）。
+    const merged: Record<string, unknown> = { ...(props as Record<string, unknown>) };
+    if (key !== undefined && key !== null) merged.key = key;
+    return [type, merged, ...rest];
+  }
+  return args;
+}
+export const jsx = (...args: unknown[]) => createElement(...mergeKey(args));
+export const jsxs = (...args: unknown[]) => {
+  // React 自动运行时语义：jsxs（静态多子元素）创建时会对每个子元素调用
+  // validateChildKeys → 标记 _store.validated = 1（"已校验，勿再告警"）。宿主 h()
+  // 是 React.createElement，但它只创建元素、不做这个标记——不补的话，
+  // `<div><A/><B/></div>` 这类“静态兄弟元素”（JSX 里无需写 key，React 自动运行时
+  // 本应抑制该警告）会被 React 误报 “Each child in a list should have a unique key”
+  // （dev-only，按 owner 去重一次）。值必须是 1（2 是另一特殊标记，仍会告警）。
+  const props = (args as [unknown, { children?: unknown } | undefined, ...unknown[]])[1];
+  const children = props?.children;
+  if (Array.isArray(children)) {
+    for (const c of children) {
+      if (c && typeof c === "object" && (c as { _store?: { validated?: number } })._store) {
+        (c as { _store: { validated: number } })._store.validated = 1;
+      }
+    }
+  }
+  return createElement(...mergeKey(args));
+};
+
+// ---------- React hooks 委托（按需增删） ----------
+export const useState = <T>(init: T | (() => T)) => c<(...a: unknown[]) => [T, (v: T | ((prev: T) => T)) => void]>("useState")(init);
+export const useEffect = (fn: () => unknown, deps?: unknown[]) => c("useEffect")(fn, deps);
+export const useRef = <T>(v: T) => c<(...a: unknown[]) => { current: T }>("useRef")(v);
+export const useCallback = <T extends (...args: never[]) => unknown>(fn: T, deps?: unknown[]) => c<(...a: unknown[]) => T>("useCallback")(fn, deps);
+export const useMemo = <T>(fn: () => T, deps?: unknown[]) => c<(...a: unknown[]) => T>("useMemo")(fn, deps);
+
+// ---------- 宿主工具委托（按需增删） ----------
+/** apiUrl(p)：把相对路径拼成当前 basePath 下的完整 API URL（多实例 /dev 前缀安全）。 */
+export function apiUrl(p: string): string {
+  const fn = getCtx()?.apiUrl as ((p: string) => string) | undefined;
+  return typeof fn === "function" ? fn(p) : p;
+}
+/** t(key, params?)：扩展 i18n 翻译（index.ts ui.i18n 里的词条）。 */
+export function t(key: string, params?: Record<string, unknown>): string {
+  const fn = getCtx()?.t as ((key: string, params?: Record<string, unknown>) => string) | undefined;
+  return typeof fn === "function" ? fn(key, params) : key;
+}
+/** appendText(text)：把文本注入 AI 输入框（plan-first「一键插入」同通道；旧宿主无此方法 → 静默跳过）。 */
+export function appendText(text: string): void {
+  const fn = getCtx()?.appendText as ((text: string) => void) | undefined;
+  try { if (typeof fn === "function") fn(text); } catch { /* 宿主未就绪时忽略 */ }
+}
+/** openFile(path, fileName?)：右侧文件标签页打开（ctx.openFile，与 aiti-doc-center / aiti-folder 同款 dock；旧宿主无此方法 → 静默跳过）。 */
+export function openFile(path: string, fileName?: string): void {
+  const fn = getCtx()?.openFile as ((path: string, fileName?: string) => void) | undefined;
+  try { if (typeof fn === "function") fn(path, fileName); } catch { /* 宿主未就绪时忽略 */ }
+}

package/client/src/jsx-runtime.ts

@@ -0,0 +1,2 @@
+// esbuild 自动 JSX runtime 别名目标：jsx/jsxs/Fragment 全委托 host-shim
+export { jsx, jsxs, Fragment } from "./host-shim";