@jacklika/dsh-tool-memory-filesystem 0.1.3-alpha.5 → 0.1.3-alpha.6

package/README.md

@@ -52,9 +52,9 @@ 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, and a `version` content fingerprint.
+- `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. Passing a `version` from `wiki_read` as `baseVersion` makes the write fail loudly when another writer changed the note in between.
+- `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.
 
 ### Security
 
@@ -81,7 +81,7 @@ The model sees the generated `wiki_read`, `wiki_search`, and `wiki_write` schema
 ##### Verbatim description for `wiki_read`
 
 ```markdown
-Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, and linked notes.
+Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, linked notes, mtime, and a modifiedExternally flag that is true when the file changed on disk since this tool last observed it.
 ```
 
 ##### Verbatim description for `wiki_search`

package/README.zh.md

@@ -52,9 +52,9 @@ kind: "package-reference"
 
 ### 工具
 
-- `wiki_read(id)` — 按仓库相对路径读取笔记，返回 frontmatter、正文、链接、已解析的链接笔记，以及内容指纹 `version`。
+- `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 并添加时间戳标题。把 `wiki_read` 返回的 `version` 作为 `baseVersion` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。
+- `wiki_write(id, content, mode?, baseVersion?)` — 创建或追加笔记。追加模式保留 frontmatter 并添加时间戳标题；两种写入模式都会把 `created`/`updated` frontmatter 值归一化为 `+08:00` 秒级精度（不可解析的值原样保留）。把 `wiki_read` 返回的 `version` 作为 `baseVersion` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。
 
 ### 安全
 
@@ -81,7 +81,7 @@ kind: "package-reference"
 ##### `wiki_read` 的完整描述
 
 ```markdown
-Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, and linked notes.
+Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, linked notes, mtime, and a modifiedExternally flag that is true when the file changed on disk since this tool last observed it.
 ```
 
 ##### `wiki_search` 的完整描述

package/lib/index.js

@@ -136,6 +136,68 @@ export function splitFrontmatter(text) {
 export function noteVersion(text) {
     return createHash('sha1').update(text, 'utf8').digest('hex');
 }
+/**
+ * Last `mtimeMs` observed per note path, keyed by absolute path so identical
+ * note ids in different vaults never collide. Bounded at 256 entries with
+ * LRU eviction: an unbounded map would grow with every note ever read in a
+ * long-running process, while a fixed cap keeps the newest observations —
+ * the only ones a `modifiedExternally` comparison can still act on.
+ */
+const observedMtimes = new Map();
+const OBSERVED_MTIME_LIMIT = 256;
+/**
+ * Record the freshest observed `mtimeMs` for a path, evicting the oldest
+ * entry when the cap is reached.
+ */
+function recordMtime(path, mtimeMs) {
+    observedMtimes.delete(path);
+    observedMtimes.set(path, mtimeMs);
+    if (observedMtimes.size > OBSERVED_MTIME_LIMIT) {
+        const oldest = observedMtimes.keys().next().value;
+        if (oldest !== undefined)
+            observedMtimes.delete(oldest);
+    }
+}
+/**
+ * Whether the note changed on disk since this plugin last observed it.
+ * The first observation records and reports `false`; a successful
+ * `wiki_write` re-records so the plugin's own writes never flag.
+ */
+function detectExternalChange(path, mtimeMs) {
+    const seen = observedMtimes.get(path);
+    recordMtime(path, mtimeMs);
+    return seen !== undefined && seen !== mtimeMs;
+}
+/**
+ * Normalize `created`/`updated` frontmatter timestamps to the vault's
+ * `+08:00` second-precision convention. Parseable values in any other form
+ * (`Z`, `+00:00`, millisecond precision) are rewritten; unparseable values
+ * pass through untouched so a non-date string is never corrupted.
+ */
+export function normalizeNoteTimestamps(frontmatter) {
+    for (const key of ['created', 'updated']) {
+        const value = frontmatter[key];
+        if (typeof value !== 'string')
+            continue;
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime()))
+            continue;
+        const normalized = formatBeijingTime(parsed);
+        if (normalized !== value)
+            frontmatter[key] = normalized;
+    }
+}
+/**
+ * Normalize timestamps inside a complete note text. Returns the text
+ * unchanged when there is no frontmatter to rewrite.
+ */
+function normalizeTextTimestamps(text) {
+    const { frontmatter, body } = splitFrontmatter(text);
+    if (Object.keys(frontmatter).length === 0)
+        return text;
+    normalizeNoteTimestamps(frontmatter);
+    return `---\n${yaml.dump(frontmatter).trim()}\n---\n${body}`;
+}
 /**
  * Find all Obsidian-style `[[link]]` references in note text. Aliases of the
  * form `[[link|alias]]` return the link target only.
@@ -480,7 +542,7 @@ export function apply(ctx, config) {
     const vaultRootFor = (exec) => resolveMemoryVaultRoot(resolved.vaultRoot, exec);
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'wiki_read',
-        description: 'Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, and linked notes.',
+        description: 'Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, linked notes, mtime, and a modifiedExternally flag that is true when the file changed on disk since this tool last observed it.',
         parameters: {
             id: {
                 type: 'string',
@@ -498,7 +560,12 @@ export function apply(ctx, config) {
             const linkResolver = createLinkResolver((await listNotePaths(vaultRoot, resolved.extensions, resolved.indexHiddenDirs))
                 .map(path => vaultRelativeId(vaultRoot, path)));
             const note = await readNote(vaultRoot, resolved.extensions, resolved.maxLinkDepth, absolutePath, new Set(), linkResolver);
-            return note;
+            const info = await stat(absolutePath);
+            return {
+                ...note,
+                mtime: formatBeijingTime(info.mtime),
+                modifiedExternally: detectExternalChange(absolutePath, info.mtimeMs),
+            };
         },
     })));
     ctx.effect(() => ctx.tools.register(defineTool({
@@ -628,10 +695,11 @@ export function apply(ctx, config) {
             }
             let finalBody;
             if (mode === 'overwrite') {
-                finalBody = args.content;
+                finalBody = normalizeTextTimestamps(args.content);
             }
             else {
                 const { frontmatter, body } = splitFrontmatter(existing ?? '');
+                normalizeNoteTimestamps(frontmatter);
                 const frontmatterText = Object.keys(frontmatter).length > 0
                     ? `---\n${yaml.dump(frontmatter).trim()}\n---\n\n`
                     : '';
@@ -640,6 +708,8 @@ export function apply(ctx, config) {
             }
             exec.signal.throwIfAborted();
             await writeAtomic(absolutePath, finalBody);
+            const info = await stat(absolutePath);
+            recordMtime(absolutePath, info.mtimeMs);
             return { id: vaultRelativeId(vaultRoot, absolutePath), mode, bytes: Buffer.byteLength(finalBody, 'utf8') };
         },
     })));

package/lib/types/index.d.ts

@@ -88,6 +88,13 @@ export declare function splitFrontmatter(text: string): {
  * @returns content hash stable across processes.
  */
 export declare function noteVersion(text: string): string;
+/**
+ * Normalize `created`/`updated` frontmatter timestamps to the vault's
+ * `+08:00` second-precision convention. Parseable values in any other form
+ * (`Z`, `+00:00`, millisecond precision) are rewritten; unparseable values
+ * pass through untouched so a non-date string is never corrupted.
+ */
+export declare function normalizeNoteTimestamps(frontmatter: Record<string, unknown>): void;
 /**
  * Find all Obsidian-style `[[link]]` references in note text. Aliases of the
  * form `[[link|alias]]` return the link target only.

package/lib/types/types.d.ts

@@ -20,6 +20,17 @@ export interface Note {
      * note in between.
      */
     version: string;
+    /**
+     * File modification time rendered as a `+08:00` timestamp. Only set on the
+     * top-level note returned by `wiki_read`.
+     */
+    mtime?: string;
+    /**
+     * True when the file's `mtime` changed since this plugin last observed it —
+     * evidence that an external writer (e.g. Obsidian) touched the note. Only
+     * set on the top-level note returned by `wiki_read`.
+     */
+    modifiedExternally?: boolean;
 }
 /** Result of a search across the vault. */
 export interface SearchResult {

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.5",
+  "version": "0.1.3-alpha.6",
   "publishConfig": {
     "access": "public"
   },