thincoder 0.7.8 → 0.8.1

package/src/mcp.mjs

@@ -1,406 +1,17 @@
 /**
  * mcp.mjs — MCP (Model Context Protocol) client
- * 零依赖：stdio transport (spawn + JSON-RPC) + HTTP transport (fetch + SSE) + WebSocket transport (global WebSocket)。
  * config: { command, args?, name } 或 { url, name, headers? } 或 { wsUrl, name, headers? }
  */
-
-import { spawn } from "node:child_process"
-
-const INIT_TIMEOUT_MS = 30_000
-const CALL_TIMEOUT_MS = 120_000
-// 等 legacy SSE 首个 endpoint 事件的上限：legacy server 连接后立即发，实际几毫秒内到达
-const ENDPOINT_WAIT_MS = 5_000
-
-// ---- JSON-RPC helpers ----
-
-let nextRpcId = 0
-function rpcId() {
-  return String(++nextRpcId) // 自增：随机数可能碰撞串响应
-}
-
-// ---- stdio transport ----
-
-function stdioTransport(command, args) {
-  // Windows 上 npx 等命令是 .cmd，Node 不带 shell 拒 spawn（EINVAL）；
-  // shell:true 又触发 DEP0190 且不转义参数——显式走 cmd.exe 并自己加引号；
-  // windowsVerbatimArguments 防止 Node 把内层引号转义成 \"（cmd 不认，会把引号当字面量传下去）
-  const spawnOptions = { stdio: ["pipe", "pipe", "pipe"], windowsHide: true, env: { ...process.env } }
-  const child =
-    process.platform === "win32" && !/\.exe$/i.test(command)
-      ? spawn("cmd.exe", ["/d", "/s", "/c", [command, ...(args ?? [])].map(quoteArg).join(" ")], {
-          ...spawnOptions,
-          windowsVerbatimArguments: true,
-        })
-      : spawn(command, args ?? [], spawnOptions)
-
-  const pending = new Map()
-  const decoder = new TextDecoder() // 单一实例：跨 chunk 保留多字节 UTF-8 的中间状态
-  let buffer = ""
-  let stderrTail = "" // 诊断用：server 起不来时给用户一点线索
-  let spawnError = null
-  let closed = false
-
-  const failAll = (message) => {
-    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message } })
-    pending.clear()
-  }
-
-  child.stdout.on("data", (chunk) => {
-    // stream:true：多字节字符跨 chunk 拆分时暂存残片，等下一个 chunk 拼完整
-    buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true })
-    const lines = buffer.split("\n")
-    buffer = lines.pop() ?? ""
-    for (const line of lines) {
-      if (!line.trim()) continue
-      try {
-        const msg = JSON.parse(line)
-        const resolver = pending.get(msg.id)
-        if (resolver) {
-          pending.delete(msg.id)
-          resolver(msg)
-        }
-      } catch {
-        // 非 JSON 行忽略
-      }
-    }
-  })
-
-  child.stderr.on("data", (chunk) => {
-    stderrTail = (stderrTail + chunk.toString()).slice(-2000)
-  })
-
-  // stdin 写错误（EPIPE 等）：没有这个监听，error 事件会崩掉整个进程；close 事件统一兜底
-  child.stdin.on("error", () => {})
-
-  // spawn 失败（命令不存在/EINVAL）：没有这个监听，error 事件会崩掉整个进程
-  child.on("error", (error) => {
-    spawnError = error
-    closed = true
-    failAll(`spawn failed: ${error.message}`)
-  })
-
-  child.on("close", () => {
-    closed = true
-    const lastLine = stderrTail.trim().split("\n").pop()
-    failAll(`Connection closed${lastLine ? ` | stderr: ${lastLine}` : ""}`)
-  })
-
-  const send = (method, params) => {
-    if (spawnError) return Promise.resolve({ id: null, error: { code: -32000, message: `spawn failed: ${spawnError.message}` } })
-    if (closed) return Promise.reject(new Error("MCP connection closed"))
-    const id = rpcId()
-    const promise = new Promise((resolve) => pending.set(id, resolve))
-    try {
-      child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n")
-    } catch (error) {
-      pending.delete(id)
-      return Promise.resolve({ id: null, error: { code: -32000, message: `stdin write failed: ${error.message}` } })
-    }
-    return withTimeout(promise, CALL_TIMEOUT_MS).finally(() => pending.delete(id))
-  }
-
-  // notification：无 id，不期待响应（协议要求）
-  const notify = (method, params) => {
-    if (closed) return
-    try {
-      child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n")
-    } catch { /* 忽略：close 事件会兜底 */ }
-  }
-
-  return { send, notify, close: () => { if (!closed) child.kill() } }
-}
-
-// ---- HTTP + SSE transport (Streamable HTTP) ----
-
-function httpTransport(baseURL, extraHeaders = {}) {
-  const url = baseURL.replace(/\/+$/, "")
-  let sessionId = null
-  let closed = false
-  let eventSource = null
-  let abortController = null
-  // legacy SSE (2024-11-05)：POST 地址由 server 的 endpoint 事件告知；
-  // Streamable HTTP (2025-03-26)：POST 到配置的 URL 本身
-  let postUrl = url
-  // 收到 endpoint 事件才置真：legacy SSE (2024-11-05) 模式，POST 只回 202，响应经 SSE 流推回；
-  // 否则按 Streamable HTTP (2025-03-26)：响应就在 POST 自身（即使 server 同时支持 GET 推送）
-  let legacySSE = false
-
-  const headers = () => {
-    const h = { "Content-Type": "application/json", Accept: "text/event-stream, application/json", ...extraHeaders }
-    if (sessionId) h["Mcp-Session-Id"] = sessionId
-    return h
-  }
-
-  const pending = new Map()
-
-  // SSE 解析器：从 response body 逐行读，处理 data: / event: / 空行(dispatch)
-  async function* parseSSE(response) {
-    const reader = response.body.getReader()
-    const decoder = new TextDecoder()
-    let buf = ""
-    let current = { data: "", event: "message" }
-    try {
-      while (true) {
-        const { done, value } = await reader.read()
-        if (done) break
-        buf += decoder.decode(value, { stream: true })
-        const lines = buf.split("\n")
-        buf = lines.pop() ?? ""
-        for (const raw of lines) {
-          const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw
-          if (line === "") {
-            if (current.data) {
-              yield { event: current.event, data: current.data.trimEnd() }
-              current = { data: "", event: "message" }
-            }
-          } else if (line.startsWith("data:")) {
-            current.data += (current.data ? "\n" : "") + line.slice(5).replace(/^ /, "")
-          } else if (line.startsWith("event:")) {
-            current.event = line.slice(6).trim()
-          }
-        }
-      }
-    } finally {
-      reader.releaseLock()
-    }
-  }
-
-  // 打开 SSE 长连接（legacy SSE transport，用于接收服务端推送）
-  // 按 2024-11-05 规范：GET 配置的 URL 本身，server 的第一个 endpoint 事件告知 POST 地址
-  async function openSSE() {
-    if (closed) return
-    abortController?.abort()
-    abortController = new AbortController()
-    const resp = await fetch(url, {
-      method: "GET",
-      headers: { Accept: "text/event-stream", ...extraHeaders },
-      signal: abortController.signal,
-    })
-    if (!resp.ok) throw new Error(`SSE connect failed: HTTP ${resp.status}`)
-    eventSource = parseSSE(resp)
-    let endpointReady
-    const gotEndpoint = new Promise((resolve) => { endpointReady = resolve })
-
-    // 后台消费 SSE 事件并分发到 pending
-    ;(async () => {
-      try {
-        for await (const { event, data } of eventSource) {
-          if (closed) break
-          if (event === "endpoint") {
-            // data 是相对/绝对 URI，拼到配置的 URL 上作为 POST 地址
-            postUrl = new URL(data.trim(), url).href
-            legacySSE = true
-            endpointReady()
-            continue
-          }
-          try {
-            const msg = JSON.parse(data)
-            const resolver = pending.get(msg.id)
-            if (resolver) {
-              pending.delete(msg.id)
-              resolver(msg)
-            }
-            // 没有 pending resolver 的可能是通知，忽略
-          } catch { /* 非 JSON，忽略 */ }
-        }
-      } catch (error) {
-        if (!closed) {
-          for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message: `SSE error: ${error.message}` } })
-          pending.clear()
-        }
-      }
-    })()
-
-    // 等 endpoint 事件再发请求（2024-11-05 要求拿到 POST 地址后才能 POST）；
-    // 超时说明不是 legacy server——Streamable HTTP 的 GET 流只推服务端消息，响应走 POST 自身
-    const wait = new Promise((resolve) => {
-      const t = setTimeout(resolve, ENDPOINT_WAIT_MS)
-      t.unref?.()
-    })
-    await Promise.race([gotEndpoint, wait])
-  }
-
-  // POST JSON-RPC 请求，同时监听响应
-  async function postRequest(method, params) {
-    const id = rpcId()
-    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params })
-
-    // legacy SSE：POST 只回 202，服务器经 SSE 流推回响应
-    if (legacySSE) {
-      return new Promise((resolve) => {
-        pending.set(id, resolve)
-        fetch(postUrl, { method: "POST", headers: headers(), body, signal: AbortSignal.timeout(CALL_TIMEOUT_MS) })
-          .then((resp) => {
-            // 2024-11-05：POST 期望 202 Accepted；其他错误码说明请求没送达
-            if (!resp.ok) {
-              pending.delete(id)
-              resolve({ id, error: { code: -32000, message: `POST failed: HTTP ${resp.status}` } })
-            }
-          })
-          .catch((e) => {
-            pending.delete(id)
-            resolve({ id, error: { code: -32000, message: `POST failed: ${e.message}` } })
-          })
-        // 兜底清理：响应超时（send 外层 withTimeout 先赢）时 pending 不留尸
-      }).finally(() => pending.delete(id))
-    }
-
-    // Streamable HTTP（无 SSE，或 GET 流只推服务端消息）：响应就在 POST 自身
-    const resp = await fetch(postUrl, {
-      method: "POST",
-      headers: headers(),
-      body,
-      signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
-    })
-    if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
-
-    const ct = resp.headers.get("content-type") ?? ""
-    const newSessionId = resp.headers.get("Mcp-Session-Id")
-    if (newSessionId) sessionId = newSessionId
-
-    if (ct.includes("text/event-stream")) {
-      // 服务器返回 SSE：第一个事件是响应
-      const sse = parseSSE(resp)
-      for await (const { data } of sse) {
-        try {
-          const msg = JSON.parse(data)
-          if (msg.id === id) return msg
-          // 可能是通知
-        } catch { /* skip */ }
-      }
-      return { id, error: { code: -32000, message: "No JSON-RPC response in SSE stream" } }
-    }
-
-    // 纯 JSON 响应
-    return resp.json()
-  }
-
-  const send = async (method, params) => withTimeout(postRequest(method, params), CALL_TIMEOUT_MS)
-
-  // notification：无 id，不期待响应（协议要求）
-  const notify = (method, params) => {
-    fetch(postUrl, {
-      method: "POST",
-      headers: headers(),
-      body: JSON.stringify({ jsonrpc: "2.0", method, params }),
-      signal: AbortSignal.timeout(10_000),
-    }).catch(() => {})
-  }
-
-  const close = () => {
-    closed = true
-    abortController?.abort()
-    // Streamable HTTP 规范：有 session 时发 DELETE 让 server 释放会话（尽力而为）
-    if (sessionId) {
-      fetch(postUrl, {
-        method: "DELETE",
-        headers: { "Mcp-Session-Id": sessionId, ...extraHeaders },
-        signal: AbortSignal.timeout(5_000),
-      }).catch(() => {})
-      sessionId = null
-    }
-    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message: "Connection closed" } })
-    pending.clear()
-  }
-
-  return { send, notify, close, openSSE, url, headers: extraHeaders }
-}
-
-// ---- WebSocket transport ----
-
-function wsTransport(wsUrl, extraHeaders = {}) {
-  const pending = new Map()
-  let closed = false
-  let ws = null
-
-  const failAll = (message) => {
-    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message } })
-    pending.clear()
-  }
-
-  const connect = () => {
-    if (closed) throw new Error("MCP WebSocket connection closed")
-    // WebSocket API 不支持自定义 header，token 走 query param
-    // （不能把 "Bearer ..." 当子协议传——含空格，违反 Sec-WebSocket-Protocol token 规则会抛 SyntaxError）
-    ws = new WebSocket(withAuthToken(wsUrl, extraHeaders.Authorization))
-
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        ws.close()
-        reject(new Error(`WebSocket connect timeout: ${wsUrl}`))
-      }, INIT_TIMEOUT_MS)
-
-      ws.addEventListener("open", () => {
-        clearTimeout(timeout)
-        resolve()
-      })
-
-      ws.addEventListener("message", (event) => {
-        try {
-          const msg = JSON.parse(event.data.toString())
-          const resolver = pending.get(msg.id)
-          if (resolver) {
-            pending.delete(msg.id)
-            resolver(msg)
-          }
-          // 没有 resolver 的是通知，忽略
-        } catch { /* 非 JSON，忽略 */ }
-      })
-
-      ws.addEventListener("error", (event) => {
-        clearTimeout(timeout)
-        closed = true
-        const errMsg = event.message || "WebSocket error"
-        if (pending.size > 0) {
-          failAll(errMsg)
-        } else {
-          reject(new Error(errMsg))
-        }
-      })
-
-      ws.addEventListener("close", () => {
-        clearTimeout(timeout)
-        closed = true
-        failAll("WebSocket closed")
-      })
-    })
-  }
-
-  const send = (method, params) => {
-    if (closed) return Promise.reject(new Error("MCP WebSocket connection closed"))
-    const id = rpcId()
-    const promise = new Promise((resolve) => pending.set(id, resolve))
-    try {
-      ws.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }))
-    } catch (error) {
-      // 非 OPEN 状态 send 会同步抛；close 事件随后统一兜底
-      pending.delete(id)
-      return Promise.resolve({ id: null, error: { code: -32000, message: `ws send failed: ${error.message}` } })
-    }
-    return withTimeout(promise, CALL_TIMEOUT_MS).finally(() => pending.delete(id))
-  }
-
-  const notify = (method, params) => {
-    if (!closed && ws?.readyState === WebSocket.OPEN) {
-      ws.send(JSON.stringify({ jsonrpc: "2.0", method, params }))
-    }
-  }
-
-  const close = () => {
-    closed = true
-    failAll("Connection closed")
-    try { ws?.close() } catch { /* 忽略 */ }
-  }
-
-  return { send, notify, close, connect }
-}
+import { INIT_TIMEOUT_MS, withTimeout, sanitizeToolName } from "./mcp/helpers.mjs"
+import { stdioTransport } from "./mcp/transport-stdio.mjs"
+import { httpTransport } from "./mcp/transport-http.mjs"
+import { wsTransport } from "./mcp/transport-ws.mjs"
 
 // ---- MCP lifecycle ----
 
 function buildTools(mcpTools, transport, config) {
   const prefix = config.name ? `${config.name}_` : "mcp_"
   return mcpTools.map((t) => ({
-    // 组合名整体 sanitize + 截断：prefix 也要计入 64 字符上限
     name: sanitizeToolName(prefix + t.name),
     description: t.description ?? `MCP tool: ${t.name}`,
     parameters: t.inputSchema ?? { type: "object", properties: {} },
@@ -435,11 +46,6 @@ async function doInitialize(transport, name) {
   return toolsResp.result?.tools ?? []
 }
 
-/**
- * 连接一个 MCP server。
- * stdio: { name, command, args? }
- * http:  { name, url, headers? }
- */
 export async function connectMcpServer(config) {
   if (config.wsUrl) {
     const transport = wsTransport(config.wsUrl, config.headers ?? {})
@@ -500,33 +106,3 @@ export function removeMcpTools(agent, serverName) {
   }
   agent.tools = keep
 }
-
-// ---- helpers ----
-
-/** 把 Authorization header 转成 ?token= query param（WebSocket 无法自定义 header） */
-function withAuthToken(wsUrl, authorization) {
-  if (!authorization) return wsUrl
-  const token = authorization.replace(/^Bearer\s+/i, "")
-  const u = new URL(wsUrl)
-  u.searchParams.set("token", token)
-  return u.href
-}
-
-function sanitizeToolName(name) {
-  return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64)
-}
-
-/** cmd.exe 参数加引号（含空格/引号时）。cmd 不认 \" 转义——内层引号必须翻倍 */
-function quoteArg(s) {
-  return /[\s"]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
-}
-
-function withTimeout(promise, ms) {
-  let timer
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms)
-    timer.unref?.() // 不拖住进程退出
-  })
-  // 竞速结束后清掉定时器，不留垃圾
-  return Promise.race([promise.finally(() => clearTimeout(timer)), timeout])
-}

package/src/memory/code-index.mjs

@@ -0,0 +1,211 @@
+/**
+ * memory/code-index.mjs — 代码和文档的分块、语言检测、符号提取
+ */
+
+import { segmentCJK, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./schema.mjs"
+
+/** 推断文件语言（按扩展名） */
+export function detectLanguage(filename) {
+  const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase()
+  const map = {
+    ".mjs": "javascript", ".js": "javascript", ".jsx": "jsx", ".ts": "typescript", ".tsx": "tsx",
+    ".py": "python", ".rs": "rust", ".go": "go", ".java": "java",
+    ".c": "c", ".h": "c", ".cpp": "cpp", ".hpp": "cpp",
+    ".rb": "ruby", ".swift": "swift", ".kt": "kotlin",
+    ".sh": "bash", ".bash": "bash", ".sql": "sql",
+    ".yaml": "yaml", ".yml": "yaml", ".toml": "toml", ".json": "json",
+    ".css": "css", ".html": "html", ".vue": "vue", ".svelte": "svelte",
+    ".md": "markdown", ".mdc": "markdown",
+  }
+  return map[ext] ?? ext.slice(1)
+}
+
+/**
+ * 用正则提取 JS/TS 文件的顶层符号声明（函数、类、const 导出等）。
+ * 返回 [{ name, line, kind }]。
+ */
+export function extractSymbols(lines, ext) {
+  const jsish = new Set([".mjs", ".js", ".ts", ".jsx", ".tsx"])
+  if (!jsish.has(ext)) return []
+
+  const symbols = []
+  const text = lines.join("\n")
+  const re = /(?:export\s+)?(?:(?:async\s+)?function\s+(\w+)|class\s+(\w+)|(?:export\s+)?(?:const|let|var)\s+(\w+))/gm
+  let m
+  while ((m = re.exec(text))) {
+    const name = m[1] || m[2] || m[3]
+    if (!name || name[0] !== name[0].toLowerCase() && name.length < 2) continue
+    const line = text.slice(0, m.index).split("\n").length
+    symbols.push({ name, line, kind: m[1] ? "function" : m[2] ? "class" : "variable" })
+  }
+  return symbols
+}
+
+/** 提取 Python 文件的顶层 def/class。 */
+export function extractPySymbols(lines) {
+  const symbols = []
+  const re = /^(?:async\s+)?(?:def|class)\s+(\w+)/gm
+  const text = lines.join("\n")
+  let m
+  while ((m = re.exec(text))) {
+    symbols.push({ name: m[1], line: text.slice(0, m.index).split("\n").length, kind: text[m.index] === "c" ? "class" : "function" })
+  }
+  return symbols
+}
+
+/**
+ * 将一个文件拆成代码块。小文件整文件一块；大文件按符号切分，符号间的内容并入前一个符号块。
+ * 每个块会额外带上符号前的 JSDoc / docstring 注释，提升搜索质量。
+ */
+export function chunkCode(lines, filepath) {
+  const ext = filepath.slice(filepath.lastIndexOf(".")).toLowerCase()
+  const chunks = []
+
+  if (lines.length <= BIG_FILE_LINES) {
+    const doc = extractLeadingDoc(lines, 1, ext)
+    const content = (doc ? doc + "\n" : "") + lines.join("\n").trimEnd()
+    chunks.push({ name: filepath, line_start: 1, line_end: lines.length, content })
+    return chunks
+  }
+
+  const symbols = ext === ".py" ? extractPySymbols(lines) : extractSymbols(lines, ext)
+  if (symbols.length <= 1) {
+    const doc = extractLeadingDoc(lines, 1, ext)
+    const content = (doc ? doc + "\n" : "") + lines.join("\n").trimEnd()
+    chunks.push({ name: filepath, line_start: 1, line_end: lines.length, content })
+    return chunks
+  }
+
+  for (let i = 0; i < symbols.length; i++) {
+    const sym = symbols[i]
+    const start = sym.line
+    const end = i + 1 < symbols.length ? symbols[i + 1].line - 1 : lines.length
+    if (start > end) continue
+    const doc = extractLeadingDoc(lines, start, ext)
+    const body = lines.slice(start - 1, end).join("\n").trimEnd()
+    const content = (doc ? doc + "\n" : "") + body
+    if (!content) continue
+    chunks.push({ name: `${filepath}:${sym.name}`, line_start: start, line_end: end, content })
+  }
+  return chunks
+}
+
+/**
+ * 提取指定行之前的 JSDoc / docstring 注释。
+ * JS/TS: 向前扫描 /** ... *​/ 或 // 连续注释行
+ * Python: 符号定义行的下一行开始找 """...""" docstring
+ */
+export function extractLeadingDoc(lines, lineNum, ext) {
+  if (ext === ".py") {
+    if (lineNum >= lines.length) return ""
+    const next = lines[lineNum]
+    const m = next?.match(/^\s*"""(.+?)"""\s*$/)
+    if (m) return m[1].trim()
+    if (/^\s*"""\s*$/.test(next)) {
+      const parts = []
+      for (let i = lineNum + 1; i < lines.length && i < lineNum + 8; i++) {
+        if (/^\s*"""\s*$/.test(lines[i])) break
+        parts.push(lines[i].trim())
+      }
+      const text = parts.join(" ").trim()
+      return text.length > 0 && text.length < 300 ? text : ""
+    }
+    return ""
+  }
+
+  const jsish = new Set([".mjs", ".js", ".ts", ".jsx", ".tsx"])
+  if (!jsish.has(ext)) return ""
+
+  const parts = []
+  let i = lineNum - 2
+  if (i >= 0 && /^\s*\*\/\s*$/.test(lines[i])) {
+    while (i >= 0) {
+      const line = lines[i].trim()
+      if (/^\s*\/\*\*/.test(line)) {
+        parts.unshift(line.replace(/^\s*\/\*\*\s*/, "").replace(/\s*\*\/\s*$/, "").trim())
+        break
+      }
+      parts.unshift(line.replace(/^\s*\*\s?/, "").trim())
+      i--
+    }
+  } else {
+    while (i >= 0 && /^\s*\/\//.test(lines[i])) {
+      parts.unshift(lines[i].replace(/^\s*\/\/\s*/, "").trim())
+      i--
+    }
+  }
+
+  const text = parts.join(" ").trim()
+  return text.length > 0 && text.length < 300 ? text : ""
+}
+
+/** 将控制权交还给事件循环一个 tick（让键盘输入有机会被处理） */
+export function yieldTick() {
+  return new Promise((r) => setTimeout(r, 0))
+}
+
+/** 单文件入索引：删除旧块 → 分块 → 插入新块 */
+export function _upsertCodeFile(memory, origin, rel, lines, lang, mtimeMs) {
+  const chunks = chunkCode(lines, rel)
+  memory.db.exec("BEGIN")
+  try {
+    memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(origin, rel)
+    const insert = memory.db.prepare(`
+      INSERT INTO code_chunks (origin, path, language, chunk_type, symbol_name, content, line_start, line_end, mtime_ms, seg_content)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+    for (const c of chunks) {
+      const isFile = c.name === rel
+      insert.run(origin, rel, lang, isFile ? "file" : "symbol", isFile ? "" : c.name.slice(rel.length + 1), c.content, c.line_start, c.line_end, mtimeMs, segmentCJK(c.content))
+    }
+    memory.db.exec("COMMIT")
+  } catch (e) {
+    memory.db.exec("ROLLBACK")
+    throw e
+  }
+}
+
+/**
+ * 按 ## 标题切分 markdown 文件。每个 ## section 独立入索引，
+ * 标题路径做 heading（如 "README.md > 部署 > Docker"），方便检索定位。
+ */
+export function chunkMarkdown(lines, filepath) {
+  const chunks = []
+  let start = 1
+  let heading = filepath
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{1,4})\s+(.+)/)
+    if (m) {
+      if (i > start) {
+        chunks.push({ heading, line_start: start, line_end: i, content: lines.slice(start - 1, i).join("\n").trimEnd() })
+      }
+      heading = `${filepath} > ${m[2].trim()}`
+      start = i + 1
+    }
+  }
+  if (start <= lines.length) {
+    chunks.push({ heading, line_start: start, line_end: lines.length, content: lines.slice(start - 1).join("\n").trimEnd() })
+  }
+  return chunks.filter((c) => c.content)
+}
+
+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"
+  memory.db.exec("BEGIN")
+  try {
+    memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(origin, rel)
+    const insert = memory.db.prepare(`
+      INSERT INTO doc_chunks (origin, path, language, heading, content, line_start, line_end, mtime_ms, seg_content)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+    for (const c of chunks) {
+      insert.run(origin, rel, lang, c.heading, c.content, c.line_start, c.line_end, mtimeMs, segmentCJK(c.content))
+    }
+    memory.db.exec("COMMIT")
+  } catch (e) {
+    memory.db.exec("ROLLBACK")
+    throw e
+  }
+}