@aalis/plugin-user-relation 0.4.1

package/dist/service.d.ts

@@ -0,0 +1,1108 @@
+/**
+ * RelationService —— 关系图的应用层 API。
+ *
+ * 职责：
+ * - 暴露给其他插件 / webui / agent middleware 的稳定查询接口
+ * - 处理"upsert 时合并 evidence + 衰减/强化 weight"的语义
+ * - 生成稳定的 ID（事件 / 边）
+ *
+ * 不处理：
+ * - LLM 提取本身 → M2 的 extractor.ts
+ * - WebUI 端点 → M4 的 actions
+ */
+import type { Context } from '@aalis/core';
+import type { ModelRef } from '@aalis/plugin-llm-api';
+import type { RelationStore } from './store.js';
+import type { CommunityMembership, EntityEntityEdge, EntityKind, EntityNode, EventEntityEdge, EventEventEdge, EventNode, EvidenceRef, PersonEntityEdge, PersonEventEdge, PersonNode, PersonPersonEdge, RelationEdge, RelationGraphSnapshot, ScoreMode } from './types.js';
+import { type WeightDecayCfg } from './utils.js';
+export type TriggerExtractionFn = (sessionId: string) => Promise<{
+    status: 'ok' | 'skipped' | 'error';
+    reason?: string;
+}>;
+export declare class RelationService {
+    private readonly store;
+    /** 可选 ctx：仅用于写 logger 审计（deleteNode / mergeNodes / changeEntityKind 等 agent 写入路径）。测试不传则 fallback 到 console。 */
+    private readonly ctx?;
+    /** 由 extractor 注入；actions 层通过 triggerExtraction() 调用 */
+    private triggerExtractionHandler?;
+    /** 最近一次 consolidate() 完成的时间戳（ms）；未运行时为 undefined */
+    private _lastConsolidateAt?;
+    /** 最近一次 consolidate() 结果的简短摘要 */
+    private _lastConsolidateResultSummary?;
+    /** 最近一次 consolidate() 的触发来源：manual | eviction | api */
+    private _lastConsolidateTrigger?;
+    constructor(store: RelationStore, 
+    /** 可选 ctx：仅用于写 logger 审计（deleteNode / mergeNodes / changeEntityKind 等 agent 写入路径）。测试不传则 fallback 到 console。 */
+    ctx?: Context | undefined);
+    /** 写 audit 日志；ctx 存在走 logger.warn，否则 fallback console.warn（主要照顾单元测试）。 */
+    private _audit;
+    /** 查询最近一次 consolidation 运行时间、触发源与结果摘要 */
+    getLastConsolidateInfo(): {
+        lastRunAt?: number;
+        summary?: string;
+        trigger?: 'manual' | 'eviction' | 'api';
+    };
+    static personId(platform: string, userId: string): string;
+    /** 由 extractor 在 start() 后注入 */
+    setTriggerExtractionHandler(fn: TriggerExtractionFn): void;
+    /** 手动触发某 session 的 LLM 提取；extractor 未挂载时返回 error */
+    triggerExtraction(sessionId: string): Promise<{
+        status: 'ok' | 'skipped' | 'error';
+        reason?: string;
+    }>;
+    observePerson(platform: string, userId: string, displayName?: string): Promise<PersonNode>;
+    getPerson(platform: string, userId: string): Promise<PersonNode | undefined>;
+    /**
+     * 同步平台 displayName 到 Person 节点：仅当节点已存在且 displayName 与传入不同时才 upsert。
+     * 不创建新节点（避免水群幽灵）；不动 mentionCount / firstSeenAt / lastMentionedAt（与
+     * 「显式提及」语义区分）；仅刷新 lastSeenAt。返回是否真的发生了改名。
+     *
+     * 调用方：rename-watcher（订阅 inbound:message:archived，从 metadata.nickname 同步）。
+     */
+    syncDisplayName(platform: string, userId: string, displayName: string): Promise<boolean>;
+    deletePerson(platform: string, userId: string): Promise<{
+        deletedEdges: number;
+    }>;
+    /**
+     * 统一节点查找入口：给定任意节点 ID（person `<platform>:<userId>` 或 event/entity UUID）
+     * 返回 { kind, name }；不存在返回 null。供 tools 层做存在性校验+友好报错使用。
+     */
+    findNodeById(id: string): Promise<{
+        kind: 'person' | 'event' | 'entity';
+        name: string;
+    } | null>;
+    /**
+     * 新建事件。严格按 normalized title 去重：若已存在同名事件，**强制合并**到旧节点
+     * （追加 evidence、累加权重 += 0.3、occurrences 追加当前时间戳），返回旧节点。
+     * 这样保证「同一件事被反复提及」不会产生重复 event，但通过 occurrences[] 保留时间维度。
+     */
+    createEvent(input: Omit<EventNode, 'id' | 'firstSeenAt' | 'lastReinforcedAt'>): Promise<EventNode>;
+    /**
+     * 按 normalized title 精确匹配（不区分大小写、压缩空白）查找已有事件。
+     * 用于 createEvent 入口去重。
+     *
+     * 若传入 scope：遵循「同名 + 同 scope 才是同事件」原则；只接受
+     *   (a) 两者 scope 相同，或 (b) 旧节点 scope 为 undefined（老数据通配）。
+     * 不传 scope：只看 title，保留老行为（供手动调用 / 测试 / 迁移）。
+     */
+    findEventByTitle(title: string, scope?: string): Promise<EventNode | undefined>;
+    /**
+     * 强化已有事件：追加 evidence、更新 lastReinforcedAt，可选更新 summary/title/category。
+     *
+     * 跨 sessionScope 软护栏：如果新 evidence 全部来自与 existing.sessionScope 不同的会话，
+     * 且 existing 既不是 'global' 也不是未限定 scope，则记录审计但**继续执行**（warn 不阻断）。
+     * 与 addEventEventEdge 的 is-alias-of 跨 scope 硬阻断对应——reinforce 走 warn，
+     * 因为它在不少正常路径（如 entity 共现、is-alias-of 后回写）也会自然跨 scope 触发。
+     */
+    reinforceEvent(eventId: string, patch: {
+        title?: string;
+        summary?: string;
+        category?: EventNode['category'];
+        evidence?: EvidenceRef[];
+    }): Promise<EventNode | undefined>;
+    getEvent(eventId: string): Promise<EventNode | undefined>;
+    deleteEvent(eventId: string): Promise<{
+        deletedEdges: number;
+    }>;
+    /**
+     * 新建实体。严格按 (entityKind, normalized name) 去重：若已存在同 kind 同名实体，
+     * **强制合并**到旧节点（追加 evidence、合并 aliases、累加权重 += 0.3），返回旧节点。
+     */
+    createEntity(input: Omit<EntityNode, 'id' | 'firstSeenAt' | 'lastReinforcedAt'>): Promise<EntityNode>;
+    /**
+     * 强化已有实体：追加 evidence、更新 lastReinforcedAt，可选更新字段。
+     *
+     * **静默改 kind / 改 name 已被禁用**（详见 patch 字段注释），LLM 反复输出"重名异 kind"
+     * 时不会把已有节点偷偷翻转身份，只会留下 audit 日志。如确需 rename/换 kind，请走
+     * rename-watcher / consolidate verify / 显式 merge 工具。
+     */
+    reinforceEntity(entityId: string, patch: {
+        /**
+         * 仅作 audit 比对；reinforceEntity **不会**通过此字段改名。传入与 existing.name normalize
+         * 后等价时，允许把 display 写法换成 patch 写法（洗写法）；不等价则记审计后保留 existing.name。
+         */
+        name?: string;
+        aliases?: string[];
+        summary?: string;
+        /**
+         * 仅作 audit 比对；reinforceEntity **不会**通过此字段改 kind。
+         * topic/work/place/thing 是底层分类，改 kind 等于换实体，必须走 consolidate verify
+         * 或显式管理工具。
+         */
+        entityKind?: EntityNode['entityKind'];
+        evidence?: EvidenceRef[];
+    }): Promise<EntityNode | undefined>;
+    getEntity(entityId: string): Promise<EntityNode | undefined>;
+    deleteEntity(entityId: string): Promise<{
+        deletedEdges: number;
+    }>;
+    /**
+     * 按 name / aliases 精确匹配（不区分大小写）查找已有实体。
+     * 用于抽取阶段去重 —— LLM 提取出"三角洲"时优先复用已存在的同名实体。
+     */
+    findEntityByName(name: string): Promise<EntityNode | undefined>;
+    /**
+     * 按 (entityKind, normalized name) 精确匹配查找已有实体；用于 createEntity 入口去重。
+     * 比 findEntityByName 更严格（要求 kind 一致），避免「同名不同类」误合并（如游戏《北京》vs 地点北京）。
+     */
+    findEntityByKindAndName(kind: EntityNode['entityKind'], name: string): Promise<EntityNode | undefined>;
+    addPersonEntityEdge(input: {
+        fromPersonId: string;
+        toEntityId: string;
+        role: PersonEntityEdge['role'];
+        sentiment?: PersonEntityEdge['sentiment'];
+        weight?: number;
+        description?: string;
+        evidence?: EvidenceRef[];
+    }): Promise<PersonEntityEdge>;
+    findPersonEntityEdge(fromPersonId: string, toEntityId: string, role: PersonEntityEdge['role']): Promise<PersonEntityEdge | undefined>;
+    addEventEventEdge(input: {
+        fromEventId: string;
+        toEventId: string;
+        relationType: string;
+        directed?: boolean;
+        weight?: number;
+        description?: string;
+        evidence?: EvidenceRef[];
+    }): Promise<EventEventEdge>;
+    findEventEventEdge(fromEventId: string, toEventId: string, relationType: string, directed: boolean): Promise<EventEventEdge | undefined>;
+    addEventEntityEdge(input: {
+        fromEventId: string;
+        toEntityId: string;
+        relationType: string;
+        weight?: number;
+        description?: string;
+        evidence?: EvidenceRef[];
+    }): Promise<EventEntityEdge>;
+    findEventEntityEdge(fromEventId: string, toEntityId: string, relationType: string): Promise<EventEntityEdge | undefined>;
+    addEntityEntityEdge(input: {
+        fromEntityId: string;
+        toEntityId: string;
+        relationType: string;
+        directed?: boolean;
+        weight?: number;
+        description?: string;
+        evidence?: EvidenceRef[];
+    }): Promise<EntityEntityEdge>;
+    findEntityEntityEdge(fromEntityId: string, toEntityId: string, relationType: string, directed: boolean): Promise<EntityEntityEdge | undefined>;
+    addPersonEventEdge(input: {
+        fromPersonId: string;
+        toEventId: string;
+        role: PersonEventEdge['role'];
+        sentiment?: PersonEventEdge['sentiment'];
+        weight?: number;
+        description?: string;
+        evidence?: EvidenceRef[];
+    }): Promise<PersonEventEdge>;
+    addPersonPersonEdge(input: {
+        fromPersonId: string;
+        toPersonId: string;
+        relationType: string;
+        directed?: boolean;
+        hierarchy?: PersonPersonEdge['hierarchy'];
+        weight?: number;
+        description?: string;
+        evidence?: EvidenceRef[];
+    }): Promise<PersonPersonEdge>;
+    findPersonEventEdge(fromPersonId: string, toEventId: string, role: PersonEventEdge['role']): Promise<PersonEventEdge | undefined>;
+    /**
+     * 查找等价的人-人边。对于对称关系 (directed=false)，(A→B, friend) 与 (B→A, friend)
+     * 视为同一条边；只看其中一种方向即可命中。
+     */
+    findPersonPersonEdge(fromPersonId: string, toPersonId: string, relationType: string, directed: boolean): Promise<PersonPersonEdge | undefined>;
+    deleteEdge(edgeId: string): Promise<void>;
+    loadAll(): Promise<RelationGraphSnapshot>;
+    /**
+     * 廉价预判：图中任一类节点 / 边的当前数量是否已达到 `evictByQuota` 的滞回触发阈值
+     * （`count >= ceil(cap · (1 + hysteresisPct))`），即下一次 `evictByQuota` **真的会删东西**。
+     *
+     * 用于 extractor 的"写后顺手老化"路径节流：避免每次提取都跑 PageRank / consolidate。
+     * 公式与 {@link evictByQuota} 内部判定一致；任一类超阈即返回 true（与 evict 的分类独立判定对齐）。
+     *
+     * `cap <= 0` 的类视为不限，跳过检查；`evictionEnabled` 由调用方负责。
+     */
+    isOverQuota(quota: {
+        maxPersons?: number;
+        maxEvents?: number;
+        maxEntities?: number;
+        maxEdges?: number;
+        hysteresisPct?: number;
+    }): Promise<boolean>;
+    /**
+     * 清理孤儿节点：删除所有"没有任何边引用"的 person / event / entity。
+     *
+     * 设计原则（v3，最简）：
+     * - **没有任何边端点引用 = 孤儿**，三类节点一视同仁。边的 6 种 kind 中只要节点
+     *   出现在任一 from/to 字段上就算"被引用"。
+     * - **person 孤儿也清**：observePerson 按 (platform, userId) upsert，删掉的"水群幽灵"
+     *   下次发言时会自动重建，所以删除安全。
+     * - **零保护**：weight/evidence 门槛属于配额淘汰阶段的事，与孤儿无关；
+     *   孤儿的语义就是"没人指向"，无条件清。
+     * - **零参数**：刻意不暴露任何 opts，避免重新引入误用。
+     *
+     * 返回被删除的 id 列表，便于 caller 打日志/报告。
+     */
+    pruneOrphans(): Promise<{
+        deletedPersons: number;
+        deletedEvents: number;
+        deletedEntities: number;
+        deletedPersonIds: string[];
+        deletedEventIds: string[];
+        deletedEntityIds: string[];
+        deletedDanglingEdges: number;
+    }>;
+    /**
+     * Eager 时间衰减回写：把所有 event/entity 节点与所有边的 `weight` 字段
+     * 物理改写为当前 `effectiveWeight`，并把 `lastReinforcedAt` 重置为 now
+     * （作为"新的衰减基准"——否则下次 rewrite 会基于同一基准再次衰减，
+     * raw 被反复折半到 0）。
+     *
+     * 设计动机（lazy → eager 切换）：
+     * - 原 lazy 模式 DB 永远存 raw 累积值，effectiveWeight 仅查询时实时算。
+     *   问题：raw=1.0 的边被衰减到 effW=0.3 后再次 reinforce 一次，
+     *   `reinforceWeight(1.0, 0.1) = 1.0`——**永远卡死在 1**，effW 从 0.3
+     *   瞬间跳回 1.0，离散跳跃，不符合"老朋友重逢慢慢回温"的人类直觉。
+     * - Eager 回写后：raw 物理变成 0.3，下次 reinforce 从 0.3 出发 → 0.37 →
+     *   0.43 …**渐进恢复**，活跃关系靠持续 reinforce 维持高位、长期不活跃的
+     *   关系自然回落到 floor 附近。每日压缩前调用一次，DB 字段就能反映
+     *   "当下真实强度"，便于调试 / 观察 / 跨时间快照对比。
+     *
+     * 语义合并（务实简化，避免新增 `lastDecayedAt` 字段）：
+     * - `lastReinforcedAt` 在 eager 模式下含义统一为"上次 weight 字段被更新的
+     *   时间"——reinforce* 方法与 rewriteWeights 都写它。物理上是衰减基准。
+     * - 调用方应理解：稳态下"长期不活跃节点"的 lastReinforcedAt 会被每日
+     *   rewrite 推到最近一次压缩时间，age 分子≈0；但它们的 effW 已收敛到 floor，
+     *   ageScore 排序退化为 `1 / (floor × PR)`——PR 边缘的依旧最先被淘汰。
+     *
+     * 副作用与正交性：
+     * - Person 节点不参与（无 weight 字段，由 mentionCount / lastSeenAt 表达活跃度）。
+     * - `halfLifeDays <= 0`（衰减关闭）时 short-circuit 返回，零写盘开销；
+     *   单测默认配置 `{ halfLifeDays: 0 }` 走此路径，**不影响现有测试行为**。
+     * - 增量阈值 `|new - raw| < 1e-6` 跳过，避免对几乎无变化的节点做无谓写盘
+     *   （也保证幂等：rewrite 后第二次立即调用本方法所有节点都命中阈值跳过）。
+     * - 活跃节点保护：被 reinforce 过的节点 lastReinforcedAt > 上次 rewrite 时间，
+     *   age 更小受保护——"最近活跃的更新鲜，更应保留"。
+     *
+     * 调用方：
+     * - `evictByQuota` 入口自动调用一次（与每日 scheduler 压缩对齐）。
+     * - `/relation rewrite-weights` 手动命令。
+     *
+     * 返回各类写回计数，便于日志 / 测试断言。
+     */
+    rewriteWeights(decay: WeightDecayCfg, opts?: {
+        now?: number;
+    }): Promise<{
+        events: number;
+        entities: number;
+        edges: number;
+        skipped: boolean;
+    }>;
+    /**
+     * 自动老化：按配额淘汰过多节点。模仿 profile 的"写后顺手扫"风格，不开独立调度器。
+     *
+     * 优先级（每次仅在超额时执行）：
+     *   1. **孤儿节点**先删（无任何边引用的 person / event / entity；委托 `pruneOrphans()`）。
+     *      孤儿清理与配额无关，旧账噪声任何时候都清。
+     *   2. 仍超额时按 `(now - lastReinforcedAt) / (max(effW,0.05) · max(PR,ε))` **降序**删；
+     *      即"老旧 + 低权重 + 在 PageRank 上无人指向"的优先丢。
+     *   3. **不再有硬豁免**（evidence≥3 / effW≥0.8）：避免老节点永久占住名额。
+     *      重要性完全由 effW + PageRank 表达：高 evidence/weight 节点自然在打分尾部，
+     *      并且随时间衰减后仍可以让出名额。Person 节点同样进入排序，
+     *      依靠 PR 个性化向量的人偶偏置（person seed=2 / entity=1.5 / event=1）自然偏保护。
+     *   4. **滞回（hysteresis）**：仅当 count > quota·(1+hysteresisPct) 时才触发，
+     *      触发后一次性裁到 floor(quota·targetPct)。默认 hysteresis=0.2, target=0.8 ——
+     *      quota=500 时会在 600 触发并裁到 400，相当于一次清理 ~200 条；不会每写一条就裁。
+     *   5. 边也按配额删——保留 `weight · 端点PR平均` 最高的，让"弱权但连接重要节点"的边受保护。
+     *
+     * 副作用：每次调用都会把 PageRank 写回三类节点的 `lastPageRank` / `lastPageRankAt`，
+     * 用于 WebUI 展示"图重要性"。
+     *
+     * PageRank 个性化向量按 kind 加权（默认 person=2 / entity=1.5 / event=1），从而"重要性 人>物>事"
+     * 直接体现为分数偏置：人物附近的事件/实体更难被淘汰。
+     * 另外 utils.computePageRank 在 person→event / person→entity 单向边上加了半权反向虚拟边（系数 0.5），
+     * 让"参与重要事件 / 关注热门实体"的人 PR 能拉开差距，避免无 person-person 边的人退化到 seed 常数。
+     *
+     * 返回各类删除计数，便于日志/测试断言。
+     */
+    evictByQuota(quota: {
+        /** 人物节点总数上限。0 = 不限（允许人物无限增长）。 */
+        maxPersons?: number;
+        maxEvents: number;
+        maxEntities: number;
+        maxEdges: number;
+        /** PageRank 阻尼，默认 0.85 */
+        pagerankDamping?: number;
+        /** PageRank 最大迭代次数，默认 20 */
+        pagerankIterations?: number;
+        /** PageRank 收敛阈值（L1 误差），默认 1e-4 */
+        pagerankEpsilon?: number;
+        /** 滞回百分比；count > quota·(1+hysteresisPct) 才触发淘汰。默认 0.2 */
+        hysteresisPct?: number;
+        /** 触发后裁到 floor(quota·targetPct)。默认 0.8 */
+        targetPct?: number;
+        /** PageRank 个性化向量种子权（人/物/事），默认 2/1.5/1 */
+        personSeed?: number;
+        entitySeed?: number;
+        eventSeed?: number;
+        /**
+         * person→event / person→entity 单向边反向虚拟边权重系数。
+         * 0 = 不加反向边；默认 0.5。
+         */
+        reverseEdgeFactor?: number;
+        /**
+         * 是否启用 component-size 缩放（Component-weighted Personalized PageRank）：
+         * 孤立小连通分量节点 PR 按 sqrt(componentSize/n) 压低，避免
+         * "1人1物1事" 这种三角小环被反向虚拟边 + dangling 重分布抬高。默认 true。
+         */
+        pagerankComponentScale?: boolean;
+        /** 时间衰减配置：用于把 raw weight 折算成有效 weight。halfLifeDays<=0 时退化为原 raw 行为。 */
+        decay?: WeightDecayCfg;
+        /**
+         * 社群发现算法；默认 'louvain'。
+         * - 'louvain'：标准硬划分，快、主社群清晰；每人恒为 1 个社群。
+         * - 'leiden'：Louvain + 内部连通性 refinement；修复 Louvain 社区内部可能不连通的问题。
+         * - 'slpa'：Speaker-Listener Label Propagation，**原生重叠社区**；跨群人物能获得多个社群隶属度。
+         */
+        communityAlgorithm?: 'louvain' | 'leiden' | 'slpa';
+    }): Promise<{
+        deletedPersons: number;
+        deletedEvents: number;
+        deletedEntities: number;
+        deletedEdges: number;
+        /** 孤儿阶段被删的 id 列表（前 50 个），便于日志/诊断 */
+        orphanSamples: {
+            persons: string[];
+            events: string[];
+            entities: string[];
+        };
+    }>;
+    /** 查询某人涉及的所有事件 + 实体 + 直连人际关系（深度 1 快捷方法） */
+    getNeighborhood(personId: string): Promise<{
+        person: PersonNode | undefined;
+        events: EventNode[];
+        entities: EntityNode[];
+        edges: RelationEdge[];
+    }>;
+    /**
+     * 按 BFS 抽取以指定 person 为起点的子图。
+     *
+     * - **maxDepth**：探求层数（0 = 仅起点；1 = 起点 + 直接邻居；以此类推）。
+     *   人 → 事件 / 人 → 人 各算 1 跳；事件 → 人也算 1 跳，因此 depth=2 可触达"同事件其他参与者"。
+     * - **maxBreadth**：单个节点在 BFS 中最多展开的邻居数，按边 weight 降序选取。
+     * - **visited**：以 nodeId 集合去重，防止环 / 重复展开（同一节点最多被加入队列一次）。
+     *
+     * 返回子图包含访问过的节点之间的全部已存在边（不仅 BFS 树边），便于上层渲染完整局部结构。
+     */
+    traverseSubgraph(opts: {
+        /** 起点节点 id 列表，按 snapshot 自动推断 kind（person / event / entity） */
+        startNodeIds: string[];
+        maxDepth: number;
+        maxBreadth: number;
+    }): Promise<{
+        persons: PersonNode[];
+        events: EventNode[];
+        entities: EntityNode[];
+        edges: RelationEdge[];
+    }>;
+    /**
+     * 寻找两个人之间的最短关系链。BFS，事件节点作为中间桥（A→事件→B 算 2 跳）。
+     * - maxDepth：路径最大边数；超过返回 null。
+     * - 返回 { nodes, edges } 节点列表按路径顺序排列；找不到返回 null。
+     */
+    findPath(fromNodeId: string, toNodeId: string, maxDepth: number): Promise<{
+        nodes: Array<PersonNode | EventNode | EntityNode>;
+        edges: RelationEdge[];
+    } | null>;
+    /**
+     * 计算两节点间联系强度（方向感知版）。
+     *
+     * **方向语义模型**：
+     * - **桥型边**（person-event / person-entity / event-entity）：事件/实体没有主观能动，
+     *   仅作中介出现 → 邻接表里总是双向（无视 edge.directed）
+     * - **主体间边**（person-person / event-event / entity-entity）：
+     *   - `directed=false` → 双向（如 event "related" event）
+     *   - `directed=true` → 严格 from→to 单向（如 A "admirer" B：B 不一定认识 A）
+     *
+     * **mode 参数**：
+     * - `'symmetric'`（默认）= **联系紧密度**。跑 a→b 与 b→a 两遍取 max。
+     *   语义："存在任意方向的关系连通"。单方面声明至少会从一侧贡献。
+     * - `'directed'` = **关注/影响传播度**。仅跑 fromNodeId → toNodeId 一次。
+     *   语义："从 A 出发能否通过主动声明触达 B"。适用于"A 都关心了谁/A 的影响波及谁"。
+     *
+     * **kindMultiplier**（待数据观察调整，目前为直觉估计）：
+     * - person-person = 1.0（社会语义最强）
+     * - person-event = 0.8（事件 = 真实互动）
+     * - person-entity = 0.5（兴趣共鸣 < 真实互动）
+     * - event-event = 0.4
+     * - event-entity = 0.4
+     * - entity-entity = 0.3（内容关联，非社会信号）
+     *
+     * **算法**：限深简单路径枚举（Katz 风格） + Adamic-Adar 共同邻居
+     * - contrib = β^|p| × Π w_e × (len==1 ? 1.5 : 1) — 直接连接 boost
+     * - common = Σ 1/log(deg(C)+1.7) — 惩罚高度共同节点（群聊噪声）
+     * - raw = katz + 0.3 × common；score = tanh(raw) ∈ [0, 1]
+     *
+     * **未来扩展点**（在 opts 里预留）：hierarchy 反向降权、relationType 加权、时间衰减…
+     */
+    scoreBetween(fromNodeId: string, toNodeId: string, opts?: {
+        maxDepth?: number;
+        beta?: number;
+        topPaths?: number;
+        /** 'symmetric'（默认）= 联系紧密度；'directed' = 关注/影响传播度 */
+        mode?: ScoreMode;
+        /**
+         * 内部优化：复用调用方已加载的 snapshot，跳过本函数内的 `store.loadAll()`。
+         * 仅在 consolidate 等批量场景使用——上层保证 snapshot 在批处理期间不变。
+         * 公共 API 调用者不要传，让本函数自己加载以获取最新数据。
+         */
+        _snapshot?: RelationGraphSnapshot;
+    }): Promise<{
+        fromId: string;
+        toId: string;
+        mode: ScoreMode;
+        score: number;
+        rawScore: number;
+        katzScore: number;
+        commonNeighborsScore: number;
+        pathsConsidered: number;
+        shortestLength: number | null;
+        directlyConnected: boolean;
+        /** 仅 symmetric 模式同时利用；directed 模式 backward* 固定 0 */
+        forwardKatzScore: number;
+        backwardKatzScore: number;
+        topPaths: Array<{
+            direction: 'forward' | 'backward';
+            nodes: Array<PersonNode | EventNode | EntityNode>;
+            edges: RelationEdge[];
+            length: number;
+            weightProduct: number;
+            contribution: number;
+        }>;
+        commonNeighbors: Array<{
+            node: PersonNode | EventNode | EntityNode;
+            degree: number;
+            aaContribution: number;
+        }>;
+    }>;
+    /**
+     * 按关键词搜索事件（substring，标题 + summary，不区分大小写）。
+     * - days：仅返回 lastReinforcedAt 在 N 天内的事件；0/未传 → 不限
+     * - limit：返回上限（默认 20）
+     */
+    searchEvents(opts: {
+        keyword?: string;
+        days?: number;
+        limit?: number;
+    }): Promise<EventNode[]>;
+    /**
+     * 按关键词搜索人物。匹配 displayName / userId / aliases / id（substring，不区分大小写）。
+     * - platform：可选，仅返回该平台下的人物
+     * - limit：返回上限（默认 20）
+     */
+    searchPersons(opts: {
+        keyword?: string;
+        platform?: string;
+        limit?: number;
+    }): Promise<PersonNode[]>;
+    /**
+     * 按关键词搜索实体。匹配 name / aliases / summary / id（substring，不区分大小写）。
+     * - kind：可选，仅返回指定 entityKind
+     * - limit：返回上限（默认 20）
+     */
+    searchEntities(opts: {
+        keyword?: string;
+        kind?: EntityNode['entityKind'];
+        limit?: number;
+    }): Promise<EntityNode[]>;
+    /**
+     * 列出符合过滤条件的边。所有过滤器是 AND 关系；不传任何过滤器 = 返回全部（受 limit 限制）。
+     * - kinds：边大类（person-event / person-person / person-entity / event-event / event-entity / entity-entity）
+     * - relationTypes：仅对带 relationType 的边生效（person-person / event-event / event-entity / entity-entity）
+     * - roles：仅对带 role 的边生效（person-event / person-entity）
+     * - nodeId：边的任一端等于该 id（用于"这条边和某节点相关"）
+     * - fromId/toId：方向敏感（注意无向边的 from/to 由 LLM 提取时给定，未必符合直觉）
+     * - days：仅返回 lastReinforcedAt 在 N 天内的；0/未传 → 不限
+     * - limit：返回上限（默认 50）
+     * 按 lastReinforcedAt 降序。
+     */
+    listEdges(opts: {
+        kinds?: RelationEdge['kind'][];
+        relationTypes?: string[];
+        roles?: string[];
+        nodeId?: string;
+        fromId?: string;
+        toId?: string;
+        days?: number;
+        limit?: number;
+    }): Promise<RelationEdge[]>;
+    /**
+     * 时间线：给定节点，返回与其相关的事件按时间倒序排列。
+     * - 节点是 person → 返回该人参与的事件（按 personEvent.lastReinforcedAt 降序）
+     * - 节点是 entity → 返回涉及该实体的事件（按 eventEntity.lastReinforcedAt 降序）
+     * - 节点是 event → 返回该事件 + 由 event-event 边相连的相关事件
+     * 返回每个事件附带触达它的边信息（用于追溯"为什么相关"）。
+     */
+    getTimeline(opts: {
+        nodeId: string;
+        days?: number;
+        limit?: number;
+    }): Promise<Array<{
+        event: EventNode;
+        viaEdge: RelationEdge;
+    }>>;
+    consolidate(opts?: {
+        autoLink?: boolean;
+        /** 可选：传入后 consolidate 末尾会调用 LLM 做别名核验与摘要重写 */
+        llm?: {
+            ctx: Context;
+            modelRef: ModelRef;
+            disableThinking?: boolean;
+        };
+        /** 调用来源标识，仅用于 getLastConsolidateInfo() 报告。默认 api。 */
+        triggerSource?: 'manual' | 'eviction' | 'api';
+        /**
+         * (1.5) 宽召回 LLM 性能优化：
+         * - skipLowScorePairs：若 true，pair 双方 compositeScore 均 < lowScoreThreshold 时跳过 LLM 核验
+         *   （两端都是 edge tier，合并价值低，不值得花 LLM 调用），默认 true。
+         * - lowScoreThreshold：阈值，默认 0.2（与 scoreToTier 的 edge 边界一致）。设 0 = 不跳过。
+         */
+        skipLowScorePairs?: boolean;
+        lowScoreThreshold?: number;
+        /**
+         * Entity 宽召回的 embedding cos 阈值，默认 0.86。
+         * 仅在 `ctx.getService('embedding')` 可用时生效；name+summary embed 后 cos≥该值即作为额外候选。
+         * 设 0 = 关闭（依然走 substring/alias 路径）。
+         */
+        entityCosThreshold?: number;
+        /**
+         * 可选 ctx。若传入则 consolidate 会顺带做一次「伪 person 自动清理」：
+         * platform 不在 `getPlatformNames(ctx)` 运行时白名单内（或 userId 命中
+         * 通用占位 self/me/bot/assistant）的 person，连同级联边一起删除。
+         * 与写入守卫 `isPlaceholderSelfPersonId` 共用同一谓词，口径一致。
+         *
+         * 警告：临时禁用了某个 adapter 时（白名单收缩），这里会把对应平台的
+         * **真实历史 person** 误判为 fake。`getPlatformNames(ctx)` 为空时本步骤
+         * 自动跳过以保护历史数据。
+         */
+        ctx?: Context;
+    }): Promise<{
+        aliasCandidates: Array<{
+            aId: string;
+            bId: string;
+            aKind: 'person' | 'entity';
+            bKind: 'person' | 'entity';
+            reason: string;
+        }>;
+        aliasEdgesCreated: number;
+        partOfEdgesCreated: number;
+        eventEdgesNormalized: number;
+        entityHierarchyCandidates: number;
+        entityHierarchyEdgesCreated: number;
+        llmVerified?: number;
+        llmRejected?: number;
+        summariesRewritten?: number;
+        lateralParentCandidates: number;
+        lateralParentsCreated: number;
+        lateralEdgesCreated: number;
+        /** 自动清理删掉的伪 person 数（platform 不在白名单或 userId 为通用占位）。 */
+        fakePersonsDeleted: number;
+        /** 自动清理时级联删的 person-* 边总数。 */
+        fakePersonEdgesDeleted: number;
+        /** event 重复合并：召回候选数（pair 数，dry-run 报告用） */
+        eventDuplicateCandidates: number;
+        /** event 重复合并：实际合并的 event 数（被合并到 canonical 的别名 event 数） */
+        eventDuplicatesMerged: number;
+    }>;
+    /**
+     * 内部入口：执行一次 event 重复检测；可选 dryRun 仅返回候选不合并。
+     *
+     * 召回融合公式（任一阈值达成即进 LLM，OR 关系）：
+     *  - 有 embedding 时：fused = 0.7·cos + 0.3·struct ≥ fusedThreshold（默认 0.7）；
+     *    任一端 embedding 失败 → 该项不参与 fused，仅看 jaccard / struct
+     *  - 永远兜底：jaccard(chars) ≥ jaccardThreshold(默认 0.4) **或** struct ≥ structuralThreshold(默认 0.5)
+     *
+     *  cos 与 struct 权重对换的原因：标题/语义高度相似但孤立（无共邻边）的事件对在旧公式
+     *  0.3·cos+0.7·struct 下永远 fused≈0 → 阈值不达 → 不进 LLM。文本相似度才是 event 同一性
+     *  的主要信号，结构作为加成。
+     *
+     * sessionScope 隔离：
+     *  - 同 scope 池内才比对（含「都 'global'」、「同 sessionId」、「都 undefined → 兜底当 'global'」）；
+     *  - 跨 scope 永不比对，与 L537 mergeAlias 硬护栏一致
+     *
+     * Lazy embed：当 EventNode.embeddingHash !== computeEventEmbeddingHash(title, summary) 时，
+     *  实时调 embedding.embed() 并写回（持久化），下次 consolidate 复用。
+     */
+    private _consolidateEventDuplicates;
+    /**
+     * 公开 API：dry-run 查找 event 重复（不执行任何合并）。
+     * 给 `/relation event-duplicates` 命令 / webui 调用使用。
+     *
+     * 与 consolidate 行为口径完全一致：sessionScope 同池 + 加权融合阈值 + mergeReject 缓存复用 + LLM 终判。
+     * 但不写图，仅返回候选 + LLM 判定。
+     */
+    findEventDuplicates(opts?: {
+        llm?: {
+            ctx: Context;
+            modelRef: ModelRef;
+            disableThinking?: boolean;
+        };
+        fusedThreshold?: number;
+        jaccardThreshold?: number;
+        structuralThreshold?: number;
+    }): Promise<{
+        candidates: Array<{
+            aId: string;
+            bId: string;
+            aTitle: string;
+            bTitle: string;
+            sessionScope: string;
+            cosineScore: number | null;
+            jaccardScore: number;
+            structuralScore: number;
+            fusedScore: number | null;
+            llmVerdict?: {
+                isSame: boolean;
+                reason: string;
+            };
+            cacheHit?: boolean;
+        }>;
+        llmVerified: number;
+        llmRejected: number;
+        llmRejectCacheHits: number;
+        embeddingAvailable: boolean;
+    }>;
+    renameNode(opts: {
+        kind: 'event' | 'entity';
+        id: string;
+        newName: string;
+        /** 调用来源标识：'llm' / 'manual' / 'consolidate' 等；默认 'manual' */
+        by?: string;
+        /** 改名理由（≤80 字），写入 audit log */
+        reason?: string;
+    }): Promise<{
+        from: string;
+        to: string;
+        aliasesAdded: boolean;
+    }>;
+    /**
+     * 关系边修正：LLM 发现某条边过弱 / 过强 / 是幻觉时调用。
+     *
+     * 设计原则（小破坏性 + 高效修正）：
+     * - **阶梯保护**：weight 越高越难物理删除，避免误删强关系
+     *   - weight ≥ 0.5：只允许 weaken；想 remove 需先反复 weaken 到 < 0.5（或 force=true）
+     *   - 0.3 ≤ weight < 0.5：可 weaken 或 remove
+     *   - weight < 0.3：自由（含 strengthen 重建）
+     * - **alias 边禁操作**：is-alias-of / alt-account-of 是结构性边，
+     *   修改会破坏 mergeAlias 不变量。需取消别名请走未来的 splitAlias 工具。
+     * - **必填 reason**（≤80 字），写入 weightHistory[] 留痕
+     * - **物理删除清理干净**：deleteEdge 直接落盘，不留墓碑（避免脏数据）
+     *
+     * 不接受 multiplier > 1 的 weaken / multiplier < 1 的 strengthen
+     * （语义错位会让 LLM 误用）。
+     */
+    correctEdge(opts: {
+        edgeId: string;
+        action: 'weaken' | 'strengthen' | 'remove';
+        /** weaken 默认 0.5；strengthen 默认 1.5；remove 忽略 */
+        multiplier?: number;
+        reason: string;
+        /** 调用来源标识，默认 'llm' */
+        by?: string;
+        /** true → 跳过阶梯保护（仅 manual / 系统纠错使用） */
+        force?: boolean;
+    }): Promise<{
+        action: 'weakened' | 'strengthened' | 'removed';
+        edgeId: string;
+        from: number;
+        to: number;
+        edge?: RelationEdge;
+    }>;
+    mergeAlias(opts: {
+        aliasId: string;
+        canonicalId: string;
+        kind: 'person' | 'entity' | 'event';
+        /** 若为 true，不做启发式校正，强制按传入方向 */
+        noCanonicalCorrection?: boolean;
+    }): Promise<{
+        effectiveCanonicalId: string;
+        effectiveAliasId: string;
+        edgesRewritten: number;
+        edgesMerged: number;
+        edgesDeleted: number;
+        swapped: boolean;
+        /** alias 节点是否被物理删除（即"真合并"是否完成）。person 当前总为 true（无 aliases 字段需合并） */
+        aliasDeleted: boolean;
+    }>;
+    /**
+     * 物理删除 event / entity 节点（级联删边）。Person 节点禁用。
+     * 保护门：weight ≥ 0.8 或 evidence.length ≥ 5 直接拒绝。
+     */
+    deleteNode(opts: {
+        kind: 'event' | 'entity';
+        id: string;
+        reason: string;
+        by?: string;
+    }): Promise<{
+        kind: 'event' | 'entity';
+        id: string;
+        deletedEdges: number;
+    }>;
+    private _assertNodeDeletable;
+    /**
+     * consolidate hierarchy 守门用：若 child→parent 的 entity-entity[part-of] 边缺失则新建；
+     * 已存在（任一方向：part-of 或反向 contains）则跳过，返回 false。
+     * 不强化既有边、不做证据合并——hierarchy 守门只负责"不被错误地 alias-merge 掉"，
+     * 后续走正规 inferEntityHierarchy / extractor 写边路径补全/强化。
+     */
+    private _upsertPartOfEdgeIfAbsent;
+    /**
+     * 物理删除一条边（带保护门，供 agent 调用）。alias 边（is-alias-of / alt-account-of）禁删；
+     * weight ≥ 0.8 或 evidence ≥ 5 拒绝（请先 correctEdge weaken）。
+     *
+     * 注：与旧 deleteEdge(edgeId)（无保护，供 consolidate 内部使用）区别开。
+     */
+    deleteEdgeWithGuard(opts: {
+        edgeId: string;
+        reason: string;
+        by?: string;
+    }): Promise<{
+        edgeId: string;
+        kind: string;
+        relationType: string;
+        weight: number;
+    }>;
+    /**
+     * 物理合并：把 aliasIds 全部并入 canonicalId，并物理删除 aliasIds。
+     * 仅支持 event / entity（person 合并请走 mergeAlias，保留 alias 标记边）。
+     *
+     * 内部分两步：
+     *  1) 复用 mergeAlias 把每个 alias 的边改写到 canonical（保留同名 alias 标记边以便回溯）；
+     *  2) 物理删除 alias 节点本身（cascade 顺手清理残留的 alias 标记边）。
+     */
+    mergeNodes(opts: {
+        kind: 'event' | 'entity';
+        canonicalId: string;
+        aliasIds: string[];
+        reason: string;
+        by?: string;
+    }): Promise<{
+        canonicalId: string;
+        mergedAliasIds: string[];
+        totalEdgesRewritten: number;
+        totalEdgesMerged: number;
+        totalEdgesDeleted: number;
+    }>;
+    /**
+     * 修改 entity 的 kind（topic/place/thing/work）。轻量操作，仅写入字段 + audit。
+     * 不变更 id，所有引用边 0 风险。
+     */
+    changeEntityKind(opts: {
+        entityId: string;
+        newKind: EntityKind;
+        reason: string;
+        by?: string;
+    }): Promise<{
+        entityId: string;
+        from: EntityKind;
+        to: EntityKind;
+    }>;
+    /**
+     * 从 entity 的 aliases[] 中剥离一个错误绑定的别名（轻量纠错）。
+     *
+     * 使用场景：consolidate 把一个不该并入 canonical 的别名错误合并了，
+     * 导致 canonical 的 aliases 里出现了一个本不属于它的名字（如把母概念错并入子概念，
+     * 母概念的名字残留为子概念的 alias）。本方法只把该名字从 aliases 中移除——
+     * **不会**重建出当初被合并掉的 entity 节点（那个节点已被物理删除，证据已迁移）。
+     * 之后 extractor 在新对话中再次看到该名字时，会自然地新建一个新 entity 节点。
+     *
+     * 不变更：name / 边 / evidence / nameHistory（不动 nameHistory：renameNode 才追写）。
+     * 别名匹配按 trim 后字符串等价（不区分大小写不在此处处理；如有需要由调用方先归一）。
+     */
+    splitAlias(opts: {
+        entityId: string;
+        aliasName: string;
+        reason: string;
+        by?: string;
+    }): Promise<{
+        entityId: string;
+        removed: string;
+        remainingAliases: string[];
+    }>;
+    /**
+     * 计算单个节点的「综合活跃度评分 + 排名 + 分级」，供 agent 快速判断节点份量。
+     *
+     * 返回字段语义：
+     *   - compositeScore: 0..1 综合分（pagerank 0.4 + edgeWeight 0.3 + recency 0.2 + degree 0.1）
+     *   - tier: 'core' | 'active' | 'normal' | 'edge'，绝对分 + 同 kind 百分位双门槛分级
+     *   - rankInKind / rankInGlobal: 'k/N' 字符串，按 compositeScore 降序，1=最高
+     *   - percentileInKind / percentileInGlobal: 0..1，0.95=前 5%，越大越中心
+     *   - pagerankFresh: false=节点从未参与过 PR 计算（lastPageRankAt=0），pagerank=0 不代表"边缘"
+     *   - 其它字段：相关邻居计数 / 入边权 / pagerank 快照 / evidence 数 / 距上次强化天数
+     *
+     * 复杂度：O(N) 全图扫描，N=节点总数（几百到几千可接受；如果发现卡顿可加节点缓存）。
+     */
+    computeNodeScore(nodeId: string): Promise<{
+        nodeId: string;
+        kind: 'person' | 'event' | 'entity';
+        name: string;
+        relatedPeople: number;
+        relatedEvents: number;
+        relatedEntities: number;
+        maxIncomingEdgeWeight: number;
+        avgIncomingEdgeWeight: number;
+        pagerank: number;
+        pagerankFresh: boolean;
+        evidenceCount: number;
+        daysSinceLastReinforced: number;
+        compositeScore: number;
+        tier: 'core' | 'active' | 'normal' | 'edge';
+        rankInKind: string;
+        rankInGlobal: string;
+        percentileInKind: number;
+        percentileInGlobal: number;
+    } | null>;
+    /**
+     * 内部：单节点综合分计算（不含排名）。抽出复用：computeNodeScore 与 actions graph_data。
+     */
+    _computeSingleNodeScore(nodeId: string, snap: {
+        persons: PersonNode[];
+        events: EventNode[];
+        entities: EntityNode[];
+        edges: RelationEdge[];
+    }): {
+        nodeId: string;
+        kind: 'person' | 'event' | 'entity';
+        name: string;
+        relatedPeople: number;
+        relatedEvents: number;
+        relatedEntities: number;
+        maxIncomingEdgeWeight: number;
+        avgIncomingEdgeWeight: number;
+        pagerank: number;
+        pagerankFresh: boolean;
+        evidenceCount: number;
+        daysSinceLastReinforced: number;
+        compositeScore: number;
+    } | null;
+    /**
+     * 计算节点的「邻居剖面」：返回每类邻居 (人/事件/实体) 的 **总数 + top-K {name, weight}**。
+     * 用于 consolidate verifyAliasPair / verifyEventPair 给 LLM 提供更丰富的邻居证据。
+     *
+     * - weight 取节点对之间所有边的 weight 之和（同一对实体可能既是 mentioned 又是 enthusiast）
+     * - 排序：weight 倒序；同权按 name 升序保证可复现
+     * - 名字截断到 24 字以控制 prompt 体积
+     * - 命中不存在的 otherId（被删/孤立）→ 跳过
+     */
+    _computeNeighborProfile(nodeId: string, snap: {
+        persons: PersonNode[];
+        events: EventNode[];
+        entities: EntityNode[];
+        edges: RelationEdge[];
+    }, topK?: number): {
+        peopleCount: number;
+        eventCount: number;
+        entityCount: number;
+        topPeople: Array<{
+            name: string;
+            weight: number;
+        }>;
+        topEvents: Array<{
+            name: string;
+            weight: number;
+        }>;
+        topEntities: Array<{
+            name: string;
+            weight: number;
+        }>;
+    };
+    /**
+     * 计算节点的「方向性出入度剖面」：返回 outByType / inByType / dominance / fanIdolHint。
+     *
+     * 仅统计 **有向的主体边**（person-person / event-event / entity-entity 且 directed=true）。
+     * 桥型边（person-event / person-entity / event-entity）按设计天然双向，是"参与"不是"指代"，
+     * 不计入此剖面。
+     *
+     * 返回的 `outByType` 含义：节点作为 from 端发出的边（"我主动指向谁"），按 relationType 分桶；
+     * `inByType`：节点作为 to 端接收的边（"谁指向我"）。每个桶含 count / totalWeight / top-K 对端节点。
+     *
+     * `dominance` 启发式判断：
+     * - outTotal - inTotal >= 2 且 outTotal/inTotal >= 1.5 → 'outgoing'（更偏向"主动方"，如典型粉丝/学生）
+     * - inTotal - outTotal >= 2 且 inTotal/outTotal >= 1.5 → 'incoming'（更偏向"被指方"，如典型偶像/导师）
+     * - 否则 'balanced'
+     *
+     * `fanIdolHint` 专门拎出 admirer 关系：fansCount = 入度 admirer（多少人 admire 我），
+     * idolsCount = 出度 admirer（我 admire 多少人）。verdict 给出粗判。
+     */
+    computeDirectionalDegree(nodeId: string, options?: {
+        topPerType?: number;
+    }): Promise<{
+        nodeId: string;
+        kind: 'person' | 'event' | 'entity';
+        name: string;
+        outTotal: number;
+        inTotal: number;
+        outByType: Record<string, {
+            count: number;
+            totalWeight: number;
+            top: Array<{
+                otherId: string;
+                otherName: string;
+                weight: number;
+                kind: 'person' | 'event' | 'entity';
+            }>;
+        }>;
+        inByType: Record<string, {
+            count: number;
+            totalWeight: number;
+            top: Array<{
+                otherId: string;
+                otherName: string;
+                weight: number;
+                kind: 'person' | 'event' | 'entity';
+            }>;
+        }>;
+        dominance: 'outgoing' | 'incoming' | 'balanced';
+        fanIdolHint: {
+            fansCount: number;
+            idolsCount: number;
+            verdict: 'idol-leaning' | 'fan-leaning' | 'mutual' | 'none';
+        };
+    } | null>;
+    /**
+     * 同社群活跃成员（Louvain 社群标签由 evictByQuota 写入；未跑过则返回空）。
+     *
+     * 用途：profile 注入 / agent 工具——「跟 X 同一个圈子的高活跃成员是谁」。
+     *
+     * - personId 必须是 `<platform>:<userId>` 完整 ID；
+     * - 仅返回 person 类型的同社群成员（事件/实体也有 communityId 但用户视角无意义）；
+     * - 按 lastPageRank desc 排序，截断到 limit；
+     * - 自己不会出现在结果里；
+     * - 如果 personId 没有 communityId（节点太新或从未跑过 evict）→ communitySize=0、peers=[]。
+     */
+    getCommunityPeers(personId: string, limit?: number): Promise<{
+        personId: string;
+        communityId: string | null;
+        communitySize: number;
+        peers: Array<{
+            id: string;
+            displayName: string;
+            pagerank: number;
+            communityId: string;
+        }>;
+    }>;
+    /**
+     * 两人是否同社群 + 各自社群信息（agent 工具 community_bridge 用）。
+     *
+     * 不算路径——find_path 已有同等能力，重复实现徒增维护。
+     */
+    getCommunityBridge(personAId: string, personBId: string): Promise<{
+        a: {
+            id: string;
+            displayName: string;
+            communityId: string | null;
+            communitySize: number;
+        };
+        b: {
+            id: string;
+            displayName: string;
+            communityId: string | null;
+            communitySize: number;
+        };
+        sameCommunity: boolean;
+    }>;
+    /**
+     * 全图社群概览：按 community 分组，每组列 top 成员/话题/事件，再算 modularity Q 和"桥梁人"。
+     *
+     * 设计要点：
+     * - `algorithm` 不传默认实时跑一遍 Louvain；传 'leiden' 跑 Leiden-lite；传 'slpa' 跑 SLPA（原生重叠）。
+     *   **不读节点上的 communityId 缓存**，保证每次调用结果与当前快照严格一致（即使 evictByQuota 还没跑）。
+     * - `sessionScope` 是**后过滤**：先在全图上跑社群算法（保证社群划分准确），再只统计 evidence 含该 scope
+     *   的节点，避免把"跨群关系"切断。
+     * - 每个节点的**分组归属**始终按"主社群"（memberships[0].id，即 SLPA 下 weight 最高的 label）；
+     *   保持 topMembers/Topics/Events 语义清晰，避免一个节点在多社群重复出现稀释 LLM 注意力。
+     * - `topN`：每个社群展示的成员/话题/事件条数。默认动态：log2 自适应。传 0 = 不限。
+     * - `bridges`：跨社群联系最广的 top-K person。`crossCommunityDegree` = 邻居中不在该 person 自身**任一**社群
+     *   隶属里的"外社群"个数（SLPA 下自然把跨群人物的多归属考虑进去）；`communityWeights` 给出按"外社群"分组的
+     *   邻居边权累计（边越重 / 邻居越多 → weight 越大），供 LLM 判断该桥梁人物的跨群强度分布。
+     *
+     * Q（modularity）值粗判：Q > 0.3 = 圈子分明；0.1 ~ 0.3 = 一般；< 0.1 = 接近随机划分。
+     * SLPA 下 Q 用"主社群"作为硬划分近似计算，仅作参考——重叠社区没有标准 modularity 定义。
+     */
+    getCommunityOverview(opts?: {
+        sessionScope?: string;
+        /** 0 = 不限 */
+        topN?: number;
+        /** 不传则跑 louvain；可临时切 leiden 或 slpa */
+        algorithm?: 'louvain' | 'leiden' | 'slpa';
+        /**
+         * Louvain/Leiden 分辨率 γ：默认 1.0（标准模块度）。
+         * - γ > 1：划得更细 → 社群数变多、单社群更小
+         * - γ < 1：划得更粗 → 社群数变少、单社群更大
+         * 常用范围 0.5 ~ 3.0。超出 [0.01, 100] 会被夹紧。
+         * **SLPA 不使用该参数**（SLPA 的粒度由阈值 r 控制，本服务暂不暴露）。
+         *
+         * 传 `'auto'` 启用图规模自适应（推荐）：γ = clamp(0.6, 2.5, 0.5 + log10(n / 30))。
+         * 详见 `computeAdaptiveResolution`。数值默认仍为 1.0，向后兼容。
+         */
+        resolution?: number | 'auto';
+    }): Promise<{
+        algorithm: 'louvain' | 'leiden' | 'slpa';
+        /**
+         * 本次实际生效的 γ。SLPA 下为 `null`（不使用）。
+         * `resolutionMode='auto'` 时为 `computeAdaptiveResolution(snap)` 的输出；
+         * `'explicit'` 时为调用方传入的数值；`'default'` 时为 1.0。
+         */
+        effectiveResolution: number | null;
+        resolutionMode: 'auto' | 'explicit' | 'default';
+        numCommunities: number;
+        /** SLPA 下基于主社群的硬划分近似 modularity，仅供参考。 */
+        modularity: number;
+        totalPersonsInScope: number;
+        totalEventsInScope: number;
+        totalEntitiesInScope: number;
+        communities: Array<{
+            communityId: string;
+            size: number;
+            topMembers: Array<{
+                id: string;
+                displayName: string;
+                pagerank: number;
+            }>;
+            topTopics: Array<{
+                id: string;
+                name: string;
+                pagerank: number;
+            }>;
+            topEvents: Array<{
+                id: string;
+                title: string;
+                weight: number;
+                sessionScope?: string;
+            }>;
+        }>;
+        bridges: Array<{
+            id: string;
+            displayName: string;
+            /** 该 person 自身的主社群（SLPA 下即权重最高的 label） */
+            communityId: string;
+            /** SLPA 下该 person 的全部社群隶属度（按 weight 降序）；louvain/leiden 永远单元素 */
+            communityMemberships: CommunityMembership[];
+            /** 邻居中不在自身任一社群隶属里的"外社群"个数（向下兼容老消费方） */
+            crossCommunityDegree: number;
+            /**
+             * 按"外社群"分组的邻居边权累计（按 weight 降序）。weight = ∑(邻居边权 × 邻居在该外社群的隶属度)。
+             * 用这个字段判断桥梁人物在每个跨群方向上的强度分布；degree 只告诉数量，weights 告诉力度。
+             */
+            communityWeights: Array<{
+                communityId: string;
+                weight: number;
+            }>;
+        }>;
+    }>;
+}
+/**
+ * compositeScore + 同 kind 百分位双门槛分级。绝对分给"够亮"的小图节点保底，
+ * 百分位给"大图但绝对分都低"的相对核心节点保底。
+ */
+export declare function scoreToTier(score: number, percentile: number): 'core' | 'active' | 'normal' | 'edge';
+//# sourceMappingURL=service.d.ts.map