thincoder 0.8.2 → 0.8.3

package/src/distill.mjs

@@ -1,53 +1,53 @@
 /**
- * distill.mjs — 从会话中提取知识候选条目（双轨制的"自动轨"）
- * 原则（已定）：手动触发、LLM 出候选、人工逐条确认后入库。
- * 绝不做会话结束后的全自动沉淀。
+ * distill.mjs — extract knowledge candidates from sessions (the "automatic track" of the dual-track system)
+ * Principle (settled): manually triggered, LLM produces candidates, human confirms each one before writing.
+ * Absolutely no automatic storage at session end.
  */
 
 import { chat } from "./provider/index.mjs"
 import { put, putMarkdown } from "./memory.mjs"
 import { commitAndPush } from "./git/gitmem.mjs"
 
-const DISTILL_PROMPT = `你是知识提取器。阅读下面的 agent 工作会话记录，提取值得跨会话长期记住的知识。
+const DISTILL_PROMPT = `You are a knowledge extractor. Read the following agent work session log and extract knowledge worth remembering across sessions.
 
-输出一个 JSON 数组（不要输出任何其他内容）：
+Output a JSON array (nothing else):
 [
   {
     "type": "rule | knowledge | decision | pattern",
-    "title": "简短标题",
-    "content": "完整内容，自包含，脱离会话上下文也能看懂",
+    "title": "Short title",
+    "content": "Full content, self-contained — understandable without session context",
     "tags": ["tag1", "tag2"],
     "scope": "personal | project"
   }
 ]
 
-提取标准：
-- knowledge：项目的事实性知识（架构、部署、约定俗成的做法）
-- decision：会话中做出的技术决策及理由
-- pattern：调试经验、问题解法、可复用的工作模式
-- rule：编码规范类（谨慎！规范通常应由人手动撰写，只有会话中明确确立的才提取）
-- scope 判断：专属于当前项目的用 project；通用的或个人偏好用 personal
+Extraction criteria:
+- knowledge: factual project knowledge (architecture, deployment, conventions)
+- decision: technical decisions made in the session and their rationale
+- pattern: debugging experiences, solutions, reusable workflows
+- rule: coding standards (caution! rules are usually best written manually; only extract rules explicitly established in the session)
+- scope: use "project" for project-specific knowledge; use "personal" for general or personal preferences
 
-不要提取：
-- 一次性的任务细节（"今天改了某个文件的某行"）
-- 会话中提到的临时状态（当前的 bug、进行中的工作）
-- 客套话和显而易见的事实
+Do NOT extract:
+- one-off task details ("changed line X in file Y today")
+- transient state mentioned in the session (current bugs, work-in-progress)
+- pleasantries and obvious facts
 
-如果没有值得提取的内容，输出 []
-如果会话太长，优先提取最后出现的、仍在生效的结论。
+If nothing is worth extracting, output []
+If the session is long, prioritize conclusions that appeared last and are still in effect.
 
-会话记录：
+Session log:
 `
 
 /**
- * 从会话记录提取候选条目。transcript: 纯文本会话记录。
- * 返回 [{ type, title, content, tags, scope }]，解析失败返回 []
+ * Extract candidates from a session transcript. transcript: plain-text session record.
+ * Returns [{ type, title, content, tags, scope }], or [] on parse failure.
  */
 export async function extractCandidates(provider, transcript) {
   const res = await chat(provider, {
     messages: [{ role: "user", content: DISTILL_PROMPT + transcript }],
   })
-  // 非贪婪匹配第一个 JSON 数组（贪婪 [\s\S]* 会跨多个数组把中间文本也吃进去）
+  // Non-greedy match first JSON array (greedy [\s\S]* would eat across multiple arrays including interstitial text)
   const match = res.content.match(/\[[\s\S]*?\]/)
   if (!match) return []
   try {
@@ -60,37 +60,37 @@ export async function extractCandidates(provider, transcript) {
 }
 
 /**
- * 把 agent 的 OpenAI 格式 history 转成可读的会话记录文本。
+ * Convert agent's OpenAI-format history to readable session transcript text.
  */
 export function historyToTranscript(history, { maxChars = 30_000 } = {}) {
   const lines = []
   for (const m of history) {
     if (m.role === "tool") {
-      lines.push(`[工具结果] ${(m.content ?? "").slice(0, 500)}`)
+      lines.push(`[tool result] ${(m.content ?? "").slice(0, 500)}`)
     } else if (m.tool_calls?.length) {
       const calls = m.tool_calls.map((tc) => `${tc.function?.name ?? "?"}(${tc.function?.arguments?.slice(0, 200) ?? ""})`).join(", ")
-      lines.push(`[assistant] ${m.content ?? ""}\n[调用工具] ${calls}`)
+      lines.push(`[assistant] ${m.content ?? ""}\n[called tools] ${calls}`)
     } else {
       lines.push(`[${m.role}] ${m.content ?? ""}`)
     }
   }
   const text = lines.join("\n\n")
-  // 超长时保留头尾（最早的需求 + 最新的结论最重要）
+  // Overlong: keep head and tail (earliest requirements + latest conclusions are most important)
   if (text.length <= maxChars) return text
   const half = Math.floor(maxChars / 2)
-  return text.slice(0, half) + "\n\n...[中间部分省略]...\n\n" + text.slice(-half)
+  return text.slice(0, half) + "\n\n...[... middle portion omitted ...]...\n\n" + text.slice(-half)
 }
 
 /**
- * 把确认的候选条目写入指定层。
+ * Write confirmed candidates to the specified layer.
  * opts: { projectDir, team: { dir } | null, author }
- * scope=team 需要 opts.team；project 需要 opts.projectDir。
- * 返回写入结果描述。
+ * scope=team requires opts.team; project requires opts.projectDir.
+ * Returns write result description.
  */
 export async function saveCandidate(memory, candidate, opts = {}) {
   const scope = candidate.scope ?? "personal"
-  // tags 来自 LLM 输出（不可信）：非数组时先 String 化再按逗号/空白切分——
-  // 直接对非字符串调 .split 会崩，模型也常给 "a, b" 这种逗号串
+  // tags come from LLM output (untrusted): if not an array, stringify then split by comma/whitespace —
+  // calling .split on a non-string would crash, and models often produce "a, b" comma strings
   const tags = Array.isArray(candidate.tags)
     ? candidate.tags.map((t) => String(t)).filter(Boolean)
     : String(candidate.tags ?? "").split(/[\s,]+/).filter(Boolean)
@@ -100,7 +100,7 @@ export async function saveCandidate(memory, candidate, opts = {}) {
     return `personal#${id}`
   }
   if (scope === "project") {
-    if (!opts.projectDir) throw new Error("project scope unavailable")
+    if (!opts.projectDir) throw new Error("project scope unavailable — no project directory configured (set memory.projectDir in ~/.thincoder/config.json)")
     const filename = await putMarkdown(memory, {
       layer: "project", dir: opts.projectDir,
       type: candidate.type, title: candidate.title, content: candidate.content,
@@ -109,7 +109,7 @@ export async function saveCandidate(memory, candidate, opts = {}) {
     return `project:${filename}`
   }
   if (scope === "team") {
-    if (!opts.team?.dir) throw new Error("team scope not configured")
+    if (!opts.team?.dir) throw new Error("team scope not configured — configure memory.team in ~/.thincoder/config.json")
     const filename = await putMarkdown(memory, {
       layer: "team", dir: opts.team.dir,
       type: candidate.type, title: candidate.title, content: candidate.content,

package/src/embedding.mjs

@@ -1,19 +1,19 @@
 /**
- * embedding.mjs — 向量嵌入
- * OpenAI 兼容 /v1/embeddings（SiliconFlow bge-m3 / Ollama / OpenAI 均可），
- * 复用 provider.mjs 的 fetch + 重试模式，零依赖。
- * 向量在入库前归一化，之后点积即余弦相似度。
+ * embedding.mjs — vector embeddings
+ * OpenAI-compatible /v1/embeddings (SiliconFlow bge-m3 / Ollama / OpenAI all supported),
+ * reuses provider.mjs fetch + retry pattern, zero dependencies.
+ * Vectors are normalized before storage; dot product then equals cosine similarity.
  */
 
 import { RETRYABLE_STATUS } from "./provider/index.mjs"
 const MAX_RETRIES = 3
-const BATCH_SIZE = 32 // 单次请求的文本数上限（SiliconFlow 限制内）
+const BATCH_SIZE = 32 // max texts per request (within SiliconFlow limits)
 
-/** 创建 embedder。config: { baseURL, apiKey, model } */
+/** Create an embedder. config: { baseURL, apiKey, model } */
 export function createEmbedder(config) {
-  if (!config?.baseURL) throw new Error("embedding config: baseURL is required")
-  if (!config?.apiKey) throw new Error("embedding config: apiKey is required (config file or SILICONFLOW_API_KEY env)")
-  if (!config?.model) throw new Error("embedding config: model is required")
+  if (!config?.baseURL) throw new Error("embedding config: baseURL is required — configure embedding.baseURL in ~/.thincoder/config.json")
+  if (!config?.apiKey) throw new Error("embedding config: apiKey is required — set SILICONFLOW_API_KEY env or configure embedding.apiKey in ~/.thincoder/config.json")
+  if (!config?.model) throw new Error("embedding config: model is required — configure embedding.model in ~/.thincoder/config.json")
   return {
     baseURL: config.baseURL.replace(/\/+$/, ""),
     apiKey: config.apiKey,
@@ -22,8 +22,8 @@ export function createEmbedder(config) {
 }
 
 /**
- * 批量嵌入。texts: string[] → Float32Array[]（已归一化）
- * 自动分批，失败重试（指数退避）。
+ * Batch embedding. texts: string[] → Float32Array[] (normalized)
+ * Auto-batches, retries on failure (exponential backoff).
  */
 export async function embed(embedder, texts, { signal } = {}) {
   if (texts.length === 0) return []
@@ -31,11 +31,11 @@ export async function embed(embedder, texts, { signal } = {}) {
   for (let i = 0; i < texts.length; i += BATCH_SIZE) {
     const batch = texts.slice(i, i + BATCH_SIZE)
     const data = await requestWithRetry(embedder, batch, signal)
-    // 数量不符直接报错——静默接受会让向量与文本错位，污染整个索引
+    // Mismatched count is a hard error — silently accepting would misalign vectors with texts, poisoning the entire index
     if (!Array.isArray(data.data) || data.data.length !== batch.length) {
       throw new Error(`Embedding API returned ${data.data?.length ?? 0} vectors for ${batch.length} inputs`)
     }
-    // 规范上 data[] 顺序与输入一致，但以 index 字段为准排序（有的话），不赌服务端实现
+    // Spec says data[] order matches input, but sort by index field if present — don't bet on server implementation
     const items = data.data.every((d) => typeof d.index === "number")
       ? [...data.data].sort((a, b) => a.index - b.index)
       : data.data
@@ -46,7 +46,7 @@ export async function embed(embedder, texts, { signal } = {}) {
   return vectors
 }
 
-/** 余弦相似度（输入均已归一化，点积即余弦） */
+/** Cosine similarity (inputs are normalized, dot product equals cosine) */
 export function cosine(a, b) {
   if (a.length !== b.length) return 0
   let sum = 0
@@ -55,20 +55,20 @@ export function cosine(a, b) {
   return sum
 }
 
-/** Float32Array → 可存 sqlite BLOB 的 Buffer */
+/** Float32Array → Buffer suitable for sqlite BLOB storage */
 export function toBlob(vec) {
   return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength)
 }
 
 /** sqlite BLOB → Float32Array */
 export function fromBlob(buf) {
-  // BLOB 可能来自 Buffer 池，byteOffset 不保证 4 对齐，直接建视图会 RangeError——先复制对齐
+  // BLOB may come from Buffer pool where byteOffset isn't 4-aligned; creating a view directly would RangeError — copy to align first
   if (buf.byteOffset % 4 !== 0) buf = new Uint8Array(buf)
   if (buf.byteLength % 4 !== 0) return new Float32Array(0)
   return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4)
 }
 
-// ---------------------------------------------------------------- 内部
+// ---------------------------------------------------------------- internal
 
 async function requestWithRetry(embedder, input, signal) {
   let lastError

package/src/git/checkpoint.mjs

@@ -1,16 +1,18 @@
 /**
- * checkpoint.mjs — 工作区快照与回滚
- * 快照 = git diff HEAD 补丁 + 未跟踪文件副本（尊重 .gitignore）。
- * 仅 git 仓库内可用。回滚前会先打新快照（回滚可逆）。
+ * checkpoint.mjs — workspace snapshot and rollback
+ * Snapshot = git diff HEAD patch + untracked file copies (respects .gitignore).
+ * Only available inside git repos. Rewind creates a new snapshot first (rewind is reversible).
+ * rewind supports a path parameter for per-file restore (restores only the specified file).
  */
-
 import { execFileSync } from "node:child_process"
 import { createHash } from "node:crypto"
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { cp, mkdir, readFile, readdir, rm, writeFile, copyFile } from "node:fs/promises"
-import { dirname, join, relative } from "node:path"
+import { dirname, join } from "node:path"
 import { configDir } from "../config.mjs"
 
+const CWD_HASH_LEN = 12
+
 const MAX_CHECKPOINTS = 20
 
 function git(cwd, args, { allowFail = false } = {}) {
@@ -23,46 +25,71 @@ function git(cwd, args, { allowFail = false } = {}) {
 }
 
 function checkpointRoot(cwd) {
-  const hash = createHash("sha1").update(cwd).digest("hex").slice(0, 12)
+  const hash = createHash("sha1").update(cwd).digest("hex").slice(0, CWD_HASH_LEN)
   return join(configDir, "checkpoints", hash)
 }
 
-/** 当前目录是否 git 仓库 */
+/** Extract the list of tracked files changed from a unified diff */
+function trackedFilesFromPatch(patch) {
+  if (!patch.trim()) return []
+  const files = new Set()
+  for (const m of patch.matchAll(/^--- a\/(.+)$/gm)) files.add(m[1])
+  return [...files].sort()
+}
+
+/** Extract a single file's patch hunks from a unified diff */
+function extractFileHunks(patch, filePath) {
+  // Split by file: each file block starts with "diff --git"
+  const sections = patch.split(/(?=^diff --git )/m)
+  for (const sec of sections) {
+    if (!sec.trim()) continue
+    const m = sec.match(/^diff --git a\/(.+) b\/(.+)/m)
+    if (!m) continue
+    if (m[1] === filePath || m[2] === filePath) return sec.trim()
+  }
+  return ""
+}
+
+/** Whether the current directory is a git repo */
 export function isGitRepo(cwd) {
   return git(cwd, ["rev-parse", "--is-inside-work-tree"], { allowFail: true }) === "true"
 }
 
 /**
- * 打快照。返回 { id, time, files } 或 null（非 git 仓库）。
+ * Create a snapshot. Returns { id, time, files } or null (non-git repo).
  */
 export async function createCheckpoint(cwd) {
   if (!isGitRepo(cwd)) return null
 
-  // 随机后缀：同一毫秒内两次快照的 id 不互撞（排序仍按时间戳前缀有序）
+  // Random suffix: prevents id collisions for two snapshots in the same millisecond (sorting stays ordered by timestamp prefix)
   const id = Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 6)
   const dir = join(checkpointRoot(cwd), id)
   await mkdir(join(dir, "untracked"), { recursive: true })
 
-  // 跟踪文件的改动 → 补丁
+  // Tracked file changes → patch
   const patch = git(cwd, ["diff", "HEAD", "--binary"], { allowFail: true }) ?? ""
   await writeFile(join(dir, "patch.diff"), patch, "utf8")
+  const tracked = trackedFilesFromPatch(patch)
 
-  // 未跟踪文件（尊重 .gitignore）→ 原样复制
+  // Untracked files (respects .gitignore) → copy as-is
   const untrackedRaw = git(cwd, ["ls-files", "--others", "--exclude-standard"], { allowFail: true }) ?? ""
   const untracked = untrackedRaw ? untrackedRaw.split("\n").filter(Boolean) : []
   for (const rel of untracked) {
     const src = join(cwd, rel)
     const dst = join(dir, "untracked", rel)
     await mkdir(dirname(dst), { recursive: true })
-    await copyFile(src, dst).catch(() => {}) // 复制失败（socket/设备文件等）跳过
+    await copyFile(src, dst).catch(() => {}) // Copy failed (socket/device file etc.) — skip
   }
-  await writeFile(join(dir, "meta.json"), JSON.stringify({ id, time: Date.now(), untracked }, null, 2), "utf8")
+
+  await writeFile(join(dir, "meta.json"), JSON.stringify({
+    id, time: Date.now(), untracked, tracked,
+  }, null, 2), "utf8")
 
   await pruneCheckpoints(cwd)
-  return { id, time: Date.now(), files: untracked.length + (patch ? 1 : 0) }
+  return { id, time: Date.now(), files: untracked.length + tracked.length, tracked, untracked }
 }
 
-/** 列出快照（新→旧） */
+/** List checkpoints (newest→oldest), with file change summary */
 export async function listCheckpoints(cwd) {
   const root = checkpointRoot(cwd)
   if (!existsSync(root)) return []
@@ -71,37 +98,38 @@ export async function listCheckpoints(cwd) {
   for (const id of ids) {
     try {
       const meta = JSON.parse(await readFile(join(root, id, "meta.json"), "utf8"))
-      out.push({ id, time: meta.time, untracked: meta.untracked.length })
+      // Compat with old checkpoints (no tracked field): extract from patch file
+      const tracked = meta.tracked ?? (() => {
+        try {
+          return trackedFilesFromPatch(readFileSync(join(root, id, "patch.diff"), "utf8"))
+        } catch { return [] }
+      })()
+      out.push({
+        id, time: meta.time,
+        untracked: meta.untracked ?? [],
+        tracked,
+      })
     } catch {
-      // 损坏的快照跳过
+      // Corrupted checkpoint — skip
     }
   }
   return out
 }
 
-/**
- * 回滚到指定快照（先把当前状态存成新快照，保证回滚可逆）。
- * 返回恢复摘要。
- */
-export async function rewind(cwd, id) {
-  const dir = join(checkpointRoot(cwd), id)
-  if (!existsSync(join(dir, "meta.json"))) throw new Error(`checkpoint ${id} not found`)
-  const meta = JSON.parse(await readFile(join(dir, "meta.json"), "utf8"))
-
-  // 回滚也可逆：先给当前状态打快照
-  await createCheckpoint(cwd)
+// ---- restore core ----
 
-  // 1. 工作区+暂存区 → HEAD，再应用快照补丁 → 快照时状态
-  // 必须连暂存区一起重置：checkout -- . 只从 index 恢复工作区，
-  // 有 staged 改动时工作区留下的是 staged 版本，补丁（diff HEAD，含 staged 内容）会 apply 失败
+/** Full restore of tracked files from a checkpoint: reset to HEAD → apply patch */
+async function fullRestoreTracked(cwd, dir) {
   git(cwd, ["restore", "--source=HEAD", "--staged", "--worktree", "."])
   const patch = await readFile(join(dir, "patch.diff"), "utf8")
   if (patch.trim()) {
-    const patchFile = join(dir, "patch.diff")
-    git(cwd, ["apply", "--whitespace=nowarn", patchFile])
+    git(cwd, ["apply", "--whitespace=nowarn", join(dir, "patch.diff")])
   }
+  return Boolean(patch.trim())
+}
 
-  // 2. 快照之后新建的未跟踪文件 → 删除
+/** Full restore of untracked files from a checkpoint: delete new ones → restore from snapshot */
+async function fullRestoreUntracked(cwd, dir, meta) {
   const nowUntracked = (git(cwd, ["ls-files", "--others", "--exclude-standard"], { allowFail: true }) ?? "")
     .split("\n")
     .filter(Boolean)
@@ -114,7 +142,6 @@ export async function rewind(cwd, id) {
     }
   }
 
-  // 3. 快照时存在、现在被改/被删的未跟踪文件 → 还原
   let restored = 0
   for (const rel of meta.untracked) {
     const src = join(dir, "untracked", rel)
@@ -124,11 +151,157 @@ export async function rewind(cwd, id) {
       restored++
     }
   }
+  return { deleted, restored }
+}
+
+/** Restore a single tracked file: checkout HEAD → apply that file's patch hunks */
+async function partialRestoreTracked(cwd, patchContent, filePath) {
+  // Reset the file to HEAD state first
+  git(cwd, ["checkout", "HEAD", "--", filePath], { allowFail: true })
+  const hunks = extractFileHunks(patchContent, filePath)
+  if (!hunks) return false
+  const tmpFile = join(checkpointRoot(cwd), ".tmp_partial.patch")
+  await writeFile(tmpFile, hunks, "utf8")
+  try {
+    git(cwd, ["apply", "--whitespace=nowarn", tmpFile])
+    return true
+  } finally {
+    await rm(tmpFile, { force: true })
+  }
+}
+
+/** Restore a single untracked file */
+async function partialRestoreUntracked(cwd, dir, filePath) {
+  const src = join(dir, "untracked", filePath)
+  if (!existsSync(src)) return false
+  await mkdir(dirname(join(cwd, filePath)), { recursive: true })
+  await cp(src, join(cwd, filePath), { force: true })
+  return true
+}
+
+// ---- rewind ----
+
+/**
+ * Rewind to a specific snapshot (saves current state as a new snapshot first, making rewind reversible).
+ *
+ * Options:
+ * - path: restore only this single file (tracked or untracked); other files are left untouched.
+ *   Omit for a full rewind (all changes → snapshot state).
+ *
+ * Returns summary { patchApplied, deleted?, restored? }; in path mode includes { file, type }.
+ */
+export async function rewind(cwd, id, { path } = {}) {
+  const root = checkpointRoot(cwd)
+  const dir = join(root, id)
+  if (!existsSync(join(dir, "meta.json"))) throw new Error(`checkpoint ${id} not found`)
+  const meta = JSON.parse(await readFile(join(dir, "meta.json"), "utf8"))
+  const patchContent = await readFile(join(dir, "patch.diff"), "utf8")
+
+  // Rewind is reversible: snapshot current state first
+  const preRewindCp = await createCheckpoint(cwd)
+
+  // ---- per-file restore ----
+  if (path) {
+    // Determine whether it's a tracked or untracked file
+    const isTracked = meta.tracked?.includes(path) ?? extractFileHunks(patchContent, path) !== ""
+    const inUntracked = (meta.untracked ?? []).includes(path)
+
+    if (!isTracked && !inUntracked) {
+      throw new Error(`file "${path}" not found in checkpoint ${id} (tracked: ${(meta.tracked ?? []).join(", ") || "none"}, untracked: ${(meta.untracked ?? []).join(", ") || "none"})`)
+    }
+
+    let ok = false
+    if (isTracked) {
+      ok = await partialRestoreTracked(cwd, patchContent, path)
+    }
+    if (inUntracked) {
+      ok = await partialRestoreUntracked(cwd, dir, path) || ok
+    }
+
+    return { path, type: isTracked ? "tracked" : "untracked", restored: ok, patchApplied: false }
+  }
+
+  // ---- full rewind ----
+  try {
+    const patchApplied = await fullRestoreTracked(cwd, dir)
+    const { deleted, restored } = await fullRestoreUntracked(cwd, dir, meta)
+    return { deleted, restored, patchApplied }
+  } catch (e) {
+    // git apply failed: working tree may have been reset to HEAD by restore.
+    // Restore from pre-rewind snapshot to ensure no data is lost on rewind failure
+    const preDir = join(root, preRewindCp.id)
+    try {
+      await fullRestoreTracked(cwd, preDir)
+      await fullRestoreUntracked(cwd, preDir, JSON.parse(await readFile(join(preDir, "meta.json"), "utf8")))
+    } catch {
+      // Double failure: pre-rewind may also be corrupt, stop trying
+    }
+    throw new Error(
+      `Rewind to ${id} failed: ${e.message}. ` +
+      `The pre-rewind state was restored from checkpoint ${preRewindCp.id} — no work was lost.`
+    )
+  }
+}
 
-  return { deleted, restored, patchApplied: Boolean(patch.trim()) }
+// ---- view ----
+
+/**
+ * View a file's content from a checkpoint (does not modify the working tree).
+ * Tracked files: temporarily restore via checkout HEAD + apply patch hunks, read, then restore original.
+ * Untracked files: read the copy directly from the checkpoint directory.
+ * Returns the file content string.
+ */
+export async function catFile(cwd, id, filePath) {
+  const root = checkpointRoot(cwd)
+  const dir = join(root, id)
+  if (!existsSync(join(dir, "meta.json"))) throw new Error(`checkpoint ${id} not found`)
+  const meta = JSON.parse(await readFile(join(dir, "meta.json"), "utf8"))
+  const patchContent = await readFile(join(dir, "patch.diff"), "utf8")
+
+  const isTracked = meta.tracked?.includes(filePath) ?? extractFileHunks(patchContent, filePath) !== ""
+  const inUntracked = (meta.untracked ?? []).includes(filePath)
+
+  if (!isTracked && !inUntracked) {
+    throw new Error(`file "${filePath}" not in checkpoint ${id}`)
+  }
+
+  // Untracked file: read the copy directly
+  if (inUntracked && !isTracked) {
+    const src = join(dir, "untracked", filePath)
+    if (!existsSync(src)) throw new Error(`untracked file "${filePath}" copy missing in checkpoint`)
+    return await readFile(src, "utf8")
+  }
+
+  // Tracked file: temporarily restore → read → restore working tree
+  const abs = join(cwd, filePath)
+  const existed = existsSync(abs)
+  let saved = null
+  if (existed) saved = await readFile(abs, "utf8")
+
+  try {
+    git(cwd, ["checkout", "HEAD", "--", filePath])
+    const hunks = extractFileHunks(patchContent, filePath)
+    if (hunks) {
+      const tmpPatch = join(root, ".tmp_cat.patch")
+      await writeFile(tmpPatch, hunks, "utf8")
+      try {
+        git(cwd, ["apply", "--whitespace=nowarn", tmpPatch])
+      } finally {
+        await rm(tmpPatch, { force: true })
+      }
+    }
+    return await readFile(abs, "utf8")
+  } finally {
+    // Restore original working tree state
+    if (existed) {
+      await writeFile(abs, saved, "utf8")
+    } else {
+      await rm(abs, { force: true })
+    }
+  }
 }
 
-/** 只留最近 MAX_CHECKPOINTS 个 */
+/** Keep only the most recent MAX_CHECKPOINTS */
 async function pruneCheckpoints(cwd) {
   const root = checkpointRoot(cwd)
   const ids = (await readdir(root)).sort()

package/src/git/gitmem.mjs

@@ -1,8 +1,9 @@
 /**
- * gitmem.mjs — Team 层记忆的 git 同步
- * 全部通过 child_process 调系统 git，零依赖。
- * 冲突策略（已定）：不同条目天然不冲突；真冲突时中止 rebase 保持仓库干净，
- * 报带手动指引的错误——不做自动合并。
+ * gitmem.mjs — Team-layer memory git sync
+ * All through child_process calling system git, zero dependencies.
+ * Conflict strategy (decided): different entries are naturally conflict-free;
+ * on real conflicts abort rebase to keep the repo clean,
+ * report an error with manual resolution guidance — no auto-merge.
  */
 
 import { execFile } from "node:child_process"
@@ -13,7 +14,7 @@ import { promisify } from "node:util"
 
 const execFileAsync = promisify(execFile)
 
-/** 在 dir 下执行 git，失败抛带 stderr 的错误 */
+/** Run git in dir, throw with stderr on failure */
 async function git(dir, args) {
   try {
     const { stdout } = await execFileAsync("git", args, { cwd: dir, encoding: "utf8" })
@@ -27,7 +28,7 @@ async function git(dir, args) {
   }
 }
 
-/** 团队仓库不存在则 clone。返回是否发生了 clone */
+/** Clone team repo if it doesn't exist. Returns whether a clone happened */
 export async function ensureClone({ repo, dir }) {
   if (existsSync(join(dir, ".git"))) return false
   await mkdir(dirname(dir), { recursive: true })
@@ -36,12 +37,12 @@ export async function ensureClone({ repo, dir }) {
 }
 
 /**
- * 同步：pull --rebase。远端还是空仓库时直接跳过（首次使用前）。
- * 冲突时中止 rebase（保持仓库干净）并抛带指引的错误。
- * 返回 true=拉取成功（调用方随后 syncDir 重建索引）
+ * Sync: pull --rebase. Skip if remote is still empty (first-time use).
+ * On conflict, abort rebase (keep repo clean) and throw a guided error.
+ * Returns true = pull succeeded (caller should then syncDir to rebuild index)
  */
 export async function pullTeam(dir) {
-  // 远端空仓库：没有可拉取的分支（ls-remote 无输出）
+  // Empty remote repo: no branch to pull (ls-remote has no output)
   const refs = await git(dir, ["ls-remote", "--heads", "origin"])
   if (!refs) return false
 
@@ -52,9 +53,9 @@ export async function pullTeam(dir) {
     if (await hasConflict(dir)) {
       await git(dir, ["rebase", "--abort"]).catch(() => {})
       throw new Error(
-        `团队记忆同步冲突：本地与远端修改了同一条目。\n` +
-        `请到 ${dir} 手动执行 git pull 解决冲突，然后重新运行 thincoder sync。\n` +
-        `（本地仓库已恢复到同步前状态，未丢失任何内容）`,
+        `Team memory sync conflict: local and remote modified the same entry.\n` +
+        `Please resolve manually in ${dir} with \`git pull\`, then re-run \`thincoder sync\`.\n` +
+        `(The local repo has been restored to its pre-sync state — nothing was lost.)`,
       )
     }
     throw error
@@ -62,28 +63,28 @@ export async function pullTeam(dir) {
 }
 
 /**
- * 提交并推送一个条目文件。push 被拒（远端有新提交）时 pull --rebase 后重试一次；
- * rebase 冲突同样中止并报错。
+ * Commit and push an entry file. On push rejection (remote has new commits),
+ * pull --rebase then retry once; rebase conflicts also abort and error out.
  */
 export async function commitAndPush(dir, filename, message) {
   await git(dir, ["add", filename])
-  // 内容没变化时 commit 会以 exit 1 报 "nothing to commit"——这是正常的幂等结果，不是错误
+  // Nothing to commit (content unchanged) — this is normal idempotent behavior, not an error
   const dirty = await git(dir, ["status", "--porcelain", "--", filename])
   if (dirty) await git(dir, ["commit", "-m", message])
   try {
     await git(dir, ["push"])
   } catch {
-    await pullTeam(dir) // 冲突时这里会抛出带指引的错误
+    await pullTeam(dir) // Conflicts will throw a guided error here
     await git(dir, ["push"])
   }
 }
 
-/** 当前是否处于 rebase 冲突状态（存在未合并路径） */
+/** Whether currently in a rebase conflict state (unmerged paths exist) */
 async function hasConflict(dir) {
   try {
     const out = await git(dir, ["status", "--porcelain"])
-    // 未合并状态共 7 种：DD AU UD UA DU AA UU——只看 UU/AA/DD 会漏掉带 U 的四种，
-    // 漏判就不 abort，仓库留在冲突中间态（与"保持仓库干净"的承诺相悖）
+    // There are 7 unmerged states: DD AU UD UA DU AA UU — only checking UU/AA/DD misses 4 states with U,
+    // which means the rebase is left mid-conflict (violating the "keep repo clean" promise)
     return out.split("\n").some((l) => l[0] === "U" || l[1] === "U" || l.startsWith("AA") || l.startsWith("DD"))
   } catch {
     return false