agent-remnote 0.0.1 → 0.0.2

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

@@ -0,0 +1,447 @@
+import { z } from "zod";
+import { buildGuidedResponse, withResolvedDatabase, parseOrThrow, } from "./shared.js";
+import { TIME_RANGE_PATTERN, timeValueSchema, resolveTimeFilters, describeFilterSummary, } from "./timeFilters.js";
+import { createPreview, coalesceText } from "./searchUtils.js";
+const inputShape = {
+    targetIds: z
+        .array(z.string().min(1))
+        .min(1, "targetIds 至少包含 1 个元素")
+        .describe("目标锚点 Rem ID 列表（被引用的对象）"),
+    maxDepth: z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe("最大引用层级（默认 1，建议 ≤2）"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("返回条数上限（分页）"),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("分页偏移量"),
+    maxCandidates: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("候选上限（控制搜索规模，默认 200）"),
+    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/毫秒/秒）"),
+    autoExpandDepth: z
+        .boolean()
+        .optional()
+        .describe("未命中时自动逐级提高深度（默认 true）"),
+    maxAutoDepth: z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe("自动扩展深度上限（默认 3）"),
+    dbPath: z.string().optional().describe("数据库文件路径（默认自动发现）"),
+    detail: z.boolean().optional().describe("是否返回更详细字段（parentId/ancestorIds 等）"),
+};
+export const findRemsByReferenceSchema = z.object(inputShape);
+export async function executeFindRemsByReference(params) {
+    const parsed = parseOrThrow(findRemsByReferenceSchema, params, { label: "find_rems_by_reference" });
+    const limit = parsed.limit ?? 40;
+    const offset = parsed.offset ?? 0;
+    const requestedDepth = parsed.maxDepth ?? 1;
+    const autoExpand = parsed.autoExpandDepth ?? true;
+    const maxAutoDepth = parsed.maxAutoDepth ?? 3;
+    const depthCeiling = Math.min(Math.max(requestedDepth, maxAutoDepth), 3);
+    const maxCandidates = parsed.maxCandidates ?? 200;
+    const detail = parsed.detail ?? false;
+    const { filters, summary } = resolveTimeFilters(parsed);
+    const { result, info } = await withResolvedDatabase(parsed.dbPath, async (db) => {
+        let matches = new Map();
+        const depthAttempts = [];
+        let appliedDepth = requestedDepth;
+        for (let depth = requestedDepth; depth <= depthCeiling; depth++) {
+            depthAttempts.push(depth);
+            matches = collectReferenceMatches(db, {
+                targetIds: parsed.targetIds,
+                filters,
+                maxDepth: depth,
+                maxCandidates,
+            });
+            appliedDepth = depth;
+            if (matches.size > 0 || !autoExpand) {
+                break;
+            }
+        }
+        const all = Array.from(matches.values());
+        all.sort((a, b) => {
+            const diff = (b.updatedAt ?? 0) - (a.updatedAt ?? 0);
+            if (diff !== 0)
+                return diff;
+            return a.id.localeCompare(b.id);
+        });
+        const sliced = all.slice(offset, offset + limit);
+        const hasMore = offset + sliced.length < all.length;
+        const nextOffset = hasMore ? offset + sliced.length : null;
+        const snippetLength = 200;
+        const items = sliced.map((match) => {
+            const preview = createPreview(match.text, snippetLength);
+            const anchors = Array.from(match.anchors);
+            const sources = Array.from(match.sources);
+            return {
+                id: match.id,
+                title: preview.title,
+                snippet: preview.snippet,
+                truncated: preview.truncated,
+                parentId: match.parentId,
+                ancestor: match.ancestorText,
+                ancestorIds: match.ancestorIds?.split(/\s+/).filter(Boolean) ?? [],
+                matchedTargets: match.matchedTargetIds,
+                anchorIds: anchors,
+                sourceIds: sources,
+                depth: match.depth,
+                updatedAt: match.updatedAt,
+                createdAt: match.createdAt,
+            };
+        });
+        return {
+            items,
+            total: all.length,
+            hasMore,
+            nextOffset,
+            appliedDepth,
+            depthAttempts,
+        };
+    });
+    const guidance = result.total > 0
+        ? `共找到 ${result.total} 条引用匹配（${describeFilterSummary(summary) ?? "无额外筛选"}）。`
+        : `未找到符合条件的引用匹配（${describeFilterSummary(summary) ?? "无筛选"}）。`;
+    const matches = detail ? result.items : result.items.map((item) => simplifyMatch(item));
+    const referenceIndex = buildReferenceIndex(result.items);
+    return {
+        dbPath: info.dbPath,
+        resolution: info.source,
+        dirName: info.dirName,
+        targetIds: params.targetIds,
+        depthRequested: requestedDepth,
+        depthApplied: result.appliedDepth,
+        depthAttempts: result.depthAttempts,
+        autoExpandDepth: autoExpand,
+        depthLimit: depthCeiling,
+        maxCandidates,
+        limit,
+        offset,
+        hasMore: result.hasMore,
+        nextOffset: result.nextOffset,
+        totalCount: result.total,
+        filtersApplied: summary,
+        count: matches.length,
+        matches,
+        markdown: buildMatchesMarkdown(matches),
+        referenceIndex,
+        guidance,
+    };
+}
+export function registerFindRemsByReference(server) {
+    server.tool("find_rems_by_reference", `<usecase>查找引用指定 Rem 的节点，可探索隐性关联。</usecase>
+<instructions>
+- targetIds 允许一次传入多个锚点 Rem。
+- maxDepth 控制引用层级，默认仅检索直接引用；建议≤2 以避免过多结果。
+- 可结合 timeRange/updatedAfter 等参数限定时间窗口。
+- 如需进一步阅读结果，可继续使用 outline_rem_subtree 或 inspect_rem_doc。
+</instructions>`, inputShape, async (input) => {
+        const parsed = findRemsByReferenceSchema.parse(input);
+        const result = await executeFindRemsByReference(parsed);
+        return buildGuidedResponse(result, buildSuggestions({
+            total: result.totalCount,
+            hasMore: result.hasMore,
+            nextOffset: result.nextOffset,
+            depthApplied: result.depthApplied,
+            depthLimit: result.depthLimit,
+            autoExpand: result.autoExpandDepth,
+        }, parsed.targetIds));
+    });
+}
+function simplifyMatch(item) {
+    return {
+        id: item.id,
+        title: item.title,
+        snippet: item.snippet,
+        truncated: item.truncated,
+        ancestor: item.ancestor,
+        matchedTargets: item.matchedTargets ?? [],
+        anchorIds: item.anchorIds ?? [],
+        depth: item.depth ?? 0,
+    };
+}
+function buildMatchesMarkdown(matches) {
+    if (!matches || matches.length === 0) {
+        return "未找到引用匹配。";
+    }
+    const lines = ["# 引用匹配概览"];
+    matches.forEach((match, index) => {
+        const title = match.title?.trim() ? match.title.trim() : "(未命名)";
+        const ancestor = match.ancestor ? `，所在：${match.ancestor}` : "";
+        const targets = match.matchedTargets.length > 0 ? `，目标：${match.matchedTargets.join(", ")}` : "";
+        lines.push(`- **${index + 1}. ${title}**（ID: ${match.id}${ancestor}，深度 ${match.depth}${targets}）`);
+        if (match.snippet) {
+            lines.push(`  - ${match.snippet}`);
+        }
+    });
+    return lines.join("\n");
+}
+function buildReferenceIndex(matches) {
+    const index = new Map();
+    if (!Array.isArray(matches)) {
+        return {};
+    }
+    for (const match of matches) {
+        const sample = {
+            viaRemId: match.id,
+            viaRemTitle: match.title,
+            snippet: match.snippet,
+            depth: match.depth ?? 0,
+        };
+        const register = (id) => {
+            if (!id)
+                return;
+            const entry = index.get(id);
+            if (entry) {
+                entry.totalOccurrences += 1;
+                if (entry.samples.length < 5) {
+                    entry.samples.push(sample);
+                }
+            }
+            else {
+                index.set(id, {
+                    totalOccurrences: 1,
+                    samples: [sample],
+                });
+            }
+        };
+        for (const target of match.matchedTargets ?? []) {
+            register(target);
+        }
+        for (const anchor of match.anchorIds ?? []) {
+            register(anchor);
+        }
+    }
+    const result = {};
+    for (const [id, entry] of index.entries()) {
+        result[id] = entry;
+    }
+    return result;
+}
+function collectReferenceMatches(db, options) {
+    const visited = new Set(options.targetIds);
+    const anchorMap = new Map();
+    for (const id of options.targetIds) {
+        anchorMap.set(id, new Set([id]));
+    }
+    const results = new Map();
+    let depth = 1;
+    let frontier = new Set(options.targetIds);
+    while (frontier.size > 0 && depth <= options.maxDepth && results.size < options.maxCandidates) {
+        const targets = Array.from(frontier);
+        frontier = new Set();
+        const rows = queryDirectReferences(db, targets, options.filters);
+        for (const row of rows) {
+            if (row.id === undefined)
+                continue;
+            const sources = row.matchedTargetIds;
+            const anchorSets = sources.map((sourceId) => anchorMap.get(sourceId) ?? new Set([sourceId]));
+            const anchors = mergeSets(anchorSets);
+            const existing = results.get(row.id);
+            if (existing) {
+                existing.depth = Math.min(existing.depth, depth);
+                existing.anchors = mergeSets([existing.anchors, anchors]);
+                existing.sources = mergeSets([existing.sources, new Set(sources)]);
+                existing.matchedTargetIds = Array.from(new Set([...existing.matchedTargetIds, ...row.matchedTargetIds]));
+                existing.updatedAt = chooseLatest(existing.updatedAt, row.updatedAt);
+                existing.createdAt = chooseLatest(existing.createdAt, row.createdAt);
+            }
+            else {
+                results.set(row.id, {
+                    ...row,
+                    depth,
+                    anchors,
+                    sources: new Set(sources),
+                });
+            }
+            if (!visited.has(row.id)) {
+                visited.add(row.id);
+                frontier.add(row.id);
+                if (!anchorMap.has(row.id)) {
+                    anchorMap.set(row.id, anchors);
+                }
+                else {
+                    anchorMap.set(row.id, mergeSets([anchorMap.get(row.id) ?? new Set(), anchors]));
+                }
+            }
+            if (results.size >= options.maxCandidates) {
+                break;
+            }
+        }
+        if (results.size >= options.maxCandidates) {
+            break;
+        }
+        depth += 1;
+    }
+    return results;
+}
+function queryDirectReferences(db, targetIds, filters) {
+    if (targetIds.length === 0)
+        return [];
+    const targetsJson = JSON.stringify(targetIds);
+    const { clause, params } = buildQuantaTimeFilterClause(filters, "q");
+    const sql = `WITH targets AS (
+      SELECT value AS targetId FROM json_each(@targetsJson)
+    ),
+    refs AS (
+      SELECT
+        q._id AS id,
+        targets.targetId AS targetId,
+        CAST(json_extract(q.doc, '$.lm') AS INTEGER) AS updatedAt,
+        CAST(json_extract(q.doc, '$.ct') AS INTEGER) AS createdAt
+      FROM quanta q
+      JOIN targets
+      WHERE q._id != targets.targetId
+        AND json_valid(q.doc)
+        AND (
+          (
+            json_extract(q.doc, '$.key') IS NOT NULL
+            AND (
+              (instr(json_extract(q.doc, '$.key'), '"i":"q"') > 0 OR instr(json_extract(q.doc, '$.key'), '"i":"p"') > 0)
+              AND instr(json_extract(q.doc, '$.key'), '"_id":"' || targets.targetId || '"') > 0
+            )
+          )
+          OR (
+            json_type(json_extract(q.doc, '$.value')) IS NOT NULL
+            AND (
+              (instr(json_extract(q.doc, '$.value'), '"i":"q"') > 0 OR instr(json_extract(q.doc, '$.value'), '"i":"p"') > 0)
+              AND instr(json_extract(q.doc, '$.value'), '"_id":"' || targets.targetId || '"') > 0
+            )
+          )
+        )
+        ${clause ? `AND ${clause}` : ""}
+    )
+    SELECT
+      refs.id AS id,
+      json_extract(rsi.doc, '$.p') AS parentId,
+      rsi.ancestor_not_ref_text AS ancestorText,
+      rsi.ancestor_ids AS ancestorIds,
+      json_extract(rsi.doc, '$.kt') AS kt,
+      json_extract(rsi.doc, '$.ke') AS ke,
+      GROUP_CONCAT(DISTINCT refs.targetId) AS matchedTargetIds,
+      MAX(refs.updatedAt) AS updatedAt,
+      MAX(refs.createdAt) AS createdAt
+    FROM refs
+    JOIN remsSearchInfos rsi ON rsi.id = refs.id
+    GROUP BY refs.id`;
+    const rows = db
+        .prepare(sql)
+        .all({ targetsJson, ...params });
+    return rows.map((row) => ({
+        id: row.id,
+        parentId: row.parentId,
+        ancestorText: row.ancestorText,
+        ancestorIds: row.ancestorIds,
+        text: coalesceText(row.kt, row.ke),
+        matchedTargetIds: row.matchedTargetIds
+            ? row.matchedTargetIds.split(",").map((value) => value.trim()).filter(Boolean)
+            : [],
+        updatedAt: row.updatedAt,
+        createdAt: row.createdAt,
+    }));
+}
+function buildQuantaTimeFilterClause(filters, alias) {
+    const conditions = [];
+    const params = {};
+    const createdExpr = `COALESCE(
+    CAST(json_extract(${alias}.doc, '$.createdAt') AS INTEGER),
+    CAST(json_extract(${alias}.doc, '$.c') AS INTEGER)
+  )`;
+    const updatedExpr = `COALESCE(
+    CAST(json_extract(${alias}.doc, '$.m') AS INTEGER),
+    CAST(json_extract(${alias}.doc, '$.createdAt') AS INTEGER)
+  )`;
+    if (filters.createdAfter !== undefined) {
+        conditions.push(`${createdExpr} >= @createdAfter`);
+        params.createdAfter = filters.createdAfter;
+    }
+    if (filters.createdBefore !== undefined) {
+        conditions.push(`${createdExpr} <= @createdBefore`);
+        params.createdBefore = filters.createdBefore;
+    }
+    if (filters.updatedAfter !== undefined) {
+        conditions.push(`${updatedExpr} >= @updatedAfter`);
+        params.updatedAfter = filters.updatedAfter;
+    }
+    if (filters.updatedBefore !== undefined) {
+        conditions.push(`${updatedExpr} <= @updatedBefore`);
+        params.updatedBefore = filters.updatedBefore;
+    }
+    return {
+        clause: conditions.join(" AND "),
+        params,
+    };
+}
+function mergeSets(sets) {
+    const result = new Set();
+    for (const set of sets) {
+        if (!set)
+            continue;
+        for (const value of set) {
+            result.add(value);
+        }
+    }
+    return result;
+}
+function chooseLatest(current, incoming) {
+    if (incoming == null)
+        return current ?? null;
+    if (current == null)
+        return incoming;
+    return Math.max(current, incoming);
+}
+function buildSuggestions(result, targetIds) {
+    const suggestions = [];
+    if (result.hasMore && result.nextOffset != null) {
+        suggestions.push(`还有更多引用匹配，可再次调用 find_rems_by_reference 并设置 offset=${result.nextOffset}`);
+    }
+    if (result.total === 0) {
+        if (result.depthApplied < result.depthLimit) {
+            suggestions.unshift(`未命中引用，可尝试提高 maxDepth 至 ${result.depthApplied + 1}（或开启 autoExpandDepth）`);
+        }
+        else if (!result.autoExpand && result.depthApplied < 3) {
+            suggestions.unshift(`已使用 maxDepth=${result.depthApplied}，可开启 autoExpandDepth 或手动提高至 ${Math.min(result.depthApplied + 1, 3)}`);
+        }
+        else {
+            suggestions.unshift("未找到引用，可尝试放宽时间范围或更换锚点 Rem");
+        }
+    }
+    else {
+        if (result.depthApplied < result.depthLimit) {
+            suggestions.push(`需要更广范围时，可将 maxDepth 提至 ${result.depthApplied + 1}（当前尝试深度 ${result.depthApplied}）`);
+        }
+    }
+    suggestions.push(`若需阅读详细内容，可调用 outline_rem_subtree id=<remId> 或 inspect_rem_doc`);
+    suggestions.push(`如需更深层引用，可适当调大 maxDepth（当前锚点：${targetIds.join(", ")})`);
+    return suggestions;
+}