@jacklika/dsh-tool-memory-graph 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -51,7 +51,7 @@ It resolves the same vault root per call as `tool-memory-filesystem`: an explici
 <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`. A breadth-first walk selects the node set first; edges are then collected from every selected node so boundary-node outgoing edges are not dropped. Output is `{ nodes: [{ id, title, backlinks }], edges: [{ from, to }] }`.
+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. A breadth-first walk 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. Output is `{ nodes: [{ id, title, backlinks }], edges: [{ from, to }] }`.
 
 -----
 
@@ -62,7 +62,7 @@ The package is a single Cordis function plugin that registers `wiki_graph` on `c
 
 #### What the model sees
 
-The model sees the generated `wiki_graph` schema in the [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-memory-graph). The description states that the graph is read-only and derived from `[[link]]` references.
+The model sees the generated `wiki_graph` schema. The description states that the graph is read-only and derived from `[[link]]` references.
 
 ##### Verbatim description for `wiki_graph`
 

package/README.zh.md

@@ -51,7 +51,7 @@ kind: "package-reference"
 <a id="understand-the-implementation"></a>
 ## 实现说明
 
-本包是单个 Cordis 函数插件，在 `ctx.tools` 上注册 `wiki_graph`。每次调用通过共享的 `resolveMemoryVaultRoot` 解析仓库根，用 `listNotePaths` 遍历笔记，用 `extractLinks`/`resolveLinkTarget` 提取 `[[link]]` 目标。先用广度优先遍历确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。输出为 `{ nodes: [{ id, title, backlinks }], edges: [{ from, to }] }`。
+本包是单个 Cordis 函数插件，在 `ctx.tools` 上注册 `wiki_graph`。每次调用通过共享的 `resolveMemoryVaultRoot` 解析仓库根，用 `listNotePaths` 遍历笔记，用 `extractLinks`/`resolveLinkTarget` 提取 `[[link]]` 目标。目标按与 `wiki_read` 相同的 Obsidian 语义解析——先精确仓库相对路径，再路径后缀，最后全仓库 basename 匹配，多重命中按确定性规则选择。先用广度优先遍历确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。节点集合超过 `maxNodes` 时，全仓库图保留码点序最小的若干 id（与 `tool-memory-filesystem` 的并列排序规则一致），子图则保留离中心最近的笔记——先按 BFS 层级、再按 id——因此保留哪些笔记不依赖目录列举顺序，子图也不会丢掉自己的中心节点。输出为 `{ nodes: [{ id, title, backlinks }], edges: [{ from, to }] }`。
 
 -----
 
@@ -62,7 +62,7 @@ kind: "package-reference"
 
 #### 模型可见内容
 
-模型在[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-memory-graph)中看到生成的 `wiki_graph` schema。描述声明该图是只读的，由 `[[link]]` 引用推导。
+模型看到生成的 `wiki_graph` schema。描述声明该图是只读的，由 `[[link]]` 引用推导。
 
 ##### `wiki_graph` 的原文描述
 

package/lib/index.js

@@ -8,7 +8,7 @@
 import { readFile } from 'node:fs/promises';
 import z from '@deepseek-ai/schemastery';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { containedPathReal, extractLinks, listNotePaths, resolveLinkTarget, resolveMemoryVaultRoot, splitFrontmatter, vaultRelativeId, } from '@jacklika/dsh-tool-memory-filesystem';
+import { codeUnitCompare, containedPathReal, createLinkResolver, extractLinks, listNotePaths, resolveLinkTarget, resolveMemoryVaultRoot, splitFrontmatter, vaultRelativeId, } from '@jacklika/dsh-tool-memory-filesystem';
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'tool-memory-graph';
 /** Services required by the wiki graph tool. */
@@ -42,8 +42,11 @@ async function noteTitle(absolutePath, id) {
 async function buildGraph(root, resolved) {
     const paths = await listNotePaths(root, resolved.extensions, resolved.indexHiddenDirs);
     const entries = paths.map(path => [vaultRelativeId(root, path), path]);
+    const linkResolver = createLinkResolver(entries.map(([id]) => id));
     const truncated = entries.length > resolved.maxNodes;
-    const capped = entries.slice(0, resolved.maxNodes);
+    // `listNotePaths` follows readdir order, so the node cap would otherwise keep
+    // a filesystem-dependent subset of the vault.
+    const capped = [...entries].sort((a, b) => codeUnitCompare(a[0], b[0])).slice(0, resolved.maxNodes);
     const nodes = [];
     for (const [id, path] of capped)
         nodes.push({ id, title: await noteTitle(path, id) });
@@ -52,7 +55,7 @@ async function buildGraph(root, resolved) {
     for (const [id, path] of capped) {
         const text = await readFile(path, 'utf8');
         for (const link of extractLinks(text)) {
-            const targetPath = await resolveLinkTarget(root, resolved.extensions, link);
+            const targetPath = await resolveLinkTarget(root, resolved.extensions, link, linkResolver);
             if (targetPath === undefined)
                 continue;
             const targetId = vaultRelativeId(root, targetPath);
@@ -73,19 +76,23 @@ async function buildGraph(root, resolved) {
  */
 async function buildSubgraph(root, resolved, startId, depth) {
     const startPath = await containedPathReal(root, startId);
+    const linkResolver = createLinkResolver((await listNotePaths(root, resolved.extensions, resolved.indexHiddenDirs))
+        .map(path => vaultRelativeId(root, path)));
     const visited = new Map([[vaultRelativeId(root, startPath), startPath]]);
+    const levels = new Map([[vaultRelativeId(root, startPath), 0]]);
     let frontier = [startPath];
     for (let level = 0; level < depth && frontier.length > 0; level += 1) {
         const next = [];
         for (const path of frontier) {
             const text = await readFile(path, 'utf8');
             for (const link of extractLinks(text)) {
-                const targetPath = await resolveLinkTarget(root, resolved.extensions, link);
+                const targetPath = await resolveLinkTarget(root, resolved.extensions, link, linkResolver);
                 if (targetPath === undefined)
                     continue;
                 const toId = vaultRelativeId(root, targetPath);
                 if (!visited.has(toId)) {
                     visited.set(toId, targetPath);
+                    levels.set(toId, level + 1);
                     next.push(targetPath);
                 }
             }
@@ -93,7 +100,12 @@ async function buildSubgraph(root, resolved, startId, depth) {
         frontier = next;
     }
     const truncated = visited.size > resolved.maxNodes;
-    const ids = [...visited.keys()].slice(0, resolved.maxNodes);
+    // Truncate by distance from the center, then by id: the neighborhood closest
+    // to the requested note survives the cap, and which notes those are does not
+    // depend on readdir or link order.
+    const ids = [...visited.keys()]
+        .sort((a, b) => (levels.get(a) ?? 0) - (levels.get(b) ?? 0) || codeUnitCompare(a, b))
+        .slice(0, resolved.maxNodes);
     const idSet = new Set(ids);
     const edges = [];
     const nodes = [];
@@ -102,7 +114,7 @@ async function buildSubgraph(root, resolved, startId, depth) {
         nodes.push({ id, title: await noteTitle(path, id) });
         const text = await readFile(path, 'utf8');
         for (const link of extractLinks(text)) {
-            const targetPath = await resolveLinkTarget(root, resolved.extensions, link);
+            const targetPath = await resolveLinkTarget(root, resolved.extensions, link, linkResolver);
             if (targetPath === undefined)
                 continue;
             const toId = vaultRelativeId(root, targetPath);

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.2",
+  "version": "0.1.0-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -32,11 +32,11 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "3.18.4",
-    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.4"
+    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.8"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.3.0-0",
-    "@deepseek-ai/dsh-util-values": ">=0.1.7-rc.1 <0.3.0-0"
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-util-values": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0"
   }
 }