agent-remnote 0.0.1 → 0.1.0

package/dist/packages/mcp/src/tools/getRemConnections.js

@@ -0,0 +1,566 @@
+import { z } from "zod";
+import { buildGuidedResponse, parseOrThrow, withResolvedDatabase, safeJsonParse } from "./shared.js";
+import { executeListRemReferences, listRemReferencesSchema, } from "./listRemReferences.js";
+import { executeFindRemsByReference } from "./findRemsByReference.js";
+import { TIME_RANGE_PATTERN, timeValueSchema } from "./timeFilters.js";
+const inputShape = {
+    id: listRemReferencesSchema.shape.id.describe("起始 Rem ID"),
+    dbPath: z.string().optional().describe("数据库文件路径（默认自动发现）"),
+    includeDescendants: z
+        .boolean()
+        .optional()
+        .describe("是否将起始 Rem 的子树也纳入锚点（默认 false）"),
+    maxDepth: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .optional()
+        .describe("展开起始 Rem 子树的最大深度（默认 0）"),
+    includeOccurrences: z.boolean().optional().describe("是否包含逐次出现的明细（默认 false）"),
+    resolveText: z.boolean().optional().describe("是否解析文本摘要（默认 true）"),
+    inboundMaxDepth: z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe("入站多跳的最大深度（默认 1）"),
+    outboundMaxDepth: z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe("出站多跳的最大深度（默认 1）"),
+    inboundMaxCandidates: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("入站候选上限（默认 200）"),
+    // 可选分页与图输出控制
+    outboundLimit: z
+        .number()
+        .int()
+        .min(1)
+        .max(2000)
+        .optional()
+        .describe("出站结果上限（默认 2000）"),
+    outboundOffset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("出站结果偏移量"),
+    inboundGraph: z
+        .boolean()
+        .optional()
+        .describe("是否输出入站多跳图（默认 false）"),
+    inboundGraphMode: z
+        .enum(["auto", "sql", "scan"]).optional().describe("入站图计算模式（默认 auto）"),
+    inboundLimit: z
+        .number()
+        .int()
+        .min(1)
+        .max(2000)
+        .optional()
+        .describe("入站图结果上限（默认 2000）"),
+    inboundOffset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("入站图结果偏移量"),
+    inboundScanLimit: z
+        .number()
+        .int()
+        .min(1000)
+        .max(200000)
+        .optional()
+        .describe("入站扫描模式的扫描上限（默认 50k-200k 区间）"),
+    // 时间过滤（仅在入站图中生效；SQL/scan 两路径均尽力筛选）
+    timeRange: z
+        .union([
+        z.literal("all"),
+        z.literal("*"),
+        z.string().regex(TIME_RANGE_PATTERN, "timeRange 需形如 '30d'、'2w'、'12h'")
+    ])
+        .optional()
+        .describe("时间范围（如 30d/2w/12h 或 all/*）"),
+    createdAfter: timeValueSchema.optional().describe("创建时间下界（ISO/毫秒/秒）"),
+    createdBefore: timeValueSchema.optional().describe("创建时间上界（ISO/毫秒/秒）"),
+    updatedAfter: timeValueSchema.optional().describe("更新时间下界（ISO/毫秒/秒）"),
+    updatedBefore: timeValueSchema.optional().describe("更新时间上界（ISO/毫秒/秒）"),
+};
+export const getRemConnectionsSchema = z.object(inputShape);
+export async function executeGetRemConnections(params) {
+    const parsed = parseOrThrow(getRemConnectionsSchema, params, { label: "get_rem_connections" });
+    const { payload: referencePayload, suggestions: baseSuggestions } = await executeListRemReferences({
+        id: parsed.id,
+        dbPath: parsed.dbPath,
+        includeDescendants: parsed.includeDescendants,
+        maxDepth: parsed.maxDepth,
+        includeOccurrences: parsed.includeOccurrences,
+        resolveText: parsed.resolveText,
+        includeInbound: true,
+        inboundMaxDepth: parsed.inboundMaxDepth,
+        inboundMaxCandidates: parsed.inboundMaxCandidates,
+    });
+    const outbound = referencePayload.references ?? [];
+    const inbound = referencePayload.inbound ?? [];
+    // 可选：扩展“出站多跳”（基于引用边，最多 3 层）。
+    let outboundExpanded;
+    const outboundMaxDepth = params.outboundMaxDepth ?? 1;
+    if (outboundMaxDepth > 1) {
+        try {
+            const res = await computeOutboundBfs({
+                dbPath: parsed.dbPath,
+                startIds: [parsed.id],
+                outboundMaxDepth,
+                includeDescendants: parsed.includeDescendants ?? false,
+                sourceTreeDepth: parsed.maxDepth ?? 0,
+                limit: params.outboundLimit,
+                offset: params.outboundOffset,
+            });
+            outboundExpanded = res;
+        }
+        catch (_) { }
+    }
+    // 可选：入站多跳图形输出（SQL/SCAN 双实现；auto 优先 SQL，必要时回退扫描）。
+    let inboundGraph;
+    const enableInboundGraph = params.inboundGraph === true;
+    if (enableInboundGraph) {
+        try {
+            const mode = params.inboundGraphMode || 'auto';
+            if (mode === 'sql' || mode === 'auto') {
+                const sqlRes = await computeInboundGraphSql({
+                    dbPath: parsed.dbPath,
+                    startIds: [parsed.id],
+                    inboundMaxDepth: parsed.inboundMaxDepth ?? 1,
+                    includeDescendants: parsed.includeDescendants ?? false,
+                    sourceTreeDepth: parsed.maxDepth ?? 0,
+                    limit: params.inboundLimit,
+                    offset: params.inboundOffset,
+                    timeRange: params.timeRange,
+                    createdAfter: params.createdAfter,
+                    createdBefore: params.createdBefore,
+                    updatedAfter: params.updatedAfter,
+                    updatedBefore: params.updatedBefore,
+                });
+                inboundGraph = sqlRes;
+                if (mode === 'auto') {
+                    const directInboundCount = inbound.length;
+                    const tooFew = (inboundGraph?.count ?? 0) === 0 && directInboundCount > 0;
+                    if (tooFew) {
+                        const scanRes = await computeInboundGraphScan({
+                            dbPath: parsed.dbPath,
+                            startIds: [parsed.id],
+                            inboundMaxDepth: parsed.inboundMaxDepth ?? 1,
+                            includeDescendants: parsed.includeDescendants ?? false,
+                            sourceTreeDepth: parsed.maxDepth ?? 0,
+                            limit: params.inboundLimit,
+                            offset: params.inboundOffset,
+                            scanLimit: params.inboundScanLimit,
+                            timeRange: params.timeRange,
+                            createdAfter: params.createdAfter,
+                            createdBefore: params.createdBefore,
+                            updatedAfter: params.updatedAfter,
+                            updatedBefore: params.updatedBefore,
+                        });
+                        inboundGraph = scanRes;
+                    }
+                }
+            }
+            else {
+                const scanRes = await computeInboundGraphScan({
+                    dbPath: parsed.dbPath,
+                    startIds: [parsed.id],
+                    inboundMaxDepth: parsed.inboundMaxDepth ?? 1,
+                    includeDescendants: parsed.includeDescendants ?? false,
+                    sourceTreeDepth: parsed.maxDepth ?? 0,
+                    limit: params.inboundLimit,
+                    offset: params.inboundOffset,
+                    scanLimit: params.inboundScanLimit,
+                    timeRange: params.timeRange,
+                    createdAfter: params.createdAfter,
+                    createdBefore: params.createdBefore,
+                    updatedAfter: params.updatedAfter,
+                    updatedBefore: params.updatedBefore,
+                });
+                inboundGraph = scanRes;
+            }
+        }
+        catch (_) { }
+    }
+    const guidance = outbound.length + inbound.length > 0
+        ? `已整理 Rem ${referencePayload.remId} 的连接情况：出站 ${outbound.length} 项，入站 ${inbound.length} 项。`
+        : `未找到 Rem ${referencePayload.remId} 的出站或入站引用。`;
+    const payload = {
+        ...referencePayload,
+        guidance,
+        outbound,
+        inbound,
+        outboundCount: outbound.length,
+        inboundCount: inbound.length,
+        outboundExpandedDepth: outboundExpanded?.depthApplied ?? 1,
+        outboundExpandedCount: outboundExpanded?.count ?? 0,
+        outboundExpandedNodes: outboundExpanded?.nodes ?? [],
+        outboundExpandedEdges: outboundExpanded?.edges ?? [],
+        inboundGraphDepth: inboundGraph?.depthApplied ?? undefined,
+        inboundGraphCount: inboundGraph?.count ?? 0,
+        inboundGraphNodes: inboundGraph?.nodes ?? [],
+        inboundGraphEdges: inboundGraph?.edges ?? [],
+    };
+    const suggestions = [...baseSuggestions];
+    if (outbound.length > 0) {
+        pushSuggestion(suggestions, "查看出站引用详情：可继续使用 outline_rem_subtree id=<refId> 或 inspect_rem_doc");
+    }
+    if (payload.outboundExpandedCount > 0) {
+        pushSuggestion(suggestions, `已启用出站多跳（深度 ${payload.outboundExpandedDepth}）。需要更广范围可将 outboundMaxDepth 调至 ${payload.outboundExpandedDepth < 3 ? payload.outboundExpandedDepth + 1 : 3}`);
+    }
+    else if (outboundMaxDepth > 1) {
+        pushSuggestion(suggestions, "未发现多跳出站引用，可尝试提高 outboundMaxDepth 或扩大锚点（includeDescendants=true）");
+    }
+    if (enableInboundGraph) {
+        if (payload.inboundGraphCount > 0) {
+            pushSuggestion(suggestions, `已启用入站多跳图（深度 ${payload.inboundGraphDepth}）。可调整 inboundLimit/offset 分页查看更多`);
+        }
+        else {
+            pushSuggestion(suggestions, "未发现入站多跳结果，可尝试提高 inboundMaxDepth 或扩大锚点（includeDescendants=true）");
+        }
+    }
+    if (inbound.length > 0) {
+        pushSuggestion(suggestions, "查看入站引用上下文：可对 inbound.remId 调用 outline_rem_subtree includeEmpty=true");
+    }
+    return buildGuidedResponse(payload, suggestions);
+}
+// --- Internal helpers (outbound BFS) ---
+async function computeOutboundBfs(args) {
+    const { result } = await withResolvedDatabase(args.dbPath, (db) => {
+        const start = new Set(args.startIds);
+        if (args.includeDescendants && args.sourceTreeDepth > 0) {
+            for (const id of expandDescendants(db, args.startIds, args.sourceTreeDepth))
+                start.add(id);
+        }
+        const visited = new Set(start);
+        const nodes = new Map();
+        const edges = [];
+        let depth = 1;
+        let frontier = new Set(start);
+        const limit = Math.max(1, Math.min(args.limit ?? 2000, 2000));
+        while (frontier.size > 0 && depth <= args.outboundMaxDepth && edges.length < limit) {
+            const next = new Set();
+            for (const fromId of frontier) {
+                const targets = getDirectOutboundRefs(db, fromId);
+                for (const toId of targets) {
+                    edges.push({ from: fromId, to: toId, depth });
+                    if (!visited.has(toId)) {
+                        visited.add(toId);
+                        next.add(toId);
+                        if (!nodes.has(toId))
+                            nodes.set(toId, { id: toId, depth, via: fromId });
+                    }
+                    if (edges.length >= limit)
+                        break;
+                }
+                if (edges.length >= limit)
+                    break;
+            }
+            if (edges.length >= limit)
+                break;
+            frontier = next;
+            depth += 1;
+        }
+        const all = Array.from(nodes.values());
+        const offset = Math.max(0, args.offset ?? 0);
+        const sliced = all.slice(offset, Math.min(offset + limit, all.length));
+        const details = enrichNodeDetails(db, sliced);
+        return {
+            nodes: details,
+            edges,
+            depthApplied: Math.min(depth - 1, args.outboundMaxDepth),
+            total: all.length,
+        };
+    });
+    return {
+        depthApplied: result.depthApplied,
+        nodes: result.nodes,
+        count: result.nodes.length,
+        edges: result.edges,
+    };
+}
+function expandDescendants(db, roots, maxDepth) {
+    if (!roots || roots.length === 0 || maxDepth <= 0)
+        return [];
+    const placeholders = roots.map(() => "?").join(",");
+    const sql = `WITH RECURSIVE tree(id, depth) AS (
+    SELECT _id, 0 FROM quanta WHERE _id IN (${placeholders})
+    UNION ALL
+    SELECT child._id, tree.depth + 1
+    FROM quanta child
+    JOIN tree ON json_extract(child.doc, '$.parent') = tree.id
+    WHERE tree.depth + 1 <= ?
+  )
+  SELECT id FROM tree WHERE depth > 0`;
+    const rows = db.prepare(sql).all(...roots, maxDepth);
+    return rows.map((r) => r.id);
+}
+function getDirectOutboundRefs(db, id) {
+    const row = db.prepare("SELECT doc FROM quanta WHERE _id = ?").get(id);
+    if (!row)
+        return new Set();
+    const doc = safeJsonParse(row.doc);
+    const refs = new Set();
+    if (!doc)
+        return refs;
+    collectReferences(doc.key, refs);
+    if (doc.value !== undefined)
+        collectReferences(doc.value, refs);
+    return refs;
+}
+function collectReferences(value, into) {
+    if (Array.isArray(value)) {
+        value.forEach((item) => collectReferences(item, into));
+        return;
+    }
+    if (value && typeof value === "object") {
+        const maybe = value;
+        if ((maybe.i === "q" || maybe.i === "p") && typeof maybe._id === "string") {
+            into.add(maybe._id);
+            return;
+        }
+        for (const child of Object.values(maybe))
+            collectReferences(child, into);
+    }
+}
+function enrichNodeDetails(db, nodes) {
+    if (nodes.length === 0)
+        return [];
+    const stmt = db.prepare(`SELECT
+      id,
+      json_extract(doc, '$.kt') AS plainText,
+      ancestor_not_ref_text AS ancestorText
+    FROM remsSearchInfos
+    WHERE id = ?`);
+    const fallback = db.prepare("SELECT doc FROM quanta WHERE _id = ?");
+    const out = [];
+    for (const n of nodes) {
+        let title = null;
+        let snippet = null;
+        let ancestor = null;
+        const info = stmt.get(n.id);
+        if (info) {
+            title = (info.plainText ?? '').trim() || null;
+            snippet = title;
+            ancestor = info.ancestorText ? info.ancestorText.trim() : null;
+        }
+        else {
+            const row = fallback.get(n.id);
+            if (row) {
+                const parsed = safeJsonParse(row.doc);
+                const rawKey = parsed?.key;
+                if (Array.isArray(rawKey)) {
+                    const text = rawKey
+                        .map((x) => (typeof x === 'string' ? x : ''))
+                        .join('')
+                        .replace(/\s+/g, ' ')
+                        .trim();
+                    if (text) {
+                        title = text;
+                        snippet = text;
+                    }
+                }
+            }
+        }
+        out.push({ ...n, title, snippet, ancestor });
+    }
+    return out;
+}
+// --- Internal helpers (inbound graph via direct JSON token scan) ---
+async function computeInboundGraphScan(args) {
+    const { result } = await withResolvedDatabase(args.dbPath, async (db) => {
+        const start = new Set(args.startIds);
+        if (args.includeDescendants && args.sourceTreeDepth > 0) {
+            for (const id of expandDescendants(db, args.startIds, args.sourceTreeDepth))
+                start.add(id);
+        }
+        const visited = new Set();
+        const edges = [];
+        const nodeMap = new Map();
+        let depth = 1;
+        let frontier = new Set(Array.from(start));
+        const limit = Math.max(1, Math.min(args.limit ?? 2000, 2000));
+        const scanLimit = Math.max(1000, Math.min(args.scanLimit ?? 50000, 200000));
+        while (frontier.size > 0 && depth <= args.inboundMaxDepth && edges.length < limit) {
+            const next = new Set();
+            for (const target of frontier) {
+                const sources = getDirectInboundRefs(db, target, scanLimit, {
+                    timeRange: args.timeRange,
+                    createdAfter: args.createdAfter,
+                    createdBefore: args.createdBefore,
+                    updatedAfter: args.updatedAfter,
+                    updatedBefore: args.updatedBefore,
+                });
+                for (const src of sources) {
+                    edges.push({ from: src, to: target, depth });
+                    if (!visited.has(src)) {
+                        visited.add(src);
+                        next.add(src);
+                        if (!nodeMap.has(src))
+                            nodeMap.set(src, { id: src, depth, via: target });
+                    }
+                    if (edges.length >= limit)
+                        break;
+                }
+                if (edges.length >= limit)
+                    break;
+            }
+            if (edges.length >= limit)
+                break;
+            frontier = next;
+            depth += 1;
+        }
+        const all = Array.from(nodeMap.values());
+        const offset = Math.max(0, args.offset ?? 0);
+        const sliced = all.slice(offset, Math.min(offset + limit, all.length));
+        const details = enrichNodeDetails(db, sliced);
+        return {
+            nodes: details,
+            edges,
+            depthApplied: Math.min(depth - 1, args.inboundMaxDepth),
+            total: all.length,
+        };
+    });
+    return {
+        depthApplied: result.depthApplied,
+        nodes: result.nodes,
+        count: result.nodes.length,
+        edges: result.edges,
+    };
+}
+function getDirectInboundRefs(db, targetId, scanLimit, filters) {
+    const out = new Set();
+    const needle = `"_id":"${targetId}"`;
+    try {
+        const stmt = db.prepare('SELECT _id, doc FROM quanta WHERE doc LIKE ? LIMIT ?');
+        for (const row of stmt.iterate(`%${needle}%`, scanLimit)) {
+            const doc = safeJsonParse(row.doc);
+            if (!doc)
+                continue;
+            if (!matchTimeFilters(doc, filters))
+                continue;
+            const refs = new Set();
+            collectReferences(doc.key, refs);
+            if (doc.value !== undefined)
+                collectReferences(doc.value, refs);
+            if (refs.has(targetId))
+                out.add(row._id);
+        }
+    }
+    catch (_) { }
+    return out;
+}
+function matchTimeFilters(doc, filters) {
+    if (!filters)
+        return true;
+    const created = pickTs(doc, ['createdAt', 'c', 'ct']);
+    const updated = pickTs(doc, ['m', 'lm', 'createdAt']);
+    const ca = normalizeMaybeTs(filters.createdAfter);
+    const cb = normalizeMaybeTs(filters.createdBefore);
+    const ua = normalizeMaybeTs(filters.updatedAfter);
+    const ub = normalizeMaybeTs(filters.updatedBefore);
+    if (ca != null && created != null && created < ca)
+        return false;
+    if (cb != null && created != null && created > cb)
+        return false;
+    if (ua != null && updated != null && updated < ua)
+        return false;
+    if (ub != null && updated != null && updated > ub)
+        return false;
+    return true;
+}
+function pickTs(obj, keys) {
+    for (const k of keys) {
+        const v = obj[k];
+        const n = typeof v === 'number' ? v : (typeof v === 'string' ? Number(v) : NaN);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return null;
+}
+function normalizeMaybeTs(v) {
+    if (v == null)
+        return null;
+    if (typeof v === 'number')
+        return v;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+// SQL 版入站图（性能好，准确性依赖索引/SQL 条件覆盖度）
+async function computeInboundGraphSql(args) {
+    const { result } = await withResolvedDatabase(args.dbPath, async (db) => {
+        const start = new Set(args.startIds);
+        if (args.includeDescendants && args.sourceTreeDepth > 0) {
+            for (const id of expandDescendants(db, args.startIds, args.sourceTreeDepth))
+                start.add(id);
+        }
+        const inbound = await executeFindRemsByReference({
+            targetIds: Array.from(start),
+            maxDepth: args.inboundMaxDepth,
+            limit: Math.max(1, Math.min(args.limit ?? 2000, 2000)),
+            offset: Math.max(0, args.offset ?? 0),
+            dbPath: args.dbPath,
+            detail: true,
+            timeRange: args.timeRange,
+            createdAfter: args.createdAfter,
+            createdBefore: args.createdBefore,
+            updatedAfter: args.updatedAfter,
+            updatedBefore: args.updatedBefore,
+        });
+        const nodes = inbound.matches.map((m) => ({
+            id: m.id,
+            depth: m.depth ?? 0,
+            via: Array.isArray(m.matchedTargets) && m.matchedTargets.length > 0 ? m.matchedTargets[0] : null,
+            title: m.title ?? null,
+            snippet: m.snippet ?? null,
+            ancestor: m.ancestor ?? null,
+        }));
+        const edges = [];
+        for (const m of inbound.matches) {
+            const tos = Array.isArray(m.matchedTargets) ? m.matchedTargets : [];
+            for (const t of tos)
+                edges.push({ from: m.id, to: t, depth: m.depth ?? 0 });
+        }
+        return {
+            nodes,
+            edges,
+            depthApplied: inbound.depthApplied,
+            total: inbound.totalCount,
+        };
+    });
+    return {
+        depthApplied: result.depthApplied,
+        nodes: result.nodes,
+        count: result.nodes.length,
+        edges: result.edges,
+    };
+}
+export function registerGetRemConnections(server) {
+    server.tool("get_rem_connections", `<usecase>同时查看某个 Rem 的出站引用和入站引用。</usecase>
+<instructions>
+- 默认只分析当前 Rem，可设 includeDescendants=true 扫描整棵子树。
+- inboundMaxDepth 控制反向引用的搜索层级（默认 1 层）。
+- outboundMaxDepth 可启用“出站多跳”（默认 1=仅直接出站，最大 3 层）。
+- 可选分页：outboundLimit/outboundOffset；入站图：inboundGraph=true 时返回 nodes/edges（可配 inboundLimit/offset）。
+- 结果将分别展示 outbound / inbound 列表，并在启用时补充出站/入站多跳图，便于顺藤摸瓜式追踪。
+- 入站图模式：inboundGraphMode=sql|scan|auto（默认 auto 优先 SQL，不足则回退扫描）；扫描上限 inboundScanLimit（默认 50000）。
+- 时间过滤（仅作用于入站图）：timeRange/createdAfter/createdBefore/updatedAfter/updatedBefore。
+</instructions>`, inputShape, async (input) => executeGetRemConnections(input));
+}
+function pushSuggestion(list, text) {
+    if (!list.includes(text)) {
+        list.push(text);
+    }
+}

package/dist/packages/mcp/src/tools/inspectRemDoc.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { buildGuidedResponse, summarizeKey, safeJsonParse, withResolvedDatabase, parseOrThrow, } from "./shared.js";
+const inputShape = {
+    id: z.string().min(1, "id 必填").describe("目标 Rem ID"),
+    dbPath: z.string().optional().describe("数据库文件路径（默认自动发现）"),
+    expandReferences: z
+        .boolean()
+        .optional()
+        .describe("是否展开引用文本，仅用于摘要（默认 false）"),
+    maxReferenceDepth: z
+        .number()
+        .int()
+        .min(0)
+        .max(5)
+        .optional()
+        .describe("引用展开最大深度（默认 1）"),
+};
+export const inspectRemDocSchema = z.object(inputShape);
+export async function executeInspectRemDoc(params) {
+    const parsed = parseOrThrow(inspectRemDocSchema, params, { label: "inspect_rem_doc" });
+    const expand = parsed.expandReferences ?? false;
+    const maxDepth = parsed.maxReferenceDepth ?? 1;
+    const { result, info } = await withResolvedDatabase(parsed.dbPath, async (db) => {
+        const row = db
+            .prepare("SELECT doc FROM quanta WHERE _id = ?")
+            .get(parsed.id);
+        if (!row) {
+            throw new Error(`未找到该 Rem（id=${parsed.id}），请确认 ID 是否存在于当前数据库`);
+        }
+        const doc = safeJsonParse(row.doc);
+        const keySummary = summarizeKey(doc?.key, db, { expand, maxDepth });
+        return {
+            id: parsed.id,
+            doc,
+            summary: {
+                text: keySummary.text,
+                references: keySummary.references,
+            },
+        };
+    });
+    return {
+        dbPath: info.dbPath,
+        resolution: info.source,
+        dirName: info.dirName,
+        ...result,
+    };
+}
+export function registerInspectRemDoc(server) {
+    server.tool("inspect_rem_doc", `<usecase>调试或深度分析 Rem 原始数据时使用。</usecase>
+<instructions>
+- 返回完整的 quanta.doc JSON，仅在确实需要底层字段时调用。
+- 如需可读大纲，请优先使用 outline_rem_subtree。
+</instructions>`, inputShape, async (input) => {
+        const parsed = parseOrThrow(inspectRemDocSchema, input, { label: "inspect_rem_doc" });
+        const result = await executeInspectRemDoc(parsed);
+        const guidance = `已获取 Rem ${result.id} 的原始 doc JSON。`;
+        const suggestions = ["如需可读内容，请改用 outline_rem_subtree 或 summarize_daily_notes"];
+        return buildGuidedResponse({ guidance, ...result }, suggestions);
+    });
+}

package/dist/packages/mcp/src/tools/listRemBackups.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import os from "os";
+import { discoverBackups, expandHome, makeToolResponse, parseOrThrow, REMNOTE_RELATIVE_DIR, } from "./shared.js";
+const inputShape = {
+    basePath: z
+        .string()
+        .optional()
+        .describe("RemNote 基础目录（默认 ~/remnote）"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("返回的备份条数上限（默认全部）"),
+};
+export const listRemBackupsSchema = z.object(inputShape);
+export async function executeListRemBackups(params) {
+    const parsed = parseOrThrow(listRemBackupsSchema, params, { label: "list_rem_backups" });
+    const basePath = expandHome(parsed.basePath ?? `${os.homedir()}/${REMNOTE_RELATIVE_DIR}`);
+    const backups = await discoverBackups(basePath);
+    const limit = parsed.limit ?? backups.length;
+    return {
+        basePath,
+        total: backups.length,
+        items: backups.slice(0, limit),
+    };
+}
+export function registerListRemBackups(server) {
+    server.tool("list_rem_backups", "List available remnote backups under ~/remnote/**/backups (newest first).", inputShape, async (input) => {
+        const parsed = parseOrThrow(listRemBackupsSchema, input, { label: "list_rem_backups" });
+        const result = await executeListRemBackups(parsed);
+        return makeToolResponse(result);
+    });
+}