@aiti-ai/aiti-folder 0.0.0-stage → 0.1.8

package/AGENTS.md

@@ -0,0 +1,28 @@
+# aiti-folder 扩展（部署目录直改指南）
+
+## 结构
+- 运行时文件平铺在本目录根（index.ts / core.cjs …，宿主 loader 按相对路径加载——**禁手改运行时平铺文件**，改 src/ 再 build）
+- `src/` 源码（client/src + 服务端 ts/cjs）· `dist/` 构建产物（禁手改）· `tools/` 构建/部署脚本
+- npm 包形态的扩展：本目录 package.json 含 version 与 aitiConfigs 声明
+
+## 小改现场流程（改文案/样式/小逻辑）
+1. 改 `src/` 下对应源码
+2. `node tools/build.mjs`（client 有构建产物的扩展；纯服务端改动跳过）
+3. `curl -X POST http://127.0.0.1:3001/api/extensions/reload`（dev；prod 3002；外部经 nginx 带 basePath：/dev、/mac、/mdev、/win、/wdev → `/xxx/api/extensions/reload`）
+4. 浏览器刷新页面验证
+
+## 大改回源码仓
+- 源码仓：`extensions/aiti-folder/`（git 管理，deploy 同步回本目录）
+- 改完在源码仓跑 `node tools/deploy.mjs`（或仓库根 `node scripts/deploy-all.mjs --only aiti-folder`）
+
+## 数据目录（数据分层：config / cache）
+- `ctx.configDir` 根级 = 配置与关键小状态（aiti-configs 备份范围；小、珍贵、人可读）
+- `ctx.cacheDir`（= `<configDir>/cache/`）= 可删缓存：db/venv/日志/大文件；rm -rf 后扩展下次访问自动重建
+- `ctx.dataDir` 已移除（访问即抛）——新代码禁用
+- 本扩展白名单（永不为 cache 的配置文件）见 package.json `aitiConfigs.configFiles`
+
+## 红线
+- 禁轮询（setInterval 拉取）；需要等待用事件/回调/SSE（桥的 SSE、aiti-event-bus topics）
+- 禁重启生产服务（pi-web 3002 等 restart 须用户明确同意）
+- 禁手改 dist/ 与运行时平铺文件；跨扩展通信走 ctx.services（禁 globalThis.__ext 直穿）
+- 服务端：SQLite 一律 WAL + 分批小事务（批间 setImmediate 让步）；禁 execFileSync 调 >1s 外部程序；>8MB 文件禁同步读

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiti-ai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @aiti-ai/aiti-folder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> fileViewer folder 接管 + pathPicker 目录选择器 —— 浏览/回收站删除 + git 工具条与分组提交计划（软依赖 aiti-git-ops）
+
+## 来源 · Origin
+
+本包是 **aiti** 生态的组成部分——以 [pi](https://pi.dev) 为引擎的个人 AI 开发工作台与本地调试注入生态：**aiti-agent**（自托管 Web 工作台，基于开源项目 [pi-web](https://github.com/aiti-ai/pi-web) 构建，浏览器为主操作面）+ 各开发工具内的调试注入（aiti-devtools）+ 丰富的扩展体系。
+
+This package is part of the **aiti** ecosystem — a personal AI development workbench powered by [pi](https://pi.dev): **aiti-agent** (a self-hosted web workbench built on the open-source [pi-web](https://github.com/aiti-ai/pi-web)) plus debug injection into mainstream dev tools (aiti-devtools) and a rich extension system.
+
+- 工作台 / workbench: <https://github.com/aiti-ai/pi-web>
+- 生态仓库 / monorepo: <https://github.com/aiti-ai/aiti-ai>
+- 官网 / site: <https://aiti.pw>
+
+## 功能定位（中文）
+
+fileViewer folder 接管 + pathPicker 目录选择器 —— 浏览/回收站删除 + git 工具条与分组提交计划（软依赖 aiti-git-ops）
+
+开发工具 · tags: `folder` · `file-viewer` · `path-picker` · `trash` · `git`
+
+## Positioning (English)
+
+fileViewer folder take-over + pathPicker directory picker — browse / delete to trash + git toolbar and grouped commit plans (soft-depends on aiti-git-ops)
+
+## 安装 / 部署
+
+```bash
+# 部署到 ~/.pi/web/extensions/aiti-folder/ 后 reload
+```
+
+## 文档 · Documentation
+
+- 中文完整文档（aiti-docs）: <https://aiti.pw/extensions/aiti-folder.html>
+- English docs: <https://aiti.pw/en/extensions/aiti-folder.html>
+- 扩展注册表 / registry: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>
+
+## License
+
+MIT

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/comp-i18n.ts

@@ -0,0 +1,144 @@
+/**
+ * comp-i18n · 跨扩展复用组件自带多语。
+ *
+ * 背景：aiti-folder 的可复用组件（WorkspaceDropdown / DirectoryBrowser / FolderSwitcher）
+ * 会被其他扩展构建期内联（session-manager、aiti-git-review 等）。运行时宿主 t() 委托的是
+ * 调用方扩展的 i18n 字典——那里没有本扩展的 key，界面会原样显示 key 字符串。
+ *
+ * 解法：可复用组件用到的文案内置在 COMPONENT_DICT，ct() 按当前语言直查；
+ * 未收录的 key 回落宿主 t()（不破坏既有行为）。新增可复用组件文案一律加到这里，
+ * 组件内不要再用宿主 t() 直查本扩展页面专属词条。
+ */
+import { t } from "./host-shim";
+
+const COMPONENT_DICT: Record<string, Record<string, string>> = {
+  en: {
+    "files.cancel": "Cancel",
+    "files.loading": "Loading files...",
+    "files.noSubdirs": "No subdirectories",
+    "files.parentDir": "Parent directory",
+    "files.selectFolder": "Select this folder",
+    "i18n.close": "Close",
+    "sidebar.customPath": "Custom path…",
+    "files.openFolder": "Open Folder",
+    "sidebar.filterProjects": "Filter projects…",
+    "sidebar.noMatchingProjects": "No matching projects",
+    "sidebar.useDefaultDirectory": "Use default directory",
+
+    "git.branchPanelTitle": "Branch panel (branch / tag / stash)",
+    "git.pushTitle": "Push commits",
+    "git.pullTitle": "Pull (ff-only)",
+    "git.pushConfirm": "Push {count} commit(s) to upstream?",
+    "git.pullConfirm": "Pull {count} commit(s) from upstream (ff-only)?",
+    "git.commitTitle": "Commit",
+    "git.commitShort": "Commit",
+    "git.stageAll": "Select all",
+    "git.stageNone": "Staged only",
+    "git.stagedCount": "{count} selected",
+    "git.commitPlaceholder": "Commit message…",
+    "git.amend": "Amend last commit",
+    "git.commitBtn": "Commit",
+    "git.planShort": "Group",
+    "git.planTitle": "Group & commit plan (staged group-by-group, breakpoint-resumable)",
+    "git.planMoveTo": "Move to next group",
+    "git.planExclude": "Exclude from plan",
+    "git.planRestore": "Restore to first group",
+    "git.planAddGroup": "＋ New group (takes last file of largest group)",
+    "git.planExcluded": "Excluded (won't be committed)",
+    "git.planStuck": "Stuck at group {group} — earlier groups already committed",
+    "git.planRolledBack": "rolled back to base HEAD",
+    "git.planRollback": "Roll back plan (reset --mixed)",
+    "git.planExecute": "Commit group by group",
+    "git.planConfirm": "Commit {count} group(s), one commit each?",
+    "git.planNewGroupMessage": "chore: new group",
+    "git.aiRefine": "AI refine",
+    "git.aiRefineBusy": "AI grouping… (up to 3 min)",
+    "git.aiMessage": "Generate",
+    "git.aiMessageBusy": "Generating… (up to 3 min)",
+    "git.aiMessageOverwrite": "Message already has content. Overwrite with the generated commit message?",
+    "git.aiMessageTitle": "Generate a commit message with AI (reads AGENTS.md and the diff of selected files)",
+    "git.stagedBucket": "Staged",
+    "git.unstagedBucket": "Changes",
+    "git.stageTitle": "Stage",
+    "git.unstageTitle": "Unstage",
+    "git.discardTitle": "Discard changes",
+    "git.discardConfirm": "Discard ALL uncommitted changes of {path}? (untracked files go to quarantine, recoverable by hand)",
+    "git.diffTitle": "View diff (git-review)",
+    "git.changesToggle": "Toggle changed-files section",
+    "git.planRetry": "Retry remaining groups",
+  },
+  "zh-CN": {
+    "files.cancel": "取消",
+    "files.loading": "正在加载文件...",
+    "files.noSubdirs": "无子目录",
+    "files.parentDir": "上级目录",
+    "files.selectFolder": "选择此文件夹",
+    "i18n.close": "关闭",
+    "sidebar.customPath": "自定义路径…",
+    "files.openFolder": "打开文件夹",
+    "sidebar.filterProjects": "筛选项目…",
+    "sidebar.noMatchingProjects": "没有匹配的项目",
+    "sidebar.useDefaultDirectory": "使用默认目录",
+
+    "git.branchPanelTitle": "分支面板（分支 / tag / stash）",
+    "git.pushTitle": "推送提交",
+    "git.pullTitle": "拉取（ff-only）",
+    "git.pushConfirm": "推送 {count} 个提交到上游？",
+    "git.pullConfirm": "从上游拉取 {count} 个提交（ff-only）？",
+    "git.commitTitle": "提交",
+    "git.commitShort": "提交",
+    "git.stageAll": "全选",
+    "git.stageNone": "仅暂存区",
+    "git.stagedCount": "已选 {count} 个",
+    "git.commitPlaceholder": "提交消息…",
+    "git.amend": "修正上一笔（amend）",
+    "git.commitBtn": "提交",
+    "git.planShort": "分组",
+    "git.planTitle": "分组提交计划（逐组提交 · 失败断点可回滚）",
+    "git.planMoveTo": "移到下一组",
+    "git.planExclude": "剔除出计划",
+    "git.planRestore": "恢复到第一组",
+    "git.planAddGroup": "＋ 新建组（取最大组的最后一个文件）",
+    "git.planExcluded": "已剔除（不会提交）",
+    "git.planStuck": "卡在第 {group} 组——之前的组已提交",
+    "git.planRolledBack": "已回滚到起点 HEAD",
+    "git.planRollback": "回滚本计划（reset --mixed）",
+    "git.planExecute": "逐组提交",
+    "git.planConfirm": "共 {count} 组，每组一笔提交？",
+    "git.planNewGroupMessage": "chore: new group",
+    "git.aiRefine": "AI 精修",
+    "git.aiRefineBusy": "AI 分组中…（最长 3 分钟）",
+    "git.aiMessage": "生成",
+    "git.aiMessageBusy": "生成中…（最长 3 分钟）",
+    "git.aiMessageOverwrite": "输入框已有内容，生成结果将覆盖，是否继续？",
+    "git.aiMessageTitle": "AI 生成提交信息（读取 AGENTS.md 与所选文件的 diff）",
+    "git.stagedBucket": "已暂存",
+    "git.unstagedBucket": "工作区",
+    "git.stageTitle": "暂存",
+    "git.unstageTitle": "取消暂存",
+    "git.discardTitle": "丢弃变更",
+    "git.discardConfirm": "丢弃 {path} 的全部未提交改动？（未跟踪文件移入隔离区，可手工找回）",
+    "git.diffTitle": "查看 diff（git-review）",
+    "git.changesToggle": "开/合变更文件区",
+    "git.planRetry": "重试剩余组",
+  },
+};
+
+/** 当前语言（pi-web 注入 __PI_LOCALE__；兜底 <html lang>；zh 系归一为 zh-CN） */
+function currentLocale(): string {
+  const raw = (window as any).__PI_LOCALE__ || document.documentElement.lang || "en";
+  const l = String(raw);
+  if (l.startsWith("zh")) return "zh-CN";
+  return l;
+}
+
+/** 组件多语：内置字典优先；未收录回落宿主 t() */
+export function ct(key: string, params?: Record<string, unknown>): string {
+  const dict = COMPONENT_DICT[currentLocale()];
+  let hit: string | undefined = dict && dict[key];
+  if (hit === undefined) hit = t(key);
+  if (params && typeof hit === "string") {
+    for (const [k, v] of Object.entries(params)) hit = hit.split("{" + k + "}").join(String(v));
+  }
+  return hit;
+}

package/client/src/directory-browser.tsx

@@ -0,0 +1,58 @@
+/**
+ * aiti-folder · 目录浏览器弹窗（自定义路径，/api/cwd/browse）——自手写版迁移，一比一
+ */
+import { useState, useEffect, useCallback } from "react";
+import { apiUrl } from "./host-shim";
+import { ct as t } from "./comp-i18n"; // 组件自带多语：内置字典优先，回落宿主 t
+import { FolderIcon } from "./icons";
+
+export const rowStyle: Record<string, any> = { display:"flex", alignItems:"center", gap:8, width:"100%", padding:"0 12px", height:26, border:"none", background:"transparent", color:"var(--text)", cursor:"pointer", textAlign:"left" };
+
+export function DirectoryBrowser({ initialPath, onSelect, onCancel }: { initialPath?: string; onSelect: (p: string) => void; onCancel: () => void }) {
+  const [path, setPath] = useState(initialPath || "");
+  const [data, setData] = useState<any>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const load = useCallback((target?: string) => {
+    if (loading) return; setLoading(true); setError(null);
+    const p = target ? { path: target } : {};
+    fetch(apiUrl("/api/cwd/browse"), { method:"POST", headers:{"content-type":"application/json"}, body: JSON.stringify(p) })
+      .then(async r => { const d = await r.json(); if (!r.ok || d.error) throw new Error(d.error||("HTTP "+r.status)); setData(d); setPath(d.path); })
+      .catch(e => setError(e&&e.message?e.message:String(e)))
+      .finally(()=>setLoading(false));
+  }, [loading]);
+  useEffect(()=>{ load(initialPath||""); /* eslint-disable-line */ }, []);
+  useEffect(()=>{ const k=(e:any)=>{ if(e.key==="Escape") onCancel(); }; document.addEventListener("keydown",k,true); return ()=>document.removeEventListener("keydown",k,true); }, [onCancel]);
+  const dirs = (data && data.directories) || []; const drives = data && data.drives;
+  return (
+    <div onClick={(e)=>{ if(e.target===e.currentTarget) onCancel(); }} style={{ position:"fixed", inset:0, zIndex:400, background:"rgba(0,0,0,0.35)", display:"flex", alignItems:"center", justifyContent:"center" }}>
+      <div style={{ width:"min(560px,92vw)", maxHeight:"80vh", display:"flex", flexDirection:"column", background:"var(--bg-panel)", border:"1px solid var(--border)", borderRadius:8, boxShadow:"0 8px 32px rgba(0,0,0,0.3)", overflow:"hidden" }}>
+        <div style={{ display:"flex", alignItems:"center", gap:8, padding:"8px 12px", borderBottom:"1px solid var(--border)", background:"var(--bg)", flexShrink:0 }}>
+          <span style={{ fontSize:13, fontWeight:600, color:"var(--text)", flex:1 }}>{t("sidebar.customPath")}</span>
+          <button onClick={onCancel} title={t("i18n.close")} style={{ height:28, padding:"0 10px", border:"1px solid var(--border)", borderRadius:5, background:"var(--bg-panel)", color:"var(--text)", cursor:"pointer", fontSize:12 }}>✕</button>
+        </div>
+        <div style={{ display:"flex", alignItems:"center", gap:6, padding:"6px 12px", borderBottom:"1px solid var(--border)", flexShrink:0, fontSize:12, color:"var(--text-muted)", fontFamily:"var(--font-mono)", overflowX:"auto", whiteSpace:"nowrap" }}>
+          {(data && data.parentPath!=null) ? <button onClick={()=>load(data.parentPath)} title={t("files.parentDir")} style={{ height:22, padding:"0 6px", border:"1px solid var(--border)", borderRadius:4, background:"var(--bg-panel)", color:"var(--text-muted)", cursor:"pointer", fontSize:12, flexShrink:0 }}>↑</button> : null}
+          <span title={path} style={{ overflow:"hidden", textOverflow:"ellipsis" }}>{path||"/"}</span>
+        </div>
+        <div style={{ flex:1, overflowY:"auto", padding:"4px 0" }}>
+          {loading ? <div style={{ padding:"12px", fontSize:12, color:"var(--text-dim)" }}>{t("files.loading")}</div> : null}
+          {error ? <div style={{ padding:"12px", fontSize:12, color:"var(--danger, #f87171)" }}>{error}</div> : null}
+          {(!loading && !error && drives && drives.length>0) ? drives.map((d: any)=> <button key={d.path} onClick={()=>load(d.path)} style={rowStyle}><FolderIcon open={false} /><span style={{fontSize:12}}>{d.name}</span></button>) : null}
+          {(!loading && !error && dirs.length===0 && (!drives||drives.length===0)) ? <div style={{ padding:"12px", fontSize:12, color:"var(--text-dim)" }}>{t("files.noSubdirs")}</div> : null}
+          {(!loading && !error) ? dirs.map((d: any)=> (
+            <button key={d.path} onClick={()=>load(d.path)} onDoubleClick={()=>onSelect(d.path)} style={rowStyle}>
+              <FolderIcon open={false} />
+              <span style={{ flex:1, fontSize:12, overflow:"hidden", textOverflow:"ellipsis", whiteSpace:"nowrap" }}>{d.name}</span>
+              <span style={{fontSize:10,color:"var(--text-dim)"}}>→</span>
+            </button>
+          )) : null}
+        </div>
+        <div style={{ display:"flex", gap:8, padding:"8px 12px", borderTop:"1px solid var(--border)", flexShrink:0, background:"var(--bg)" }}>
+          <button onClick={()=>path&&onSelect(path)} disabled={!path} style={{ height:28, padding:"0 12px", border:"none", borderRadius:5, background:"var(--accent)", color:"#fff", cursor:path?"pointer":"not-allowed", fontSize:12, fontWeight:600, opacity:path?1:0.5 }}>{t("files.selectFolder")}</button>
+          <button onClick={onCancel} style={{ height:28, padding:"0 10px", border:"1px solid var(--border)", borderRadius:5, background:"var(--bg-panel)", color:"var(--text)", cursor:"pointer", fontSize:12 }}>{t("files.cancel")}</button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/client/src/entry.tsx

@@ -0,0 +1,82 @@
+/**
+ * aiti-folder · client 入口（JSX + TypeScript + vite 构建）。
+ *
+ * 注册两项（均复用核心端点）：
+ *  - fileViewer 项 aiti-folder：match kind==="folder" → FolderBrowser
+ *  - pathPicker 项 aiti-folder-picker：FolderSwitcher（能力，不切 cwd）
+ *
+ * 开放点：window.__aitiFolder.registerAction（其他扩展注册目录级工具条按钮）
+ * [懒加载 v2 D3] 薄入口拆包：FolderBrowser（~113K）按需 import()；本文件 + pathPicker
+ * + registerAction 开放点为薄入口（~8K），随启动物化即时可用。
+ *
+ * 构建：node tools/build-client.mjs   （或 npm run build:client）
+ * 部署：node tools/deploy.mjs         （自动先构建再拷贝）
+ */
+import { useState, useEffect } from "react";
+import { __setCtx } from "./host-shim";
+import { registerAction } from "./folder-actions";
+import { FolderSwitcher } from "./folder-switcher";
+import { syncFolderDockFaces, INSTANCES_EVENT, openFolderDocked } from "./folder-dock";
+
+// [懒加载 v2 D3 拆包] FolderBrowser（目录树/预览，~113K 大头）按需 import()：
+// 薄入口（本文件 + pathPicker + registerAction 开放点）随启动物化即时可用；
+// 首次真正渲染目录 tab 时才拉重 chunk（加载期返回 null——接管判定已由 match 先行命中）。
+let FolderBrowserComp: ((props: any) => unknown) | null = null;
+function FolderBrowserLazy(props: Record<string, unknown>) {
+  const [, force] = useState(0);
+  useEffect(() => {
+    // 每个实例独立等 import 完成后各自唤醒（同 URL 模块加载浏览器天然去重；
+    // 不设全局 loading 标志——否则并发挂载的第二个实例永远等不到重渲染）
+    let alive = true;
+    import("./folder-browser").then((m) => {
+      if (!alive) return;
+      FolderBrowserComp = m.FolderBrowser;
+      force((n) => n + 1);
+    });
+    return () => { alive = false; };
+  }, []);
+  // 必须以 JSX 组件渲染（<Comp {...props}/>），严禁普通函数调用 Comp(props)：
+  // 函数调用会把 FolderBrowser 的 ~50 个 hooks 并进本薄壳的 hook 链——首渲染只挂 1 个
+  // hook（返回 null 等加载），加载完成后 force 重渲染变成 1+N 个，React 更新路径发现
+  // hook 列表越界 → #310「Rendered fewer hooks than expected」崩溃（2026-09-08 修复）。
+  const Comp = FolderBrowserComp;
+  return Comp ? <Comp {...(props as any)} /> : null;
+}
+
+// 开放点暴露（其他扩展注册目录级工具条按钮；aiti-git-review 的「审此目录」用它）
+// openFolderDocked：其他扩展可显式把目录以 dock face 落右栏（带全套 ⇱ 停靠菜单）
+try { (window as any).__aitiFolder = { registerAction, openFolderDocked }; } catch { /* noop */ }
+// 就绪广播（开页方案 §1 F5）：aiti-git-review「审此目录」动作晚注册用（同 aiti-editor:ready 注）
+try { window.dispatchEvent(new CustomEvent("aiti-folder:ready")); } catch { /* noop */ }
+
+export default function register(ctx: Record<string, unknown>) {
+  // 重要：必须在任何 JSX 组件渲染前调用（host-shim 模块级持 ctx）
+  __setCtx(ctx);
+
+  ctx.registerItems?.("fileViewer", [{
+    id: "aiti-folder",
+    render: (props: Record<string, unknown>) => <FolderBrowserLazy {...props} />,
+    meta: { label: "文件夹", title: "aiti-folder: folder browser", match: (_fp: unknown, opts: any) => opts && opts.kind === "folder" },
+  }]);
+  ctx.registerItems?.("pathPicker", [{
+    id: "aiti-folder-picker",
+    // 选中目录走本扩展 dock 状态机（openFolderDocked）而非宿主 onSelect（handleOpenFolder
+    // 开旧式文件夹 tab——不在 dock 状态机里，tab 条无 ⇱ 浮窗/停靠菜单）。拦截 onSelect
+    // 纯扩展侧闭环：宿主 onSelect 仅用于无本扩展时的兜底路径，此处覆盖后不再触达。
+    render: (props: Record<string, unknown>) => (
+      <FolderSwitcher {...(props as any)} onSelect={(p: string) => openFolderDocked(p, "right-panel")} />
+    ),
+    meta: { label: "目录选择", title: "aiti-folder: directory switcher (no cwd change)" },
+  }]);
+
+  // 多实例 dock faces（v2）：左栏栈/浮窗/右栏三面按清单动态注册；instances 变化
+  // （项目切换自动加 / ＋ 选择器 / 钉住 / FIFO 挤出）→ 事件驱动重注册（零轮询）。
+  try {
+    const resync = () => { try { syncFolderDockFaces(ctx); } catch { /* noop */ } };
+    resync();
+    window.addEventListener(INSTANCES_EVENT, resync);
+    window.addEventListener("storage", resync);
+  } catch { /* noop */ }
+
+  try { console.log("[aiti-folder] client 已挂载（fileViewer 文件夹接管 + pathPicker 目录选择器 + registerAction 开放点 + dock faces 多实例）"); } catch { /* noop */ }
+}