thincoder 0.8.2 → 0.8.3

package/src/tools/git.mjs

@@ -20,7 +20,7 @@ export const gitDiffTool = {
   readonly: true,
   execute(args, ctx) {
     const ref = args.ref ?? "HEAD"
-    // ref 由模型提供且位于 "--" 之前：校验字符集，防 "--output=..." 之类被 git 当成选项
+    // ref supplied by model and placed before "--": validate charset, prevent "--output=..." etc. from being treated as git options
     if (!/^[A-Za-z0-9._\/~^][A-Za-z0-9._\/~^-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
     const flags = args.staged ? ["--staged"] : []
     const paths = args.path ? [args.path] : []
@@ -49,14 +49,14 @@ export const gitStatusTool = {
     const conflicts = []
     for (const line of porcelain.split("\n")) {
       if (!line) continue
-      // porcelain: XY path — 2 状态字符 + 空格 + 文件路径（部分环境只 1 空格）
-      // 去掉可能的 CR（execFileSync 在某些 Windows git 下会残留 \r 在行末但不在换行符中）
+      // porcelain: XY path — 2 status chars + space + file path (some environments have only 1 space)
+      // Strip possible CR (execFileSync on some Windows git leaves \r at end of line but not in newline)
       const clean = line.replace(/\r/g, "")
-      // 尝试匹配 "XY path" 或 "XY  path"（可变间距）
+      // Try matching "XY path" or "XY  path" (variable spacing)
       const m = clean.match(/^(..?)\s+(.+)$/)
       if (!m) continue
       const [, status, rawFile] = m
-      // 重命名条目 porcelain 输出为 "R  old -> new"，拆开明确展示而非当成一个字面文件名
+      // Rename entries in porcelain output are "R  old -> new", split for clarity instead of treating as a literal filename
       const file = status.includes("R") && rawFile.includes(" -> ") ? rawFile.replace(" -> ", " → ") : rawFile
       const idx = status[0] ?? " "
       const wt = status[1] ?? " "
@@ -128,7 +128,7 @@ export const questionTool = {
   },
 }
 
-/** 执行 git 命令；非 git 仓库 / git 不可用时返回空字符串 */
+/** Execute a git command; returns empty string when not a git repo / git unavailable */
 
 // ---------------------------------------------------------------- checkpoint
 
@@ -138,8 +138,9 @@ export const checkpointTool = {
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: ["list", "create", "rewind"], description: "list snapshots / create one now / restore a snapshot by id" },
-      id: { type: "string", description: "Snapshot id (required for rewind)" },
+      action: { type: "string", enum: ["list", "create", "rewind", "cat"], description: "list snapshots / create one now / restore a snapshot by id / read a file's content from a snapshot" },
+      id: { type: "string", description: "Snapshot id (required for rewind and cat; optional for list — shows file tree of that snapshot)" },
+      path: { type: "string", description: "Restore only this single file from the checkpoint (tracked or untracked). Other files are left untouched." },
     },
     required: ["action"],
   },
@@ -149,18 +150,88 @@ export const checkpointTool = {
     if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
     if (args.action === "create") {
       const cp = await createCheckpoint(ctx.cwd)
-      return `Checkpoint ${cp.id} created (${cp.files} file(s) captured)`
+      return `Checkpoint ${cp.id} created (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked)`
     }
     if (args.action === "rewind") {
       if (!args.id) throw new Error("id is required for rewind — use action=list to see snapshot ids")
-      const s = await rewind(ctx.cwd, args.id)
-      return `Rewound to checkpoint ${args.id}: patch ${s.patchApplied ? "applied" : "(empty)"}, ${s.restored} untracked file(s) restored, ${s.deleted} file(s) deleted.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+      const s = await rewind(ctx.cwd, args.id, { path: args.path })
+      if (args.path) {
+        return `Restored "${args.path}" (${s.type}) from checkpoint ${args.id}.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+      }
+      return `Rewound to checkpoint ${args.id}: patch ${s.patchApplied ? "applied" : "(empty)"}, ${s.restored ?? 0} untracked file(s) restored, ${s.deleted ?? 0} file(s) deleted.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+    }
+    if (args.action === "cat") {
+      if (!args.id) throw new Error("id is required for cat — use action=list to see snapshot ids")
+      if (!args.path) throw new Error("path is required for cat — specify which file to read")
+      const { catFile } = await import("../git/checkpoint.mjs")
+      return await catFile(ctx.cwd, args.id, args.path)
     }
     if (args.action === "list") {
       const cps = await listCheckpoints(ctx.cwd)
       if (cps.length === 0) return "(no checkpoints yet — one is auto-created before each user task)"
-      return cps.map((c) => `${c.id}  ${new Date(c.time).toISOString()}  ${c.untracked} untracked file(s)`).join("\n")
+
+      // Specific id: show the file tree within that snapshot
+      if (args.id) {
+        const cp = cps.find((c) => c.id === args.id)
+        if (!cp) throw new Error(`checkpoint ${args.id} not found`)
+        return formatFileTree(cp)
+      }
+
+      // Overview: list of all snapshots
+      return cps.map((c) => {
+        const parts = [`${c.id}  ${new Date(c.time).toISOString()}`]
+        if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.join(", ")}`)
+        if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.join(", ")}`)
+        return parts.join("  ")
+      }).join("\n")
     }
     throw new Error(`Unknown action: ${args.action}`)
   },
 }
+
+/** Format a checkpoint's file list as a directory tree (directories first, indented display) */
+function formatFileTree(cp) {
+  const all = [
+    ...(cp.tracked ?? []).map((f) => ({ path: f, type: "" })),
+    ...(cp.untracked ?? []).map((f) => ({ path: f, type: " (untracked)" })),
+  ]
+  if (all.length === 0) return "(empty checkpoint)"
+
+  // Sort by path (directories group naturally)
+  all.sort((a, b) => a.path.localeCompare(b.path))
+
+  // Build directory → file list map
+  const tree = new Map()
+  for (const { path, type } of all) {
+    const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "."
+    if (!tree.has(dir)) tree.set(dir, [])
+    tree.get(dir).push({ name: path.slice(dir === "." ? 0 : dir.length + 1), type })
+  }
+
+  // Output sorted by directory
+  const lines = []
+  const dirs = [...tree.keys()].sort()
+  for (const dir of dirs) {
+    if (dir !== "." && !lines.includes(dir + "/")) {
+      // Parent directory before child directory
+      const parts = dir.split("/")
+      for (let i = 1; i <= parts.length; i++) {
+        const prefix = parts.slice(0, i).join("/") + "/"
+        if (!lines.includes(prefix)) lines.push(prefix)
+      }
+    }
+  }
+  // Ensure directories precede files
+  for (const dir of dirs) {
+    if (dir !== ".") {
+      for (const { name, type } of tree.get(dir)) {
+        lines.push(`  ${dir}/${name}${type}`)
+      }
+    }
+  }
+  for (const { name, type } of tree.get(".") ?? []) {
+    lines.push(name + type)
+  }
+
+  return lines.join("\n")
+}

package/src/tools/index.mjs

@@ -1,4 +1,4 @@
-// tools/index.mjs — 后端兼容重导出
+// tools/index.mjs — backend-compatible re-export
 export { toOpenAISchema } from "./shared.mjs";
 
 import { readTool, writeTool, editTool, insertAfterTool, readImageTool } from "./file.mjs";

package/src/tools/patch.mjs

@@ -13,11 +13,12 @@ import { existsSync } from "node:fs";
 import { join, relative, dirname } from "node:path";
 
 /**
- * 解析统一 diff（unified diff）：返回 [{ path, isNew, hunks: [{ ops: [{type:" "|"-"|"+", text}] }] }]
- * 按 @@ 头的行数计数消费 hunk 行——LLM 常把上下文空行剥成纯空行，靠计数而不是行首字符判断 hunk 边界
+ * Parse a unified diff: returns [{ path, isNew, hunks: [{ ops: [{type:" "|"-"|"+", text}] }] }]
+ * Consume hunk lines by the line counts in the @@ header — LLMs often strip context blank lines to pure empty lines,
+ * so we use counts rather than first characters to determine hunk boundaries
  */
 function parsePatch(patch) {
-  // 补丁文本常来自 CRLF 终端/模型输出，行尾 \r 会混进 hunk 内容导致上下文对不上，统一剥掉
+  // Patch text often comes from CRLF terminals/model output; trailing \r mixed into hunk content breaks context matching, strip uniformly
   const lines = patch.replace(/\r(?=\n|$)/g, "").split("\n")
   const files = []
   let cur = null
@@ -48,7 +49,7 @@ function parsePatch(patch) {
         if (i >= lines.length) throw new Error("Malformed patch: hunk truncated (line counts in @@ header not satisfied)")
         const hl = lines[i]
         if (hl.startsWith("\\")) { i++; continue } // ""
-        const tag = hl === "" ? " " : hl[0] // 纯空行按上下文行宽容处理
+        const tag = hl === "" ? " " : hl[0] // pure blank line: treat leniently as context line
         const text = hl === "" ? "" : hl.slice(1)
         if (tag === " ") { hunk.ops.push({ type: " ", text }); oldNeed--; newNeed-- }
         else if (tag === "-") { hunk.ops.push({ type: "-", text }); oldNeed-- }
@@ -59,13 +60,13 @@ function parsePatch(patch) {
       cur.hunks.push(hunk)
       continue
     }
-    i++ // diff --git / index / 空行等元信息跳过
+    i++ // skip diff --git / index / blank lines and other metadata
   }
   if (files.length === 0) throw new Error("No file changes found in patch (need --- / +++ headers)")
   return files
 }
 
-/** 在内存行数组上按序应用 hunks；任何一步失败抛错（调用方保证不落盘）。比较时忽略行尾 \r，上下文行保留原始字节 */
+/** Apply hunks sequentially onto an in-memory line array; any failure throws (caller guarantees nothing is written to disk). Ignores trailing \r when comparing; context lines retain original bytes */
 function applyHunks(fileLines, hunks, eol, path) {
   const cr = eol === "\r\n" ? "\r" : ""
   for (let h = 0; h < hunks.length; h++) {
@@ -88,7 +89,7 @@ function applyHunks(fileLines, hunks, eol, path) {
     const out = []
     let src = pos
     for (const op of hunks[h].ops) {
-      if (op.type === " ") out.push(fileLines[src++]) // 上下文保留原始行（行尾/空白原样）
+      if (op.type === " ") out.push(fileLines[src++]) // preserve original context line (trailing whitespace as-is)
       else if (op.type === "-") src++
       else out.push(op.text + cr)
     }
@@ -107,13 +108,13 @@ export const applyPatchTool = {
     required: ["patch"],
   },
   readonly: false,
-  /** 供 agent 层追踪触碰文件（多路径，替代单 path 参数） */
+  /** For the agent layer to track touched files (multi-path, replaces single path parameter) */
   touchedPaths(args) {
     try { return parsePatch(args.patch ?? "").map((f) => f.path) } catch { return [] }
   },
   async execute(args, ctx) {
     const files = parsePatch(args.patch ?? "")
-    // 先全部读入内存试算：任何一个 hunk 不上就整体抛错，不写半个补丁（原子性）
+    // Read all into memory first for trial: if any hunk fails, abort entirely — never write a partial patch (atomicity)
     const planned = []
     for (const f of files) {
       const abs = resolveInCwd(ctx, f.path)
@@ -129,7 +130,7 @@ export const applyPatchTool = {
         planned.push({ abs, path: f.path, content: lines.join("\n"), isNew: false })
       }
     }
-    // 多文件写：先全部写 .tmp，全部成功后再 rename——任一写失败清理已写的 .tmp 不影响已落盘的文件
+    // Multi-file write: write all to .tmp first, rename only after all succeed — failure cleans up written .tmp without affecting committed files
     const { rename, unlink } = await import("node:fs/promises")
     const written = []
     try {
@@ -142,17 +143,18 @@ export const applyPatchTool = {
         await rename(p.abs + ".thincoder-tmp", p.abs)
       }
     } catch (renameError) {
-      // rename 阶段失败：清理残留 .tmp 文件
+      // rename phase failed: clean up leftover .tmp files
       for (const abs of written) {
         try { await unlink(abs + ".thincoder-tmp") } catch {}
       }
       throw renameError
     }
     const summary = planned.map((p) => `  ${p.isNew ? "created " : "modified"} ${p.path}`).join("\n")
-    const syntaxResults = planned.map((p) => {
-      const r = autoSyntaxCheck(p.abs)
+    const syntaxChecks = await Promise.all(planned.map(async (p) => {
+      const r = await autoSyntaxCheck(p.abs)
       return r ? `${p.path}:${r.replace("Syntax: ", "")}` : ""
-    }).filter(Boolean).join("\n")
+    }))
+    const syntaxResults = syntaxChecks.filter(Boolean).join("\n")
     return `Applied patch to ${planned.length} file(s):\n${summary}${syntaxResults ? "\n\nSyntax checks:\n" + syntaxResults : ""}`
   },
 }
@@ -181,7 +183,7 @@ export const syntaxCheckTool = {
       })
       return `Syntax OK: ${args.path}`
     } catch (e) {
-      // node --check 把错误写到 stderr
+      // node --check writes errors to stderr
       const msg = (e.stderr || e.stdout || e.message || "").trim()
       return `Syntax error in ${args.path}:\n${msg || "(unknown)"}`
     }
@@ -207,15 +209,15 @@ export const deleteTool = {
     if (!existsSync(abs)) throw new Error(`File not found: ${args.path}`)
     const s = await stat(abs)
     if (s.isDirectory()) throw new Error(`"${args.path}" is a directory — use bash to remove directories`)
-    // git 跟踪文件拒绝直接删除（安全网）；未跟踪的放行
-    // 用解析后的相对路径（统一正斜杠），防反斜杠/非常规路径绕过 ls-files 匹配
+    // git-tracked files: refuse direct deletion (safety net); untracked: allow
+    // Use resolved relative path (normalized forward slashes) to prevent backslash/unusual paths from bypassing ls-files matching
     const rel = relative(ctx.cwd, abs).replace(/\\/g, "/")
     let tracked = false
     try {
       execFileSync("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: ctx.cwd, stdio: "ignore" })
       tracked = true
     } catch {
-      // 未跟踪 / 非 git 仓库
+      // untracked / non-git repo
     }
     if (tracked && !args.force) throw new Error(`"${args.path}" is git-tracked. Set force=true to delete anyway.`)
     await unlink(abs)

package/src/tools/repomap-parse.mjs

@@ -1,14 +1,14 @@
 /**
- * repomap-parse.mjs — 仓库依赖图解析（零依赖，纯 regex）
- * 从 code_chunks 取已知文件列表，实时解析每个文件的 import/export 关系，
- * 构建正向依赖图 + 反向引用图。被 repomap.mjs 的 buildSummary / buildOutline 共用。
+ * repomap-parse.mjs — repo dependency graph parser (zero dependencies, pure regex)
+ * Gets known file list from code_chunks, parses each file's import/export relationships in real time,
+ * builds forward dependency graph + reverse reference graph. Shared by repomap.mjs's buildSummary / buildOutline.
  */
 import { readFileSync, existsSync } from "node:fs"
 import { join } from "node:path"
 
 /**
- * 扫描全量文件，构建正向依赖图 + 反向引用图。
- * 返回 { deps, importers, fileCount } 供 buildOutline / buildSummary 共用。
+ * Scan all files, build forward dependency graph + reverse reference graph.
+ * Returns { deps, importers, fileCount } shared by buildOutline / buildSummary.
  */
 export function buildDepGraph(db, cwd) {
   const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ORDER BY path`).all().map((r) => r.path)
@@ -34,7 +34,7 @@ export function buildDepGraph(db, cwd) {
       exports = parseExports(lines, ext)
     }
 
-    // 把 import 路径解析成相对路径（处理 ./ ../）
+    // Resolve import paths to relative paths (handle ./ ../)
     const resolved = []
     for (let imp of imports) {
       if (imp.startsWith("./")) imp = imp.slice(2)
@@ -62,17 +62,17 @@ export function buildDepGraph(db, cwd) {
   return { deps, importers, fileCount: allFiles.length }
 }
 
-// ---------------------------------------------------------- 内部实现
+// ---------------------------------------------------------- internal implementation
 
 function normalizeExt(p) {
   return p.replace(/\.(m?js|jsx|tsx?)$/i, "")
 }
 
-/** 提取 JS/TS 文件的 import 路径（去掉 .ts/.js/.mjs 后缀统一） */
+/** Extract JS/TS file import paths (normalize by stripping .ts/.js/.mjs suffixes) */
 function parseImports(lines, ext) {
   const imports = []
   const text = lines.join("\n")
-  // 普通 import
+  // standard import
   const re = /import\s+(?:{[^}]*}|\*\s+as\s+\w+|\w+\s*,?\s*(?:{[^}]*})?)\s*from\s*['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/g
   let m
   while ((m = re.exec(text))) {
@@ -90,7 +90,7 @@ function parseImports(lines, ext) {
   return [...new Set(imports)]
 }
 
-/** 提取 JS/TS 文件的 export 符号 */
+/** Extract JS/TS file export symbols */
 function parseExports(lines, ext) {
   const exports = []
   const text = lines.join("\n")
@@ -107,17 +107,17 @@ function parseExports(lines, ext) {
     if (name) exports.push(name)
     else if (!exports.some((e) => e === "default")) exports.push("default")
   }
-  // export { a, b as c } —— 优先取 as 后的导出名
+  // export { a, b as c } — prefer the "as" alias as the exported name
   const braceRe = /export\s*\{([^}]+)\}/g
   while ((m = braceRe.exec(text))) {
     for (const name of m[1].split(",")) {
       const parts = name.trim().split(/\s+/)
-      // "a as b" → b（导出名），"a" → a
+      // "a as b" → b (exported name), "a" → a
       const exported = parts.length >= 3 ? parts[2] : parts[0]
       if (exported) exports.push(exported)
     }
   }
-  // export const { a, b } = ...（解构导出）
+  // export const { a, b } = ... (destructured export)
   const destructRe = /export\s+(?:const|let|var)\s*\{([^}]+)\}\s*=/g
   while ((m = destructRe.exec(text))) {
     for (const name of m[1].split(",")) {
@@ -129,7 +129,7 @@ function parseExports(lines, ext) {
   return [...new Set(exports)]
 }
 
-/** 提取 Python 的 import 和顶层 def/class */
+/** Extract Python imports and top-level def/class */
 function parsePyOutline(lines) {
   const imports = []
   const symbols = []
@@ -155,9 +155,9 @@ function parsePyOutline(lines) {
 }
 
 /**
- * Python 相对导入 → 相对文件路径：
- * 前导 n 个点表示上溯 n-1 层（"."=当前包），模块点号转路径分隔符。
- * 非相对导入（不以 . 开头）或纯包导入（"from . import x"）返回 null。
+ * Python relative import → relative file path:
+ * Leading n dots mean go up n-1 levels ("." = current package), module dots become path separators.
+ * Non-relative imports (not starting with .) or bare package imports ("from . import x") return null.
  */
 function pyRelPath(mod) {
   if (!mod?.startsWith(".")) return null

package/src/tools/repomap.mjs

@@ -1,16 +1,16 @@
 /**
- * repomap.mjs — 仓库依赖大纲（零依赖，纯 regex）
- * 实时解析 import/export 关系，生成紧凑文本给 LLM 理解代码结构。
- * 不存索引——每次调用读文件解析，~50ms 完成。
+ * repomap.mjs — repo dependency outline (zero dependencies, pure regex)
+ * Real-time import/export parsing, generates compact text for LLMs to understand code structure.
+ * No index stored — reads and parses files on each call, ~50ms.
  */
 import { readFileSync, existsSync } from "node:fs"
 import { join } from "node:path"
 
-/** 提取 JS/TS 文件的 import 路径（去掉 .ts/.js/.mjs 后缀统一） */
+/** Extract JS/TS file import paths (normalize by stripping .ts/.js/.mjs suffixes) */
 function parseImports(lines, ext) {
   const imports = []
   const text = lines.join("\n")
-  // 普通 import
+  // standard import
   const re = /import\s+(?:{[^}]*}|\*\s+as\s+\w+|\w+\s*,?\s*(?:{[^}]*})?)\s*from\s*['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/g
   let m
   while ((m = re.exec(text))) {
@@ -28,7 +28,7 @@ function parseImports(lines, ext) {
   return [...new Set(imports)]
 }
 
-/** 提取 JS/TS 文件的 export 符号 */
+/** Extract JS/TS file export symbols */
 function parseExports(lines, ext) {
   const exports = []
   const text = lines.join("\n")
@@ -45,17 +45,17 @@ function parseExports(lines, ext) {
     if (name) exports.push(name)
     else if (!exports.some((e) => e === "default")) exports.push("default")
   }
-  // export { a, b as c } —— 优先取 as 后的导出名
+  // export { a, b as c } — prefer the "as" alias as the exported name
   const braceRe = /export\s*\{([^}]+)\}/g
   while ((m = braceRe.exec(text))) {
     for (const name of m[1].split(",")) {
       const parts = name.trim().split(/\s+/)
-      // "a as b" → b（导出名），"a" → a
+      // "a as b" → b (exported name), "a" → a
       const exported = parts.length >= 3 ? parts[2] : parts[0]
       if (exported) exports.push(exported)
     }
   }
-  // export const { a, b } = ...（解构导出）
+  // export const { a, b } = ... (destructured export)
   const destructRe = /export\s+(?:const|let|var)\s*\{([^}]+)\}\s*=/g
   while ((m = destructRe.exec(text))) {
     for (const name of m[1].split(",")) {
@@ -67,7 +67,7 @@ function parseExports(lines, ext) {
   return [...new Set(exports)]
 }
 
-/** 提取 Python 的 import 和顶层 def/class */
+/** Extract Python imports and top-level def/class */
 function parsePyOutline(lines) {
   const imports = []
   const symbols = []
@@ -93,9 +93,9 @@ function parsePyOutline(lines) {
 }
 
 /**
- * Python 相对导入 → 相对文件路径：
- * 前导 n 个点表示上溯 n-1 层（"."=当前包），模块点号转路径分隔符。
- * 非相对导入（不以 . 开头）或纯包导入（"from . import x"）返回 null。
+ * Python relative import → relative file path:
+ * Leading n dots mean go up n-1 levels ("." = current package), module dots become path separators.
+ * Non-relative imports (not starting with .) or bare package imports ("from . import x") return null.
  */
 function pyRelPath(mod) {
   if (!mod?.startsWith(".")) return null
@@ -110,8 +110,8 @@ function normalizeExt(p) {
 }
 
 /**
- * 内部：扫描全量文件，构建正向依赖图 + 反向引用图。
- * 返回 { deps, importers, fileCount } 供 buildOutline / buildSummary 共用。
+ * Internal: scan all files, build forward dependency graph + reverse reference graph.
+ * Returns { deps, importers, fileCount } shared by buildOutline / buildSummary.
  */
 function _buildDepGraph(db, cwd) {
   const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ORDER BY path`).all().map((r) => r.path)
@@ -137,7 +137,7 @@ function _buildDepGraph(db, cwd) {
       exports = parseExports(lines, ext)
     }
 
-    // 把 import 路径解析成相对路径（处理 ./ ../）
+    // Resolve import paths to relative paths (handle ./ ../)
     const resolved = []
     for (let imp of imports) {
       if (imp.startsWith("./")) imp = imp.slice(2)
@@ -166,12 +166,12 @@ function _buildDepGraph(db, cwd) {
 }
 
 /**
- * 生成紧凑架构摘要（替换旧的全量注入）。
- * 三层信息，每层信息密度递减：
- *  1. 目录级依赖（多目录项目才有意义，单目录跳过）
- *  2. 枢纽文件 Top-12（被 import 最多的文件——架构骨架）
- *  3. 入口文件（无人 import 的文件——启动/顶层入口）
- * 输出天然有界（~1000-2000 字符），不再需要 OUTLINE_INJECT_MAX 硬截断。
+ * Generate a compact architecture summary (replaces the old full-dump injection).
+ * Three layers, each with decreasing information density:
+ *  1. Directory-level dependencies (meaningful only for multi-directory projects, skipped for single-directory)
+ *  2. Hub files Top-12 (most-imported files — architecture skeleton)
+ *  3. Entry points (files with no importers — startup/top-level entry points)
+ * Output is naturally bounded (~1000-2000 chars), no more OUTLINE_INJECT_MAX hard truncation.
  */
 export function buildSummary(db, cwd) {
   const graph = _buildDepGraph(db, cwd)
@@ -181,7 +181,7 @@ export function buildSummary(db, cwd) {
   const out = []
   out.push(`${fileCount} source files indexed.`)
 
-  // 1) 目录级依赖
+  // 1) Directory-level dependencies
   const dirDeps = new Map() // dir → Set<imported-dir>
   const dirSet = new Set()
   for (const [rel, d] of deps) {
@@ -204,7 +204,7 @@ export function buildSummary(db, cwd) {
     }
   }
 
-  // 2) 枢纽文件 Top-12：按被 import 次数降序
+  // 2) Hub files Top-12: sorted by import count descending
   const HUB_LIMIT = 12
   const hubScores = []
   for (const [rel] of deps) {
@@ -227,7 +227,7 @@ export function buildSummary(db, cwd) {
     }
   }
 
-  // 3) 入口文件：无人 import 的（叶子/入口）
+  // 3) Entry points: files not imported by others (leaf/entry)
   const entries = []
   for (const [rel] of deps) {
     const key = rel.replace(/\.(m?js|jsx|tsx?)$/i, "")
@@ -247,7 +247,7 @@ export function buildSummary(db, cwd) {
   return out.join("\n")
 }
 
-/** 从 code_chunks 取已知文件列表（复用索引），按路径解析生成大纲文本 */
+/** Get known file list from code_chunks (reuse index), parse by path to generate outline text */
 export function buildOutline(db, cwd, focusPath) {
   const graph = _buildDepGraph(db, cwd)
   if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
@@ -260,7 +260,7 @@ export function buildOutline(db, cwd, focusPath) {
     const d = deps.get(rel)
     if (!d) continue
     const parts = []
-    // imported by（匹配时去掉扩展名，因为 import 路径通常不含 .mjs/.js 后缀）
+    // imported by (strip extension when matching, since import paths usually don't include .mjs/.js suffix)
     const key = rel.replace(/\.(m?js|jsx|tsx?)$/i, "")
     const rev = importers.get(key)
     if (rev?.size) parts.push(`← imported by: ${[...rev].join(", ")}`)
@@ -281,8 +281,8 @@ export function buildOutline(db, cwd, focusPath) {
 }
 
 /**
- * 生成 repo_outline 工具（只读）。
- * 需要 memory.db（复用 code_chunks 文件列表）和 cwd。
+ * Build the repo_outline tool (read-only).
+ * Requires memory.db (reuses code_chunks file list) and cwd.
  */
 export function repoOutlineTool(db, cwd) {
   return {