@whispering233/ai-editor-tools 0.0.1

package/dist/query/outline.js

@@ -0,0 +1,68 @@
+// 查询类工具：大纲侧实现（S6.3）
+// get_outline / get_outline_path（tools.md「大纲查询」）
+// 契约来源：doc/api/tools.md；doc/api/endpoints.md 大纲端点；决策 12 修订（默认过滤软删）、
+//   决策 19（严格三层，无游离节点）。
+//
+// db 层能力确认与分工：
+// - get_outline：db readOutlineFile 返回存储形态 OutlineFileTree——
+//   工具层 mapOutlineFileToTree 映射为 API 形态（camelCase）；**默认不含 metadata**
+//   （省 token，tools.md 明确：需统计走 API with_metadata）；软删节点整棵剔除
+//   （决策 12 修订：查询类工具不返回回收站中的对象）
+// - get_outline_path：db getOutlinePathIds 返回根 → 目标节点路径（含 root）；
+//   节点不存在抛错——工具层转 null（查询无结果）；路径上任一节点软删 → null（不可见）
+import { findOutlineNode, getOutlinePathIds, readOutlineFile } from "@whispering233/ai-editor-db";
+import { mapOutlineFileToTree } from "@whispering233/ai-editor-shared";
+/**
+ * 递归剔除软删节点（决策 12 修订）：deleted === true 的节点整棵不可见——
+ * 级联软删（决策 12）保证其子树已一并软删，但防御性仍剔除整棵子树
+ * （手改 outline.json 可能产生不一致，查询层不因脏数据暴露回收站对象）。
+ * 泛型 T 保持调用处的节点联合类型（root 层 volume|chapter，递归层逐级收窄）。
+ */
+function stripDeletedNodes(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        if (node.deleted === true)
+            continue;
+        const children = node.children;
+        out.push(children === undefined ? node : { ...node, children: stripDeletedNodes(children) });
+    }
+    return out;
+}
+/**
+ * 完整大纲树（tools.md get_outline() → 严格三层树，决策 19）。
+ * - 默认不含 metadata 统计（省 token；需统计走 API GET /outline?with_metadata=）
+ * - 软删节点过滤（决策 12 修订）
+ * - 返回 API 形态 OutlineTree（camelCase；data 嵌套字段原样透传）
+ * 无参工具：签名省略 args（少参数赋值兼容 ToolDefinition.run，避免未使用参数 lint）
+ */
+export function runGetOutline(ctx) {
+    const tree = readOutlineFile(ctx.outlineDir);
+    const stripped = { ...tree, children: stripDeletedNodes(tree.children) };
+    return mapOutlineFileToTree(stripped);
+}
+/**
+ * 根 → 目标节点的路径 ID 列表（tools.md get_outline_path(node_id)，含 root，
+ * 如 ["root", "vol-1", "ch-3", "sc-15"]；严格三层下路径唯一，决策 19）。
+ * - 节点不存在 → null（db getOutlinePathIds 抛错，工具层转查询无结果）
+ * - 路径上任一节点软删 → null（决策 12 修订：软删对象不可见——目标节点软删时
+ *   其路径对 AI 无意义；防御手改 outline.json 产生的祖先软删不一致）
+ */
+export function runGetOutlinePath(ctx, args) {
+    const tree = readOutlineFile(ctx.outlineDir);
+    let path;
+    try {
+        path = getOutlinePathIds(tree, args.node_id);
+    }
+    catch {
+        return null; // 节点不存在（getOutlinePathIds 抛错语义，见 db 注释）
+    }
+    for (const nodeId of path) {
+        if (nodeId === "root")
+            continue; // root 非节点，无软删概念
+        const node = findOutlineNode(tree, nodeId);
+        if (node?.deleted === true)
+            return null;
+    }
+    return path;
+}
+//# sourceMappingURL=outline.js.map

package/dist/query/outline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.js","sourceRoot":"","sources":["../../src/query/outline.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,iDAAiD;AACjD,oEAAoE;AACpE,uBAAuB;AACvB,EAAE;AACF,eAAe;AACf,4DAA4D;AAC5D,qEAAqE;AACrE,0DAA0D;AAC1D,+BAA+B;AAC/B,gEAAgE;AAChE,oDAAoD;AAEpD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAKvE;;;;;GAKG;AACH,SAAS,iBAAiB,CAA4B,KAAmB;IACvE,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;YAAE,SAAS;QACpC,MAAM,QAAQ,GAAI,IAAkD,CAAC,QAAQ,CAAC;QAC9E,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EAAQ,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzE,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAgB,EAAE,IAAwB;IAC1E,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,IAAc,CAAC;IACnB,IAAI,CAAC;QACH,IAAI,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,wCAAwC;IACvD,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,IAAI,EAAE,CAAC;QAC1B,IAAI,MAAM,KAAK,MAAM;YAAE,SAAS,CAAC,iBAAiB;QAClD,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3C,IAAI,IAAI,EAAE,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/query/relation.d.ts

@@ -0,0 +1,12 @@
+import type { RelationQueryResult } from "@whispering233/ai-editor-shared";
+import type { ToolContext } from "../context.js";
+import type { QueryRelationshipsArgs } from "@whispering233/ai-editor-shared";
+/**
+ * 关系图子图（tools.md query_relationships → [{source,target,type,metadata}] 简写；
+ * 实际透传 db 的 RelationQueryResult 完整形态：relations: RelationRecord[]（含
+ * sourceName/targetName 联表名）+ depth>=2 时 paths: RelationPath[]）。
+ * 参数映射：snake_case 工具参数 → db 层 camelCase RelationQuery（字段一一对应）；
+ * depth 1=紧邻 / 2=k跳 / 3=全量。
+ */
+export declare function runQueryRelationships(ctx: ToolContext, args: QueryRelationshipsArgs): RelationQueryResult;
+//# sourceMappingURL=relation.d.ts.map

package/dist/query/relation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation.d.ts","sourceRoot":"","sources":["../../src/query/relation.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,sBAAsB,GAAG,mBAAmB,CAazG"}

package/dist/query/relation.js

@@ -0,0 +1,30 @@
+// 查询类工具：关系侧实现（S6.3）
+// query_relationships（tools.md「关系查询」→ 关系图子图）
+// 契约来源：doc/api/tools.md；doc/api/endpoints.md 关系端点；决策 12 修订
+//   （关系可见性联动端点状态：任一端点软删即不可见）、决策 10（plot_edge 同规则）。
+//
+// db 层能力确认：listRelations（db relation.ts）已实现全部所需语义——
+// 1. 关系自身软删过滤（SQL 层）
+// 2. **端点软删可见性校验**（buildEndpointContext：实体端点查 entities 软删集合、
+//    大纲端点读 outline.json 收集软删节点——决策 12 修订）
+// 3. name 联表填充（实体 entities.name、大纲节点 outline.json title）
+// 4. depth>=2 的 k 跳 BFS 路径（防环、多起点）
+// 工具层仅做参数映射透传，无额外过滤逻辑。
+import { listRelations } from "@whispering233/ai-editor-db";
+/**
+ * 关系图子图（tools.md query_relationships → [{source,target,type,metadata}] 简写；
+ * 实际透传 db 的 RelationQueryResult 完整形态：relations: RelationRecord[]（含
+ * sourceName/targetName 联表名）+ depth>=2 时 paths: RelationPath[]）。
+ * 参数映射：snake_case 工具参数 → db 层 camelCase RelationQuery（字段一一对应）；
+ * depth 1=紧邻 / 2=k跳 / 3=全量。
+ */
+export function runQueryRelationships(ctx, args) {
+    return listRelations(ctx.db, {
+        sourceType: args.source_type,
+        sourceId: args.source_id,
+        targetType: args.target_type,
+        targetId: args.target_id,
+        relationType: args.relation_type,
+    }, args.depth, ctx.outlineDir);
+}
+//# sourceMappingURL=relation.js.map

package/dist/query/relation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation.js","sourceRoot":"","sources":["../../src/query/relation.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,6CAA6C;AAC7C,2DAA2D;AAC3D,mDAAmD;AACnD,EAAE;AACF,oDAAoD;AACpD,qBAAqB;AACrB,6DAA6D;AAC7D,0CAA0C;AAC1C,yDAAyD;AACzD,mCAAmC;AACnC,uBAAuB;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAK5D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAgB,EAAE,IAA4B;IAClF,OAAO,aAAa,CAClB,GAAG,CAAC,EAAE,EACN;QACE,UAAU,EAAE,IAAI,CAAC,WAAW;QAC5B,QAAQ,EAAE,IAAI,CAAC,SAAS;QACxB,UAAU,EAAE,IAAI,CAAC,WAAW;QAC5B,QAAQ,EAAE,IAAI,CAAC,SAAS;QACxB,YAAY,EAAE,IAAI,CAAC,aAAa;KACjC,EACD,IAAI,CAAC,KAAK,EACV,GAAG,CAAC,UAAU,CACf,CAAC;AACJ,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,41 @@
+import type { z } from "zod";
+import type { ToolPermission } from "@whispering233/ai-editor-shared";
+import type { ToolContext } from "./context.js";
+/**
+ * 工具定义（argsSchema 的推断类型约束 run 的 args 入参）。
+ * run 声明为**方法**（而非函数属性）：方法参数双变检查——具体 schema 的
+ * ToolDefinition<X> 可赋给容器默认的 ToolDefinition<z.ZodTypeAny>（run args 为
+ * unknown），executor 从注册表取出后先 schema 校验（parsed.data 为 unknown）再执行，
+ * 运行时由 argsSchema 兜底，类型层面双变无实际风险。
+ */
+export interface ToolDefinition<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** 工具名（tools.md 工具目录，如 get_entity；LLM tool_call 的 tool 字段） */
+    name: string;
+    /** 人类可读描述（注入 LLM 工具列表，说明用途与参数语义） */
+    description: string;
+    /** 参数 zod schema（入参校验；推断类型即 run 的 args 类型） */
+    argsSchema: TSchema;
+    /** 权限级别（TOOL_PERMISSION.AUTO / PROPOSAL） */
+    permission: ToolPermission;
+    /**
+     * 执行函数：注入 ToolContext（db/outlineDir/projectId），返回可序列化结果或抛错。
+     * signal：可选取消通道（决策 16 ③「长工具执行中检查 signal」）——S6.4 分析类
+     * 是长任务候选，executor 在 SSE 断开时中止在途工具；同步短工具可不检查。
+     */
+    run(ctx: ToolContext, args: z.infer<TSchema>, signal?: AbortSignal): unknown;
+}
+/**
+ * 注册单个工具：重复注册同名工具抛错——防后续切片扩展时撞名，
+ * 保证「注册表 = 工具目录唯一事实来源」。
+ * 防呆：name 必须为非空字符串（S6.4-6.7 拼错名不应静默注册新工具）。
+ */
+export declare function registerTool(def: ToolDefinition): void;
+/** 批量注册（各工具模块组装定义数组后统一挂载；内部逐个调 registerTool 保证判重） */
+export declare function registerTools(defs: readonly ToolDefinition[]): void;
+/** 按名查询工具；未注册返回 undefined（executor 收到未知工具名时按失败处理） */
+export declare function getTool(name: string): ToolDefinition | undefined;
+/** 全部已注册工具（按名称排序，稳定输出；供 S7.2 上下文组装注入 LLM 工具列表） */
+export declare function listTools(): ToolDefinition[];
+/** 当前注册的工具数量（冒烟/测试断言用） */
+export declare function toolCount(): number;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IACzE,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,UAAU,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,UAAU,EAAE,cAAc,CAAC;IAC3B;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;CAC9E;AAKD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAQtD;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI,CAEnE;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEhE;AAED,kDAAkD;AAClD,wBAAgB,SAAS,IAAI,cAAc,EAAE,CAE5C;AAED,0BAA0B;AAC1B,wBAAgB,SAAS,IAAI,MAAM,CAElC"}

package/dist/registry.js

@@ -0,0 +1,46 @@
+// 工具注册表（S6.3）：统一工具定义结构 + 注册/查询 API
+// 契约来源：doc/api/tools.md（工具分级、工具执行契约）；doc/design/decisions.md 决策 14/15。
+// 供后续切片扩展：S6.4 分析类 / S6.5 伏笔 / S6.6 提案 / S6.7 执行 + executor 均可
+// registerTool 挂载新工具；S7.4 executor 通过 getTool(name) 按名调度。
+//
+// 定义结构 { name, description, argsSchema, permission, run }：
+// - argsSchema：zod 参数校验（执行前 preflight 校验，批量 tool_call 先全部校验再执行，
+//   tools.md「工具执行契约」）；校验失败即抛错（executor 统一转结构化 tool_result 喂回 LLM）
+// - permission：TOOL_PERMISSION.AUTO（自动）/ PROPOSAL（提案确认）两级（tools.md「工具分级」）
+// - run(ctx, args)：同步执行，返回 JSON 可序列化结果；抛错即失败（不把失败编码进正常 content）
+//
+// 注册语义：重复注册同名工具抛错（防 S6.4-6.7 与查询类撞名；注册表是唯一事实来源）。
+/** 注册表内部存储（Map 保证按名 O(1) 查询） */
+const registry = new Map();
+/**
+ * 注册单个工具：重复注册同名工具抛错——防后续切片扩展时撞名，
+ * 保证「注册表 = 工具目录唯一事实来源」。
+ * 防呆：name 必须为非空字符串（S6.4-6.7 拼错名不应静默注册新工具）。
+ */
+export function registerTool(def) {
+    if (typeof def.name !== "string" || def.name.trim() === "") {
+        throw new Error("registerTool: 工具名必须为非空字符串");
+    }
+    if (registry.has(def.name)) {
+        throw new Error(`registerTool: 工具 ${def.name} 已注册（重复注册禁止）`);
+    }
+    registry.set(def.name, def);
+}
+/** 批量注册（各工具模块组装定义数组后统一挂载；内部逐个调 registerTool 保证判重） */
+export function registerTools(defs) {
+    for (const def of defs)
+        registerTool(def);
+}
+/** 按名查询工具；未注册返回 undefined（executor 收到未知工具名时按失败处理） */
+export function getTool(name) {
+    return registry.get(name);
+}
+/** 全部已注册工具（按名称排序，稳定输出；供 S7.2 上下文组装注入 LLM 工具列表） */
+export function listTools() {
+    return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** 当前注册的工具数量（冒烟/测试断言用） */
+export function toolCount() {
+    return registry.size;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,uEAAuE;AACvE,+DAA+D;AAC/D,0DAA0D;AAC1D,EAAE;AACF,2DAA2D;AAC3D,gEAAgE;AAChE,kEAAkE;AAClE,0EAA0E;AAC1E,gEAAgE;AAChE,EAAE;AACF,iDAAiD;AA8BjD,gCAAgC;AAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAmB;IAC9C,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC,IAAI,cAAc,CAAC,CAAC;IAC9D,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,IAA+B;IAC3D,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,YAAY,CAAC,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,SAAS;IACvB,OAAO,QAAQ,CAAC,IAAI,CAAC;AACvB,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@whispering233/ai-editor-tools",
+  "version": "0.0.1",
+  "description": "AI 工具目录：工具定义 + 执行器",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepack": "node ../../scripts/prepare-package-for-publish.mjs",
+    "postpack": "node ../../scripts/restore-package-json.mjs"
+  },
+  "dependencies": {
+    "@whispering233/ai-editor-db": "0.0.1",
+    "@whispering233/ai-editor-shared": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "zod": "^4.0.0"
+  }
+}