agent-remnote 0.0.1 → 0.0.2

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

@@ -0,0 +1,605 @@
+import { z } from "zod";
+import { buildGuidedResponse, parseOrThrow } from "./shared.js";
+import { executeSearchRemOverview } from "./searchRemOverview.js";
+import { executeOutlineRemSubtree } from "./outlineRemSubtree.js";
+import { TIME_RANGE_PATTERN, timeValueSchema, resolveTimeFilters, describeFilterSummary, } from "./timeFilters.js";
+import { executeFindRemsByReference, } from "./findRemsByReference.js";
+const inputShape = {
+    keywords: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe("关键词数组，与 query 二选一"),
+    query: z.string().min(1).optional().describe("搜索查询字符串，与 keywords 二选一"),
+    timeRange: z
+        .union([
+        z.literal("all"),
+        z.literal("*"),
+        z.string().regex(TIME_RANGE_PATTERN, "timeRange 需形如 '30d'、'2w'、'12h'"),
+    ])
+        .optional()
+        .describe("时间范围（如 30d/2w/12h 或 all/*；默认 30d）"),
+    createdAfter: timeValueSchema.optional().describe("创建时间下界（ISO/毫秒/秒）"),
+    createdBefore: timeValueSchema.optional().describe("创建时间上界（ISO/毫秒/秒）"),
+    updatedAfter: timeValueSchema.optional().describe("更新时间下界（ISO/毫秒/秒）"),
+    updatedBefore: timeValueSchema.optional().describe("更新时间上界（ISO/毫秒/秒）"),
+    maxResults: z
+        .number()
+        .int()
+        .min(1)
+        .max(30)
+        .optional()
+        .describe("聚合的结果条数上限（默认 8）"),
+    maxNodesPerResult: z
+        .number()
+        .int()
+        .min(5)
+        .max(200)
+        .optional()
+        .describe("单个条目展开的最大节点数（默认 60）"),
+    expandReferences: z.boolean().optional().describe("是否展开 [[引用]] 文本（默认 true）"),
+    maxReferenceDepth: z
+        .number()
+        .int()
+        .min(0)
+        .max(5)
+        .optional()
+        .describe("引用展开最大深度（默认 1）"),
+    includeEmpty: z.boolean().optional().describe("是否包含空节点（默认 false）"),
+    excludeProperties: z
+        .boolean()
+        .optional()
+        .describe("是否排除表格属性/选项节点（默认 true）"),
+    groupBy: z
+        .enum(["none", "parent", "date"]).optional().describe("分组方式（默认 parent）"),
+    searchLimit: z
+        .number()
+        .int()
+        .min(5)
+        .max(100)
+        .optional()
+        .describe("每轮搜索拉取上限（默认 3×maxResults）"),
+    mode: z
+        .enum(["auto", "like", "fts"]).optional().describe("检索模式（默认 auto）"),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("搜索起始偏移（分页）"),
+    referenceIds: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("可选：作为引用锚点的 Rem ID 列表"),
+    includeReferenceMatches: z
+        .boolean()
+        .optional()
+        .describe("是否合并引用命中的条目（默认 true）"),
+    referenceDepth: z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe("引用搜索深度（默认 1）"),
+    maxReferenceCandidates: z
+        .number()
+        .int()
+        .min(1)
+        .max(400)
+        .optional()
+        .describe("引用候选上限（默认 200）"),
+    dbPath: z.string().optional().describe("数据库文件路径（默认自动发现）"),
+    detail: z.boolean().optional().describe("是否返回 items/groups 等详细结构（默认 false）"),
+};
+export const summarizeTopicActivitySchema = z.object(inputShape);
+export async function executeSummarizeTopicActivity(params) {
+    const parsed = parseOrThrow(summarizeTopicActivitySchema, params, { label: "summarize_topic_activity" });
+    const keywords = parsed.keywords ?? [];
+    const query = (parsed.query ?? keywords.join(" ")).trim();
+    if (!query) {
+        throw new Error("必须提供 query 或 keywords");
+    }
+    const maxResults = parsed.maxResults ?? 8;
+    const maxNodesPerResult = parsed.maxNodesPerResult ?? 60;
+    const expandReferences = parsed.expandReferences ?? true;
+    const maxReferenceDepth = parsed.maxReferenceDepth ?? 1;
+    const includeEmpty = parsed.includeEmpty ?? false;
+    const excludeProperties = parsed.excludeProperties ?? true;
+    const groupBy = parsed.groupBy ?? "parent";
+    const searchLimit = parsed.searchLimit ?? Math.min(maxResults * 3, 60);
+    const { filters: timeFilters, summary: filterSummary, effectiveTimeRange } = resolveTimeFilters(parsed, { defaultTimeRange: "30d" });
+    const searchTimeRange = parsed.timeRange ?? effectiveTimeRange;
+    const detail = parsed.detail ?? false;
+    const includeReferenceMatches = parsed.includeReferenceMatches ?? true;
+    const requestedReferenceDepth = parsed.referenceDepth ?? 1;
+    const maxReferenceCandidates = parsed.maxReferenceCandidates ?? 200;
+    const anchorIds = new Set(parsed.referenceIds ?? []);
+    const collected = new Map();
+    const orderedIds = [];
+    const referenceIndex = new Map();
+    const ensureMatch = (id) => {
+        let entry = collected.get(id);
+        if (!entry) {
+            entry = {
+                id,
+                title: null,
+                snippet: null,
+                ancestor: null,
+                ancestorIds: [],
+                parentId: null,
+                matchedBy: new Set(),
+                matchedTargets: new Set(),
+                anchorIds: new Set(),
+                sourceIds: new Set(),
+            };
+            collected.set(id, entry);
+            orderedIds.push(id);
+        }
+        return entry;
+    };
+    // 若未提供参考锚点，先进行一次宽松搜索获取候选概念 Rem
+    if (anchorIds.size === 0) {
+        const anchorSearch = await executeSearchRemOverview({
+            query,
+            limit: 5,
+            mode: parsed.mode,
+            dbPath: parsed.dbPath,
+        });
+        for (const match of anchorSearch.matches) {
+            anchorIds.add(match.id);
+        }
+    }
+    let offset = parsed.offset ?? 0;
+    let iterations = 0;
+    let lastSearchResult = null;
+    let totalFetched = 0;
+    while (collected.size < maxResults && iterations < 6) {
+        const searchResult = await executeSearchRemOverview({
+            query,
+            limit: searchLimit,
+            offset,
+            mode: parsed.mode,
+            dbPath: parsed.dbPath,
+            ...(searchTimeRange ? { timeRange: searchTimeRange } : {}),
+            createdAfter: parsed.createdAfter,
+            createdBefore: parsed.createdBefore,
+            updatedAfter: parsed.updatedAfter,
+            updatedBefore: parsed.updatedBefore,
+        });
+        lastSearchResult = searchResult;
+        totalFetched += searchResult.matches.length;
+        for (const match of searchResult.matches) {
+            const entry = ensureMatch(match.id);
+            entry.matchedBy.add("text");
+            if (!entry.title && match.title)
+                entry.title = match.title;
+            if (!entry.snippet && match.snippet)
+                entry.snippet = match.snippet;
+            if (!entry.ancestor && match.ancestor)
+                entry.ancestor = match.ancestor;
+            if (entry.ancestorIds.length === 0 &&
+                Array.isArray(match.ancestorIds) &&
+                (match.ancestorIds?.length ?? 0) > 0) {
+                entry.ancestorIds = match.ancestorIds ?? [];
+            }
+            entry.parentId ??= match.parentId ?? null;
+        }
+        if (!searchResult.hasMore || searchResult.nextOffset == null) {
+            break;
+        }
+        offset = searchResult.nextOffset;
+        iterations += 1;
+    }
+    let referenceTotalCount = 0;
+    let referenceDepthUsed = includeReferenceMatches ? requestedReferenceDepth : null;
+    let referenceDepthAttempts = [];
+    let referenceAutoExpandUsed = includeReferenceMatches;
+    let referenceDepthLimit = includeReferenceMatches ? requestedReferenceDepth : null;
+    if (includeReferenceMatches && anchorIds.size > 0) {
+        const referenceArgs = {
+            targetIds: Array.from(anchorIds),
+            maxDepth: requestedReferenceDepth,
+            maxCandidates: maxReferenceCandidates,
+            limit: maxReferenceCandidates,
+            offset: 0,
+            timeRange: parsed.timeRange ?? filterSummary.timeRange ?? undefined,
+            createdAfter: parsed.createdAfter,
+            createdBefore: parsed.createdBefore,
+            updatedAfter: parsed.updatedAfter,
+            updatedBefore: parsed.updatedBefore,
+            dbPath: parsed.dbPath,
+        };
+        const referenceResult = await executeFindRemsByReference(referenceArgs);
+        referenceTotalCount = referenceResult.totalCount;
+        const appliedDepth = referenceResult.depthApplied ?? requestedReferenceDepth;
+        for (const match of referenceResult.matches) {
+            const entry = ensureMatch(match.id);
+            entry.matchedBy.add("reference");
+            if (!entry.title && match.title)
+                entry.title = match.title;
+            if (!entry.snippet && match.snippet)
+                entry.snippet = match.snippet;
+            if (!entry.ancestor && match.ancestor)
+                entry.ancestor = match.ancestor;
+            if (entry.ancestorIds.length === 0 && match.ancestorIds && match.ancestorIds.length > 0) {
+                entry.ancestorIds = match.ancestorIds;
+            }
+            entry.parentId ??= match.parentId ?? null;
+            if (match.matchedTargets) {
+                for (const target of match.matchedTargets) {
+                    entry.matchedTargets.add(target);
+                }
+            }
+            if (match.anchorIds) {
+                for (const anchor of match.anchorIds) {
+                    entry.anchorIds.add(anchor);
+                }
+            }
+            if (match.sourceIds) {
+                for (const source of match.sourceIds) {
+                    entry.sourceIds.add(source);
+                }
+            }
+            entry.referenceDepth = entry.referenceDepth
+                ? Math.min(entry.referenceDepth, match.depth ?? appliedDepth)
+                : match.depth ?? appliedDepth;
+            entry.updatedAt = chooseLatest(entry.updatedAt ?? null, match.updatedAt ?? null);
+            entry.createdAt = chooseLatest(entry.createdAt ?? null, match.createdAt ?? null);
+        }
+        referenceDepthUsed = appliedDepth;
+        referenceDepthAttempts = referenceResult.depthAttempts ?? [];
+        referenceAutoExpandUsed = referenceResult.autoExpandDepth ?? includeReferenceMatches;
+        referenceDepthLimit = referenceResult.depthLimit ?? appliedDepth;
+    }
+    const orderedMatches = orderedIds
+        .map((id) => collected.get(id))
+        .slice(0, maxResults);
+    const items = [];
+    for (const match of orderedMatches) {
+        try {
+            const outline = await executeOutlineRemSubtree({
+                id: match.id,
+                dbPath: parsed.dbPath,
+                includeEmpty,
+                expandReferences,
+                maxReferenceDepth,
+                startOffset: 0,
+                maxNodes: maxNodesPerResult,
+                format: "markdown",
+                excludeProperties,
+                detail: true,
+            });
+            const markdown = outline.markdown;
+            const lineCount = markdown ? markdown.split("\n").length : 0;
+            const nodes = Array.isArray(outline.tree)
+                ? (outline.tree ?? [])
+                : [];
+            collectReferenceSummaries(referenceIndex, nodes, match.id, outline.title ?? match.title ?? match.id);
+            const item = {
+                remId: match.id,
+                title: match.title ?? outline.title ?? match.id,
+                ancestor: match.ancestor,
+                ancestorIds: match.ancestorIds,
+                parentId: match.parentId,
+                snippet: match.snippet,
+                truncated: Boolean(outline.hasMore || lineCount > maxNodesPerResult),
+                matchedBy: Array.from(match.matchedBy),
+                matchedTargets: Array.from(match.matchedTargets),
+                anchorIds: Array.from(match.anchorIds),
+                sourceIds: Array.from(match.sourceIds),
+                referenceDepth: match.referenceDepth,
+                updatedAt: match.updatedAt ?? null,
+                createdAt: match.createdAt ?? null,
+                markdown,
+                outlineTitle: outline.title,
+                nodeCount: outline.nodeCount,
+                totalNodeCount: outline.totalNodeCount,
+                hasMore: outline.hasMore,
+                nextOffset: outline.nextOffset,
+            };
+            if (detail) {
+                item.nodes = nodes;
+            }
+            items.push(item);
+        }
+        catch (error) {
+            items.push({
+                remId: match.id,
+                title: match.title ?? match.id,
+                ancestor: match.ancestor,
+                ancestorIds: match.ancestorIds,
+                parentId: match.parentId,
+                snippet: match.snippet,
+                truncated: false,
+                matchedBy: Array.from(match.matchedBy),
+                matchedTargets: Array.from(match.matchedTargets),
+                anchorIds: Array.from(match.anchorIds),
+                sourceIds: Array.from(match.sourceIds),
+                referenceDepth: match.referenceDepth,
+                updatedAt: match.updatedAt ?? null,
+                createdAt: match.createdAt ?? null,
+                error: String(error),
+            });
+        }
+    }
+    const groups = groupItems(items, groupBy);
+    const aggregateMarkdown = buildAggregateMarkdown(groups, groupBy);
+    const highlights = buildHighlights(items);
+    const referenceIndexData = convertReferenceIndex(referenceIndex);
+    const count = items.length;
+    const info = lastSearchResult ?? {
+        dbPath: parsed.dbPath ?? "",
+        resolution: "explicit",
+        dirName: undefined,
+        queryUsed: query,
+        totalFetched: 0,
+        matches: [],
+        count: 0,
+        offset: 0,
+        limit: 0,
+        hasMore: false,
+        nextOffset: null,
+        filtersApplied: null,
+    };
+    const response = {
+        dbPath: info.dbPath,
+        resolution: info.resolution,
+        dirName: info.dirName,
+        queryUsed: info.queryUsed ?? query,
+        keywords,
+        groupBy,
+        timeRange: filterSummary.timeRange ?? null,
+        filtersApplied: filterSummary,
+        count,
+        maxResults,
+        maxNodesPerResult,
+        totalFetched,
+        collected: items.length,
+        hasMore: info.hasMore,
+        nextOffset: info.nextOffset,
+        includeReferenceMatches,
+        referenceDepthRequested: requestedReferenceDepth,
+        referenceDepthUsed,
+        referenceDepthAttempts,
+        referenceAutoExpandUsed,
+        referenceDepthLimit,
+        referenceAnchors: Array.from(anchorIds),
+        referenceTotalCount,
+        markdown: aggregateMarkdown || "未找到相关 Rem。",
+        highlights,
+        referenceIndex: referenceIndexData,
+    };
+    if (detail) {
+        Object.assign(response, { items, groups });
+    }
+    return response;
+}
+export function registerSummarizeTopicActivity(server) {
+    server.tool("summarize_topic_activity", `<usecase>在指定时间范围内按关键词整理 Rem，回答“最近一个月我记录了什么…”之类的问题。</usecase>
+<instructions>
+- keywords 和 query 至少提供其一；默认会在最近 30 天内搜索。
+- 可用 timeRange（如 '30d'）、createdAfter/updatedAfter 精确控制时间窗口。
+- 默认按父级节点分组；可通过 groupBy=none/date 调整呈现方式。
+- 如需细读某条目，可继续调用 outline_rem_subtree 或 inspect_rem_doc。
+</instructions>`, inputShape, async (input) => {
+        const parsed = parseOrThrow(summarizeTopicActivitySchema, input, { label: "summarize_topic_activity" });
+        const result = await executeSummarizeTopicActivity(parsed);
+        const suggestions = [
+            `可继续调用 outline_rem_subtree id=<remId> startOffset=${result.maxNodesPerResult} 深入阅读`,
+        ];
+        if (result.includeReferenceMatches &&
+            result.referenceTotalCount === 0 &&
+            (result.referenceDepthUsed ?? 0) < Math.min(result.referenceDepthLimit ?? 3, 3)) {
+            suggestions.unshift(`引用未命中，可尝试提高 referenceDepth 至 ${(result.referenceDepthUsed ?? 0) + 1} 或指定 referenceIds`);
+        }
+        if (result.hasMore && result.nextOffset != null) {
+            suggestions.unshift(`搜索结果仍有剩余，可再次调用 summarize_topic_activity 并设置 searchLimit 或使用 nextOffset=${result.nextOffset}`);
+        }
+        const count = typeof result.count === "number"
+            ? result.count
+            : Array.isArray(result.items)
+                ? (result.items?.length ?? 0)
+                : 0;
+        if (count === 0) {
+            suggestions.unshift("可尝试放宽时间范围或更换关键词");
+        }
+        if (result.includeReferenceMatches && result.referenceTotalCount > 0) {
+            suggestions.unshift(`引用命中了 ${result.referenceTotalCount} 条，可使用 find_rems_by_reference targetIds=${JSON.stringify(result.referenceAnchors)} 深入探索`);
+        }
+        const filterDesc = describeFilterSummary(result.filtersApplied);
+        const guidance = `整理 "${result.queryUsed}" 的专题活动，共 ${count} 条${result.markdown ? "，已生成 Markdown 摘要" : ""}${filterDesc ? `（${filterDesc}）` : ""}。`;
+        return buildGuidedResponse({ guidance, ...result }, suggestions);
+    });
+}
+function groupItems(items, groupBy) {
+    if (groupBy === "none") {
+        return [
+            {
+                key: "all",
+                label: "全部",
+                items,
+            },
+        ];
+    }
+    const map = new Map();
+    for (const item of items) {
+        const key = groupBy === "parent" ? determineParentLabel(item) : determineDateLabel(item);
+        const existing = map.get(key.key);
+        if (existing) {
+            existing.items.push(item);
+        }
+        else {
+            map.set(key.key, {
+                key: key.key,
+                label: key.label,
+                items: [item],
+            });
+        }
+    }
+    return Array.from(map.values());
+}
+function determineParentLabel(item) {
+    const label = item.ancestor && item.ancestor.trim() ? item.ancestor.trim() : "未分类";
+    return { key: label, label };
+}
+function determineDateLabel(item) {
+    const candidates = [
+        item.outlineTitle,
+        item.title,
+        item.snippet,
+        item.markdown?.split("\n")[0],
+    ];
+    for (const candidate of candidates) {
+        const normalized = extractDate(candidate);
+        if (normalized) {
+            return { key: normalized, label: normalized };
+        }
+    }
+    return { key: "未识别日期", label: "未识别日期" };
+}
+function extractDate(text) {
+    if (!text)
+        return null;
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    const isoMatch = trimmed.match(/(\d{4})[\/-](\d{1,2})[\/-](\d{1,2})/);
+    if (isoMatch) {
+        return normalizeDateParts(isoMatch[1], isoMatch[2], isoMatch[3]);
+    }
+    const dotMatch = trimmed.match(/(\d{4})\.(\d{1,2})\.(\d{1,2})/);
+    if (dotMatch) {
+        return normalizeDateParts(dotMatch[1], dotMatch[2], dotMatch[3]);
+    }
+    const cnMatch = trimmed.match(/(\d{4})年(\d{1,2})月(\d{1,2})日/);
+    if (cnMatch) {
+        return normalizeDateParts(cnMatch[1], cnMatch[2], cnMatch[3]);
+    }
+    return null;
+}
+function normalizeDateParts(year, month, day) {
+    const y = year.padStart(4, "0");
+    const m = month.padStart(2, "0");
+    const d = day.padStart(2, "0");
+    return `${y}-${m}-${d}`;
+}
+function buildAggregateMarkdown(groups, groupBy) {
+    const lines = [];
+    if (groups.length === 0 || groups.every((group) => group.items.length === 0)) {
+        return "未找到相关 Rem。";
+    }
+    for (const group of groups) {
+        if (groupBy !== "none") {
+            lines.push(`## ${group.label}`);
+        }
+        for (const item of group.items) {
+            const title = item.outlineTitle || item.title || item.remId;
+            const truncatedNote = item.truncated ? " _(内容已截断)_" : "";
+            lines.push(`- **${title}**${truncatedNote}`);
+            if (item.ancestor && groupBy !== "parent") {
+                lines.push(`  - 上级：${item.ancestor}`);
+            }
+            if (item.matchedBy.length > 0) {
+                const sourceLabel = item.matchedBy
+                    .map((source) => (source === "text" ? "文本" : "引用"))
+                    .join(" + ");
+                lines.push(`  - 命中来源：${sourceLabel}`);
+            }
+            if (item.referenceDepth) {
+                lines.push(`  - 引用深度：${item.referenceDepth}`);
+            }
+            if (item.anchorIds && item.anchorIds.length > 0) {
+                lines.push(`  - 对应锚点：${item.anchorIds.join(", ")}`);
+            }
+            if (item.matchedTargets && item.matchedTargets.length > 0) {
+                lines.push(`  - 引用目标：${item.matchedTargets.join(", ")}`);
+            }
+            if (item.markdown) {
+                lines.push(indentMarkdown(item.markdown, "  "));
+            }
+            else if (item.snippet) {
+                lines.push(`  - 摘要：${item.snippet}`);
+            }
+            if (item.error) {
+                lines.push(`  - 读取失败：${item.error}`);
+            }
+            else if (item.truncated) {
+                lines.push(`  - 提示：继续使用 outline_rem_subtree id=${item.remId} 获取完整内容`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trim();
+}
+function indentMarkdown(content, prefix) {
+    return content
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+function chooseLatest(current, incoming) {
+    if (incoming == null)
+        return current ?? null;
+    if (current == null)
+        return incoming;
+    return Math.max(current, incoming);
+}
+function buildHighlights(items) {
+    return items.map((item) => ({
+        remId: item.remId,
+        title: item.title,
+        ancestor: item.ancestor,
+        matchedBy: item.matchedBy,
+        truncated: item.truncated,
+        referenceDepth: item.referenceDepth ?? null,
+        anchorIds: item.anchorIds ?? [],
+        matchedTargets: item.matchedTargets ?? [],
+        hasMore: Boolean(item.hasMore),
+    }));
+}
+function collectReferenceSummaries(index, nodes, remId, remTitle) {
+    if (!nodes || nodes.length === 0)
+        return;
+    for (const node of nodes) {
+        if (!node.references || node.references.length === 0)
+            continue;
+        for (const refId of node.references) {
+            if (!refId)
+                continue;
+            const entry = ensureReferenceEntry(index, refId);
+            entry.totalOccurrences += 1;
+            if (entry.samples.length < 5) {
+                entry.samples.push({
+                    remId,
+                    remTitle,
+                    nodeId: node.id,
+                    text: node.text,
+                    depth: node.depth,
+                });
+            }
+        }
+    }
+}
+function ensureReferenceEntry(index, id) {
+    let entry = index.get(id);
+    if (!entry) {
+        entry = {
+            id,
+            totalOccurrences: 0,
+            samples: [],
+        };
+        index.set(id, entry);
+    }
+    return entry;
+}
+function convertReferenceIndex(index) {
+    const result = {};
+    for (const [id, entry] of index.entries()) {
+        result[id] = {
+            totalOccurrences: entry.totalOccurrences,
+            samples: entry.samples,
+        };
+    }
+    return result;
+}