@jacklika/dsh-tool-memory-filesystem 0.1.3-alpha.7 → 0.1.3-alpha.9

package/README.md

@@ -53,8 +53,8 @@ A relative `vaultRoot` resolves against the calling session's workspace.
 ### Tools
 
 - `wiki_read(id)` — read one note by vault-relative path and return its frontmatter, body, links, linked notes, a `version` content fingerprint, the file's `mtime` as a `+08:00` timestamp, and a `modifiedExternally` flag that is `true` when the file changed on disk since this plugin last observed it (e.g. an Obsidian edit). The plugin keeps a bounded 256-entry LRU of observed mtimes keyed by absolute path; its own `wiki_write` re-records the mtime so plugin writes never flag.
-- `wiki_search(query)` — keyword search across note titles, ids, and bodies; query terms are OR-matched and ranked by field-weighted BM25-style scoring (title/id hits weigh most, rare terms weigh more) plus a verbatim-phrase bonus and a link-graph boost; when `wiki_semantic_search` is mounted the two rankings fuse via reciprocal rank fusion. Results include the score and backlink counts.
-- `wiki_write(id, content, mode?, baseVersion?)` — create or append to a note. Append mode preserves frontmatter and adds a timestamp header; both write modes normalize `created`/`updated` frontmatter values to `+08:00` second precision (unparseable values pass through). Passing a `version` from `wiki_read` as `baseVersion` makes the write fail loudly when another writer changed the note in between.
+- `wiki_search(query)` — keyword search across note titles, ids, and bodies; query terms are OR-matched and ranked by field-weighted BM25-style scoring (title/id hits weigh most, rare terms weigh more) plus a verbatim-phrase bonus and a link-graph boost; when `wiki_semantic_search` is mounted the two rankings fuse via reciprocal rank fusion. Returns a `{ hits, total, truncated }` page: each hit carries the note id, title, score, and backlinks; `total` counts every match *before* the `maxSearchResults` cap; `truncated` is `true` when that cap cut the list, so a caller can tell a complete result set from a partial one instead of assuming the vault holds nothing else.
+- `wiki_write(id, content, mode?, baseVersion?)` — create or append to a note. Append mode preserves frontmatter and adds a timestamp header; both write modes normalize `created`/`updated` frontmatter values to `+08:00` second precision (unparseable values pass through). Passing a `version` from `wiki_read` as `baseVersion` makes the write fail loudly when another writer changed the note in between. The result is `{ id, mode, bytes, version }`, where `version` fingerprints the bytes just published — feed it straight back as `baseVersion` on the next write to chain optimistic-concurrency checks without a `wiki_read` round-trip.
 
 ### Security
 
@@ -87,18 +87,18 @@ Read one Markdown note from the wiki vault, optionally following Obsidian-style
 ##### Verbatim description for `wiki_search`
 
 ```markdown
-Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns matching note ids, titles, scores, and backlink counts. Use this before asking the user which note to read.
+Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns { hits, total, truncated }: each hit carries the note id, title, score, and backlinks, total counts every match before the result cap, and truncated is true when that cap cut the list. Use this before asking the user which note to read.
 ```
 
 ##### Verbatim description for `wiki_write`
 
 ```markdown
-Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header.
+Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header. Returns { id, mode, bytes, version }, where version fingerprints the written content and can be passed as baseVersion on the next write without reading the note again.
 ```
 
 #### Token effect
 
-`wiki_read` returns the full body of the requested note plus every linked note reachable within `maxLinkDepth`. Long notes or dense link graphs can add many tokens to the next request. `wiki_search` returns a bounded list of result metadata only.
+`wiki_read` returns the full body of the requested note plus every linked note reachable within `maxLinkDepth`. Long notes or dense link graphs can add many tokens to the next request. `wiki_search` returns a bounded list of result metadata only; its `total` reports matches beyond the cap without returning them.
 
 #### KV Cache effect
 

package/README.zh.md

@@ -53,8 +53,8 @@ kind: "package-reference"
 ### 工具
 
 - `wiki_read(id)` — 按仓库相对路径读取笔记，返回 frontmatter、正文、链接、已解析的链接笔记、内容指纹 `version`、`+08:00` 格式的文件 `mtime`，以及 `modifiedExternally` 标志（文件自本插件上次观察以来在磁盘上被改动时为 `true`，例如 Obsidian 编辑）。插件按绝对路径维护一个 256 条上限的 LRU mtime 表；自身的 `wiki_write` 会刷新记录，因此插件写入永不误报。
-- `wiki_search(query)` — 按标题、id、正文关键词搜索；查询词采用 OR 匹配，并按字段加权的 BM25 式评分排序（标题/id 命中权重最高，稀有词权重更高），另有整段短语加分与被强命中笔记链接的图增强；挂载 `wiki_semantic_search` 时两路排序经 RRF 融合。结果包含分数与反向链接数量。
-- `wiki_write(id, content, mode?, baseVersion?)` — 创建或追加笔记。追加模式保留 frontmatter 并添加时间戳标题；两种写入模式都会把 `created`/`updated` frontmatter 值归一化为 `+08:00` 秒级精度（不可解析的值原样保留）。把 `wiki_read` 返回的 `version` 作为 `baseVersion` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。
+- `wiki_search(query)` — 按标题、id、正文关键词搜索；查询词采用 OR 匹配，并按字段加权的 BM25 式评分排序（标题/id 命中权重最高，稀有词权重更高），另有整段短语加分与被强命中笔记链接的图增强；挂载 `wiki_semantic_search` 时两路排序经 RRF 融合。返回 `{ hits, total, truncated }` 分页结构：每条命中含笔记 id、标题、分数与反向链接；`total` 是 `maxSearchResults` 截断**之前**的全部命中数；`truncated` 为 `true` 表示结果被该上限截断，调用方因此能区分“结果完整”与“还有更多”，而不会误以为仓库里只有这些。
+- `wiki_write(id, content, mode?, baseVersion?)` — 创建或追加笔记。追加模式保留 frontmatter 并添加时间戳标题；两种写入模式都会把 `created`/`updated` frontmatter 值归一化为 `+08:00` 秒级精度（不可解析的值原样保留）。把 `wiki_read` 返回的 `version` 作为 `baseVersion` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。返回值为 `{ id, mode, bytes, version }`，其中 `version` 就是刚发布内容的指纹——可直接作为下一次写入的 `baseVersion`，无需再 `wiki_read` 一次即可串联乐观并发校验。
 
 ### 安全
 
@@ -87,18 +87,18 @@ Read one Markdown note from the wiki vault, optionally following Obsidian-style
 ##### `wiki_search` 的完整描述
 
 ```markdown
-Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns matching note ids, titles, scores, and backlink counts. Use this before asking the user which note to read.
+Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns { hits, total, truncated }: each hit carries the note id, title, score, and backlinks, total counts every match before the result cap, and truncated is true when that cap cut the list. Use this before asking the user which note to read.
 ```
 
 ##### `wiki_write` 的完整描述
 
 ```markdown
-Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header.
+Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header. Returns { id, mode, bytes, version }, where version fingerprints the written content and can be passed as baseVersion on the next write without reading the note again.
 ```
 
 #### Token 影响
 
-`wiki_read` 返回请求笔记的完整正文，以及 `maxLinkDepth` 范围内所有可达链接笔记的正文。长笔记或密集链接图可能显著增加下次请求的 token 数。`wiki_search` 只返回有限的结果元数据。
+`wiki_read` 返回请求笔记的完整正文，以及 `maxLinkDepth` 范围内所有可达链接笔记的正文。长笔记或密集链接图可能显著增加下次请求的 token 数。`wiki_search` 只返回有限的结果元数据；其 `total` 会告知被上限截断而未返回的命中数量。
 
 #### KV Cache 影响
 

package/lib/index.js

@@ -15,6 +15,12 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { formatBeijingTime } from '@jacklika/dsh-memory-time';
 import yaml from 'js-yaml';
 import { codeUnitCompare, fuseRankings, rankNotes } from "./search.js";
+/**
+ * Locale-independent note-id ordering, re-exported so sibling packages that
+ * truncate or tie-break id lists sort by the same rule instead of a copy that
+ * can drift.
+ */
+export { codeUnitCompare };
 /**
  * Compute a vault-relative note id from an absolute path. The result always
  * uses POSIX separators so note ids are stable across Windows, macOS, and Linux.
@@ -480,10 +486,13 @@ export async function buildIndex(root, extensions, indexHiddenDirs = false) {
     }
     const index = new Map();
     for (const note of notes) {
+        const explicitTitle = typeof note.frontmatter.title === 'string' ? note.frontmatter.title.trim() : '';
         const headingMatch = /^#\s+(.+)$/m.exec(note.body);
-        const title = headingMatch !== null && headingMatch[1] !== undefined
-            ? headingMatch[1].trim()
-            : note.id.replace(/\.[^.]+$/, '');
+        const title = explicitTitle !== ''
+            ? explicitTitle
+            : (headingMatch !== null && headingMatch[1] !== undefined
+                ? headingMatch[1].trim()
+                : note.id.replace(/\.[^.]+$/, ''));
         index.set(note.id, { id: note.id, title, backlinks: [], body: note.body });
     }
     const linkResolver = createLinkResolver([...index.keys()]);
@@ -570,7 +579,7 @@ export function apply(ctx, config) {
     })));
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'wiki_search',
-        description: 'Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns matching note ids, titles, scores, and backlink counts. Use this before asking the user which note to read.',
+        description: 'Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns { hits, total, truncated }: each hit carries the note id, title, score, and backlinks, total counts every match before the result cap, and truncated is true when that cap cut the list. Use this before asking the user which note to read.',
         parameters: {
             query: {
                 type: 'string',
@@ -580,16 +589,24 @@ export function apply(ctx, config) {
         },
         output: {
             schema: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    additionalProperties: false,
-                    properties: {
-                        id: { type: 'string' },
-                        title: { type: 'string' },
-                        score: { type: 'number' },
-                        backlinks: { type: 'array', items: { type: 'string' } },
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    hits: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                id: { type: 'string' },
+                                title: { type: 'string' },
+                                score: { type: 'number' },
+                                backlinks: { type: 'array', items: { type: 'string' } },
+                            },
+                        },
                     },
+                    total: { type: 'integer' },
+                    truncated: { type: 'boolean' },
                 },
             },
             render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
@@ -632,12 +649,13 @@ export function apply(ctx, config) {
                     ctx.logger?.warn('tool-memory-filesystem: semantic fusion skipped: wiki_semantic_search returned an error');
                 }
             }
-            return hits.slice(0, resolved.maxSearchResults);
+            const capped = hits.slice(0, resolved.maxSearchResults);
+            return { hits: capped, total: hits.length, truncated: capped.length < hits.length };
         },
     })));
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'wiki_write',
-        description: 'Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header.',
+        description: 'Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header. Returns { id, mode, bytes, version }, where version fingerprints the written content and can be passed as baseVersion on the next write without reading the note again.',
         parameters: {
             id: {
                 type: 'string',
@@ -656,7 +674,7 @@ export function apply(ctx, config) {
             },
             baseVersion: {
                 type: 'string',
-                description: 'Optional version returned by wiki_read. When provided, the write fails if the note changed since that read.',
+                description: 'Optional version returned by wiki_read or by an earlier wiki_write. When provided, the write fails if the note changed since that version.',
             },
         },
         output: {
@@ -667,6 +685,10 @@ export function apply(ctx, config) {
                     id: { type: 'string' },
                     mode: { type: 'string' },
                     bytes: { type: 'integer' },
+                    version: { type: 'string' },
+                    created: { type: 'string' },
+                    updated: { type: 'string' },
+                    committed: { type: 'boolean' },
                 },
             },
             render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
@@ -694,11 +716,15 @@ export function apply(ctx, config) {
                 throw new Error(`tool-memory-filesystem: note ${args.id} changed since it was read; re-read it before writing`);
             }
             let finalBody;
+            let frontmatter = {};
             if (mode === 'overwrite') {
                 finalBody = normalizeTextTimestamps(args.content);
+                frontmatter = splitFrontmatter(finalBody).frontmatter;
             }
             else {
-                const { frontmatter, body } = splitFrontmatter(existing ?? '');
+                const split = splitFrontmatter(existing ?? '');
+                frontmatter = split.frontmatter;
+                const body = split.body;
                 normalizeNoteTimestamps(frontmatter);
                 const timestamp = formatBeijingTime(new Date());
                 // Track note lifetime the way memory_capture does: `created` on the
@@ -722,7 +748,19 @@ export function apply(ctx, config) {
             await writeAtomic(absolutePath, finalBody);
             const info = await stat(absolutePath);
             recordMtime(absolutePath, info.mtimeMs);
-            return { id: vaultRelativeId(vaultRoot, absolutePath), mode, bytes: Buffer.byteLength(finalBody, 'utf8') };
+            const result = {
+                id: vaultRelativeId(vaultRoot, absolutePath),
+                mode,
+                bytes: Buffer.byteLength(finalBody, 'utf8'),
+                // `writeAtomic` publishes `finalBody` verbatim, so this is the same
+                // fingerprint `wiki_read` would report — without a second read.
+                version: noteVersion(finalBody),
+            };
+            if (typeof frontmatter.created === 'string' && frontmatter.created !== '')
+                result.created = frontmatter.created;
+            if (typeof frontmatter.updated === 'string' && frontmatter.updated !== '')
+                result.updated = frontmatter.updated;
+            return result;
         },
     })));
 }

package/lib/types/index.d.ts

@@ -10,8 +10,15 @@
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { type ToolRunContext } from '@deepseek-ai/dsh-tools';
+import { codeUnitCompare } from './search.ts';
 import type { IndexedNote, Note } from './types.ts';
 export type * from './types.ts';
+/**
+ * Locale-independent note-id ordering, re-exported so sibling packages that
+ * truncate or tie-break id lists sort by the same rule instead of a copy that
+ * can drift.
+ */
+export { codeUnitCompare };
 /**
  * Compute a vault-relative note id from an absolute path. The result always
  * uses POSIX separators so note ids are stable across Windows, macOS, and Linux.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jacklika/dsh-tool-memory-filesystem",
   "description": "Model-facing wiki/memory tools over a local Markdown vault: read, search, and write notes with Obsidian-style links and YAML frontmatter.",
-  "version": "0.1.3-alpha.7",
+  "version": "0.1.3-alpha.9",
   "publishConfig": {
     "access": "public"
   },