@jacklika/dsh-tool-memory-graph 0.1.0-alpha.6 → 0.1.0-alpha.7

package/README.md

@@ -41,17 +41,18 @@ It resolves the same vault root per call as `tool-memory-filesystem`: an explici
 | `indexHiddenDirs` | `boolean` | `false` | Index directories whose names start with `.` (`.git` and `node_modules` stay excluded). Enable when `vaultRoot` points at the workspace root so `.dsh/memory/` notes are included. |
 | `maxDepth` | `number` | `1` | Maximum BFS depth when a center id is given. |
 | `maxNodes` | `number` | `200` | Maximum nodes returned in one graph. |
+| `maxEdges` | `number` | `1000` | Maximum edges returned in one graph. |
 
 ### Tools
 
-- `wiki_graph(id?, depth?)` — without `id`, return every note and directed edge in the vault. With `id`, return the reachable subgraph within `depth` hops; edges from boundary nodes are included when both endpoints are selected. Edges carry `type` (`link` or `keyword`), `keywords` (for `keyword` edges), and `weight` (combined term frequency).
+- `wiki_graph(id?, depth?)` — without `id`, return every note and directed edge in the vault. With `id`, return the reachable subgraph within `depth` hops; edges from boundary nodes are included when both endpoints are selected. Edges carry `type` (`link` or `keyword`), `keywords` (for `keyword` edges), and `weight` (combined term frequency). Output is `{ nodes, edges, truncated, edgesTruncated }`: `truncated` reports the `maxNodes` cut and `edgesTruncated` the `maxEdges` cut, kept separate so a complete node set is not misread as a complete graph.
 
 -----
 
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
 
-The package is a single Cordis function plugin that registers `wiki_graph` on `ctx.tools`. Per call it resolves the vault root through the shared `resolveMemoryVaultRoot` helper, lists notes through the shared `listNotePaths` walker, and extracts `[[link]]` targets through `extractLinks`/`resolveLinkTarget`. Targets resolve with the same Obsidian-style tiers as `wiki_read` — exact vault-relative path, then path suffix, then basename anywhere in the vault, with deterministic ambiguity handling. In addition to explicit links, the tool extracts significant terms from each note (frontmatter `tags` ×3, frontmatter `title` ×2, body terms ×1) and creates `keyword` edges between any two notes that share one or more terms. A breadth-first walk that follows both `link` and `keyword` edges selects the node set first; edges are then collected from every selected node so boundary-node outgoing edges are not dropped. When the node set exceeds `maxNodes`, a whole-vault graph keeps the lowest ids in code-unit order (the ordering `tool-memory-filesystem` tie-breaks with) and a subgraph keeps the notes nearest the center — BFS level first, then id — so which notes survive the cap never depends on directory-listing order and a subgraph never drops its own center. Because `wiki_graph` recomputes from disk on every call, rewriting a note removes stale `keyword` edges and creates new ones for the terms that survive or appear in the new text. Output is `{ nodes: [{ id, title }], edges: [{ from, to, type, keywords?, weight? }], truncated: boolean }`.
+The package is a single Cordis function plugin that registers `wiki_graph` on `ctx.tools`. Per call it resolves the vault root through the shared `resolveMemoryVaultRoot` helper, lists notes through the shared `listNotePaths` walker, and extracts `[[link]]` targets through `extractLinks`/`resolveLinkTarget`. Targets resolve with the same Obsidian-style tiers as `wiki_read` — exact vault-relative path, then path suffix, then basename anywhere in the vault, with deterministic ambiguity handling. In addition to explicit links, the tool extracts significant terms from each note (frontmatter `tags` ×3, frontmatter `title` ×2, body terms ×1) and creates `keyword` edges between any two notes that share one or more terms. A breadth-first walk with a visited set (so cyclical link graphs terminate) follows both `link` and `keyword` edges to select the node set first; edges are then collected from every selected node so boundary-node outgoing edges are not dropped. When the node set exceeds `maxNodes`, a whole-vault graph keeps the lowest ids in code-unit order (the ordering `tool-memory-filesystem` tie-breaks with) and a subgraph keeps the notes nearest the center — BFS level first, then id — so which notes survive the cap never depends on directory-listing order and a subgraph never drops its own center. Because `wiki_graph` recomputes from disk on every call, rewriting a note removes stale `keyword` edges and creates new ones for the terms that survive or appear in the new text. Edges are capped at `maxEdges` after node selection: explicit `link` edges first, then `keyword` edges by descending weight, with a deterministic id tie-break, so the surviving set never depends on directory-listing order. Requesting a center id that is not an indexed note fails with `note not found`, and an unreadable note is skipped (logged as a warning) instead of failing the call. Output is `{ nodes: [{ id, title }], edges: [{ from, to, type, keywords?, weight? }], truncated: boolean, edgesTruncated: boolean }`, where `truncated` covers the node cap and `edgesTruncated` the edge cap.
 
 -----
 
@@ -67,7 +68,7 @@ The model sees the generated `wiki_graph` schema. The description states that th
 ##### Verbatim description for `wiki_graph`
 
 ```markdown
-Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth.
+Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth. Nodes are capped at maxNodes (`truncated`) and edges at maxEdges (`edgesTruncated`).
 ```
 
 #### Token effect
@@ -83,7 +84,7 @@ Independent. The plugin only supplies tool results; it does not change the reque
 <a id="known-limitations-and-deferred-work"></a>
 
 - **No visualization** — the tool returns JSON nodes and edges; rendering (Obsidian graph view, Mermaid) is left to consumers.
-- **Edges are scoped to selected nodes** — only links whose source and target both survive the `maxNodes` cap are returned, so boundary links outside the selected set are omitted.
+- **Edges are scoped to selected nodes** — only links whose source and target both survive the `maxNodes` cap are returned, so boundary links outside the selected set are omitted. A dense vault can then also hit the `maxEdges` cap; `edgesTruncated` reports when the returned edges are only a deterministic slice.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -41,17 +41,18 @@ kind: "package-reference"
 | `indexHiddenDirs` | `boolean` | `false` | 是否索引以 `.` 开头的目录（`.git` 与 `node_modules` 始终排除）。当 `vaultRoot` 指向工作区根时开启，以纳入 `.dsh/memory/`。 |
 | `maxDepth` | `number` | `1` | 指定中心笔记时 BFS 的最大深度。 |
 | `maxNodes` | `number` | `200` | 单次图查询返回的最大节点数。 |
+| `maxEdges` | `number` | `1000` | 单次图查询返回的最大边数。 |
 
 ### 工具
 
-- `wiki_graph(id?, depth?)` —— 不传 `id` 时返回全仓库的节点与有向边；传 `id` 时返回 `depth` 跳内的可达子图，两个端点都被选中时边界节点的出边也会包含。边携带 `type`（`link` 或 `keyword`）、`keywords`（仅 `keyword` 边）和 `weight`（合并词频）。
+- `wiki_graph(id?, depth?)` —— 不传 `id` 时返回全仓库的节点与有向边；传 `id` 时返回 `depth` 跳内的可达子图，两个端点都被选中时边界节点的出边也会包含。边携带 `type`（`link` 或 `keyword`）、`keywords`（仅 `keyword` 边）和 `weight`（合并词频）。输出为 `{ nodes, edges, truncated, edgesTruncated }`：`truncated` 对应 `maxNodes` 截断，`edgesTruncated` 对应 `maxEdges` 截断，两者分开报告，节点完整不会被误读为整图完整。
 
 -----
 
 <a id="understand-the-implementation"></a>
 ## 实现说明
 
-本包是单个 Cordis 函数插件，在 `ctx.tools` 上注册 `wiki_graph`。每次调用通过共享的 `resolveMemoryVaultRoot` 解析仓库根，用 `listNotePaths` 遍历笔记，用 `extractLinks`/`resolveLinkTarget` 提取 `[[link]]` 目标。目标按与 `wiki_read` 相同的 Obsidian 语义解析——先精确仓库相对路径，再路径后缀，最后全仓库 basename 匹配，多重命中按确定性规则选择。除显式链接外，工具还会从每条笔记提取显著词（frontmatter `tags` ×3、frontmatter `title` ×2、正文词 ×1），并为任意两篇共享一个或多个词的笔记创建 `keyword` 边。广度优先遍历同时跟随 `link` 边与 `keyword` 边以确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。节点集合超过 `maxNodes` 时，全仓库图保留码点序最小的若干 id（与 `tool-memory-filesystem` 的并列排序规则一致），子图则保留离中心最近的笔记——先按 BFS 层级、再按 id——因此保留哪些笔记不依赖目录列举顺序，子图也不会丢掉自己的中心节点。由于 `wiki_graph` 每次调用都会从磁盘重新计算，重写一条笔记会移除旧的 `keyword` 边，并为新正文中保留下来的或新出现的词建立新边。输出为 `{ nodes: [{ id, title }], edges: [{ from, to, type, keywords?, weight? }], truncated: boolean }`。
+本包是单个 Cordis 函数插件，在 `ctx.tools` 上注册 `wiki_graph`。每次调用通过共享的 `resolveMemoryVaultRoot` 解析仓库根，用 `listNotePaths` 遍历笔记，用 `extractLinks`/`resolveLinkTarget` 提取 `[[link]]` 目标。目标按与 `wiki_read` 相同的 Obsidian 语义解析——先精确仓库相对路径，再路径后缀，最后全仓库 basename 匹配，多重命中按确定性规则选择。除显式链接外，工具还会从每条笔记提取显著词（frontmatter `tags` ×3、frontmatter `title` ×2、正文词 ×1），并为任意两篇共享一个或多个词的笔记创建 `keyword` 边。广度优先遍历带 visited 集合（循环链接图因此可终止），同时跟随 `link` 边与 `keyword` 边以确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。节点集合超过 `maxNodes` 时，全仓库图保留码点序最小的若干 id（与 `tool-memory-filesystem` 的并列排序规则一致），子图则保留离中心最近的笔记——先按 BFS 层级、再按 id——因此保留哪些笔记不依赖目录列举顺序，子图也不会丢掉自己的中心节点。由于 `wiki_graph` 每次调用都会从磁盘重新计算，重写一条笔记会移除旧的 `keyword` 边，并为新正文中保留下来的或新出现的词建立新边。边在节点集合确定后按 `maxEdges` 截断：显式 `link` 边优先，其后是 `keyword` 边按 `weight` 降序，并以 id 作确定性并列裁决——保留哪些边同样不依赖目录列举顺序。以非已索引笔记作为中心 id 会以 `note not found` 失败；无法读取的笔记会被跳过（记入 logger 警告），不会让整次调用失败。输出为 `{ nodes: [{ id, title }], edges: [{ from, to, type, keywords?, weight? }], truncated: boolean, edgesTruncated: boolean }`，其中 `truncated` 对应节点上限、`edgesTruncated` 对应边上限。
 
 -----
 
@@ -67,7 +68,7 @@ kind: "package-reference"
 ##### `wiki_graph` 的原文描述
 
 ```markdown
-Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth.
+Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth. Nodes are capped at maxNodes (`truncated`) and edges at maxEdges (`edgesTruncated`).
 ```
 
 #### Token 影响
@@ -83,7 +84,7 @@ Return the link and keyword graph of the wiki vault: note ids, titles, and direc
 <a id="known-limitations-and-deferred-work"></a>
 
 - **无可视化** —— 工具返回 JSON 节点与边；渲染（Obsidian 图谱、Mermaid）由消费方负责。
-- **边限于已选节点** —— 只有两端都在 `maxNodes` 截断后保留下来的节点之间的链接才会出现，子图边界外的出边被省略。
+- **边限于已选节点** —— 只有两端都在 `maxNodes` 截断后保留下来的节点之间的链接才会出现，子图边界外的出边被省略；密集仓库随后可能触及 `maxEdges` 上限，`edgesTruncated` 会表明返回的边只是确定性切片。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -25,6 +25,7 @@ export const Config = z.object({
     extensions: z.array(z.string()).default(['.md']),
     maxDepth: z.number().default(1),
     maxNodes: z.number().default(200),
+    maxEdges: z.number().default(1000),
     indexHiddenDirs: z.boolean().default(false),
 });
 function assertPositiveInteger(name, value) {
@@ -161,20 +162,64 @@ function buildKeywordEdges(noteTerms) {
     }
     return edges;
 }
-async function loadVaultNotes(root, resolved) {
-    const paths = await listNotePaths(root, resolved.extensions, resolved.indexHiddenDirs);
+async function loadVaultNotes(root, resolved, onSkip) {
+    const paths = await listNotePaths(root, resolved.extensions, resolved.indexHiddenDirs, onSkip);
     const ids = paths.map(path => vaultRelativeId(root, path));
     const linkResolver = createLinkResolver(ids);
     const parsed = [];
     const parsedById = new Map();
+    const skipped = new Map();
     for (const path of paths) {
         const id = vaultRelativeId(root, path);
-        const text = await readFile(path, 'utf8');
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            // One unreadable note must not fail the graph for the whole vault; the
+            // note is omitted and the loader logs the degradation.
+            skipped.set(id, error);
+            onSkip?.(path, error);
+            continue;
+        }
         const note = { id, path, text, terms: extractTerms(text) };
         parsed.push(note);
         parsedById.set(id, note);
     }
-    return { parsed, parsedById, linkResolver };
+    return { parsed, parsedById, linkResolver, skipped };
+}
+/** Build the skip callback that reports unreadable entries to the Loader logger. */
+function skipLogger(ctx, root) {
+    return (path, error) => {
+        const code = error.code ?? 'unknown';
+        ctx.logger?.warn(`tool-memory-graph: skipped unreadable entry ${vaultRelativeId(root, path)} (${code})`);
+    };
+}
+/** Validate that at least one note extension is configured. */
+function assertExtensions(extensions) {
+    if (extensions.length === 0) {
+        throw new Error('tool-memory-graph: extensions must list at least one file extension');
+    }
+}
+/**
+ * Apply the edge budget deterministically: explicit `link` edges are kept
+ * first, then `keyword` edges by descending weight and id order, so the same
+ * vault returns the same subset regardless of directory-listing order. Below
+ * the budget the edge list is returned untouched.
+ */
+function capEdges(edges, maxEdges) {
+    if (edges.length <= maxEdges)
+        return { edges, truncated: false };
+    const ordered = [...edges].sort((a, b) => {
+        const linkFirst = (a.type === 'keyword' ? 1 : 0) - (b.type === 'keyword' ? 1 : 0);
+        if (linkFirst !== 0)
+            return linkFirst;
+        const weightOrder = (b.weight ?? 0) - (a.weight ?? 0);
+        if (weightOrder !== 0)
+            return weightOrder;
+        return codeUnitCompare(a.from, b.from) || codeUnitCompare(a.to, b.to);
+    });
+    return { edges: ordered.slice(0, maxEdges), truncated: true };
 }
 /**
  * Build the vault-wide link graph: every note is a node; every `[[link]]`
@@ -184,8 +229,8 @@ async function loadVaultNotes(root, resolved) {
  * @param resolved - applied plugin configuration.
  * @returns the full graph, node-capped.
  */
-async function buildGraph(root, resolved) {
-    const { parsed, linkResolver } = await loadVaultNotes(root, resolved);
+async function buildGraph(root, resolved, onSkip) {
+    const { parsed, linkResolver } = await loadVaultNotes(root, resolved, onSkip);
     const truncated = parsed.length > resolved.maxNodes;
     const capped = [...parsed].sort((a, b) => codeUnitCompare(a.id, b.id)).slice(0, resolved.maxNodes);
     const idSet = new Set(capped.map(p => p.id));
@@ -205,7 +250,8 @@ async function buildGraph(root, resolved) {
     edges.push(...buildKeywordEdges(noteTerms));
     // Safety: every edge endpoint must be in the returned node set.
     const safeEdges = edges.filter(e => idSet.has(e.from) && idSet.has(e.to));
-    return { nodes, edges: safeEdges, truncated };
+    const budgeted = capEdges(safeEdges, resolved.maxEdges);
+    return { nodes, edges: budgeted.edges, truncated, edgesTruncated: budgeted.truncated };
 }
 /**
  * Collect the subgraph reachable from one note by following `[[link]]`
@@ -216,10 +262,21 @@ async function buildGraph(root, resolved) {
  * @param depth - maximum link/keyword hops from the center.
  * @returns the neighborhood graph, node-capped.
  */
-async function buildSubgraph(root, resolved, startId, depth) {
-    const { parsed, parsedById, linkResolver } = await loadVaultNotes(root, resolved);
+async function buildSubgraph(root, resolved, startId, depth, onSkip) {
+    const { parsed, parsedById, linkResolver, skipped } = await loadVaultNotes(root, resolved, onSkip);
     const startPath = await containedPathReal(root, startId);
     const startNoteId = vaultRelativeId(root, startPath);
+    // A missing path, a directory, or a file outside the configured extensions
+    // resolves fine but has no indexed note; seeding the BFS with it would crash
+    // on the first `parsedById.get(id)!` lookup.
+    if (!parsedById.has(startNoteId)) {
+        const skipError = skipped.get(startNoteId);
+        if (skipError !== undefined) {
+            const code = skipError.code ?? 'unknown error';
+            throw new Error(`tool-memory-graph: cannot read note ${JSON.stringify(startNoteId)}: ${code}`);
+        }
+        throw new Error(`tool-memory-graph: note not found: ${startNoteId}`);
+    }
     const idSetAll = new Set(parsed.map(p => p.id));
     const adjacency = new Map();
     for (const p of parsed) {
@@ -279,7 +336,8 @@ async function buildSubgraph(root, resolved, startId, depth) {
     }
     const filteredKeywordEdges = keywordEdges.filter(e => idSet.has(e.from) && idSet.has(e.to));
     edges.push(...filteredKeywordEdges);
-    return { nodes, edges, truncated };
+    const budgeted = capEdges(edges, resolved.maxEdges);
+    return { nodes, edges: budgeted.edges, truncated, edgesTruncated: budgeted.truncated };
 }
 /**
  * Register the `wiki_graph` tool on `ctx.tools`.
@@ -295,9 +353,11 @@ export function apply(ctx, config) {
     const resolved = config;
     assertPositiveInteger('maxDepth', resolved.maxDepth);
     assertPositiveInteger('maxNodes', resolved.maxNodes);
+    assertPositiveInteger('maxEdges', resolved.maxEdges);
+    assertExtensions(resolved.extensions);
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'wiki_graph',
-        description: 'Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth.',
+        description: 'Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth. Nodes are capped at maxNodes (`truncated`) and edges at maxEdges (`edgesTruncated`).',
         parameters: {
             id: {
                 type: 'string',
@@ -316,9 +376,10 @@ export function apply(ctx, config) {
             const vaultRoot = resolveMemoryVaultRoot(resolved.vaultRoot, exec);
             const depth = args.depth ?? resolved.maxDepth;
             assertPositiveInteger('depth', depth);
+            const onSkip = skipLogger(ctx, vaultRoot);
             const graph = args.id === undefined
-                ? await buildGraph(vaultRoot, resolved)
-                : await buildSubgraph(vaultRoot, resolved, args.id, depth);
+                ? await buildGraph(vaultRoot, resolved, onSkip)
+                : await buildSubgraph(vaultRoot, resolved, args.id, depth, onSkip);
             return graph;
         },
     })));

package/lib/types/index.d.ts

@@ -31,6 +31,8 @@ export interface Config {
     maxDepth?: number;
     /** Maximum nodes returned in one graph. */
     maxNodes?: number;
+    /** Maximum edges returned in one graph. */
+    maxEdges?: number;
     /** Descend into dot-directories besides the fixed exclusions while indexing. */
     indexHiddenDirs?: boolean;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jacklika/dsh-tool-memory-graph",
   "description": "Model-facing link-graph tool over a Markdown memory vault: returns note nodes and [[link]] edges, or the subgraph reachable from one note.",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "publishConfig": {
     "access": "public"
   },
@@ -32,7 +32,7 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "3.18.4",
-    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.9"
+    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.10"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "4.0.4",