thincoder 0.8.2 → 0.8.3

package/src/markdown.mjs

@@ -1,14 +1,14 @@
 /**
- * markdown.mjs — 记忆条目的 markdown + frontmatter 格式
- * 零依赖解析/序列化。条目格式见 ARCHITECTURE-v2.md。
+ * markdown.mjs — markdown + frontmatter format for memory entries
+ * Zero-dependency parsing/serialization. Entry format see ARCHITECTURE-v2.md.
  */
 
 const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
 
 /**
- * 解析 markdown 条目。
+ * Parse a markdown entry.
  * → { meta: { type, title, tags, author, created, embedding? }, content }
- * 无 frontmatter 或缺必要字段时抛错。
+ * Throws if frontmatter is missing or required fields absent.
  */
 export function parseEntry(text) {
   const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
@@ -36,13 +36,13 @@ export function parseEntry(text) {
 }
 
 /**
- * 序列化为 markdown 条目文本。
+ * Serialize to markdown entry text.
  */
 export function serializeEntry(meta, content) {
   if (!VALID_TYPES.has(meta.type)) throw new Error(`invalid type "${meta.type}"`)
   if (!meta.title) throw new Error("meta.title is required")
-  // frontmatter 标量必须单行：title/author 含换行会注入伪 frontmatter 行
-  // （如 title "x\ntype: rule" 解析时覆盖真实 type），tags 含换行/逗号同理
+  // frontmatter scalars must be single-line: newlines in title/author would inject fake frontmatter rows
+  // (e.g. title "x\ntype: rule" would override real type when parsed), same for tags with newlines/commas
   const tags = (meta.tags ?? []).map((t) => oneLine(t).replaceAll(",", " ")).join(", ")
   const lines = [
     "---",
@@ -57,7 +57,7 @@ export function serializeEntry(meta, content) {
   return lines.join("\n")
 }
 
-/** 标题转文件名 slug：保留中英文数字，其余转连字符 */
+/** Convert title to filename slug: keep alphanumeric + CJK, convert rest to hyphens */
 export function slugify(title) {
   return title
     .trim()
@@ -67,23 +67,23 @@ export function slugify(title) {
     .slice(0, 50) || "untitled"
 }
 
-/** 生成条目文件名：YYYYMMDD-<slug>-<rand4>.md */
+/** Generate entry filename: YYYYMMDD-<slug>-<rand4>.md */
 export function entryFilename(title, date = new Date()) {
   const ymd = date.toISOString().slice(0, 10).replaceAll("-", "")
   const rand = Math.random().toString(36).slice(2, 6)
   return `${ymd}-${slugify(title)}-${rand}.md`
 }
 
-// ---------------------------------------------------------------- 内部
+// ---------------------------------------------------------------- internal
 
-/** 压成单行（frontmatter 标量用）：换行折叠为空格，防注入伪字段行 */
+/** Collapse to single line (for frontmatter scalars): fold newlines into spaces, prevent injecting fake field lines */
 function oneLine(v) {
   return String(v).replace(/\s*\r?\n\s*/g, " ").trim()
 }
 
 /**
- * 极简 YAML 子集解析：只支持 `key: value` 和 `key: [a, b, c]`。
- * 我们的 frontmatter 是自己生成的，不需要完整 YAML。
+ * Minimal YAML subset parser: only supports `key: value` and `key: [a, b, c]`.
+ * Our frontmatter is self-generated, no need for full YAML.
  */
 function parseFrontmatter(text) {
   const meta = {}

package/src/mcp/helpers.mjs

@@ -1,5 +1,5 @@
 /**
- * mcp/helpers.mjs — MCP 共享工具函数与常量
+ * mcp/helpers.mjs — MCP shared utility functions and constants
  */
 
 export const INIT_TIMEOUT_MS = 30_000
@@ -7,10 +7,12 @@ export const CALL_TIMEOUT_MS = 120_000
 export const ENDPOINT_WAIT_MS = 5_000
 
 let nextRpcId = 0
+/** Generate a unique incrementing RPC ID string */
 export function rpcId() {
   return String(++nextRpcId)
 }
 
+/** Race a promise against a timeout, rejecting after ms milliseconds */
 export function withTimeout(promise, ms) {
   let timer
   const timeout = new Promise((_, reject) => {
@@ -20,10 +22,12 @@ export function withTimeout(promise, ms) {
   return Promise.race([promise.finally(() => clearTimeout(timer)), timeout])
 }
 
+/** Quote a shell argument: wrap in double-quotes if it contains whitespace or quotes */
 export function quoteArg(s) {
   return /[\s"]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
 }
 
+/** Append a Bearer token as a query parameter to a WebSocket URL */
 export function withAuthToken(wsUrl, authorization) {
   if (!authorization) return wsUrl
   const token = authorization.replace(/^Bearer\s+/i, "")
@@ -32,6 +36,7 @@ export function withAuthToken(wsUrl, authorization) {
   return u.href
 }
 
+/** Sanitize a tool name: replace non-alphanumeric chars with underscores, cap at 64 chars */
 export function sanitizeToolName(name) {
   return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64)
 }

package/src/mcp/transport-http.mjs

@@ -3,6 +3,7 @@
  */
 import { rpcId, CALL_TIMEOUT_MS, ENDPOINT_WAIT_MS, withTimeout } from "./helpers.mjs"
 
+/** Create an MCP HTTP+SSE transport for Streamable HTTP servers */
 export function httpTransport(baseURL, extraHeaders = {}) {
   const url = baseURL.replace(/\/+$/, "")
   let sessionId = null
@@ -82,7 +83,7 @@ export function httpTransport(baseURL, extraHeaders = {}) {
               pending.delete(msg.id)
               resolver(msg)
             }
-          } catch { /* 非 JSON，忽略 */ }
+          } catch { /* not JSON, ignore */ }
         }
       } catch (error) {
         if (!closed) {

package/src/mcp/transport-stdio.mjs

@@ -4,6 +4,7 @@
 import { spawn } from "node:child_process"
 import { rpcId, CALL_TIMEOUT_MS, withTimeout, quoteArg } from "./helpers.mjs"
 
+/** Create an MCP stdio transport over a spawned child process */
 export function stdioTransport(command, args) {
   const spawnOptions = { stdio: ["pipe", "pipe", "pipe"], windowsHide: true, env: { ...process.env } }
   const child =
@@ -39,7 +40,7 @@ export function stdioTransport(command, args) {
           pending.delete(msg.id)
           resolver(msg)
         }
-      } catch { /* 非 JSON 行忽略 */ }
+      } catch { /* non-JSON line, ignore */ }
     }
   })
 
@@ -77,7 +78,7 @@ export function stdioTransport(command, args) {
     if (closed) return
     try {
       child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n")
-    } catch { /* 忽略 */ }
+    } catch { /* ignore */ }
   }
 
   return { send, notify, close: () => { if (!closed) child.kill() } }

package/src/mcp/transport-ws.mjs

@@ -3,6 +3,7 @@
  */
 import { rpcId, INIT_TIMEOUT_MS, CALL_TIMEOUT_MS, withTimeout, withAuthToken } from "./helpers.mjs"
 
+/** Create an MCP WebSocket transport */
 export function wsTransport(wsUrl, extraHeaders = {}) {
   const pending = new Map()
   let closed = false
@@ -36,7 +37,7 @@ export function wsTransport(wsUrl, extraHeaders = {}) {
             pending.delete(msg.id)
             resolver(msg)
           }
-        } catch { /* 非 JSON，忽略 */ }
+        } catch { /* not JSON, ignore */ }
       })
 
       ws.addEventListener("error", (event) => {
@@ -80,7 +81,7 @@ export function wsTransport(wsUrl, extraHeaders = {}) {
   const close = () => {
     closed = true
     failAll("Connection closed")
-    try { ws?.close() } catch { /* 忽略 */ }
+    try { ws?.close() } catch { /* ignore */ }
   }
 
   return { send, notify, close, connect }

package/src/mcp.mjs

@@ -1,6 +1,6 @@
 /**
  * mcp.mjs — MCP (Model Context Protocol) client
- * config: { command, args?, name } 或 { url, name, headers? } 或 { wsUrl, name, headers? }
+ * config: { command, args?, name } or { url, name, headers? } or { wsUrl, name, headers? }
  */
 import { INIT_TIMEOUT_MS, withTimeout, sanitizeToolName } from "./mcp/helpers.mjs"
 import { stdioTransport } from "./mcp/transport-stdio.mjs"
@@ -46,6 +46,7 @@ async function doInitialize(transport, name) {
   return toolsResp.result?.tools ?? []
 }
 
+/** Connect to an MCP server (stdio/http/ws), initialize, and return built tool wrappers */
 export async function connectMcpServer(config) {
   if (config.wsUrl) {
     const transport = wsTransport(config.wsUrl, config.headers ?? {})
@@ -64,7 +65,7 @@ export async function connectMcpServer(config) {
     try {
       await transport.openSSE()
     } catch {
-      // 不支持 GET 的 server（纯 Streamable HTTP POST）：降级为无 SSE 模式
+      // Server doesn't support GET (pure Streamable HTTP POST): degrade to no-SSE mode
     }
     try {
       const mcpTools = await doInitialize(transport, config.name ?? config.url)
@@ -89,12 +90,14 @@ export async function connectMcpServer(config) {
   throw new Error(`MCP server "${config.name}": needs either 'wsUrl' (websocket), 'command' (stdio), or 'url' (http)`)
 }
 
+/** Close all MCP transport connections on an agent's tools */
 export function closeAllMcp(agent) {
   for (const t of agent.tools) {
     if (t._mcpTransport) t._mcpTransport.close()
   }
 }
 
+/** Remove MCP tools belonging to a specific server from the agent's tool list */
 export function removeMcpTools(agent, serverName) {
   const keep = []
   for (const t of agent.tools) {

package/src/memory/code-index.mjs

@@ -1,10 +1,10 @@
 /**
- * memory/code-index.mjs — 代码和文档的分块、语言检测、符号提取
+ * memory/code-index.mjs — code and document chunking, language detection, symbol extraction
  */
 
 import { segmentCJK, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./schema.mjs"
 
-/** 推断文件语言（按扩展名） */
+/** Infer file language by extension */
 export function detectLanguage(filename) {
   const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase()
   const map = {
@@ -21,8 +21,8 @@ export function detectLanguage(filename) {
 }
 
 /**
- * 用正则提取 JS/TS 文件的顶层符号声明（函数、类、const 导出等）。
- * 返回 [{ name, line, kind }]。
+ * Extract top-level symbol declarations (functions, classes, const exports, etc.)
+ * from JS/TS files using regex. Returns [{ name, line, kind }].
  */
 export function extractSymbols(lines, ext) {
   const jsish = new Set([".mjs", ".js", ".ts", ".jsx", ".tsx"])
@@ -41,7 +41,7 @@ export function extractSymbols(lines, ext) {
   return symbols
 }
 
-/** 提取 Python 文件的顶层 def/class。 */
+/** Extract top-level def/class from Python files. */
 export function extractPySymbols(lines) {
   const symbols = []
   const re = /^(?:async\s+)?(?:def|class)\s+(\w+)/gm
@@ -54,8 +54,9 @@ export function extractPySymbols(lines) {
 }
 
 /**
- * 将一个文件拆成代码块。小文件整文件一块；大文件按符号切分，符号间的内容并入前一个符号块。
- * 每个块会额外带上符号前的 JSDoc / docstring 注释，提升搜索质量。
+ * Split a file into code chunks. Small files become a single chunk;
+ * large files are split by symbol, with inter-symbol content merged into the preceding symbol chunk.
+ * Each chunk includes the JSDoc/docstring before its symbol to improve search quality.
  */
 export function chunkCode(lines, filepath) {
   const ext = filepath.slice(filepath.lastIndexOf(".")).toLowerCase()
@@ -91,9 +92,9 @@ export function chunkCode(lines, filepath) {
 }
 
 /**
- * 提取指定行之前的 JSDoc / docstring 注释。
- * JS/TS: 向前扫描 /** ... *​/ 或 // 连续注释行
- * Python: 符号定义行的下一行开始找 """...""" docstring
+ * Extract the JSDoc/docstring comment preceding a given line.
+ * JS/TS: scan backwards for JSDoc block comments or consecutive // comment lines
+ * Python: look for a """...""" docstring on the line after the symbol definition
  */
 export function extractLeadingDoc(lines, lineNum, ext) {
   if (ext === ".py") {
@@ -139,12 +140,12 @@ export function extractLeadingDoc(lines, lineNum, ext) {
   return text.length > 0 && text.length < 300 ? text : ""
 }
 
-/** 将控制权交还给事件循环一个 tick（让键盘输入有机会被处理） */
+/** Yield control to the event loop for one tick (allows keyboard input to be processed) */
 export function yieldTick() {
   return new Promise((r) => setTimeout(r, 0))
 }
 
-/** 单文件入索引：删除旧块 → 分块 → 插入新块 */
+/** Index a single file: delete old chunks → chunk → insert new chunks */
 export function _upsertCodeFile(memory, origin, rel, lines, lang, mtimeMs) {
   const chunks = chunkCode(lines, rel)
   memory.db.exec("BEGIN")
@@ -166,8 +167,8 @@ export function _upsertCodeFile(memory, origin, rel, lines, lang, mtimeMs) {
 }
 
 /**
- * 按 ## 标题切分 markdown 文件。每个 ## section 独立入索引，
- * 标题路径做 heading（如 "README.md > 部署 > Docker"），方便检索定位。
+ * Split a markdown file by ## headings. Each ## section is indexed independently,
+ * with the heading path as the heading label (e.g. "README.md > Deployment > Docker") for easy retrieval.
  */
 export function chunkMarkdown(lines, filepath) {
   const chunks = []
@@ -190,6 +191,7 @@ export function chunkMarkdown(lines, filepath) {
   return chunks.filter((c) => c.content)
 }
 
+/** Upsert a documentation file's chunks into the doc_chunks table within a transaction */
 export function _upsertDocFile(memory, origin, rel, lines, mtimeMs) {
   const chunks = chunkMarkdown(lines, rel)
   const lang = rel.endsWith(".rst") ? "rst" : rel.endsWith(".adoc") ? "asciidoc" : rel.endsWith(".txt") ? "text" : "markdown"

package/src/memory/code-sync.mjs

@@ -1,18 +1,22 @@
 /**
- * memory/code-sync.mjs — 代码索引同步、检索、增量更新
+ * memory/code-sync.mjs — code index sync, retrieval, incremental update
  */
 
 import { readFile, stat } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { CODE_EXTS, DOC_EXTS, SKIP_DIRS } from "./schema.mjs"
-import { buildFtsQuery, ensureEmbeddings } from "./core.mjs"
+import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { detectLanguage, _upsertCodeFile, _upsertDocFile, yieldTick } from "./code-index.mjs"
 
+const DIFF_FULL_SYNC_THRESHOLD = 200
+const CODE_EMBED_BATCH = 64
+
 /**
- * git 驱动增量索引：用 git diff 找出上次索引以来的变更文件，
- * 只重建这些文件的 FTS5 块（不碰向量）。比全量 mtime 扫描快一个数量级。
- * 返回 { updated, removed, skipped } 或 null（git 不可用）。
+ * git-driven incremental indexing: use git diff to find files changed since
+ * the last index, and only rebuild FTS5 chunks for those files (vectors are untouched).
+ * An order of magnitude faster than full mtime scanning.
+ * Returns { updated, removed, skipped } or null (git unavailable).
  */
 export async function gitSync(memory, dir, { onProgress } = {}) {
   const { execSync, execFileSync } = await import("node:child_process")
@@ -34,8 +38,8 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
     return null
   }
 
-  if (diffOut.length > 200) {
-    // diff 太大，增量没意义——回退全量同步并更新锚点
+  if (diffOut.length > DIFF_FULL_SYNC_THRESHOLD) {
+    // diff too large, incremental is useless — fall back to full sync and update anchor
     await codeSync(memory, dir, { onProgress })
     const { docSync } = await import("./docs.mjs")
     await docSync(memory, dir, { onProgress })
@@ -60,11 +64,11 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
       if (CODE_EXTS.has(ext)) {
         const lang = detectLanguage(abs)
         let mtimeMs = 0
-        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* 新文件 */ }
+        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* new file */ }
         _upsertCodeFile(memory, dir, rel, lines, lang, mtimeMs)
       } else {
         let mtimeMs = 0
-        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* 新文件 */ }
+        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* new file */ }
         _upsertDocFile(memory, dir, rel, lines, mtimeMs)
       }
       updated++
@@ -94,8 +98,8 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
 }
 
 /**
- * 同步代码索引：扫描 dir 下所有源文件 → 分块 → upsert 到 code_chunks。
- * 按 mtime 增量——只重建变更过的文件块。
+ * Sync code index: scan all source files under dir → chunk → upsert into code_chunks.
+ * Incremental by mtime — only rebuilds chunks for files that have changed.
  */
 export async function codeSync(memory, dir, { onProgress } = {}) {
   const files = []
@@ -165,19 +169,19 @@ export async function codeSync(memory, dir, { onProgress } = {}) {
   return { updated, removed, skipped, failed, errors, total: files.length }
 }
 
-/** 记录当前 HEAD 作为索引锚点（gitSync 增量 diff 基准）；非 git 仓库静默跳过 */
+/** Record current HEAD as the index anchor (gitSync incremental diff baseline); silently skip non-git repos */
 export async function markIndexedCommit(memory, dir) {
   try {
     const { execSync } = await import("node:child_process")
     const head = execSync("git rev-parse HEAD", { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim()
     memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('last_indexed_commit', ?)
       ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(head)
-  } catch { /* 非 git 仓库或 git 不可用，跳过 */ }
+  } catch { /* not a git repo or git unavailable, skip */ }
 }
 
 /**
- * 代码检索：FTS5(BM25) + 可选向量余弦，RRF 合并。
- * 无 embedder 时退化为纯 FTS；ftsQuery 为空且有 embedder 时退化为纯向量。
+ * Code search: FTS5(BM25) + optional vector cosine, RRF merged.
+ * Falls back to pure FTS when no embedder; falls back to pure vector when ftsQuery is empty and embedder is present.
  */
 export async function codeSearch(memory, query, { limit = 5 } = {}) {
   const ftsQuery = buildFtsQuery(query)
@@ -219,14 +223,20 @@ export async function codeSearch(memory, query, { limit = 5 } = {}) {
   const fetchChunk = memory.db.prepare(`
     SELECT path, language, symbol_name, content, line_start, line_end FROM code_chunks WHERE rowid = ?
   `)
-  return [...scores.entries()]
+  const sorted = [...scores.entries()]
     .sort((a, b) => b[1] - a[1])
     .slice(0, limit)
-    .map(([rowid]) => fetchChunk.get(rowid))
+  return sorted
+    .map(([rowid, score]) => {
+      const chunk = fetchChunk.get(rowid)
+      if (!chunk) return null
+      chunk._score = Math.round(score * 100) / 100
+      return chunk
+    })
     .filter(Boolean)
 }
 
-/** 惰性补算 code_chunks 缺失的向量 */
+/** Lazily backfill missing vectors for code_chunks */
 export async function ensureCodeEmbeddings(memory) {
   if (!memory.embedder) return
   const modelKey = memory.embedder.model
@@ -237,17 +247,17 @@ export async function ensureCodeEmbeddings(memory) {
       ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(modelKey)
   }
 
-  const pending = memory.db.prepare(`SELECT rowid, path, symbol_name, content FROM code_chunks WHERE embedding IS NULL LIMIT 64`).all()
+  const pending = memory.db.prepare(`SELECT rowid, path, symbol_name, content FROM code_chunks WHERE embedding IS NULL LIMIT ${CODE_EMBED_BATCH}`).all()
   if (pending.length === 0) return
 
-  const texts = pending.map((r) => `${r.path}${r.symbol_name ? " :: " + r.symbol_name : ""}\n${r.content.slice(0, 2000)}`)
+  const texts = pending.map((r) => `${r.path}${r.symbol_name ? " :: " + r.symbol_name : ""}\n${r.content.slice(0, EMBED_TEXT_MAX_LEN)}`)
   const vecs = await embed(memory.embedder, texts)
 
   const update = memory.db.prepare(`UPDATE code_chunks SET embedding = ? WHERE rowid = ?`)
   pending.forEach((r, i) => update.run(toBlob(vecs[i]), r.rowid))
 }
 
-/** 生成 code_search 工具（只读）。 */
+/** Generate the code_search tool (read-only). */
 export function codeSearchTool(memory) {
   return {
     name: "code_search",
@@ -266,14 +276,14 @@ export function codeSearchTool(memory) {
       const results = await codeSearch(memory, args.query, { limit: args.limit ?? 5 })
       if (results.length === 0) return "(no matching code)"
       return results.map((r) =>
-        `${r.path}${r.symbol_name ? ` :: ${r.symbol_name}` : ""} (L${r.line_start}-L${r.line_end}):\n${r.content.slice(0, 2000)}`
+        `${r.path}${r.symbol_name ? ` :: ${r.symbol_name}` : ""} (L${r.line_start}-L${r.line_end}, relevance ${r._score?.toFixed(2) ?? "?"}):\n${r.content.slice(0, 2000)}`
       ).join("\n\n---\n\n")
     },
   }
 }
 
 /**
- * 单文件增量重索引：write/edit/delete 后调用，只重建这一条路径。
+ * Single-file incremental reindex: called after write/edit/delete, only rebuilds this one path.
  */
 export async function reindexFile(memory, cwd, absPath) {
   const ext = absPath.slice(absPath.lastIndexOf(".")).toLowerCase()
@@ -293,14 +303,14 @@ export async function reindexFile(memory, cwd, absPath) {
   if (CODE_EXTS.has(ext)) {
     const lang = detectLanguage(absPath)
     let mtimeMs = 0
-    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* 新文件 */ }
+    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertCodeFile(memory, cwd, rel, lines, lang, mtimeMs)
   } else if (DOC_EXTS.has(ext)) {
     let mtimeMs = 0
-    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* 新文件 */ }
+    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertDocFile(memory, cwd, rel, lines, mtimeMs)
   }
   if (memory.embedder) {
-    try { await ensureEmbeddings(memory) } catch { /* embedding 失败不阻塞 */ }
+    try { await ensureEmbeddings(memory) } catch { /* embedding failure is non-blocking */ }
   }
 }