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

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@aiti-ai/aiti-git-trace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.12",
+  "type": "module",
+  "description": "编外 AI 变更追踪扩展（.git/aiti 追踪仓 + 关注路径 + 回撤/部分回滚）—— JSX + vite 构建 client bundle",
+  "scripts": {
+    "build:client": "vite build --config vite.config.ts",
+    "watch": "vite build --watch --config vite.config.ts",
+    "deploy": "node tools/deploy.mjs",
+    "test": "node --test trace-core.test.mjs"
+  },
+  "devDependencies": {
+    "vite": "^6.4.3"
+  },
+  "aitiConfigs": {
+    "configFiles": [
+      "config.json"
+    ]
+  },
+  "aitiExtProtocol": "1.0",
+  "dependencies": {
+    "@aiti-ai/ext-shared": "^0.1.3"
+  },
+  "license": "MIT",
+  "contentHash": "fb74b3285b6a2695",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aiti-ai/aiti-ai.git",
+    "directory": "extensions/aiti-git-trace"
+  },
+  "homepage": "https://github.com/aiti-ai/aiti-ai#readme",
+  "bugs": {
+    "url": "https://github.com/aiti-ai/aiti-ai/issues"
+  }
+}

package/reconcile-deps.mjs

@@ -0,0 +1,41 @@
+/**
+ * _shared/reconcile-deps.mjs · 通知 pi-web 双实例对齐扩展共享依赖（各扩展 deploy.mjs 共用）
+ *
+ * 背景：扩展运行时依赖统一装进共享根 <webRoot>/node_modules（jiti 从扩展目录向上解析
+ * 自动命中；机制仿 pi 本体 npm: 包安装）。共享根的唯一写入方是 aiti-extman 的
+ * shared-deps reconcile——deploy.mjs 拷完文件后 POST 本通知即可，不在部署脚本里跑 npm。
+ *
+ * 用法（与 reload-instances 同款：允许失败，永不 throw、不影响 deploy 退出码）：
+ *   import { notifyReconcile } from "../../_shared/reconcile-deps.mjs";
+ *   await notifyReconcile();               // 默认 "[deploy] " 前缀；建议在 reloadInstances() 之前调
+ *
+ * 失败无害：extman 在下一次 install/remove/reconcile-deps 时会自愈对齐；双实例各自
+ * reconcile 各自的 webRoot（~/.pi/web 与 ~/.pi/web-dev），互不相干。
+ */
+import { buildInstances } from "./reload-instances.mjs";
+
+export async function notifyReconcile(prefix = "[deploy] ") {
+  for (const inst of buildInstances()) {
+    if (inst.base === null) {
+      console.log(`${prefix}reconcile ${inst.name} 跳过：basePath 非法`);
+      continue;
+    }
+    try {
+      const r = await fetch(inst.base + "/api/extensions/aiti-extman/ops", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ action: "reconcile-deps", source: "deploy" }),
+      });
+      const body = await r.json().catch(() => null);
+      const err = body && body.deps && body.deps.error;
+      if (r.ok && body && body.ok) {
+        console.log(`${prefix}reconcile ${inst.name} → ✓（${Object.keys(body.deps?.deps || {}).length} 个共享依赖）`);
+      } else {
+        console.log(`${prefix}reconcile ${inst.name} → HTTP ${r.status} ⚠${err ? " " + err : "（extman 未就绪？下次安装时自动对齐）"}`);
+      }
+    } catch (e) {
+      const cause = e && e.cause ? String(e.cause.code || e.cause.message || e.cause) : String((e && e.message) || e);
+      console.log(`${prefix}reconcile ${inst.name} 不可达（${cause}）— 下次安装时自动对齐`);
+    }
+  }
+}

package/reload-instances.mjs

@@ -0,0 +1,60 @@
+/**
+ * _shared/reload-instances.mjs · pi-web 双实例热重载（各扩展 deploy.mjs 共用）
+ *
+ * dev 3001 / 生产 3002；端口可经 AITI_DEV_PORT / AITI_PROD_PORT 覆盖；
+ * basePath 双 env（AITI_DEV_BASE_PATH / AITI_PROD_BASE_PATH）按机器设值，
+ *   推荐值不带斜杠（48：dev 与 空；155：系统级 wdev 与 win）——git-bash 启动
+ *   原生程序时会把 / 开头的 env 值做 MSYS 路径转换（/wdev → D:/apps/Git/wdev）
+ *   致 URL 非法；不带斜杠则不触发转换。此处自动补 /（旧 /xxx 格式仍兼容），
+ *   兼容不了时提示 MSYS_NO_PATHCONV=1。
+ * 避免「server 端代码改了、实例没 reload 导致跑旧逻辑」。
+ *
+ * 用法（静态 import 或顶层 await import 均可）：
+ *   import { reloadInstances } from "../../_shared/reload-instances.mjs";
+ *   await reloadInstances();              // 默认 "[deploy] " 前缀
+ */
+const BASE_PATH_RE = /^\/[A-Za-z0-9._-]*$/;
+
+function buildInstance(name, portEnv, portDefault, pathEnv, pathDefault) {
+  const origin = `http://127.0.0.1:${process.env[portEnv] || portDefault}`;
+  const raw = process.env[pathEnv];
+  if (raw === undefined || raw === null || String(raw).trim() === "") return { name, base: origin + pathDefault };
+  // 自动补 /：wdev → /wdev（推荐无斜杠格式，MSYS 不转换）；/wdev → /wdev（旧格式兼容）
+  const p = "/" + String(raw).trim().replace(/^\/+|\/+$/g, "");
+  if (BASE_PATH_RE.test(p)) return { name, base: origin + p };
+  return { name, base: null, raw };
+}
+
+/** 双实例清单（dev/prod 各 {name, base}）；reload-instances 与 reconcile-deps 等共用。 */
+export function buildInstances() {
+  return [
+    buildInstance("dev", "AITI_DEV_PORT", 3001, "AITI_DEV_BASE_PATH", "/dev"),
+    buildInstance("prod", "AITI_PROD_PORT", 3002, "AITI_PROD_BASE_PATH", ""),
+  ];
+}
+
+export async function reloadInstances(prefix = "[deploy] ") {
+  // 批次合并（deploy-all 场景）：子条目部署脚本被注入 PI_WEB_DEFER_RELOAD=1 时不各自 reload，
+  // 由 deploy-all 在全部条目完成后统一执行一轮（N 条目 × 2 实例 → 2 次 POST）。
+  // 避免批量部署时的 reload 风暴（2026-09-15 实测：65 条目逐个 reload 把 dev 实例打满）。
+  // 单独跑某个扩展 deploy.mjs 不带该 env → 行为不变（部署完立即 reload）。
+  if (process.env.PI_WEB_DEFER_RELOAD === "1") {
+    console.log(`${prefix}reload 已 defer（PI_WEB_DEFER_RELOAD=1，由 deploy-all 收尾统一执行）`);
+    return;
+  }
+  // 允许失败：网络异常/非 2xx/服务未启动/env 非法一律只打提示，永不 throw——不影响 deploy 退出码
+  for (const inst of buildInstances()) {
+    if (inst.base === null) {
+      const msysHint = /[\\:]/.test(inst.raw) ? "——疑似 git-bash MSYS 路径转换，用 MSYS_NO_PATHCONV=1 前缀重跑" : "";
+      console.log(`${prefix}reload ${inst.name} 跳过：AITI_${inst.name.toUpperCase()}_BASE_PATH="${inst.raw}" 非法（须形如 /xxx 或留空）${msysHint}`);
+      continue;
+    }
+    try {
+      const r = await fetch(inst.base + "/api/extensions/reload", { method: "POST" });
+      console.log(`${prefix}reload ${inst.name} → HTTP ${r.status} ${r.ok ? "✓" : "⚠ 失败（请手动 POST /api/extensions/reload）"}`);
+    } catch (e) {
+      const cause = e && e.cause ? String(e.cause.code || e.cause.message || e.cause) : String((e && e.message) || e);
+      console.log(`${prefix}reload ${inst.name} 不可达（${cause}）— 需手动 POST /api/extensions/reload`);
+    }
+  }
+}

package/scripts/aiti-trace.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * aiti-trace CLI（M4-2）：编外追踪仓的瘦 身 / 报告 / 会话清单。
+ *
+ * 用法：
+ *   node aiti-trace.mjs sessions <cwd>                 列出 cwd 仓被追踪的全部会话（分支 + op 数 + 末次时间）
+ *   node aiti-trace.mjs report  <cwd> [sessionId]      打印某会话（缺省全部）台账摘要
+ *   node aiti-trace.mjs gc      <cwd> --days 30 [--dry-run]
+ *                                                      删除末次提交早于 N 天的会话分支（追加式历史瘦身；
+ *                                                      --dry-run 只列出将删除的分支）
+ *
+ * 说明：
+ *   - 追踪仓 = <repoRoot>/.aiti-trace（§13.2 顶层）；一切调用显式 --git-dir/--work-tree（hermetic 红线）
+ *   - 台账（ops/*.jsonl）不删（体积小、可审计）；分支删除后历史 commit 成为孤儿，待 git gc 自然回收
+ *   - 安全分支永不删：refs/heads/aiti/safety/*（safety 存档无时间语义，宁多勿删）
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const cwd = path.resolve(args[1] && !args[1].startsWith("--") ? args[1] : process.cwd());
+const flag = (name, dft) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : dft; };
+const dryRun = args.includes("--dry-run");
+const days = Number(flag("--days", 30));
+
+const configDir = process.env.PI_WEB_DATA_DIR
+  ? path.join(path.resolve(process.env.PI_WEB_DATA_DIR), "aiti-git-trace", "config")
+  : path.join(os.homedir(), ".pi", "web", "data", "aiti-git-trace", "config");
+
+function git(gitDir, workTree, gitArgs) {
+  return execFileSync("git", [
+    "--git-dir", gitDir, "--work-tree", workTree,
+    "-c", "core.hooksPath=/dev/null", "-c", "commit.gpgsign=false",
+    ...gitArgs,
+  ], { cwd: workTree, encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+       env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" } });
+}
+
+function resolveRepoRoot(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    const g = path.join(dir, ".git");
+    try { if (fs.statSync(g).isDirectory() && fs.existsSync(path.join(g, "HEAD"))) return dir; } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const repoRoot = resolveRepoRoot(cwd);
+if (!repoRoot) { console.error("该目录无外层 git 仓：" + cwd); process.exit(1); }
+const gitDir = path.join(repoRoot, ".aiti-trace");
+if (!fs.existsSync(gitDir)) { console.log("该仓尚无追踪史（.aiti-trace 不存在）"); process.exit(0); }
+
+function branches() {
+  const out = git(gitDir, repoRoot, ["for-each-ref", "--format=%(refname)%09%(committerdate:iso-strict)%09%(committerdate:unix)", "refs/heads/aiti/"]);
+  return out.trim().split("\n").filter(Boolean).map((l) => {
+    const [ref, iso, unix] = l.split("\t");
+    return { ref, iso, unix: Number(unix) * 1000, session: path.basename(ref) };
+  });
+}
+
+function ledgerFor(session) {
+  // 分支名是 16 位短 id；台账文件用完整会话 id → state/ops 目录按前缀匹配（数据分层：台账在 state/ops）
+  // 数据分层：configDir = <extRoot>/config，台账在 <extRoot>/state/ops
+  const dir = path.join(path.dirname(configDir), "state", "ops");
+  let f = path.join(dir, session + ".jsonl");
+  if (!fs.existsSync(f)) {
+    try {
+      const hit = fs.readdirSync(dir).find((n) => n.startsWith(session));
+      if (hit) f = path.join(dir, hit);
+    } catch { /* ops 目录缺失 */ }
+  }
+  try { return fs.readFileSync(f, "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l)); }
+  catch { return []; }
+}
+
+if (cmd === "sessions") {
+  for (const b of branches()) {
+    const rows = ledgerFor(b.session);
+    const files = new Set();
+    for (const r of rows) for (const st of r.stores || []) for (const p of st.paths || []) files.add(p);
+    console.log(`${b.session.slice(0, 16)}  ops=${rows.length}  files=${files.size}  last=${b.iso}`);
+  }
+} else if (cmd === "report") {
+  const sid = args[2] && !args[2].startsWith("--") ? args[2] : null;
+  for (const b of branches().filter((x) => !sid || x.session.startsWith(sid))) {
+    const rows = ledgerFor(b.session);
+    console.log("== " + b.session + "  ops=" + rows.length + "  last=" + b.iso);
+    for (const r of rows) {
+      const paths = (r.stores || []).flatMap((s) => s.paths || []);
+      console.log(`  op#${r.op} ${r.tool} ${String(r.summary).slice(0, 60)}  [${paths.slice(0, 5).join(", ")}${paths.length > 5 ? "…" : ""}]`);
+    }
+  }
+} else if (cmd === "gc") {
+  const cutoff = Date.now() - days * 86400_000;
+  const victims = branches().filter((b) => b.unix < cutoff && !/\/safety\//.test(b.ref));
+  if (!victims.length) { console.log("无可回收分支（" + days + " 天内均有活动）"); process.exit(0); }
+  const before = git(gitDir, repoRoot, ["count-objects", "-v"]);
+  const sz = (s) => Number((s.match(/size-pack: (\d+)/) || [])[1] || 0);
+  for (const v of victims) {
+    console.log((dryRun ? "[dry-run] 将删除 " : "删除 ") + v.ref + "  last=" + v.iso);
+    if (!dryRun) git(gitDir, repoRoot, ["update-ref", "-d", v.ref]);
+  }
+  if (!dryRun) {
+    try { git(gitDir, repoRoot, ["reflog", "expire", "--expire=now", "--all"]); git(gitDir, repoRoot, ["gc", "--prune=now", "--quiet"]); } catch {}
+    const after = git(gitDir, repoRoot, ["count-objects", "-v"]);
+    console.log("size-pack KB: " + sz(before) + " → " + sz(after));
+  } else {
+    console.log("[dry-run] 未执行删除；去掉 --dry-run 生效");
+  }
+} else {
+  console.log("用法：aiti-trace.mjs sessions|report|gc <cwd> [--days N] [--dry-run]");
+}

package/skills/index.json

@@ -0,0 +1 @@
+["trace-ops", "rollback-session", "watch-path"]

package/skills/rollback-session/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: rollback-session
+title: 回滚会话的文件变更（恢复到指定提交）
+placeholder: 描述回滚需求，例如：把 pi-work 会话 7942… 的文件恢复到 op1 之前
+summary: 用 aiti-git-trace 的安全机制把工作区文件恢复到追踪历史中的某个提交（先自动打 safety 存档，可再回滚）。涉及 storeRoot/sessionId/targetCommit 三个参数。
+outputs:
+  format: json-obj
+  schema:
+    rolledBack: 是否成功
+    storeRoot: 恢复的仓根
+    commit: 恢复到的提交
+action:
+  type: api
+  method: POST
+  path: /api/extensions/aiti-git-trace/rollback
+  mapping:
+    storeRoot: storeRoot
+    sessionId: sessionId
+    targetCommit: targetCommit
+---
+
+# rollback-session · 回滚会话文件变更
+
+你是 aiti-git-trace 的回滚助手。用户想把工作区文件恢复到追踪历史中的某个时点。
+
+## 步骤
+1. 先 GET `{basePath}/api/extensions/aiti-git-trace/ops?session=<sessionId>` 查台账，和用户确认要恢复到哪个 op（用其 before 提交；partial 仓最早可恢复点=首 commit）
+2. 确定参数：storeRoot=仓根（台账 stores[].root）、sessionId=会话 ID、targetCommit=目标提交 sha
+3. 严格按 outputs 字段输出；client 预览后由用户确认执行
+
+## 注意
+- 回滚前 API 会自动打 safety 存档（phase=safety），回滚本身也可再回滚
+- 只能恢复被追踪仓（.git/aiti 存在）内的文件；ignored/未跟踪文件不受影响
+- 用户犹豫时用 aiti_user_choose 列出候选 op 让其选择，不要擅自回滚

package/skills/trace-ops/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: trace-ops
+title: 查询会话的 AI 文件追踪操作
+placeholder: 想查哪个会话的操作？给我会话 ID（不填就查当前会话）
+summary: 读取 aiti-git-trace 台账，列出某会话被追踪的全部 AI 文件操作（op 编号/工具/变更文件），可用于「这个文件是谁改的」「这轮对话动了哪些文件」类问题。
+outputs:
+  format: json-obj
+  schema:
+    session: 会话 ID
+    ops_count: 操作条数
+    ops: 操作摘要数组（每项含 op/tool/paths/时间）
+action:
+  type: api
+  method: GET
+  path: /api/extensions/aiti-git-trace/ops?session={session}
+---
+
+# trace-ops · 查询会话追踪操作
+
+你是 aiti-git-trace 的查询助手。用户想了解某会话里 AI 对文件做了哪些改动。
+
+## 步骤
+1. 确定 session ID：用户给了就用；没给就查当前会话（发起上下文里的「来源会话 ID」）
+2. GET `{basePath}/api/extensions/aiti-git-trace/ops?session=<session>` 拿台账
+3. 按用户关注点整理：按 op 编号/工具/文件路径归纳；文件级追溯可指出 op 与 paths 的对应
+
+## 注意
+- `stores[]` 里 `paths` 是该 op 实际变更的文件（来自 before..after diff，上限 50 条）
+- `partial:true` 表示该仓首次被追踪时缺 before（最早可恢复点=首 commit）
+- `leaks[]` 是 cwd 之外、无 git 仓归属的改动（仅列示，不入库）
+- 台账为空说明该会话未产生被追踪的文件变更（纯读/未开启）

package/skills/watch-path/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: watch-path
+title: 管理关注路径（cwd 之外的追踪范围）
+placeholder: 例如：把 ~/workspace/pi-web 加入关注；或查看当前关注列表
+summary: 查看/添加/删除 aiti-git-trace 的 workspace 级关注路径。关注路径中已识别的 git 仓会被副 store 正式追踪（cwd 之外的多仓场景）。
+outputs:
+  format: json-obj
+  schema:
+    done: 是否完成
+    key: workspace key
+    config: 当前关注路径配置
+action:
+  type: api
+  method: POST
+  path: /api/extensions/aiti-git-trace/workspace
+  mapping:
+    key: key
+    config: config
+---
+
+# watch-path · 管理关注路径
+
+你是 aiti-git-trace 的关注路径助手。用户想查看或修改「cwd 之外哪些仓要被追踪」。
+
+## 步骤
+1. 确定 workspace：用户指定 cwd 就用；否则用发起上下文的「工作目录」
+2. 查列表：POST `{basePath}/api/extensions/aiti-git-trace/workspace/resolve` body {"cwd": "<cwd>"} 得到 key 与现有配置
+3. 添加：按用户说的路径构造 config（{autoDiscover, paths:[{path, origin:"user", repoRoot, addedAt}]}），POST `{basePath}/api/extensions/aiti-git-trace/workspace` body {key, ...config}
+4. 删除：DELETE `{basePath}/api/extensions/aiti-git-trace/workspace?key=<key>`（整份删除；改单条走「读-改-POST」）
+
+## 注意
+- 只有路径归属的 git 仓会被追踪（向上走查 .git；目录会向下扫一层找嵌套仓）
+- key = 主仓根（无 git 则 cwd）规范路径的 sha256 前 16 位；不确定就让 resolve 算
+- 修改后对新操作即时生效（pi 扩展每个 op 边界重读配置）

package/test/fixtures/ops-sample.jsonl

@@ -0,0 +1,3 @@
+{"op":1,"entryId":"e_a1","msgSeq":3,"tool":"bash","summary":"npm test","t0":1726000000000,"t1":1726000001000,"cwd":"/home/pi/workspace/x","userHead":"2e519b1f","parent":null,"stores":[{"root":"/home/pi/workspace/x","before":"aaa111","after":"bbb222","files":{"M":1,"A":0,"D":0,"skipped":0},"paths":["src/a.ts"],"partial":false}],"leaks":[]}
+{"op":2,"entryId":"e_a2","msgSeq":3,"tool":"edit","summary":"edit /home/pi/workspace/pi-web/src/b.ts","t0":1726000002000,"t1":1726000003000,"cwd":"/home/pi/workspace/x","userHead":"2e519b1f","parent":null,"stores":[{"root":"/home/pi/workspace/x","before":"bbb222","after":"ccc333","files":{"M":0,"A":1,"D":0,"skipped":0},"paths":["x.md"],"partial":false},{"root":"/home/pi/workspace/pi-web","before":null,"after":"9aa8fed","files":{"M":2},"paths":["src/b.ts"],"partial":true}],"leaks":[]}
+{"op":3,"entryId":"e_a2","msgSeq":4,"tool":"bash","summary":"echo x > /tmp/leak.log","t0":1726000004000,"t1":1726000005000,"cwd":"/home/pi/workspace/x","userHead":"2e519b1f","parent":null,"stores":[{"root":"/home/pi/workspace/x","before":"ccc333","after":"ddd444","files":{"M":0,"A":1,"D":0},"paths":["out.txt"],"partial":false}],"leaks":[{"path":"/tmp/leak.log","size":12,"kind":"create"}]}

package/tools/deploy.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * aiti-git-trace · 部署到 ~/.pi/web/extensions/ 与 ~/.pi/web-dev/extensions/（pi-web 双实例）
+ *
+ * 步骤：
+ *   0) 构建 JSX client bundle（client/src/*.tsx → client/aiti-git-trace-client.mjs）
+ *   1) 拷贝服务端源码 index.ts → 两个扩展目录
+ *   2) 拷贝 client 产物 → 两个扩展目录 client/
+ *   3) 提交部署状态到扩展 git 仓库（~/.pi/web/extensions/）（失败不影响部署）
+ *
+ * 用法：node tools/deploy.mjs
+ * 生效：POST /api/extensions/reload（或重启 pi-web）；client no-store 刷新页面即新
+ */
+import { copyFileSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { deployCommit } from "../../_shared/deploy-commit.mjs";
+import { copyIcons } from "../../_shared/ext-icons-deploy.mjs";
+import { notifyReconcile } from "../../_shared/reconcile-deps.mjs";
+
+// client TS 残留检查（.mjs 里是合法 JS 语法检查不报、运行时必炸；FAIL 即部署失败）
+{
+  const { checkClientDir } = await import("../../_shared/check-client.mjs");
+  checkClientDir(fileURLToPath(new URL("../client", import.meta.url)), { log: (m) => console.log("[deploy] " + m) });
+}
+
+const root = resolve(import.meta.dirname, ".."); // pi-web-ext/aiti-git-trace
+const targets = [
+  resolve(homedir(), ".pi", "web", "extensions", "aiti-git-trace"),
+  resolve(homedir(), ".pi", "web-dev", "extensions", "aiti-git-trace"),
+];
+const extRepo = resolve(homedir(), ".pi", "web", "extensions");
+
+// 0) 客户端 bundle 构建（client/src/*.tsx → client/aiti-git-trace-client.mjs）
+console.log("[deploy] 构建 JSX client bundle…");
+try {
+  execSync("npm run build:client", { cwd: root, stdio: "inherit" });
+} catch (e) {
+  console.error("[deploy] 构建失败，中止部署：", e.message);
+  process.exit(1);
+}
+
+for (const extDir of targets) {
+  mkdirSync(extDir, { recursive: true });
+  for (const f of ["package.json", "index.ts", "icon.svg", "api.ts", "trace-core.ts"]) {
+    copyFileSync(resolve(root, f), resolve(extDir, f));
+    console.log("[deploy] 源码 → " + resolve(extDir, f));
+  }
+  // trace-compact CLI（影子仓瘦身；schedule/startup 子进程调用 + 手动 CLI）
+  try {
+    mkdirSync(resolve(extDir, "tools"), { recursive: true });
+    copyFileSync(resolve(root, "tools", "trace-compact.mjs"), resolve(extDir, "tools", "trace-compact.mjs"));
+    console.log("[deploy] CLI → " + resolve(extDir, "tools", "trace-compact.mjs"));
+  } catch (e) { console.warn("[deploy] trace-compact.mjs 缺失"); }
+  // skills/（aiti-helper 规范：整目录递归拷贝）
+  try {
+    const { cpSync } = await import("node:fs");
+    cpSync(resolve(root, "skills"), resolve(extDir, "skills"), { recursive: true });
+    console.log("[deploy] skills → " + resolve(extDir, "skills"));
+  } catch (e) { console.warn("[deploy] skills 缺失"); }
+
+  // client（薄壳拆分 2026-09-13：主 bundle + 全部 hash 分块 panels-*.js/entry-*.js，清理陈旧分块）
+  const clientDir = resolve(extDir, "dist");
+  mkdirSync(clientDir, { recursive: true });
+  try {
+    const srcClient = resolve(root, "dist");
+    const srcFiles = readdirSync(srcClient).filter((f) => f.endsWith(".mjs") || f.endsWith(".js"));
+    for (const f of srcFiles) copyFileSync(resolve(srcClient, f), resolve(clientDir, f));
+    for (const f of readdirSync(clientDir)) {
+      if (f.endsWith(".js") && !srcFiles.includes(f)) { try { unlinkSync(resolve(clientDir, f)); } catch { /* noop */ } }
+    }
+    console.log("[deploy] client bundle + chunks（" + srcFiles.length + " 文件） → " + clientDir);
+  } catch (e) { console.warn("[deploy] client 缺失：", e.message); }
+}
+console.log("[deploy] 完成。生效：POST /api/extensions/reload（或重启 pi-web）；client 刷新页面即新");
+
+// 提交部署状态到扩展 git 仓库（生产目录是 git 仓库）
+
+
+// 图标文件拷贝（icon: "icons/<name>.svg" → 宿主加载时内嵌；库在 _shared/icons/）
+for (const t of targets) copyIcons(resolve(t, "icons"), ["git-branch", "git-commit-horizontal"], { log: (m2) => console.log(m2) });
+deployCommit({ repo: extRepo, name: "aiti-git-trace", paths: ["aiti-git-trace"], log: (m) => console.log("[deploy] " + m) });
+
+// ── 共享依赖 reconcile 通知（依赖进 <webRoot>/node_modules；允许失败，永不 throw）──
+await notifyReconcile();
+
+// ── 双实例热重载（basePath 双 env 按机器设值）——允许失败：服务未启动/共享模块缺失仅提示，不影响 deploy 退出码 ──
+try {
+  const { reloadInstances } = await import("../../_shared/reload-instances.mjs");
+  await reloadInstances();
+} catch (e) {
+  console.log("[deploy] 自动 reload 未执行（" + String((e && e.message) || e) + "）— 需手动 POST /api/extensions/reload");
+}
+
+// ── dev-pack（方案 §3.2：源码+构建工具+AGENTS.md 直达部署目录，AI 可现场直改）——允许失败，不影响 deploy 退出码 ──
+try {
+  const { packDevPack } = await import("../../_shared/dev-pack.mjs");
+  packDevPack({ extRoot: resolve(import.meta.dirname, ".."), log: (m) => console.log("[deploy] " + m) });
+} catch (e) {
+  console.log("[deploy] dev-pack 未执行（" + String((e && e.message) || e) + "）");
+}

package/tools/trace-compact.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * aiti-git-trace · 影子仓按时间瘦身 CLI（方案四 §5.2 / M6）
+ *
+ * 用法：
+ *   node tools/trace-compact.mjs <repoRoot>...          # 实跑：删过期会话分支 + gc 回收 + 同批清台账/state
+ *   node tools/trace-compact.mjs <repoRoot> --dry-run   # 默认 dry-run 出报告（不删任何数据）
+ *   node tools/trace-compact.mjs --all [--ext-config-dir <dir>]   # 遍历已知仓（state cwd + workspace paths）
+ *   参数：--days 30（保留窗）· --keep-active-hours 24（活跃保护）· --max-objects-mb 300（水位）
+ *
+ * 不可逆提示：裁剪丢的是 N 天前的 AI 操作追溯（时间线/回滚能力）；默认 30 天审计窗。
+ * 并发安全：compact 全程持 compact.lock（O_EXCL）；trace 写入侧 commit 前探测等待（防撕裂窗口）。
+ */
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+
+const args = process.argv.slice(2);
+const opt = (name, dflt) => {
+  const i = args.indexOf("--" + name);
+  return i >= 0 ? args[i + 1] : dflt;
+};
+const has = (name) => args.includes("--" + name);
+const DRY = has("dry-run");
+const DAYS = Number(opt("days", "30")) || 30;
+const KEEP_ACTIVE = Number(opt("keep-active-hours", "24")) || 24;
+const MAX_MB = Number(opt("max-objects-mb", "300")) || 300;
+
+const { compact, collectTraceRepos, storeOk } = await import(pathToFileURL(resolve(dirname(fileURLToPath(import.meta.url)), "..", "trace-core.ts")).href); // Windows 盘符路径必须转 file:// URL
+
+// 仓根列表：位置参数优先；--all = 从扩展 configDir 收集已知仓
+const extConfigDir = opt("ext-config-dir", join(homedir(), ".pi", "web", "data", "aiti-git-trace", "config"));
+let roots = args.filter((a) => !a.startsWith("--") && !/^\d+$/.test(a)).map((r) => resolve(r));
+if (!roots.length && (has("all") || !roots.length)) {
+  roots = collectTraceRepos(extConfigDir);
+  console.log(`[trace-compact] 收集到 ${roots.length} 个已知追踪仓（来源：state cwd + workspace paths）`);
+}
+if (!roots.length) {
+  console.log("未指定仓根且未发现已知仓。用法：node tools/trace-compact.mjs <repoRoot> --dry-run [--days 30]");
+  process.exit(0);
+}
+
+let totalReclaimed = 0, totalRemoved = 0, failed = 0;
+for (const repo of roots) {
+  if (!storeOk(repo)) { console.log(`[skip] ${repo}（无 .aiti-trace）`); continue; }
+  const r = await compact(repo, { days: DAYS, keepActiveHours: KEEP_ACTIVE, maxObjectsMB: MAX_MB, dryRun: DRY, extConfigDir, log: console.log });
+  if (r.error) { console.log(`[✗] ${repo} → ${r.error}`); failed++; continue; }
+  if (DRY) {
+    console.log(`[dry-run] ${repo}\n  候删 ${r.branchesCandidate ?? 0} 分支（含 ${r.tagsCandidate ?? 0} tag / ${r.indexesCandidate ?? 0} index）：${(r.removedBranches || []).slice(0, 10).join(" ")}${(r.removedBranches || []).length > 10 ? " …" : ""}\n  objects 现 ${((r.objectsMBBefore ?? 0) || 0).toFixed(0)}MB · 无主台账/state 可清 ${r.opsStateCleaned ?? 0} 个`);
+  } else {
+    totalReclaimed += r.reclaimedMB || 0;
+    totalRemoved += r.branchesRemoved || 0;
+    console.log(`[✓] ${repo} → 删 ${r.branchesRemoved ?? 0} 分支 · ${r.tagsRemoved ?? 0} tag · ${r.indexesRemoved ?? 0} index · 回收 ${(r.reclaimedMB ?? 0).toFixed(0)}MB（objects ${((r.objectsMBBefore ?? 0) || 0).toFixed(0)}→${((r.objectsMBAfter ?? 0) || 0).toFixed(0)}MB · 台账/state 清 ${r.opsStateCleaned ?? 0}）`);
+  }
+}
+if (!DRY) console.log(`\n完成：共删 ${totalRemoved} 分支 · 回收 ${totalReclaimed.toFixed(0)}MB${failed ? ` · 失败 ${failed} 仓` : ""}`);
+else console.log("\n（dry-run 未动数据；确认后去掉 --dry-run 实跑）");