thincoder 0.1.0

package/src/distill.mjs

@@ -0,0 +1,117 @@
+/**
+ * distill.mjs — 从会话中提取知识候选条目（双轨制的"自动轨"）
+ * 原则（已定）：手动触发、LLM 出候选、人工逐条确认后入库。
+ * 绝不做会话结束后的全自动沉淀。
+ */
+
+import { chat } from "./provider.mjs"
+import { put, putMarkdown } from "./memory.mjs"
+import { commitAndPush } from "./gitmem.mjs"
+
+const DISTILL_PROMPT = `你是知识提取器。阅读下面的 agent 工作会话记录，提取值得跨会话长期记住的知识。
+
+输出一个 JSON 数组（不要输出任何其他内容）：
+[
+  {
+    "type": "rule | knowledge | decision | pattern",
+    "title": "简短标题",
+    "content": "完整内容，自包含，脱离会话上下文也能看懂",
+    "tags": ["tag1", "tag2"],
+    "scope": "personal | project"
+  }
+]
+
+提取标准：
+- knowledge：项目的事实性知识（架构、部署、约定俗成的做法）
+- decision：会话中做出的技术决策及理由
+- pattern：调试经验、问题解法、可复用的工作模式
+- rule：编码规范类（谨慎！规范通常应由人手动撰写，只有会话中明确确立的才提取）
+- scope 判断：专属于当前项目的用 project；通用的或个人偏好用 personal
+
+不要提取：
+- 一次性的任务细节（"今天改了某个文件的某行"）
+- 会话中提到的临时状态（当前的 bug、进行中的工作）
+- 客套话和显而易见的事实
+
+如果没有值得提取的内容，输出 []
+如果会话太长，优先提取最后出现的、仍在生效的结论。
+
+会话记录：
+`
+
+/**
+ * 从会话记录提取候选条目。transcript: 纯文本会话记录。
+ * 返回 [{ type, title, content, tags, scope }]，解析失败返回 []
+ */
+export async function extractCandidates(provider, transcript) {
+  const res = await chat(provider, {
+    messages: [{ role: "user", content: DISTILL_PROMPT + transcript }],
+  })
+  const match = res.content.match(/\[[\s\S]*\]/)
+  if (!match) return []
+  try {
+    const parsed = JSON.parse(match[0])
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter((c) => c?.type && c?.title && c?.content)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 把 agent 的 OpenAI 格式 history 转成可读的会话记录文本。
+ */
+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)}`)
+    } 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}`)
+    } else {
+      lines.push(`[${m.role}] ${m.content ?? ""}`)
+    }
+  }
+  const text = lines.join("\n\n")
+  // 超长时保留头尾（最早的需求 + 最新的结论最重要）
+  if (text.length <= maxChars) return text
+  const half = Math.floor(maxChars / 2)
+  return text.slice(0, half) + "\n\n...[中间部分省略]...\n\n" + text.slice(-half)
+}
+
+/**
+ * 把确认的候选条目写入指定层。
+ * opts: { projectDir, team: { dir } | null, author }
+ * scope=team 需要 opts.team；project 需要 opts.projectDir。
+ * 返回写入结果描述。
+ */
+export async function saveCandidate(memory, candidate, opts = {}) {
+  const scope = candidate.scope ?? "personal"
+  const tags = Array.isArray(candidate.tags) ? candidate.tags : (candidate.tags ?? "").split(/\s+/).filter(Boolean)
+
+  if (scope === "personal") {
+    const id = await put(memory, { type: candidate.type, title: candidate.title, content: candidate.content, tags: tags.join(" ") })
+    return `personal#${id}`
+  }
+  if (scope === "project") {
+    if (!opts.projectDir) throw new Error("project scope unavailable")
+    const filename = await putMarkdown(memory, {
+      layer: "project", dir: opts.projectDir,
+      type: candidate.type, title: candidate.title, content: candidate.content,
+      tags, author: opts.author ?? "unknown",
+    })
+    return `project:${filename}`
+  }
+  if (scope === "team") {
+    if (!opts.team?.dir) throw new Error("team scope not configured")
+    const filename = await putMarkdown(memory, {
+      layer: "team", dir: opts.team.dir,
+      type: candidate.type, title: candidate.title, content: candidate.content,
+      tags, author: opts.author ?? "unknown",
+    })
+    await commitAndPush(opts.team.dir, filename, `memory: [${candidate.type}] ${candidate.title} (distilled)`)
+    return `team:${filename}`
+  }
+  throw new Error(`unknown scope: ${scope}`)
+}

package/src/embedding.mjs

@@ -0,0 +1,107 @@
+/**
+ * embedding.mjs — 向量嵌入
+ * OpenAI 兼容 /v1/embeddings（SiliconFlow bge-m3 / Ollama / OpenAI 均可），
+ * 复用 provider.mjs 的 fetch + 重试模式，零依赖。
+ * 向量在入库前归一化，之后点积即余弦相似度。
+ */
+
+import { RETRYABLE_STATUS } from "./provider.mjs"
+const MAX_RETRIES = 3
+const BATCH_SIZE = 32 // 单次请求的文本数上限（SiliconFlow 限制内）
+
+/** 创建 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")
+  return {
+    baseURL: config.baseURL.replace(/\/+$/, ""),
+    apiKey: config.apiKey,
+    model: config.model,
+  }
+}
+
+/**
+ * 批量嵌入。texts: string[] → Float32Array[]（已归一化）
+ * 自动分批，失败重试（指数退避）。
+ */
+export async function embed(embedder, texts, { signal } = {}) {
+  if (texts.length === 0) return []
+  const vectors = []
+  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)
+    // API 按 data[].embedding 返回，顺序与输入一致
+    for (const item of data.data) {
+      vectors.push(normalize(Float32Array.from(item.embedding)))
+    }
+  }
+  return vectors
+}
+
+/** 余弦相似度（输入均已归一化，点积即余弦） */
+export function cosine(a, b) {
+  let sum = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) sum += a[i] * b[i]
+  return sum
+}
+
+/** Float32Array → 可存 sqlite BLOB 的 Buffer */
+export function toBlob(vec) {
+  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength)
+}
+
+/** sqlite BLOB → Float32Array */
+export function fromBlob(buf) {
+  return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4)
+}
+
+// ---------------------------------------------------------------- 内部
+
+async function requestWithRetry(embedder, input, signal) {
+  let lastError
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0) await sleep(2 ** (attempt - 1) * 1000)
+
+    let response
+    try {
+      response = await fetch(`${embedder.baseURL}/embeddings`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${embedder.apiKey}`,
+        },
+        body: JSON.stringify({ model: embedder.model, input }),
+        signal,
+      })
+    } catch (error) {
+      if (error.name === "AbortError") throw error
+      lastError = error
+      continue
+    }
+
+    if (response.ok) return response.json()
+
+    const text = await response.text().catch(() => "")
+    const message = `Embedding API error ${response.status}: ${text}`
+    if (RETRYABLE_STATUS.has(response.status)) {
+      lastError = new Error(message)
+      continue
+    }
+    throw new Error(message)
+  }
+  throw lastError
+}
+
+function normalize(vec) {
+  let sum = 0
+  for (let i = 0; i < vec.length; i++) sum += vec[i] * vec[i]
+  const norm = Math.sqrt(sum) || 1
+  for (let i = 0; i < vec.length; i++) vec[i] /= norm
+  return vec
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/gitmem.mjs

@@ -0,0 +1,87 @@
+/**
+ * gitmem.mjs — Team 层记忆的 git 同步
+ * 全部通过 child_process 调系统 git，零依赖。
+ * 冲突策略（已定）：不同条目天然不冲突；真冲突时中止 rebase 保持仓库干净，
+ * 报带手动指引的错误——不做自动合并。
+ */
+
+import { execFile } from "node:child_process"
+import { existsSync } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { promisify } from "node:util"
+
+const execFileAsync = promisify(execFile)
+
+/** 在 dir 下执行 git，失败抛带 stderr 的错误 */
+async function git(dir, args) {
+  try {
+    const { stdout } = await execFileAsync("git", args, { cwd: dir, encoding: "utf8" })
+    return stdout.trim()
+  } catch (error) {
+    const detail = error.stderr?.trim() || error.message
+    const err = new Error(`git ${args.join(" ")} failed: ${detail}`)
+    err.gitError = true
+    err.stderr = detail
+    throw err
+  }
+}
+
+/** 团队仓库不存在则 clone。返回是否发生了 clone */
+export async function ensureClone({ repo, dir }) {
+  if (existsSync(join(dir, ".git"))) return false
+  await mkdir(dirname(dir), { recursive: true })
+  await git(dirname(dir), ["clone", repo, dir])
+  return true
+}
+
+/**
+ * 同步：pull --rebase。远端还是空仓库时直接跳过（首次使用前）。
+ * 冲突时中止 rebase（保持仓库干净）并抛带指引的错误。
+ * 返回 true=拉取成功（调用方随后 syncDir 重建索引）
+ */
+export async function pullTeam(dir) {
+  // 远端空仓库：没有可拉取的分支（ls-remote 无输出）
+  const refs = await git(dir, ["ls-remote", "--heads", "origin"])
+  if (!refs) return false
+
+  try {
+    await git(dir, ["pull", "--rebase"])
+    return true
+  } catch (error) {
+    if (await hasConflict(dir)) {
+      await git(dir, ["rebase", "--abort"]).catch(() => {})
+      throw new Error(
+        `团队记忆同步冲突：本地与远端修改了同一条目。\n` +
+        `请到 ${dir} 手动执行 git pull 解决冲突，然后重新运行 thincoder sync。\n` +
+        `（本地仓库已恢复到同步前状态，未丢失任何内容）`,
+      )
+    }
+    throw error
+  }
+}
+
+/**
+ * 提交并推送一个条目文件。push 被拒（远端有新提交）时 pull --rebase 后重试一次；
+ * rebase 冲突同样中止并报错。
+ */
+export async function commitAndPush(dir, filename, message) {
+  await git(dir, ["add", filename])
+  await git(dir, ["commit", "-m", message])
+  try {
+    await git(dir, ["push"])
+  } catch {
+    await pullTeam(dir) // 冲突时这里会抛出带指引的错误
+    await git(dir, ["push"])
+  }
+}
+
+/** 当前是否处于 rebase 冲突状态（存在未合并路径） */
+async function hasConflict(dir) {
+  try {
+    const out = await git(dir, ["status", "--porcelain"])
+    return out.split("\n").some((l) => l.startsWith("UU") || l.startsWith("AA") || l.startsWith("DD"))
+  } catch {
+    return false
+  }
+}

package/src/markdown.mjs

@@ -0,0 +1,99 @@
+/**
+ * markdown.mjs — 记忆条目的 markdown + frontmatter 格式
+ * 零依赖解析/序列化。条目格式见 ARCHITECTURE-v2.md。
+ */
+
+const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
+
+/**
+ * 解析 markdown 条目。
+ * → { meta: { type, title, tags, author, created, embedding? }, content }
+ * 无 frontmatter 或缺必要字段时抛错。
+ */
+export function parseEntry(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  if (!match) throw new Error("entry missing frontmatter (expected --- ... ---)")
+
+  const meta = parseFrontmatter(match[1])
+  const content = match[2].trim()
+
+  if (!VALID_TYPES.has(meta.type)) {
+    throw new Error(`invalid type "${meta.type}"; expected one of: ${[...VALID_TYPES].join(", ")}`)
+  }
+  if (!meta.title) throw new Error("frontmatter missing required field: title")
+
+  return {
+    meta: {
+      type: meta.type,
+      title: meta.title,
+      tags: Array.isArray(meta.tags) ? meta.tags : meta.tags ? [meta.tags] : [],
+      author: meta.author ?? "unknown",
+      created: meta.created ?? "",
+      ...(meta.embedding ? { embedding: meta.embedding } : {}),
+    },
+    content,
+  }
+}
+
+/**
+ * 序列化为 markdown 条目文本。
+ */
+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")
+  const tags = (meta.tags ?? []).map((t) => `${t}`).join(", ")
+  const lines = [
+    "---",
+    `type: ${meta.type}`,
+    `title: ${meta.title}`,
+    `tags: [${tags}]`,
+    `author: ${meta.author ?? "unknown"}`,
+    `created: ${meta.created ?? new Date().toISOString().slice(0, 10)}`,
+  ]
+  if (meta.embedding) lines.push(`embedding: ${meta.embedding}`)
+  lines.push("---", "", content.trim(), "")
+  return lines.join("\n")
+}
+
+/** 标题转文件名 slug：保留中英文数字，其余转连字符 */
+export function slugify(title) {
+  return title
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w一-鿿]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50) || "untitled"
+}
+
+/** 生成条目文件名：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`
+}
+
+// ---------------------------------------------------------------- 内部
+
+/**
+ * 极简 YAML 子集解析：只支持 `key: value` 和 `key: [a, b, c]`。
+ * 我们的 frontmatter 是自己生成的，不需要完整 YAML。
+ */
+function parseFrontmatter(text) {
+  const meta = {}
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/)
+    if (!m) continue
+    const [, key, raw] = m
+    const value = raw.trim()
+    if (value.startsWith("[") && value.endsWith("]")) {
+      meta[key] = value
+        .slice(1, -1)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    } else {
+      meta[key] = value
+    }
+  }
+  return meta
+}