@whispering233/ai-editor-tools 0.0.1

package/dist/analysis/path.d.ts

@@ -0,0 +1,23 @@
+import type { ToolContext } from "../context.js";
+import type { TracePlotPathsArgs } from "@whispering233/ai-editor-shared";
+/** 路径节点（tools.md trace_plot_paths paths[].nodes 项；type/id/name 与 relation 路径同构） */
+export interface PlotPathNode {
+    type: string;
+    id: string;
+    name: string;
+}
+/** 一条剧情路径（tools.md trace_plot_paths paths[] 项） */
+export interface PlotPath {
+    nodes: PlotPathNode[];
+    description: string;
+    risk_factors: string[];
+}
+/**
+ * 剧情路径推演（tools.md trace_plot_paths(from_node_id, to_node_id)）。
+ * 输出 paths（树路径优先，随后连线路径）；两节点不存在/已软删 → null（查询无结果）。
+ * signal：连线路径遍历为长任务候选，循环中检查（决策 16 ③）。
+ */
+export declare function runTracePlotPaths(ctx: ToolContext, args: TracePlotPathsArgs, signal?: AbortSignal): {
+    paths: PlotPath[];
+} | null;
+//# sourceMappingURL=path.d.ts.map

package/dist/analysis/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/analysis/path.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAsED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GAAG,IAAI,CAwChI"}

package/dist/analysis/path.js

@@ -0,0 +1,114 @@
+// 分析类工具：trace_plot_paths（剧情路径推演，S6.4）
+// 契约来源：doc/api/tools.md「路径分析」→ { paths: [{ nodes: [], description, risk_factors: [] }] }
+// 语义：从 from_node_id 到 to_node_id 推演可能的剧情路径——两类来源：
+// 1. **树路径**：两节点在大纲树同一分支（祖先后裔关系）→ 沿树的直接推进链（决策 19 严格三层下唯一）
+// 2. **连线路径**：沿 plot_edge 剧情连线（决策 10 画布连线）从 from 出发的 k 跳路径（depth=3）
+// 风险因素（risk_factors，从节点属性推导）：路径过长（≥5 节点）、途经 scene 缺 goal、
+//   途经 chapter 缺 reversal、路径经过软删节点（手改树的不一致形态）。
+// 数据访问：db 查询层（listRelations plot_edge）+ outline.json 读取（树路径），无原生 SQL。
+import { findOutlineNode, getOutlinePathIds, listRelations, readOutlineFile } from "@whispering233/ai-editor-db";
+import { throwIfAborted } from "./utils.js";
+/** 节点信息（type/id/name=title；root 防御：name 用 "root" 占位） */
+function nodeInfo(node, id) {
+    if (node === undefined)
+        return { type: "outline_node", id, name: id }; // 脏引用防御（树外 id）
+    return { type: node.type, id: node.id, name: node.title };
+}
+/**
+ * 树路径推导：若 from 是 to 的祖先 → 顺向链（from → to）；若 to 是 from 的祖先 → 回溯链（from → to）。
+ * 两节点在不同分支（无祖先后裔关系）→ null（无树路径，靠连线路径）。
+ * root 非可寻址大纲节点 → null。
+ */
+function treeSubPath(tree, fromId, toId) {
+    if (fromId === "root" || toId === "root")
+        return null;
+    let fromPath;
+    let toPath;
+    try {
+        fromPath = getOutlinePathIds(tree, fromId);
+        toPath = getOutlinePathIds(tree, toId);
+    }
+    catch {
+        return null; // 节点不存在（getOutlinePathIds 抛错语义）
+    }
+    const fromIdx = toPath.indexOf(fromId); // from 在 to 的路径上（from 是 to 祖先）
+    if (fromIdx !== -1) {
+        return { nodes: toPath.slice(fromIdx).map((id) => nodeInfo(findOutlineNode(tree, id), id)), backward: false };
+    }
+    const toIdx = fromPath.indexOf(toId); // to 在 from 的路径上（to 是 from 祖先）
+    if (toIdx !== -1) {
+        return { nodes: fromPath.slice(toIdx).reverse().map((id) => nodeInfo(findOutlineNode(tree, id), id)), backward: true };
+    }
+    return null; // 不同分支
+}
+/**
+ * 风险因素收集（树路径与连线路径共用）：从节点属性推导推进风险。
+ * - 路径过长（≥4 节点）→ 中段易拖沓（连线路径 3 跳 = depth=3 推演上限，已达全量深度；
+ *   树路径最多 3 层不触发）
+ * - scene 缺 data.goal（麦基字段集，决策 23）→ 场景缺乏目标
+ * - chapter 缺 data.reversal → 章节缺乏反转
+ * - 途经软删节点（手改 outline.json 的不一致形态）→ 数据不一致
+ */
+function collectRiskFactors(tree, nodes) {
+    const risks = [];
+    if (nodes.length >= 4) {
+        risks.push(`路径过长（${nodes.length} 个节点），中段易拖沓，建议拆分为多幕推进`);
+    }
+    for (const n of nodes) {
+        const node = findOutlineNode(tree, n.id);
+        if (node === undefined) {
+            risks.push(`路径经过不存在的节点 ${n.id}（数据不一致）`);
+            continue;
+        }
+        if (node.type === "scene" && node.data?.goal === undefined) {
+            risks.push(`场景「${node.title}」未定义目标（goal），推进缺乏动机`);
+        }
+        if (node.type === "chapter" && node.data?.reversal === undefined) {
+            risks.push(`章「${node.title}」未定义反转（reversal），高潮乏力`);
+        }
+        if (node.deleted === true) {
+            risks.push(`路径经过已软删节点「${node.title}」（数据不一致，建议先还原）`);
+        }
+    }
+    return risks;
+}
+/**
+ * 剧情路径推演（tools.md trace_plot_paths(from_node_id, to_node_id)）。
+ * 输出 paths（树路径优先，随后连线路径）；两节点不存在/已软删 → null（查询无结果）。
+ * signal：连线路径遍历为长任务候选，循环中检查（决策 16 ③）。
+ */
+export function runTracePlotPaths(ctx, args, signal) {
+    const tree = readOutlineFile(ctx.outlineDir);
+    const from = findOutlineNode(tree, args.from_node_id);
+    const to = findOutlineNode(tree, args.to_node_id);
+    if (from === undefined || from.deleted === true || to === undefined || to.deleted === true)
+        return null;
+    throwIfAborted(signal);
+    const paths = [];
+    // 1. 树路径（唯一性：严格三层下同分支路径唯一，决策 19）
+    const treePath = treeSubPath(tree, args.from_node_id, args.to_node_id);
+    if (treePath !== null) {
+        paths.push({
+            nodes: treePath.nodes,
+            description: treePath.backward
+                ? `沿大纲树回溯（${args.from_node_id} → ${args.to_node_id}）：共 ${treePath.nodes.length} 个节点`
+                : `沿大纲树直接推进（${args.from_node_id} → ${args.to_node_id}）：共 ${treePath.nodes.length} 个节点`,
+            risk_factors: collectRiskFactors(tree, treePath.nodes),
+        });
+    }
+    // 2. plot_edge 连线路径（决策 10 画布连线；有向 BFS 沿 source→target，depth=3 上限）
+    const edgeResult = listRelations(ctx.db, { relationType: "plot_edge", sourceId: args.from_node_id }, 3, ctx.outlineDir);
+    for (const p of edgeResult.paths ?? []) {
+        throwIfAborted(signal);
+        const last = p.nodes[p.nodes.length - 1];
+        if (last === undefined || last.id !== args.to_node_id)
+            continue; // 只取终点 = to 的路径
+        paths.push({
+            nodes: p.nodes.map((n) => ({ type: n.type, id: n.id, name: n.name })),
+            description: `沿剧情连线（plot_edge）推进：共 ${p.nodes.length - 1} 跳`,
+            risk_factors: collectRiskFactors(tree, p.nodes),
+        });
+    }
+    return { paths };
+}
+//# sourceMappingURL=path.js.map

package/dist/analysis/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/analysis/path.ts"],"names":[],"mappings":"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"}

package/dist/analysis/suggest.d.ts

@@ -0,0 +1,19 @@
+import type { ToolContext } from "../context.js";
+import type { SuggestConnectionsArgs } from "@whispering233/ai-editor-shared";
+/** 潜在关联建议（tools.md suggest_connections 返回项） */
+export interface ConnectionSuggestion {
+    target_id: string;
+    /** 建议的关系类型（预定义枚举；用户确认后可建立） */
+    relation_type: string;
+    reason: string;
+}
+/**
+ * 潜在关系发现（tools.md suggest_connections(entity_id)）。
+ * 实体不存在/已软删 → null（查询无结果）；同类型无其他实体 → 空建议。
+ * 信号优先级：共享场景（S1）> 共同邻居（S2），每候选最多一条建议（取最强信号）；
+ * 软删对象不可见（查询层默认过滤，决策 12）；已有直接关系的候选跳过。
+ */
+export declare function runSuggestConnections(ctx: ToolContext, args: SuggestConnectionsArgs, signal?: AbortSignal): {
+    suggestions: ConnectionSuggestion[];
+} | null;
+//# sourceMappingURL=suggest.d.ts.map

package/dist/analysis/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/analysis/suggest.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG;IAAE,WAAW,EAAE,oBAAoB,EAAE,CAAA;CAAE,GAAG,IAAI,CAyE1J"}

package/dist/analysis/suggest.js

@@ -0,0 +1,92 @@
+// 分析类工具：suggest_connections（潜在关系发现，S6.4）
+// 契约来源：doc/api/tools.md「关系发现」→ { suggestions: [{ target_id, relation_type, reason }] }
+// 语义：为指定实体发现与同类型其他实体的潜在关联（启发式信号）：
+// - S1 共享场景（强信号）：两角色共同 appears_in 于同一大纲节点（同场戏出现过）
+// - S2 共同邻居（次信号）：两实体在实体关系图中共享直接关联实体（「朋友的朋友」）
+// 已存在直接关系的候选跳过；建议按信号强度降序取 top 10；relation_type 建议
+// ally（同场戏相识）/ ally（经中间人相识）。
+// 数据访问：db 查询层（getEntity/listEntities/listRelations）+ 纯函数图分析，无原生 SQL。
+// signal：全量候选 × 信号计算为长任务候选，循环中检查（决策 16 ③）。
+import { getEntity, listEntities, listRelations } from "@whispering233/ai-editor-db";
+import { buildEntityGraph, intersectSets, isEntityType, throwIfAborted } from "./utils.js";
+/** 建议条数上限（防 token 爆炸，决策 15） */
+const SUGGESTION_LIMIT = 10;
+/** 场景标题映射（outline_node 端点的 targetName 由 listRelations 联表填充） */
+function sceneTitleOf(relations, sceneId) {
+    return relations.find((r) => r.targetId === sceneId)?.targetName ?? sceneId;
+}
+/**
+ * 潜在关系发现（tools.md suggest_connections(entity_id)）。
+ * 实体不存在/已软删 → null（查询无结果）；同类型无其他实体 → 空建议。
+ * 信号优先级：共享场景（S1）> 共同邻居（S2），每候选最多一条建议（取最强信号）；
+ * 软删对象不可见（查询层默认过滤，决策 12）；已有直接关系的候选跳过。
+ */
+export function runSuggestConnections(ctx, args, signal) {
+    const entity = getEntity(ctx.db, args.entity_id);
+    if (entity === null)
+        return null;
+    throwIfAborted(signal);
+    // 1. 同类型候选（非软删，排除自身）；全量实体名映射（S2 共同邻居可能跨类型——
+    //    邻居名从全量映射取，避免退化为 id）
+    const candidates = listEntities(ctx.db, { type: entity.type, limit: 200 }).items.filter((c) => c.id !== entity.id);
+    const allEntities = listEntities(ctx.db, { limit: 200 }).items;
+    const entityName = new Map(allEntities.map((e) => [e.id, e.name]));
+    if (candidates.length === 0)
+        return { suggestions: [] };
+    // 2. 全量可见关系：实体图（共同邻居）+ appears_in 分组（共享场景）+ 直接关联集合
+    const relations = listRelations(ctx.db, {}, 1, ctx.outlineDir).relations;
+    throwIfAborted(signal);
+    const graph = buildEntityGraph(relations);
+    const appearsIn = new Map(); // 实体 id → 出现节点集合
+    const directlyLinked = new Set(); // 与目标实体已有实体-实体直接关系的候选
+    for (const r of relations) {
+        if (r.relationType === "appears_in" && isEntityType(r.sourceType) && r.targetType === "outline_node") {
+            const list = appearsIn.get(r.sourceId) ?? [];
+            list.push(r.targetId);
+            appearsIn.set(r.sourceId, list);
+        }
+        if (isEntityType(r.sourceType) && isEntityType(r.targetType)) {
+            if (r.sourceId === entity.id)
+                directlyLinked.add(r.targetId);
+            if (r.targetId === entity.id)
+                directlyLinked.add(r.sourceId);
+        }
+    }
+    const scored = [];
+    const myScenes = new Set(appearsIn.get(entity.id) ?? []);
+    const myNeighbors = new Set(graph.get(entity.id) ?? []);
+    for (const c of candidates) {
+        throwIfAborted(signal);
+        if (directlyLinked.has(c.id))
+            continue; // 已有直接关系，无需建议
+        // S1：共享场景（同场戏出现过）
+        const sharedScenes = intersectSets(myScenes, new Set(appearsIn.get(c.id) ?? []));
+        if (sharedScenes.length > 0) {
+            const sceneName = sceneTitleOf(relations, sharedScenes[0]);
+            scored.push({
+                targetId: c.id,
+                score: 100 + sharedScenes.length, // 场景信号优先于邻居信号
+                relationType: "ally",
+                reason: `与「${c.name}」共同出现于 ${sharedScenes.length} 个场景（如「${sceneName}」），可建立相识/盟友关系`,
+            });
+            continue;
+        }
+        // S2：共同邻居（「朋友的朋友」）
+        const sharedNeighbors = intersectSets(myNeighbors, new Set(graph.get(c.id) ?? []));
+        if (sharedNeighbors.length > 0) {
+            const neighborName = entityName.get(sharedNeighbors[0]) ?? sharedNeighbors[0]; // 跨类型邻居名（全量映射）
+            scored.push({
+                targetId: c.id,
+                score: sharedNeighbors.length,
+                relationType: "ally",
+                reason: `与「${c.name}」有 ${sharedNeighbors.length} 个共同关联实体（如「${neighborName}」），可经中间人建立关系`,
+            });
+        }
+    }
+    // 4. 信号强度降序 → top 10（并列按 target_id 稳定排序）
+    scored.sort((a, b) => (b.score === a.score ? a.targetId.localeCompare(b.targetId) : b.score - a.score));
+    return {
+        suggestions: scored.slice(0, SUGGESTION_LIMIT).map((s) => ({ target_id: s.targetId, relation_type: s.relationType, reason: s.reason })),
+    };
+}
+//# sourceMappingURL=suggest.js.map

package/dist/analysis/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/analysis/suggest.ts"],"names":[],"mappings":"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"}

package/dist/analysis/utils.d.ts

@@ -0,0 +1,54 @@
+import type { OutlineFileTree, RelationRecord } from "@whispering233/ai-editor-shared";
+import type { ToolContext } from "../context.js";
+/**
+ * 工具取消专用错误（决策 16 ③）：signal 中止时抛出。
+ * name = "AbortError"（与 DOMException 同名约定）——S7.4 executor 据此区分
+ * 「SSE 断开取消」（**不喂回 LLM、不计失败轮**）与「工具执行失败」（结构化喂回 LLM 自纠）。
+ */
+export declare class AbortedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 中止检查（决策 16 ③「长工具执行中检查 signal」）：
+ * 分析工具是长任务候选（全量关系/Delta 遍历），在循环中周期性调用——
+ * signal 已中止即抛 AbortedError（executor 捕获后按取消处理，不产生部分结果）。
+ */
+export declare function throwIfAborted(signal?: AbortSignal): void;
+/** 实体端点判定（relation 端点类型：character/setting/location/hook 为实体，outline_node 为大纲节点） */
+export declare function isEntityType(type: string): boolean;
+/**
+ * 无向实体邻接图：从可见关系构建「实体 id → 邻居实体 id 集合」。
+ * 只保留两端均为实体的边（appears_in 等指向大纲节点的关系不参与实体连通性）；
+ * 自环（source === target）忽略。供 detect_conflicts（对称缺失检测）与
+ * suggest_connections（共同邻居信号）复用。
+ */
+export declare function buildEntityGraph(relations: readonly RelationRecord[]): Map<string, Set<string>>;
+/** 两集合交集元素（保持第一个集合的迭代序；供共享场景/共同邻居信号使用） */
+export declare function intersectSets<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): T[];
+/**
+ * 章节序索引：一次读树 + 推导章节序，供工具内多次「节点 → 章序号」查询。
+ * 口径（决策 21）：全局**章**序号（跨卷连续累计），root → 卷 → 章先序遍历，
+ * scene 归入所属 chapter 不单独编号；节点 move 后下次构建自动更新（不落库、查询时现推）。
+ * **软删可见性（决策 12）**：软删节点视为不可见——chapterOf 返回 null（供伏笔指标/
+ * 活跃度等判定；级联软删保证其子树一并软删，无需逐祖先检查）。
+ */
+export interface ChapterIndex {
+    /** 节点 id → 全局章序号（scene 归入所属章、chapter 取自身；volume/root/不存在/**软删** → null） */
+    chapterOf(nodeId: string): number | null;
+    /**
+     * 当前章节（决策 21/hooks.md「当前章节」= project.json 的 current_position 所属章——
+     * 写作进度而非规划终点，与伏笔/孤儿工具口径一致）：
+     * 1. current_position 已设置且可推导章号 → 该章序号
+     * 2. 未设置/节点不存在/无章号 → 退化树末章（合理默认）
+     */
+    currentChapter: number | null;
+}
+/**
+ * 构建章节序索引（决策 21）。节点所属章查找：chapter 取自身序号；scene 沿父链
+ * 向上找最近 chapter（严格三层下即其父）。读一次 outline.json 支撑全量查询，
+ * 避免 N 次文件读取（getChapterNumber 逐次读文件）。
+ */
+export declare function buildChapterIndex(ctx: ToolContext): ChapterIndex;
+/** 大纲节点名称（title；节点不存在 → id 占位——脏引用防御） */
+export declare function outlineNodeName(tree: OutlineFileTree, nodeId: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/analysis/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/analysis/utils.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAmB,eAAe,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACxG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,SAAqB;CAIzC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAIzD;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAiB/F;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAM1E;AAID;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACzC;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,YAAY,CA6ChE;AAED,yCAAyC;AACzC,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG7E"}

package/dist/analysis/utils.js

@@ -0,0 +1,123 @@
+// 分析类工具共享辅助（S6.4/S6.5）：中止检查 + 实体关系图 + 章节序索引
+// 纯函数模块，单一职责：被 analysis/ 各工具与测试复用，不持有状态。
+import { deriveChapterOrder, findOutlineNode, readOutlineFile, readProjectFile } from "@whispering233/ai-editor-db";
+/**
+ * 工具取消专用错误（决策 16 ③）：signal 中止时抛出。
+ * name = "AbortError"（与 DOMException 同名约定）——S7.4 executor 据此区分
+ * 「SSE 断开取消」（**不喂回 LLM、不计失败轮**）与「工具执行失败」（结构化喂回 LLM 自纠）。
+ */
+export class AbortedError extends Error {
+    constructor(message = "工具执行已中止（aborted）") {
+        super(message);
+        this.name = "AbortError";
+    }
+}
+/**
+ * 中止检查（决策 16 ③「长工具执行中检查 signal」）：
+ * 分析工具是长任务候选（全量关系/Delta 遍历），在循环中周期性调用——
+ * signal 已中止即抛 AbortedError（executor 捕获后按取消处理，不产生部分结果）。
+ */
+export function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new AbortedError();
+    }
+}
+/** 实体端点判定（relation 端点类型：character/setting/location/hook 为实体，outline_node 为大纲节点） */
+export function isEntityType(type) {
+    return type === "character" || type === "setting" || type === "location" || type === "hook";
+}
+/**
+ * 无向实体邻接图：从可见关系构建「实体 id → 邻居实体 id 集合」。
+ * 只保留两端均为实体的边（appears_in 等指向大纲节点的关系不参与实体连通性）；
+ * 自环（source === target）忽略。供 detect_conflicts（对称缺失检测）与
+ * suggest_connections（共同邻居信号）复用。
+ */
+export function buildEntityGraph(relations) {
+    const graph = new Map();
+    const addEdge = (a, b) => {
+        if (a === b)
+            return;
+        let neighbors = graph.get(a);
+        if (neighbors === undefined) {
+            neighbors = new Set();
+            graph.set(a, neighbors);
+        }
+        neighbors.add(b);
+    };
+    for (const r of relations) {
+        if (!isEntityType(r.sourceType) || !isEntityType(r.targetType))
+            continue;
+        addEdge(r.sourceId, r.targetId);
+        addEdge(r.targetId, r.sourceId); // 无向：双向登记
+    }
+    return graph;
+}
+/** 两集合交集元素（保持第一个集合的迭代序；供共享场景/共同邻居信号使用） */
+export function intersectSets(a, b) {
+    const out = [];
+    for (const v of a) {
+        if (b.has(v))
+            out.push(v);
+    }
+    return out;
+}
+/**
+ * 构建章节序索引（决策 21）。节点所属章查找：chapter 取自身序号；scene 沿父链
+ * 向上找最近 chapter（严格三层下即其父）。读一次 outline.json 支撑全量查询，
+ * 避免 N 次文件读取（getChapterNumber 逐次读文件）。
+ */
+export function buildChapterIndex(ctx) {
+    const tree = readOutlineFile(ctx.outlineDir);
+    const order = deriveChapterOrder(ctx.outlineDir);
+    const chapterNumbers = new Map(order.map((c) => [c.chapterId, c.chapterNumber]));
+    // 软删节点集合（决策 12：不可见 → 无章号）
+    const deletedNodeIds = new Set();
+    // 节点 id → 父节点 id（scene → chapter 归属链）
+    const parentOf = new Map();
+    const visit = (nodes, parentId) => {
+        for (const node of nodes) {
+            parentOf.set(node.id, parentId);
+            if (node.deleted === true)
+                deletedNodeIds.add(node.id);
+            const children = node.children;
+            if (children !== undefined)
+                visit(children, node.id);
+        }
+    };
+    visit(tree.children, "root");
+    const chapterOf = (nodeId) => {
+        if (deletedNodeIds.has(nodeId))
+            return null; // 软删节点不可见（决策 12）
+        // 自身是章
+        const self = chapterNumbers.get(nodeId);
+        if (self !== undefined)
+            return self;
+        // 沿父链向上找章（scene → chapter；volume/root 无章号）
+        let cur = nodeId;
+        for (let depth = 0; depth < 4 && cur !== undefined; depth++) {
+            cur = parentOf.get(cur);
+            if (cur === undefined)
+                return null;
+            const n = chapterNumbers.get(cur);
+            if (n !== undefined)
+                return n;
+        }
+        return null;
+    };
+    // 当前章节：current_position 优先（决策 21），退化树末章
+    let currentChapter = null;
+    const config = readProjectFile(ctx.outlineDir);
+    if (config !== null && config.current_position !== null && config.current_position !== "") {
+        currentChapter = chapterOf(config.current_position);
+    }
+    if (currentChapter === null) {
+        currentChapter = order.length > 0 ? order[order.length - 1].chapterNumber : null;
+    }
+    return { chapterOf, currentChapter };
+}
+/** 大纲节点名称（title；节点不存在 → id 占位——脏引用防御） */
+export function outlineNodeName(tree, nodeId) {
+    const node = findOutlineNode(tree, nodeId);
+    return node === undefined ? nodeId : node.title;
+}
+//# sourceMappingURL=utils.js.map

package/dist/analysis/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/analysis/utils.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { Db } from "@whispering233/ai-editor-db";
+export interface ToolContext {
+    /** 当前项目的 data.db 连接（@whispering233/ai-editor-db openDatabase 返回值） */
+    db: Db;
+    /** 项目根目录（outline.json 所在目录，决策 8；关系/Delta 端点软删校验读树用） */
+    outlineDir: string;
+    /** 当前项目 id（proj- 前缀；提案归属绑定，S6.6 使用） */
+    projectId: string;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,6BAA6B,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,EAAE,EAAE,EAAE,CAAC;IACP,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/context.js

@@ -0,0 +1,11 @@
+// 工具执行上下文（S6.3 ToolContext 设计）
+// 由上层（agent/server，S7）注入：db 访问 + outline.json 读取 + projectId。
+// 工具实现只依赖本接口工作，不持有任何全局状态——同一实例可服务多次工具调用；
+// projectId 本卡查询工具暂未使用（S6.6 提案工具需要提案归属项目），先定义供后续扩展。
+//
+// 注入方职责（S7.4 executor 组装）：
+// - db：当前项目的 data.db 连接（better-sqlite3 同步连接，查询层 API 直接使用）
+// - outlineDir：项目根目录（outline.json 所在目录，决策 8）
+// - projectId：当前打开项目的 id（决策 22 会话归属项目；提案绑定 project_id）
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,8DAA8D;AAC9D,yCAAyC;AACzC,oDAAoD;AACpD,EAAE;AACF,2BAA2B;AAC3B,0DAA0D;AAC1D,6CAA6C;AAC7C,uDAAuD"}

package/dist/executor/delta.d.ts

@@ -0,0 +1,4 @@
+import { type ExecutorFn } from "./types.js";
+/** add_delta（tools.md：add_delta(node_id, target, changes) → id） */
+export declare const executeAddDelta: ExecutorFn;
+//# sourceMappingURL=delta.d.ts.map

package/dist/executor/delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","sourceRoot":"","sources":["../../src/executor/delta.ts"],"names":[],"mappings":"AAUA,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1E,mEAAmE;AACnE,eAAO,MAAM,eAAe,EAAE,UAU7B,CAAC"}

package/dist/executor/delta.js

@@ -0,0 +1,22 @@
+// 执行类工具：Delta（S6.7，tools.md「执行类」1 个）
+// add_delta
+//
+// - node_id / target_type / target_id / changes 已由 S6.6 提案层派生规范化到 args
+// - description（delta_records NOT NULL）：取 **proposal.summary** 作人类可读描述
+//   （S6.6 delta.ts 注释：由执行器取 summary——args 不带 description，提案摘要即变更描述）
+// - order 由 db 层全局单调生成（insertDelta 事务内 MAX+1），此处无 order 入参
+import { insertDelta } from "@whispering233/ai-editor-db";
+import { requireArray, requireString } from "./types.js";
+/** add_delta（tools.md：add_delta(node_id, target, changes) → id） */
+export const executeAddDelta = (ctx, proposal) => {
+    const args = proposal.args;
+    const row = insertDelta(ctx.db, {
+        nodeId: requireString(args, "node_id"),
+        targetType: requireString(args, "target_type"),
+        targetId: requireString(args, "target_id"),
+        changes: requireArray(args, "changes"), // 提案层 schema 已校验 deltaChangeSchema
+        description: proposal.summary,
+    });
+    return { id: row.id };
+};
+//# sourceMappingURL=delta.js.map

package/dist/executor/delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.js","sourceRoot":"","sources":["../../src/executor/delta.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,YAAY;AACZ,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,2DAA2D;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AAE1E,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;IAC3D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE;QAC9B,MAAM,EAAE,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC;QACtC,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE,aAAa,CAAC;QAC9C,QAAQ,EAAE,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC;QAC1C,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,SAAS,CAAkB,EAAE,mCAAmC;QAC5F,WAAW,EAAE,QAAQ,CAAC,OAAO;KAC9B,CAAC,CAAC;IACH,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;AACxB,CAAC,CAAC"}

package/dist/executor/entity.d.ts

@@ -0,0 +1,8 @@
+import { type ExecutorFn } from "./types.js";
+/** create_entity（tools.md：create_entity(type, name, data) → id） */
+export declare const executeCreateEntity: ExecutorFn;
+/** update_entity（tools.md：update_entity(id, patches) → updated；patches 浅合并进 data） */
+export declare const executeUpdateEntity: ExecutorFn;
+/** delete_entity（tools.md：delete_entity(id) → void；软删 + 级联，可回收站还原，决策 12） */
+export declare const executeDeleteEntity: ExecutorFn;
+//# sourceMappingURL=entity.d.ts.map

package/dist/executor/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/executor/entity.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAgD,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3F,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,EAAE,UAQjC,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,EAAE,UASjC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,UAOjC,CAAC"}

package/dist/executor/entity.js

@@ -0,0 +1,47 @@
+// 执行类工具：实体（S6.7，tools.md「执行类」3 个）
+// create_entity / update_entity / delete_entity
+//
+// 与 S6.6 提案工具的核心差异：**直接调 db 写层落库**（唯一写路径，S7.5 确认后由 executor
+// 门面调用）；抛错即失败（事务/单语句失败向上传播，S7.5 转错误响应）。不注册 registry
+// （registry 是 LLM 可见工具表；执行类不暴露给 LLM，tools.md「核心设计原则」）。
+//
+// 语义对齐（决策 12/14）：
+// - create_entity：type/name 必填 + data 可选，id 由 db 层生成（char-/set-/loc-/hook- 前缀）
+// - update_entity：patches 为 data **浅合并**字段（未传字段保留，endpoints.md 第 267 行）；
+//   软删实体不可更新（getEntity 过滤 → null → 抛错）
+// - delete_entity：软删 + 级联关系与 Delta（决策 12，本体保留可回收站还原）
+// 参数形态：与 S6.6 proposal.args 对齐（propose_create_entity → { type, name, data? } 等），
+// 由 executeProposal 按 proposal.type 映射后直接消费。
+import { createEntity, nowIso, softDeleteEntity, updateEntity } from "@whispering233/ai-editor-db";
+import { optionalRecord, requireRecord, requireString } from "./types.js";
+/** create_entity（tools.md：create_entity(type, name, data) → id） */
+export const executeCreateEntity = (ctx, proposal) => {
+    const args = proposal.args;
+    const row = createEntity(ctx.db, {
+        type: requireString(args, "type"), // 提案层 zod 校验（ENTITY_TYPES），此处防御
+        name: requireString(args, "name"),
+        data: optionalRecord(args, "data"),
+    });
+    return { id: row.id };
+};
+/** update_entity（tools.md：update_entity(id, patches) → updated；patches 浅合并进 data） */
+export const executeUpdateEntity = (ctx, proposal) => {
+    const args = proposal.args;
+    const entityId = requireString(args, "entity_id");
+    const patches = requireRecord(args, "patches");
+    const row = updateEntity(ctx.db, entityId, { data: patches }); // data 浅合并（决策 23 同语义）
+    if (row === null) {
+        throw new Error(`实体不存在或已软删: ${entityId}`);
+    }
+    return { id: row.id, updated: true };
+};
+/** delete_entity（tools.md：delete_entity(id) → void；软删 + 级联，可回收站还原，决策 12） */
+export const executeDeleteEntity = (ctx, proposal) => {
+    const entityId = requireString(proposal.args, "entity_id");
+    const result = softDeleteEntity(ctx.db, entityId, nowIso());
+    if (result === null) {
+        throw new Error(`实体不存在或已软删: ${entityId}`);
+    }
+    return { id: entityId, deleted: true, cascaded: result };
+};
+//# sourceMappingURL=entity.js.map

package/dist/executor/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/executor/entity.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,gDAAgD;AAChD,EAAE;AACF,4DAA4D;AAC5D,oDAAoD;AACpD,uDAAuD;AACvD,EAAE;AACF,kBAAkB;AAClB,+EAA+E;AAC/E,yEAAyE;AACzE,uCAAuC;AACvC,qDAAqD;AACrD,iFAAiF;AACjF,6CAA6C;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEnG,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AAE3F,mEAAmE;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;IAC/D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE;QAC/B,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,CAAe,EAAE,gCAAgC;QACjF,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC;QACjC,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC;KACnC,CAAC,CAAC;IACH,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;AACxB,CAAC,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,MAAM,mBAAmB,GAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;IAC/D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,sBAAsB;IACrF,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,cAAc,QAAQ,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;IAC/D,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5D,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,cAAc,QAAQ,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC3D,CAAC,CAAC"}

package/dist/executor/hook.d.ts

@@ -0,0 +1,8 @@
+import { type ExecutorFn } from "./types.js";
+/** advance_hook（tools.md：advance_hook(hook_id, node_id, description) → id） */
+export declare const executeAdvanceHook: ExecutorFn;
+/** resolve_hook（tools.md：resolve_hook(hook_id, node_id, description) → id） */
+export declare const executeResolveHook: ExecutorFn;
+/** abandon_hook（tools.md：abandon_hook(hook_id, description) → id；仅 delta 记 status=abandoned） */
+export declare const executeAbandonHook: ExecutorFn;
+//# sourceMappingURL=hook.d.ts.map

package/dist/executor/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/executor/hook.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAiB,KAAK,UAAU,EAAuB,MAAM,YAAY,CAAC;AAuJjF,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,EAAE,UACsC,CAAC;AAExE,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,EAAE,UACmC,CAAC;AAErE,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,EAAE,UAC8B,CAAC"}