@kk-irving/knowledge-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * knowledge-mcp-server v1.0.0
+ *
+ * 本地三源知识库（Zmind PR / Gerrit changes / Confluence pages）：
+ *   - SQLite + FTS5 全文索引
+ *   - BGE-small-zh ONNX 嵌入（@xenova/transformers）+ Float32Array BLOB 列存向量
+ *   - vector / fts / hybrid 三模式跨源融合检索
+ *
+ * 工具：
+ *   1. sync_zmind        — 拉 Zmind issues 到本地（增量水位）
+ *   2. sync_gerrit       — 拉 Gerrit changes 到本地（双通道认证）
+ *   3. sync_confluence   — 拉 Confluence pages 到本地（cookie 认证）
+ *   4. embed_pending     — 给未嵌入或已过期的行批量计算嵌入
+ *   5. search_local      — 单源/跨源 vector|fts|hybrid 检索
+ *   6. get_indexed       — 取本地索引完整记录
+ *
+ * 数据库：默认 ./data/knowledge.db（KNOWLEDGE_DB_PATH 可覆盖）
+ * 模型：默认 Xenova/bge-small-zh-v1.5（首次启动自动下载到 ./data/models/）
+ *
+ * 凭据复用：
+ *   - Zmind: ZMIND_URL + ZMIND_API_KEY
+ *   - Gerrit: GERRIT_URL + (GERRIT_AUTH_HEADER + GERRIT_COOKIE) 或 (GERRIT_USERNAME + GERRIT_HTTP_PASSWORD)
+ *   - Confluence: CONFLUENCE_BASE_URL + CONFLUENCE_COOKIE
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { config } from "./config.js";
+import { syncZmind } from "./sources/zmind-sync.js";
+import { syncGerrit } from "./sources/gerrit-sync.js";
+import { syncConfluence } from "./sources/confluence-sync.js";
+import { embedPending } from "./embed-pending.js";
+import { searchLocal, getIndexed } from "./search.js";
+import { getDb } from "./db.js";
+import { indexAospModule, clearAospIndex } from "./aosp/indexer.js";
+import { searchAosp } from "./aosp/search.js";
+import { embedAospPending } from "./aosp/embed-aosp.js";
+import { listModulesOfPlatform, loadModuleMap } from "./aosp/module-map-loader.js";
+import { analyzeIssue } from "./analyze-issue.js";
+const server = new McpServer({ name: "knowledge-mcp-server", version: "1.0.0" });
+// =============================================================================
+// 错误统一包装
+// =============================================================================
+function asJsonText(value) {
+    return JSON.stringify(value, null, 2);
+}
+function wrap(handler) {
+    return async () => {
+        try {
+            const result = await handler();
+            return { content: [{ type: "text", text: asJsonText(result) }] };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: asJsonText({ error: msg }),
+                    },
+                ],
+            };
+        }
+    };
+}
+// =============================================================================
+// 工具注册
+// =============================================================================
+server.tool("sync_zmind", "增量同步 Zmind issues 到本地 SQLite。默认按 sync_state 的 last_full_sync 水位增量拉取，未配置时全量从最新开始按 updated_on 降序拉。", {
+    since: z.string().optional().describe("(可选) 仅同步 updated_on >= since 的 issues，YYYY-MM-DD"),
+    limit: z.number().int().min(1).max(50000).default(1000).describe("最大同步条数"),
+    statusId: z.string().optional().describe("(可选) 状态过滤；默认 '*' 全部"),
+}, ({ since, limit, statusId }) => wrap(() => syncZmind({ since, limit, statusId }))());
+server.tool("sync_gerrit", "增量同步 Gerrit changes 到本地 SQLite。使用 v1.1 双通道认证。可指定 query 与 project 缩小范围。", {
+    query: z.string().optional().describe("(可选) Gerrit 原生 query 表达式（拼接到 query 后）"),
+    project: z.string().optional().describe("(可选) project 过滤"),
+    since: z.string().optional().describe("(可选) after:\"YYYY-MM-DD\" 增量水位；未传则用 sync_state"),
+    limit: z.number().int().min(1).max(50000).default(1000).describe("最大同步条数"),
+}, ({ query, project, since, limit }) => wrap(() => syncGerrit({ query, project, since, limit }))());
+server.tool("sync_confluence", "增量同步 Confluence pages 到本地 SQLite。space 不传时遍历所有 global 空间；HTML 自动转纯文本入库。", {
+    space: z.string().optional().describe("(可选) 空间 key（CSV 多个，如 'TVENG,DOC'）；未传则全空间"),
+    since: z.string().optional().describe("(可选) lastmodified > since（YYYY-MM-DD HH:MM）"),
+    limit: z.number().int().min(1).max(50000).default(1000).describe("最大同步条数"),
+}, ({ space, since, limit }) => wrap(() => syncConfluence({ space, since, limit }))());
+server.tool("embed_pending", "批量为未嵌入或嵌入过期（embedding_updated_at < updated）的行计算向量并回写。完成后内存索引会失效，下次 search_local 自动重建。", {
+    source: z.enum(["zmind", "gerrit", "confluence"]).describe("数据源"),
+    batch_size: z.number().int().min(1).max(5000).default(200).describe("单次处理上限"),
+}, ({ source, batch_size }) => wrap(() => embedPending({ source, batch_size }))());
+server.tool("search_local", "本地索引混合检索。source='all' 跨三源并行返回 { zmind, gerrit, confluence } 各自 Top-K。mode='hybrid' 走向量+FTS5 合并去重，'vector' 纯语义，'fts' 纯关键词。返回每条命中的 source/id/title/url/snippet/score/match。", {
+    query: z.string().min(1).describe("查询字符串"),
+    source: z.enum(["zmind", "gerrit", "confluence", "all"]).default("all").describe("数据源；'all' 跨源"),
+    mode: z.enum(["vector", "fts", "hybrid"]).default("hybrid").describe("检索模式"),
+    limit: z.number().int().min(1).max(20).default(5).describe("每个源返回上限"),
+}, ({ query, source, mode, limit }) => wrap(() => searchLocal({ query, source, mode, limit }))());
+server.tool("get_indexed", "从本地索引读取单条记录的完整字段（不含嵌入向量）。", {
+    source: z.enum(["zmind", "gerrit", "confluence"]).describe("数据源"),
+    id: z.union([z.string(), z.number()]).describe("主键（zmind=数字 / gerrit=Change-Id / confluence=页面 id）"),
+}, ({ source, id }) => wrap(() => Promise.resolve(getIndexed({ source, id })))());
+// =============================================================================
+// P2: AOSP 模块级精搜
+// =============================================================================
+server.tool("list_aosp_modules", "列出 module-path-map 中某个平台已登记的全部模块名（来自 steering/module-path-map.md）。", {
+    platform: z.enum(["D4", "X5", "STB"]).describe("平台"),
+}, ({ platform }) => wrap(async () => {
+    const map = await loadModuleMap();
+    return {
+        platform,
+        modules: listModulesOfPlatform(map, platform),
+        source: map.source,
+        generated_at: map.generated_at,
+    };
+})());
+server.tool("index_aosp_module", "为指定平台的指定模块建立 chunk 索引：递归扫描 module_path 下源码，按函数/类边界切块，写入 aosp_chunks 表。完成后再调 embed_aosp_pending 计算向量。", {
+    platform: z.enum(["D4", "X5", "STB"]).describe("平台"),
+    module: z.string().min(1).describe("模块名（与 module-path-map 一致；用作过滤 key）"),
+    module_path: z.string().min(1).describe("模块根路径（相对 repo_root 或绝对）"),
+    repo_root: z.string().min(1).describe("AOSP 工作树根目录（绝对路径）"),
+}, ({ platform, module, module_path, repo_root }) => wrap(() => indexAospModule({ platform, module, module_path, repo_root }))());
+server.tool("embed_aosp_pending", "给 aosp_chunks 中未嵌入的行批量计算向量。批量大小默认 200；可按 platform / module 过滤分批跑大模块。", {
+    batch_size: z.number().int().min(1).max(5000).default(200).describe("单次处理上限"),
+    platform: z.enum(["D4", "X5", "STB"]).optional().describe("(可选) 仅处理某平台"),
+    module: z.string().optional().describe("(可选) 仅处理某模块"),
+}, ({ batch_size, platform, module }) => wrap(() => embedAospPending({ batch_size, platform, module }))());
+server.tool("search_aosp", "在 aosp_chunks 上做 vector / fts / hybrid 检索，可按 platform + module 过滤搜索域（自动从 module-path-map 翻译为路径前缀）。返回命中文件的相对路径、行号、symbol、snippet、score。", {
+    query: z.string().min(1).describe("查询字符串（支持中英文）"),
+    platform: z.enum(["D4", "X5", "STB"]).optional().describe("(可选) 平台过滤"),
+    module: z.string().optional().describe("(可选) 模块名（需与 platform 同时给）"),
+    module_path: z.string().optional().describe("(可选) 直接传路径前缀（绕过 module-map）"),
+    mode: z.enum(["vector", "fts", "hybrid"]).default("hybrid").describe("检索模式"),
+    limit: z.number().int().min(1).max(20).default(5).describe("返回上限"),
+}, ({ query, platform, module, module_path, mode, limit }) => wrap(() => searchAosp({ query, platform, module, module_path, mode, limit }))());
+server.tool("clear_aosp_index", "按 platform / module 删除 aosp_chunks 行（用于源码大改后重建）。两个参数都不传则清空整张表。", {
+    platform: z.enum(["D4", "X5", "STB"]).optional(),
+    module: z.string().optional(),
+}, ({ platform, module }) => wrap(() => Promise.resolve(clearAospIndex({ platform, module })))());
+// =============================================================================
+// P2: analyze_issue 端到端工作流
+// =============================================================================
+server.tool("analyze_issue", "一键 PR/Bug 端到端分析：拉 Zmind issue → 准备工作目录 → 提取关键词 → 三源 hybrid 检索 → 推断平台/模块 → (可选) AOSP 模块级精搜 → 渲染 analysis-context.md 落盘。返回 JSON 汇总，best-effort 模式（任何子步骤失败都继续）。", {
+    issue_id: z.number().int().positive().describe("Zmind issue ID"),
+    workspace_root: z.string().optional().describe("(可选) 工作目录根，最终路径 <root>/.workspace/issue-<id>/；默认 cwd"),
+    include_aosp: z.boolean().default(false).describe("是否启用 AOSP 模块级精搜（需先 index_aosp_module + embed_aosp_pending）"),
+    platform: z.enum(["D4", "X5", "STB"]).optional().describe("(可选) 强制指定平台；不传则从 issue/project 推断"),
+    per_source_limit: z.number().int().min(1).max(10).default(3).describe("单源命中上限"),
+}, ({ issue_id, workspace_root, include_aosp, platform, per_source_limit }) => wrap(() => analyzeIssue({ issue_id, workspace_root, include_aosp, platform, per_source_limit }))());
+// =============================================================================
+// 启动
+// =============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // 提前初始化 DB（让首次工具调用不带建表延迟）
+    try {
+        getDb();
+    }
+    catch (e) {
+        console.error(`[knowledge-mcp-server] DB 初始化失败: ${e.message}`);
+    }
+    console.error(`[knowledge-mcp-server v1.0.0] started — db=${config.dbPath}, model=${config.embeddingModelId} (dim=${config.embeddingDim}, threads=${config.embeddingThreads})`);
+}
+main().catch((err) => {
+    console.error("[knowledge-mcp-server] fatal error:", err);
+    process.exit(1);
+});

package/dist/search.js

@@ -0,0 +1,274 @@
+/**
+ * 检索：vector / fts / hybrid 三模式 + 单源/跨源。
+ */
+import { config, isSourceName } from "./config.js";
+import { getDb } from "./db.js";
+import { embedOne } from "./embedder.js";
+import { vectorTopK } from "./index-store.js";
+const ALL_SOURCES = ["zmind", "gerrit", "confluence"];
+function ftsSearch(source, query, limit) {
+    const db = getDb();
+    // 注意：FTS5 MATCH 需要把 query 中的特殊字符转义，否则会被当成查询语法
+    const safeQuery = escapeFts5(query);
+    if (source === "zmind") {
+        const rows = db
+            .prepare(`SELECT z.id AS _key,
+                bm25(zmind_issues_fts) AS bm,
+                z.subject AS title,
+                z.description AS body,
+                z.status, z.project_name, z.updated_on
+           FROM zmind_issues_fts
+           JOIN zmind_issues z ON z.id = zmind_issues_fts.rowid
+          WHERE zmind_issues_fts MATCH ?
+          ORDER BY bm
+          LIMIT ?`)
+            .all(safeQuery, limit);
+        return rows.map((r) => ({
+            key: r._key,
+            bm25: r.bm,
+            meta: {
+                source: "zmind",
+                id: r._key,
+                title: r.title ?? "",
+                url: zmindUrl(r._key),
+                snippet: snippet(r.body ?? "", config.snippetMaxChars),
+                status: r.status ?? "",
+                project: r.project_name ?? "",
+                updated: r.updated_on ?? "",
+            },
+        }));
+    }
+    if (source === "gerrit") {
+        const rows = db
+            .prepare(`SELECT g.change_id AS _key,
+                bm25(gerrit_changes_fts) AS bm,
+                g.subject AS title,
+                g.commit_message AS body,
+                g.project, g.number, g.status, g.updated
+           FROM gerrit_changes_fts
+           JOIN gerrit_changes g ON g.rowid = gerrit_changes_fts.rowid
+          WHERE gerrit_changes_fts MATCH ?
+          ORDER BY bm
+          LIMIT ?`)
+            .all(safeQuery, limit);
+        return rows.map((r) => ({
+            key: r._key,
+            bm25: r.bm,
+            meta: {
+                source: "gerrit",
+                id: r._key,
+                title: r.title ?? "",
+                url: gerritUrl(r.project, r.number),
+                snippet: snippet(r.body ?? "", config.snippetMaxChars),
+                status: r.status ?? "",
+                project: r.project ?? "",
+                updated: r.updated ?? "",
+                extra: { number: r.number },
+            },
+        }));
+    }
+    // confluence
+    const rows = db
+        .prepare(`SELECT c.id AS _key,
+              bm25(confluence_pages_fts) AS bm,
+              c.title,
+              c.body_text AS body,
+              c.space_key, c.webui, c.version, c.updated
+         FROM confluence_pages_fts
+         JOIN confluence_pages c ON c.rowid = confluence_pages_fts.rowid
+        WHERE confluence_pages_fts MATCH ?
+        ORDER BY bm
+        LIMIT ?`)
+        .all(safeQuery, limit);
+    return rows.map((r) => ({
+        key: r._key,
+        bm25: r.bm,
+        meta: {
+            source: "confluence",
+            id: r._key,
+            title: r.title ?? "",
+            url: confluenceUrl(r.webui),
+            snippet: snippet(r.body ?? "", config.snippetMaxChars),
+            space: r.space_key ?? "",
+            updated: r.updated ?? "",
+            extra: { version: r.version },
+        },
+    }));
+}
+// =============================================================================
+// Hybrid 合并
+// =============================================================================
+/** 把 BM25 分数 normalize 到 (0, 1]：bm25 越小越好（SQLite FTS5 约定为负数 / 越接近 0 越相似）。 */
+function normalizeFtsScore(bm25Values) {
+    const map = new Map();
+    if (bm25Values.length === 0)
+        return map;
+    // FTS5 默认 bm25 返回值越小越好（相似度越高），通常是负数
+    const min = Math.min(...bm25Values);
+    const max = Math.max(...bm25Values);
+    const span = max - min || 1;
+    bm25Values.forEach((v) => {
+        // map (min..max) → (1..0)
+        map.set(v, 1 - (v - min) / span);
+    });
+    return map;
+}
+async function searchOneSource(source, query, mode, limit) {
+    if (!query.trim())
+        return [];
+    let vectorHits = [];
+    let ftsHits = [];
+    if (mode === "vector" || mode === "hybrid") {
+        try {
+            const vec = await embedOne(query);
+            vectorHits = vectorTopK(source, vec, limit * 2);
+        }
+        catch (e) {
+            // 嵌入失败（模型未加载等）→ 在 hybrid 下降级为 fts only
+            if (mode === "vector")
+                throw e;
+        }
+    }
+    if (mode === "fts" || mode === "hybrid") {
+        try {
+            ftsHits = ftsSearch(source, query, limit * 2);
+        }
+        catch (e) {
+            if (mode === "fts")
+                throw e;
+        }
+    }
+    if (mode === "vector") {
+        return vectorHits
+            .slice(0, limit)
+            .map((h) => ({ ...h.meta, score: h.score, match: "vector" }));
+    }
+    if (mode === "fts") {
+        const norm = normalizeFtsScore(ftsHits.map((h) => h.bm25));
+        return ftsHits
+            .slice(0, limit)
+            .map((h) => ({
+            ...h.meta,
+            score: norm.get(h.bm25) ?? 0,
+            match: "fts",
+        }));
+    }
+    // hybrid：合并去重
+    const merged = new Map();
+    for (const h of vectorHits) {
+        const key = String(h.id) + "::" + h.meta.source;
+        merged.set(key, { ...h.meta, score: h.score, match: "vector" });
+    }
+    const norm = normalizeFtsScore(ftsHits.map((h) => h.bm25));
+    for (const h of ftsHits) {
+        const key = String(h.key) + "::" + h.meta.source;
+        const existed = merged.get(key);
+        const ftsScore = norm.get(h.bm25) ?? 0;
+        if (existed) {
+            // 同时命中：取最高分，标 both
+            const finalScore = Math.max(existed.score, ftsScore);
+            merged.set(key, { ...h.meta, score: finalScore, match: "both" });
+        }
+        else {
+            merged.set(key, { ...h.meta, score: ftsScore, match: "fts" });
+        }
+    }
+    return Array.from(merged.values())
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}
+// =============================================================================
+// 公共入口
+// =============================================================================
+export async function searchLocal(args) {
+    const limit = Math.max(1, Math.min(config.searchMaxLimit, args.limit ?? config.searchDefaultLimit));
+    const mode = args.mode ?? "hybrid";
+    const source = args.source ?? "all";
+    if (source === "all") {
+        const out = {};
+        await Promise.all(ALL_SOURCES.map(async (s) => {
+            try {
+                out[s] = await searchOneSource(s, args.query, mode, limit);
+            }
+            catch (e) {
+                out[s] = [];
+                out[s + "_error"] = e.message;
+            }
+        }));
+        return { source: "all", query: args.query, mode, ...out };
+    }
+    if (!isSourceName(source)) {
+        throw new Error(`unknown source: ${source}`);
+    }
+    const hits = await searchOneSource(source, args.query, mode, limit);
+    return { source, query: args.query, mode, hits };
+}
+// =============================================================================
+// FTS5 query 转义
+// =============================================================================
+function escapeFts5(q) {
+    // 把每个 token 用双引号包起来，让 FTS5 当 phrase 处理；同时用空格连接（OR 语义会被 default 处理）
+    // 简化版：保留中文/英文/数字 token，用空格分割
+    const tokens = q
+        .replace(/["']/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0)
+        return q;
+    return tokens.map((t) => `"${t}"`).join(" ");
+}
+export function getIndexed(args) {
+    const db = getDb();
+    if (args.source === "zmind") {
+        const r = db
+            .prepare("SELECT * FROM zmind_issues WHERE id = ?")
+            .get(typeof args.id === "string" ? parseInt(args.id, 10) : args.id);
+        if (!r)
+            return null;
+        delete r.embedding;
+        return { source: "zmind", id: args.id, data: r };
+    }
+    if (args.source === "gerrit") {
+        const r = db
+            .prepare("SELECT * FROM gerrit_changes WHERE change_id = ?")
+            .get(String(args.id));
+        if (!r)
+            return null;
+        delete r.embedding;
+        return { source: "gerrit", id: args.id, data: r };
+    }
+    const r = db
+        .prepare("SELECT * FROM confluence_pages WHERE id = ?")
+        .get(String(args.id));
+    if (!r)
+        return null;
+    delete r.embedding;
+    return { source: "confluence", id: args.id, data: r };
+}
+// =============================================================================
+// 辅助函数
+// =============================================================================
+function snippet(text, n) {
+    const clean = text.replace(/\s+/g, " ").trim();
+    if (clean.length <= n)
+        return clean;
+    return clean.slice(0, n).trimEnd() + "…";
+}
+function zmindUrl(id) {
+    const base = (process.env.ZMIND_URL ?? "https://zmind.whaletv.com").replace(/\/+$/, "");
+    return `${base}/issues/${id}`;
+}
+function gerritUrl(project, num) {
+    const base = (process.env.GERRIT_URL ?? "").replace(/\/+$/, "");
+    if (!base || !num)
+        return "";
+    return `${base}/c/${project}/+/${num}`;
+}
+function confluenceUrl(webui) {
+    if (!webui)
+        return "";
+    if (/^https?:\/\//i.test(webui))
+        return webui;
+    const base = (process.env.CONFLUENCE_BASE_URL ?? "").replace(/\/+$/, "");
+    return base ? base + webui : webui;
+}

package/dist/sources/confluence-sync.js

@@ -0,0 +1,180 @@
+/**
+ * Confluence 同步：拉 pages 写入本地 confluence_pages 表。
+ *
+ * 使用 cookie 认证（CONFLUENCE_BASE_URL + CONFLUENCE_COOKIE）。
+ * 走 GET /rest/api/content?spaceKey=...&type=page 分页拉取所有页面，HTML 转纯文本入库。
+ */
+import { getDb, getSyncState, setSyncState, runInTransaction } from "../db.js";
+const CONFLUENCE_BASE_URL = (process.env.CONFLUENCE_BASE_URL ?? "").replace(/\/+$/, "");
+const CONFLUENCE_COOKIE = (process.env.CONFLUENCE_COOKIE ?? "").trim();
+const CONFLUENCE_REQUEST_DELAY_MS = (() => {
+    const raw = (process.env.CONFLUENCE_REQUEST_DELAY_MS ?? "").trim();
+    if (!/^\d+$/.test(raw))
+        return 150;
+    return parseInt(raw, 10);
+})();
+async function confluenceGet(pathOrUrl, params) {
+    if (!CONFLUENCE_BASE_URL || !CONFLUENCE_COOKIE) {
+        throw new Error("缺少 Confluence 凭据：请配置 CONFLUENCE_BASE_URL + CONFLUENCE_COOKIE。运行 scripts/refresh-auth.* 自动生成。");
+    }
+    const url = new URL(pathOrUrl, CONFLUENCE_BASE_URL);
+    for (const [k, v] of Object.entries(params))
+        url.searchParams.set(k, String(v));
+    const res = await fetch(url.toString(), {
+        method: "GET",
+        headers: {
+            Accept: "application/json",
+            Cookie: CONFLUENCE_COOKIE,
+        },
+        redirect: "manual",
+    });
+    if (res.status === 302 || res.status === 303) {
+        throw new Error("Confluence 302 → /login.action：cookie 已过期。运行 scripts/refresh-auth.* 重新抓取。");
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`Confluence HTTP ${res.status}: ${text.slice(0, 300)}`);
+    }
+    return JSON.parse(text);
+}
+function stripHtml(html) {
+    if (!html)
+        return "";
+    let t = html.replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/gi, " ");
+    t = t.replace(/<[^>]+>/g, " ");
+    t = t
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/gi, "'")
+        .replace(/&apos;/gi, "'");
+    return t.replace(/\s+/g, " ").trim();
+}
+const UPSERT_SQL = `
+INSERT INTO confluence_pages (
+  id, space_key, title, body_text, version, webui, created, updated
+) VALUES (
+  @id, @space_key, @title, @body_text, @version, @webui, @created, @updated
+)
+ON CONFLICT(id) DO UPDATE SET
+  space_key = excluded.space_key,
+  title = excluded.title,
+  body_text = excluded.body_text,
+  version = excluded.version,
+  webui = excluded.webui,
+  created = excluded.created,
+  updated = excluded.updated
+`;
+async function listAllSpaces() {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < 50; i++) {
+        const data = await confluenceGet("/rest/api/space", {
+            type: "global",
+            start,
+            limit: 100,
+        });
+        const items = data.results ?? [];
+        for (const s of items)
+            if (s.key)
+                out.push(s.key);
+        if (items.length < 100)
+            break;
+        start += items.length;
+        await sleep(CONFLUENCE_REQUEST_DELAY_MS);
+    }
+    return out;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * 全量/增量同步 Confluence pages。
+ *
+ * @param args.space  仅同步指定空间（可重复传入多个空间用 CSV，如 "TVENG,DOC"）
+ * @param args.limit  最大同步条数（防一次性拉爆）。默认 1000
+ * @param args.since  仅同步 lastmodified > since 的页面（YYYY-MM-DD HH:MM）
+ */
+export async function syncConfluence(args = {}) {
+    const db = getDb();
+    const limit = Math.max(1, Math.min(50000, args.limit ?? 1000));
+    const stateSince = args.since ?? getSyncState("confluence", "last_full_sync") ?? "";
+    // 决定要同步的空间集合
+    let spaces;
+    if (args.space) {
+        spaces = args.space.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    }
+    else {
+        spaces = await listAllSpaces();
+    }
+    const upsert = db.prepare(UPSERT_SQL);
+    function upsertMany(rows) {
+        runInTransaction(db, () => {
+            for (const r of rows)
+                upsert.run(r);
+        });
+    }
+    let fetched = 0;
+    let upserted = 0;
+    const pageSize = 100;
+    for (const spaceKey of spaces) {
+        let start = 0;
+        while (fetched < limit) {
+            const remaining = limit - fetched;
+            const n = Math.min(pageSize, remaining);
+            let resp;
+            if (stateSince) {
+                // 走 CQL 增量
+                const cql = `space.key = "${spaceKey}" AND type = page AND lastmodified > "${stateSince}"`;
+                resp = await confluenceGet("/rest/api/content/search", {
+                    cql,
+                    start,
+                    limit: n,
+                    expand: "body.storage,version,space",
+                });
+            }
+            else {
+                resp = await confluenceGet("/rest/api/content", {
+                    spaceKey,
+                    type: "page",
+                    start,
+                    limit: n,
+                    expand: "body.storage,version,space",
+                });
+            }
+            const items = resp.results ?? [];
+            if (items.length === 0)
+                break;
+            const rows = items.map((p) => ({
+                id: String(p.id),
+                space_key: p.space?.key ?? spaceKey,
+                title: p.title ?? "",
+                body_text: stripHtml(p.body?.storage?.value),
+                version: p.version?.number ?? 0,
+                webui: p._links?.webui ?? "",
+                created: p.history?.createdDate ?? "",
+                updated: p.version?.when ?? "",
+            }));
+            upsertMany(rows);
+            fetched += items.length;
+            upserted += items.length;
+            start += items.length;
+            if (items.length < n)
+                break;
+            await sleep(CONFLUENCE_REQUEST_DELAY_MS);
+        }
+        if (fetched >= limit)
+            break;
+    }
+    const watermark = new Date().toISOString();
+    setSyncState("confluence", "last_full_sync", watermark);
+    return {
+        source: "confluence",
+        fetched,
+        upserted,
+        spaces: spaces.length,
+        watermark,
+    };
+}