@jacklika/dsh-tool-memory-graph 0.1.0-alpha.3 → 0.1.0-alpha.5

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`. 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. 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 }], edges: [{ from, to }], truncated: boolean }`.
 
 -----
 
@@ -83,7 +83,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.
-- **Backlinks reflect the whole vault** — node `backlinks` counts are computed over all notes, not just the selected subgraph.
+- **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 id="dev-note"></a>
 ### Dev Note

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]]` 目标。目标按与 `wiki_read` 相同的 Obsidian 语义解析——先精确仓库相对路径，再路径后缀，最后全仓库 basename 匹配，多重命中按确定性规则选择。先用广度优先遍历确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。输出为 `{ 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 }], edges: [{ from, to }], truncated: boolean }`。
 
 -----
 
@@ -83,7 +83,7 @@ Return the Obsidian-style [[link]] graph of the wiki vault: note ids, titles, an
 <a id="known-limitations-and-deferred-work"></a>
 
 - **无可视化** —— 工具返回 JSON 节点与边；渲染（Obsidian 图谱、Mermaid）由消费方负责。
-- **backlinks 基于全仓库统计** —— 节点的 `backlinks` 计数覆盖全部笔记，而非仅选中子图。
+- **边限于已选节点** —— 只有两端都在 `maxNodes` 截断后保留下来的节点之间的链接才会出现，子图边界外的出边被省略。
 
 <a id="dev-note"></a>
 ### 开发备注

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, createLinkResolver, 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. */
@@ -28,7 +28,10 @@ function assertPositiveInteger(name, value) {
 }
 async function noteTitle(absolutePath, id) {
     const text = await readFile(absolutePath, 'utf8');
-    const { body } = splitFrontmatter(text);
+    const { frontmatter, body } = splitFrontmatter(text);
+    const explicitTitle = typeof frontmatter.title === 'string' ? frontmatter.title.trim() : '';
+    if (explicitTitle !== '')
+        return explicitTitle;
     const heading = /^#\s+(.+)$/m.exec(body);
     return heading?.[1]?.trim() ?? id.replace(/\.[^.]+$/, '');
 }
@@ -44,7 +47,9 @@ async function buildGraph(root, resolved) {
     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) });
@@ -77,6 +82,7 @@ async function buildSubgraph(root, resolved, startId, depth) {
     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 = [];
@@ -89,6 +95,7 @@ async function buildSubgraph(root, resolved, startId, depth) {
                 const toId = vaultRelativeId(root, targetPath);
                 if (!visited.has(toId)) {
                     visited.set(toId, targetPath);
+                    levels.set(toId, level + 1);
                     next.push(targetPath);
                 }
             }
@@ -96,7 +103,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 = [];

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.3",
+  "version": "0.1.0-alpha.5",
   "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.5"
+    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.9"
   },
   "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"
   }
 }