thincoder 0.8.2 → 0.8.4

package/src/context.mjs

@@ -1,14 +1,16 @@
 /**
- * context.mjs — 上下文管理与压缩
- * token 无实测值时用估算兜底（ASCII/4 + 非 ASCII/1，不引 tokenizer 依赖）；
- * 有实测值（响应 usage.prompt_tokens）以实测为准——估算对 CJK 低估 3-4 倍，靠它触发可能永远来不及压缩。
- * 压缩策略：保留最早 2 条 + 最近 N 条，中间由 LLM 摘要成一条（学 kimi-code，简化版）。
+ * context.mjs — Context management and compaction
+ * When no measured token count is available, use estimation as fallback (ASCII/4 + non-ASCII/1, no tokenizer dependency).
+ * When a measured value exists (response usage.prompt_tokens), trust it — estimation underestimates CJK by 3-4x and relying solely on it may never trigger compaction.
+ * Compaction strategy: keep earliest 2 + latest N messages, summarize the middle into one via LLM (inspired by kimi-code, simplified).
  */
 
 import { chat } from "./provider/index.mjs"
 import { estimateText } from "./provider/rate.mjs"
 
-/** 粗估一组消息的 token 数（正文 + 思考链 + tool_calls 参数） */
+const IMAGE_TOKEN_ESTIMATE = 256 // rough estimate for image placeholder tokens
+
+/** Rough token count for a list of messages (body + reasoning + tool_calls params) */
 export function estimateTokens(messages) {
   let tokens = 0
   for (const m of messages) {
@@ -16,7 +18,7 @@ export function estimateTokens(messages) {
     else if (Array.isArray(m.content)) {
       for (const part of m.content) {
         if (part.type === "text") tokens += estimateText(part.text)
-        else if (part.type === "image_url") tokens += 256 // 图片占位估算
+        else if (part.type === "image_url") tokens += IMAGE_TOKEN_ESTIMATE
       }
     }
     if (typeof m.reasoning_content === "string") tokens += estimateText(m.reasoning_content)
@@ -27,59 +29,58 @@ export function estimateTokens(messages) {
   return tokens
 }
 
-const KEEP_HEAD = 2 // 最早的用户意图，不能丢
-const KEEP_TAIL = 10 // 最近的工作现场，不能丢
+const KEEP_HEAD = 2 // Keep the earliest user intent — must not lose it
+const KEEP_TAIL = 10 // Keep the most recent work context — must not lose it
 
-const SUMMARIZE_PROMPT = `你是一个对话压缩器。把下面的 agent 工作记录压缩成一份紧凑的摘要，供后续对话作为上下文使用。
-要求：
-- 用第一人称、现在时书写——这是"我"的交接笔记，延续自己的思路
-- 最重要的：保留设计决策与原因——架构选择、API 约定、命名规范、取舍理由。这是后续代码不能偏离的锚点
-- 保留：用户的原始需求、修改过的文件及原因、未解决的问题、下一步计划
-- 丢弃：客套话、重复内容、工具输出的细枝末节
-- 诚实标注不确定项：没有实际验证过的事必须写"未验证"，不要把猜测写成事实
-- 用条目式输出，以信息完整为目标，不要硬卡字数（旧 500 字限制已作废，1M 上下文时代宁长勿缺）
+const SUMMARIZE_PROMPT = `You are a conversation compressor. Summarize the following agent work log into a compact summary for use as context in the ongoing conversation.
+Requirements:
+- Write in first person, present tense — these are "my" handover notes, continuing my own train of thought
+- Most important: preserve design decisions and their reasons — architecture choices, API contracts, naming conventions, trade-off rationale. These are the anchors the subsequent code must not deviate from
+- Keep: the user's original request, files modified and why, unresolved issues, next steps
+- Drop: pleasantries, repetition, fine-grained tool output details
+- Honestly mark uncertain items: anything not actually verified must say "unverified"; do not present guesses as facts
+- Use bullet-point output; aim for information completeness, not a hard word limit (old 500-char cap is deprecated; in a 1M-context era, err on the long side)
 
-工作记录：
+Work log:
 `
 
-/** 压缩后的上下文前缀，告知 agent 发生了什么 */
+/** Context prefix after compaction, informing the agent what happened */
 const COMPACTION_PREFIX =
   "[Context was automatically compacted. Below is a summary of earlier work. " +
   "Treat it as notes, not proof — trust its conclusions (don't redo what it reports as done) " +
-  "but re-verify transient state (open files, running processes) with tools before relying on them. " +
-  "Design decisions made earlier may be summarized — if you recall a decision that is missing from the summary, check memory_search or re-examine the code.]\n\n"
+  "but re-verify transient state with tools. Check memory_search for any missing decisions.]\n\n"
 
-/** 压缩摘要调用连续失败达到此次数后，降级为确定性截断（丢信息好过任务被 400 打死） */
+/** After this many consecutive compaction summary failures, degrade to deterministic truncation (losing info is better than task-killing 400 errors) */
 export const COMPRESS_FAILURE_LIMIT = 3
 
-/** task 回注提醒前缀（压缩后重新注入前，先清掉历史里的旧版本，保持单一信息源） */
+/** Task re-injection reminder prefix (after compaction, clear old versions from history first for a single source of truth) */
 const TASK_REINJECT_PREFIX = "[System reminder: your current task list after compaction:"
 
-/** 截断兜底笔记（摘要 LLM 连续失败时用，无 LLM 调用） */
+/** Truncation fallback note (used when the summary LLM fails repeatedly; no LLM call) */
 const FALLBACK_NOTE =
   "[Context was truncated after repeated summarization failures. " +
   "The middle portion of earlier work was dropped WITHOUT a summary. " +
   "Re-verify any state you need with tools before relying on it.]\n\n"
 
 /**
- * 切分 head / middle(被摘要) / tail；没有可压缩的中间段返回 null。
- * head 终点必须避开断头 tool_calls：assistant 带了 tool_calls 时其 tool 响应必须留在 head，
- * 否则响应被摘要成纯文本后协议校验 400（tool_calls must be followed by tool messages）。
- * tail 起点必须包含 tool 结果对应的 assistant——tool 在 tail、assistant 在 middle 时，
- * 摘要会把 assistant 吞掉，留下 orphan tool 结果 → 协议 400。
+ * Split history into head / middle (to be summarized) / tail; return null if no middle to compress.
+ * The head boundary must avoid orphan tool_calls: when an assistant message has tool_calls, all its tool responses must stay in head,
+ * otherwise compressing them to plain text violates the protocol (tool_calls must be followed by tool messages).
+ * The tail boundary must include any assistant whose tool results are in the tail — if the assistant is in the middle,
+ * the summary swallows it, leaving orphan tool results → protocol 400.
  */
 function splitHistory(history) {
   if (history.length <= KEEP_HEAD + KEEP_TAIL + 1) return null
   let headEnd = KEEP_HEAD
-  // head 不能以断头 tool_calls 结尾：assistant 声明了 tool_calls，其 tool 结果必须全部留在 head。
-  // 并行调用时一个 assistant 后面跟多条 tool 消息——只收一条照样 400，必须一次收完
+  // head must not end with dangling tool_calls: when assistant declares tool_calls, all its tool results must stay in head.
+  // Parallel calls: one assistant followed by multiple tool messages — accepting only one still causes 400, must collect all
   if (history[headEnd - 1]?.role === "assistant" && history[headEnd - 1].tool_calls?.length) {
     while (headEnd < history.length && history[headEnd].role === "tool") headEnd++
   }
   let tailStart = history.length - KEEP_TAIL
 
-  // tail 区域内的 tool 消息对应的 assistant tool_calls 若在 middle 里，摘要会把 assistant 吞掉，
-  // 剩下 orphan tool 结果 → 协议 400。从 tail 收集 tool_call_id，往前找回所属 assistant 拉进 tail
+  // Tool messages in the tail region whose assistant tool_calls are in the middle: the summary would swallow the assistant,
+  // leaving orphan tool results → protocol 400. Collect tool_call_ids from the tail, find their owner assistants and pull them into tail
   const tailToolIds = new Set()
   for (let i = tailStart; i < history.length; i++) {
     if (history[i].role === "tool") tailToolIds.add(history[i].tool_call_id)
@@ -100,7 +101,7 @@ function splitHistory(history) {
   return { headEnd, tailStart }
 }
 
-/** 用一条笔记替换 middle，并回注 task/plan 状态（LLM 摘要与截断兜底共用） */
+/** Replace middle with a note, then re-inject task/plan state (shared by LLM summary and truncation fallback) */
 function applyCompression(agent, headEnd, tailStart, note) {
   const head = agent.history.slice(0, headEnd)
   const tail = agent.history.slice(tailStart)
@@ -110,13 +111,13 @@ function applyCompression(agent, headEnd, tailStart, note) {
     { role: "assistant", content: "Understood. I'll continue from these notes, re-verifying anything transient." },
     ...tail,
   ]
-  // 实测 token 基准随旧历史一起失效（prompt_tokens 对应的是压缩前的上下文），退回估算直到下次响应
+  // Measured token baseline is invalidated along with old history (prompt_tokens were for pre-compaction context), fall back to estimation until next response
   agent._lastPromptTokens = null
   agent._usageAtLen = null
 
-  // 压缩后回注 task 列表（agent 需要知道自己做到哪了）。
-  // 单一信息源：先清掉 tail 里残留的旧回注，再注入最新版本——
-  // 不再嵌入摘要正文（会与这里重复且逐渐过时）
+  // After compaction, re-inject the task list (the agent needs to know what it was doing).
+  // Single source of truth: first remove any stale re-injections from the tail, then inject the latest version —
+  // no longer embedded in the summary body (would duplicate and grow stale)
   agent.history = agent.history.filter(
     (m) => !(m.role === "user" && typeof m.content === "string" && m.content.startsWith(TASK_REINJECT_PREFIX))
   )
@@ -128,11 +129,7 @@ function applyCompression(agent, headEnd, tailStart, note) {
     })
   }
 
-  // 重置跟踪计数器（上下文已重建，从头开始计数）
-  agent._turnsSinceTaskUpdate = 0
-  agent._turnsInPlanMode = 0
-
-  // plan mode 中压缩：重新注入 plan 模式引导
+  // Plan mode compaction: re-inject plan mode guidance
   if (agent.planMode) {
     agent.history.push({
       role: "user",
@@ -142,14 +139,14 @@ function applyCompression(agent, headEnd, tailStart, note) {
 }
 
 /**
- * 如果历史超长则压缩。返回是否发生了压缩。
- * 只在循环的安全点调用（history 末尾是 user 或 tool 消息——完整交换的边界）。
- * 压缩后自动回注 task 列表状态。
+ * If history exceeds threshold, compact it. Returns whether compaction happened.
+ * Only called at safe points in the loop (history ends with user or tool message — a complete exchange boundary).
+ * Automatically re-injects task list state after compaction.
  */
 export async function compressIfNeeded(agent, threshold) {
   const history = agent.history
-  // 真实基准优先：上次响应的 prompt_tokens 是完整上下文（system+tools+history）的实测值，
-  // 之后追加的消息用估算补增量；无实测（首轮/恢复后/刚压缩完）退化为纯估算
+  // Prefer the real baseline: the last response's prompt_tokens is the measured value for the full context (system+tools+history).
+  // Subsequent appended messages use estimation as increment; when no measured value exists (first turn / after restore / right after compaction), fall back to pure estimation
   const tokens =
     agent._lastPromptTokens != null
       ? agent._lastPromptTokens + estimateTokens(history.slice(agent._usageAtLen ?? history.length))
@@ -158,23 +155,24 @@ export async function compressIfNeeded(agent, threshold) {
 
   const split = splitHistory(history)
   if (!split) {
-    // 历史太短（≤13 条）切不出中间段，但 token 已超阈值——典型是一条巨型消息
-    // （大段粘贴/超大注入）。摘要无路可走时退化为确定性瘦身，保证上下文总能减下去
+    // History is too short (≤13 messages) to find a middle section, but tokens exceed threshold — typically a single giant message
+    // (large paste / huge injection). When summarization has no room, degrade to deterministic shrinking to ensure context always reduces
     return shrinkOversized(agent)
   }
 
   const middle = history.slice(split.headEnd, split.tailStart)
   const serialized = middle
     .map((m) => {
-      const toolNote = m.tool_calls ? ` [调用了工具: ${m.tool_calls.map((t) => t.function.name).join(", ")}]` : ""
-      // user 消息放宽到 8000：用户粘贴的长需求被切掉会让摘要丢失原始意图；tool/assistant 2000 足够
+      const toolNote = m.tool_calls ? ` [called tools: ${m.tool_calls.map((t) => t.function.name).join(", ")}]` : ""
+      // user messages get a wider cap (8000): cutting off a long user-pasted requirement loses original intent; tool/assistant capped at 2000 is enough
       const cap = m.role === "user" ? 8000 : 2000
       const content = typeof m.content === "string" ? m.content.slice(0, cap) : ""
       return `[${m.role}]${toolNote} ${content}`
     })
     .join("\n")
 
-  const summary = await chat(agent.provider, {
+  // The summary is a plain-text task, no reasoning needed — passing thinking to the compaction provider wastes tokens
+  const summary = await chat({ ...agent.provider, thinking: null, reasoningEffort: null }, {
     messages: [{ role: "user", content: SUMMARIZE_PROMPT + serialized }],
   })
 
@@ -183,8 +181,8 @@ export async function compressIfNeeded(agent, threshold) {
 }
 
 /**
- * 确定性截断兜底：摘要 LLM 连续失败时调用，不碰网络。
- * 丢掉 middle 换任务能继续跑。返回是否发生了截断。
+ * Deterministic truncation fallback: called when the summary LLM fails repeatedly, no network call.
+ * Drops the middle so the task can continue. Returns whether truncation happened.
  */
 export function compressFallback(agent) {
   const split = splitHistory(agent.history)
@@ -193,21 +191,21 @@ export function compressFallback(agent) {
   return true
 }
 
-/** 单条消息正文的硬截断长度：超过且在压缩无法切分时截断换桩（防一条巨消息卡死压缩） */
+/** Hard truncation limit for a single message body: when exceeded and the splitter can't find a middle section, truncate to a stub (prevents one giant message from blocking compaction) */
 const OVERSIZE_CONTENT_LIMIT = 8_000
 
 /**
- * 确定性瘦身：splitHistory 切不出中间段（历史太短）但已超阈值时的最后手段，无 LLM 调用。
- * 把超过 OVERSIZE_CONTENT_LIMIT 的 user/tool 正文截断换桩（保留首尾）；
- * 不动 reasoning_content（DeepSeek/Kimi 回传协议）与 tool_calls 配对结构，无协议 400 风险。
- * 只在 compressIfNeeded 判定超阈值后调用。返回是否有消息被截断。
+ * Deterministic shrinking: last resort when splitHistory can't find a middle section (history too short) but threshold is exceeded. No LLM call.
+ * Truncates user/tool message bodies exceeding OVERSIZE_CONTENT_LIMIT to a stub (keeps head + tail);
+ * does not touch reasoning_content (DeepSeek/Kimi echo protocol) or tool_calls pairing structure — no protocol 400 risk.
+ * Only called after compressIfNeeded determines threshold is exceeded. Returns whether any message was truncated.
  */
 export function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
   let shrunk = false
   for (const m of agent.history) {
     if ((m.role !== "user" && m.role !== "tool") || typeof m.content !== "string") continue
     if (m.content.length <= limit) continue
-    // 截断保留首尾，中间换桩说明；keepHead/keepTail 按比例但不超过 limit 的 50%/25%
+    // Truncate keeping head + tail, insert stub in between; keepHead/keepTail proportional but not exceeding 50%/25% of limit
     const keepHead = Math.min(Math.floor(limit * 0.5), 4000)
     const keepTail = Math.min(Math.floor(limit * 0.25), 2000)
     m.content =
@@ -217,7 +215,7 @@ export function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
     shrunk = true
   }
   if (shrunk) {
-    // 与压缩同理：实测 token 基准随被改动的历史失效，退回估算直到下次响应
+    // Same as compaction: measured token baseline is invalidated by the changed history, fall back to estimation until next response
     agent._lastPromptTokens = null
     agent._usageAtLen = null
   }

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