dsh-tiddlywiki 0.26.4 → 0.26.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-tiddlywiki",
   "description": "TiddlyWiki 5 as the DSH persistent knowledge base: fifteen tiddlywiki_* agent tools (filtered search/recent/tags/batch/rewrite/trash/lint + git sync & conflict resolve), a full TiddlyWiki editor embedded in the GUI center column (same-origin proxy, works over Tailscale/LAN/domain), a right-side wiki tab, a per-session summary tab, a quick-note card with draft auto-save behind a single knowledge FAB, an optional clip bookmarklet that also saves selected images as attachments, and git-based sync with auto-commit. Mounts via the official dsh plugin system — no DSH source changes.",
-  "version": "0.26.4",
+  "version": "0.26.6",
   "type": "module",
   "keywords": [
     "dsh",

package/src/client/markdown-editor.ts

@@ -1,128 +1,128 @@
-/**
- * CodeMirror 6 Markdown editor for the quick-note widget (replaces the
- * hand-rolled regex highlighter in the old markdown.ts — real Lezer syntax
- * tree, proper GFM coverage, undo/redo, and a native editing surface).
- *
- * The widget stays a plain-DOM product: CodeMirror is framework-agnostic, so
- * no React is pulled in. The editor is built into a wrapper `<div>`
- * (`.dsh-tw-note-editor`) that the widget can append, drag-drop onto, and
- * re-read via `getValue()`/`setValue()`.
- *
- * Theming follows the DSH design tokens (`--dsw-alias-*`) through a
- * `HighlightStyle` that maps Markdown tags onto the same palette the old
- * `.md-*` rules used, so light/dark both look right.
- *
- * @module dsh-tiddlywiki/client/markdown-editor
- */
-import { EditorView, keymap, placeholder, drawSelection } from '@codemirror/view'
-import { EditorState } from '@codemirror/state'
-import { markdown, markdownLanguage } from '@codemirror/lang-markdown'
-import { syntaxHighlighting, HighlightStyle } from '@codemirror/language'
-import { defaultKeymap, history, historyKeymap } from '@codemirror/commands'
-import { tags as t } from '@lezer/highlight'
-
-/** Design-token aliases (same values as styles.ts / the old .md-* rules). */
-const BRAND = 'var(--dsw-alias-brand-primary, #3e63dd)'
-const BRAND_DIM = 'color-mix(in srgb, var(--dsw-alias-brand-primary, #3e63dd) 55%, transparent)'
-const SECONDARY = 'var(--dsw-alias-label-secondary, #888)'
-const DIMMED = 'var(--dsw-alias-label-dimmed, #999)'
-const MONO = 'ui-monospace, "Cascadia Mono", Consolas, "SF Mono", Menlo, monospace'
-const CODE_BG = 'color-mix(in srgb, var(--dsw-alias-label-secondary, #888) 12%, transparent)'
-const CODE_BLOCK_BG = 'color-mix(in srgb, var(--dsw-alias-label-secondary, #888) 8%, transparent)'
-
-/** Markdown token → design-token style map (mirrors the old .md-* palette). */
-const mdHighlight = HighlightStyle.define([
-  // Headings (# … ######) — brand + bold.
-  { tag: [t.heading1, t.heading2, t.heading3, t.heading4, t.heading5, t.heading6], color: BRAND, fontWeight: '700' },
-  // Markers: #, >, -, *, `, [ ] etc.
-  { tag: t.processingInstruction, color: BRAND_DIM },
-  // Inline code + fenced code text — monospace, tinted background.
-  { tag: t.monospace, fontFamily: MONO, backgroundColor: CODE_BG, borderRadius: '4px', padding: '0 3px' },
-  // Code block content (inside a fence) gets a slightly wider tint.
-  { tag: t.content, fontFamily: MONO, backgroundColor: CODE_BLOCK_BG },
-  { tag: t.strong, fontWeight: '700' },
-  { tag: t.emphasis, fontStyle: 'italic' },
-  { tag: t.strikethrough, textDecoration: 'line-through', opacity: '.75' },
-  { tag: t.link, color: BRAND, textDecoration: 'underline' },
-  { tag: t.url, color: BRAND_DIM, textDecoration: 'underline dotted' },
-  { tag: t.quote, fontStyle: 'italic', color: SECONDARY },
-  { tag: t.contentSeparator, color: DIMMED, textDecoration: 'line-through' },
-  { tag: t.comment, color: DIMMED },
-])
-
-/** Public editor surface the quick-note widget consumes. */
-export interface MarkdownEditor {
-  /** Wrapper element (append/drag-target). */
-  el: HTMLDivElement
-  /** The CodeMirror EditorView (advanced use / future extensions). */
-  view: EditorView
-  getValue(): string
-  setValue(value: string): void
-  /** Insert a Markdown line at the current caret (used by file upload). */
-  insertAtCaret(markdown: string): void
-  focus(): void
-}
-
-export interface MarkdownEditorOptions {
-  /** Placeholder text shown when the doc is empty. */
-  placeholder?: string
-  /** Called on Ctrl/Cmd+Enter (wired after save is defined by the widget). */
-  onSave?: () => void
-  /** Called after every doc change (used for draft auto-save). */
-  onChange?: () => void
-}
-
-/**
- * Build a CodeMirror 6 Markdown editor inside `.dsh-tw-note-editor`.
- * GFM base language (strikethrough, tables, task lists, autolinks) — strictly
- * more coverage than the old regex highlighter.
- */
-export function buildMarkdownEditor(opts: MarkdownEditorOptions = {}): MarkdownEditor {
-  const wrap = document.createElement('div')
-  wrap.className = 'dsh-tw-note-editor'
-
-  const view = new EditorView({
-    parent: wrap,
-    state: EditorState.create({
-      doc: '',
-      extensions: [
-        EditorView.lineWrapping,
-        history(),
-        markdown({ base: markdownLanguage }),
-        syntaxHighlighting(mdHighlight),
-        drawSelection(),
-        placeholder(opts.placeholder ?? ''),
-        keymap.of([
-          ...defaultKeymap,
-          ...historyKeymap,
-          { key: 'Mod-Enter', run: () => { opts.onSave?.(); return true } },
-        ]),
-        EditorView.updateListener.of((update) => {
-          if (update.docChanged) opts.onChange?.()
-        }),
-      ],
-    }),
-  })
-
-  return {
-    el: wrap,
-    view,
-    getValue: () => view.state.doc.toString(),
-    setValue(value: string) {
-      view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: value } })
-    },
-    insertAtCaret(markdownLine: string) {
-      const { from } = view.state.selection.main
-      const line = view.state.doc.lineAt(from)
-      const atLineStart = from === line.from
-      const insert = `${atLineStart ? '' : '\n'}${markdownLine}\n`
-      view.dispatch({
-        changes: { from, insert },
-        selection: { anchor: from + insert.length },
-        scrollIntoView: true,
-      })
-      view.focus()
-    },
-    focus: () => view.focus(),
-  }
-}
+/**
+ * CodeMirror 6 Markdown editor for the quick-note widget (replaces the
+ * hand-rolled regex highlighter in the old markdown.ts — real Lezer syntax
+ * tree, proper GFM coverage, undo/redo, and a native editing surface).
+ *
+ * The widget stays a plain-DOM product: CodeMirror is framework-agnostic, so
+ * no React is pulled in. The editor is built into a wrapper `<div>`
+ * (`.dsh-tw-note-editor`) that the widget can append, drag-drop onto, and
+ * re-read via `getValue()`/`setValue()`.
+ *
+ * Theming follows the DSH design tokens (`--dsw-alias-*`) through a
+ * `HighlightStyle` that maps Markdown tags onto the same palette the old
+ * `.md-*` rules used, so light/dark both look right.
+ *
+ * @module dsh-tiddlywiki/client/markdown-editor
+ */
+import { EditorView, keymap, placeholder, drawSelection } from '@codemirror/view'
+import { EditorState } from '@codemirror/state'
+import { markdown, markdownLanguage } from '@codemirror/lang-markdown'
+import { syntaxHighlighting, HighlightStyle } from '@codemirror/language'
+import { defaultKeymap, history, historyKeymap } from '@codemirror/commands'
+import { tags as t } from '@lezer/highlight'
+
+/** Design-token aliases (same values as styles.ts / the old .md-* rules). */
+const BRAND = 'var(--dsw-alias-brand-primary, #3e63dd)'
+const BRAND_DIM = 'color-mix(in srgb, var(--dsw-alias-brand-primary, #3e63dd) 55%, transparent)'
+const SECONDARY = 'var(--dsw-alias-label-secondary, #888)'
+const DIMMED = 'var(--dsw-alias-label-dimmed, #999)'
+const MONO = 'ui-monospace, "Cascadia Mono", Consolas, "SF Mono", Menlo, monospace'
+const CODE_BG = 'color-mix(in srgb, var(--dsw-alias-label-secondary, #888) 12%, transparent)'
+const CODE_BLOCK_BG = 'color-mix(in srgb, var(--dsw-alias-label-secondary, #888) 8%, transparent)'
+
+/** Markdown token → design-token style map (mirrors the old .md-* palette). */
+const mdHighlight = HighlightStyle.define([
+  // Headings (# … ######) — brand + bold.
+  { tag: [t.heading1, t.heading2, t.heading3, t.heading4, t.heading5, t.heading6], color: BRAND, fontWeight: '700' },
+  // Markers: #, >, -, *, `, [ ] etc.
+  { tag: t.processingInstruction, color: BRAND_DIM },
+  // Inline code + fenced code text — monospace, tinted background.
+  { tag: t.monospace, fontFamily: MONO, backgroundColor: CODE_BG, borderRadius: '4px', padding: '0 3px' },
+  // Code block content (inside a fence) gets a slightly wider tint.
+  { tag: t.content, fontFamily: MONO, backgroundColor: CODE_BLOCK_BG },
+  { tag: t.strong, fontWeight: '700' },
+  { tag: t.emphasis, fontStyle: 'italic' },
+  { tag: t.strikethrough, textDecoration: 'line-through', opacity: '.75' },
+  { tag: t.link, color: BRAND, textDecoration: 'underline' },
+  { tag: t.url, color: BRAND_DIM, textDecoration: 'underline dotted' },
+  { tag: t.quote, fontStyle: 'italic', color: SECONDARY },
+  { tag: t.contentSeparator, color: DIMMED, textDecoration: 'line-through' },
+  { tag: t.comment, color: DIMMED },
+])
+
+/** Public editor surface the quick-note widget consumes. */
+export interface MarkdownEditor {
+  /** Wrapper element (append/drag-target). */
+  el: HTMLDivElement
+  /** The CodeMirror EditorView (advanced use / future extensions). */
+  view: EditorView
+  getValue(): string
+  setValue(value: string): void
+  /** Insert a Markdown line at the current caret (used by file upload). */
+  insertAtCaret(markdown: string): void
+  focus(): void
+}
+
+export interface MarkdownEditorOptions {
+  /** Placeholder text shown when the doc is empty. */
+  placeholder?: string
+  /** Called on Ctrl/Cmd+Enter (wired after save is defined by the widget). */
+  onSave?: () => void
+  /** Called after every doc change (used for draft auto-save). */
+  onChange?: () => void
+}
+
+/**
+ * Build a CodeMirror 6 Markdown editor inside `.dsh-tw-note-editor`.
+ * GFM base language (strikethrough, tables, task lists, autolinks) — strictly
+ * more coverage than the old regex highlighter.
+ */
+export function buildMarkdownEditor(opts: MarkdownEditorOptions = {}): MarkdownEditor {
+  const wrap = document.createElement('div')
+  wrap.className = 'dsh-tw-note-editor'
+
+  const view = new EditorView({
+    parent: wrap,
+    state: EditorState.create({
+      doc: '',
+      extensions: [
+        EditorView.lineWrapping,
+        history(),
+        markdown({ base: markdownLanguage }),
+        syntaxHighlighting(mdHighlight),
+        drawSelection(),
+        placeholder(opts.placeholder ?? ''),
+        keymap.of([
+          ...defaultKeymap,
+          ...historyKeymap,
+          { key: 'Mod-Enter', run: () => { opts.onSave?.(); return true } },
+        ]),
+        EditorView.updateListener.of((update) => {
+          if (update.docChanged) opts.onChange?.()
+        }),
+      ],
+    }),
+  })
+
+  return {
+    el: wrap,
+    view,
+    getValue: () => view.state.doc.toString(),
+    setValue(value: string) {
+      view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: value } })
+    },
+    insertAtCaret(markdownLine: string) {
+      const { from } = view.state.selection.main
+      const line = view.state.doc.lineAt(from)
+      const atLineStart = from === line.from
+      const insert = `${atLineStart ? '' : '\n'}${markdownLine}\n`
+      view.dispatch({
+        changes: { from, insert },
+        selection: { anchor: from + insert.length },
+        scrollIntoView: true,
+      })
+      view.focus()
+    },
+    focus: () => view.focus(),
+  }
+}

package/src/client/state.ts

@@ -1,39 +1,39 @@
-/**
- * Tiny pub/sub panel state shared by the sidebar entry and the center panel.
- *
- * @module dsh-tiddlywiki/client/state
- */
-
-export type PanelListener = (open: boolean) => void
-
-export class PanelState {
-  private open = false
-  private readonly listeners = new Set<PanelListener>()
-
-  isOpen(): boolean {
-    return this.open
-  }
-
-  toggle(): void {
-    this.set(!this.open)
-  }
-
-  openPanel(): void {
-    this.set(true)
-  }
-
-  closePanel(): void {
-    this.set(false)
-  }
-
-  set(value: boolean): void {
-    if (this.open === value) return
-    this.open = value
-    for (const listener of [...this.listeners]) listener(value)
-  }
-
-  subscribe(listener: PanelListener): () => void {
-    this.listeners.add(listener)
-    return () => { this.listeners.delete(listener) }
-  }
-}
+/**
+ * Tiny pub/sub panel state shared by the sidebar entry and the center panel.
+ *
+ * @module dsh-tiddlywiki/client/state
+ */
+
+export type PanelListener = (open: boolean) => void
+
+export class PanelState {
+  private open = false
+  private readonly listeners = new Set<PanelListener>()
+
+  isOpen(): boolean {
+    return this.open
+  }
+
+  toggle(): void {
+    this.set(!this.open)
+  }
+
+  openPanel(): void {
+    this.set(true)
+  }
+
+  closePanel(): void {
+    this.set(false)
+  }
+
+  set(value: boolean): void {
+    if (this.open === value) return
+    this.open = value
+    for (const listener of [...this.listeners]) listener(value)
+  }
+
+  subscribe(listener: PanelListener): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+}

package/src/client/toast.ts

@@ -1,22 +1,22 @@
-/**
- * One-shot transient toast, shared by the quick-note widget and the settings
- * page. Reuses a single body-level element (`.dsh-tw-toast`) with a show
- * class; the element is created lazily and styled by styles.ts.
- *
- * @module dsh-tiddlywiki/client/toast
- */
-
-export function toast(message: string): void {
-  let el = document.querySelector<HTMLElement>('.dsh-tw-toast')
-  if (el === null) {
-    el = document.createElement('div')
-    el.className = 'dsh-tw-toast'
-    document.body.append(el)
-  }
-  el.textContent = message
-  el.classList.add('dsh-tw-toast-show')
-  clearTimeout((el as HTMLElement & { __twToastTimer?: number }).__twToastTimer)
-  ;(el as HTMLElement & { __twToastTimer?: number }).__twToastTimer = window.setTimeout(() => {
-    el?.classList.remove('dsh-tw-toast-show')
-  }, 2_500)
-}
+/**
+ * One-shot transient toast, shared by the quick-note widget and the settings
+ * page. Reuses a single body-level element (`.dsh-tw-toast`) with a show
+ * class; the element is created lazily and styled by styles.ts.
+ *
+ * @module dsh-tiddlywiki/client/toast
+ */
+
+export function toast(message: string): void {
+  let el = document.querySelector<HTMLElement>('.dsh-tw-toast')
+  if (el === null) {
+    el = document.createElement('div')
+    el.className = 'dsh-tw-toast'
+    document.body.append(el)
+  }
+  el.textContent = message
+  el.classList.add('dsh-tw-toast-show')
+  clearTimeout((el as HTMLElement & { __twToastTimer?: number }).__twToastTimer)
+  ;(el as HTMLElement & { __twToastTimer?: number }).__twToastTimer = window.setTimeout(() => {
+    el?.classList.remove('dsh-tw-toast-show')
+  }, 2_500)
+}

package/src/host/tools.ts

@@ -27,6 +27,7 @@ import {
   assertNoConflict,
   buildWriteTiddler,
   flattenTiddlerFields,
+  normalizeFieldsArg,
   normalizeTagArg,
 } from './write-policy.ts'
 import { WORKSPACE_FIELD, WORKSPACE_TAG_PREFIX, workspaceMarkFromCwd } from './workspace.ts'
@@ -112,12 +113,37 @@ function workspaceMarkFor(deps: ToolsDeps, exec: unknown): { id: string; tag: st
   return workspaceMarkFromCwd(deps.workspaceName(sessionId))
 }
 
+/**
+ * 工具参数的 `fields` 归一化（v0.26.5，见 `normalizeFieldsArg`）。
+ *
+ * 历史：`fields` 的参数 schema 曾是 `{ type: 'json' }`——编译后是**纯注解**，
+ * 模型收不到「这是个对象」的信息，于是把 JSON 当字符串发来，被
+ * `withWorkspaceMark` 的 `{ ...fields }` 拆成单字符字段。schema 已改成 object；
+ * 这里再兜一层，字符串能解析成对象就直接用，不必让模型重发一次。
+ * 解析不出对象 → 抛错（绝不静默丢字段，也不按字符展开）。
+ */
+function normalizeFieldsInArgs(args: Record<string, unknown>): Record<string, unknown> {
+  if (!('fields' in args)) return args
+  return { ...args, fields: normalizeFieldsArg(args.fields) }
+}
+
+/** batch_put 专用：逐条目归一化 `fields`（非对象条目原样留给逐条校验报错）。 */
+function normalizeBatchItemsFields(items: unknown): unknown {
+  if (!Array.isArray(items)) return items
+  return items.map((item) => (item !== null && typeof item === 'object' && !Array.isArray(item))
+    ? normalizeFieldsInArgs(item as Record<string, unknown>)
+    : item)
+}
+
 /**
  * Merge the workspace marker into a NEW note's explicit tags and fields.
  *
  * ADDITIVE, never replacing: the caller's tags are kept in front and the caller's
  * own `workspace` field (if it set one) wins, so an explicit value is never
  * silently overwritten. Returns the inputs untouched when there is no marker.
+ *
+ * ⚠️ `fields` 必须已经过 `normalizeFieldsArg()`（v0.26.5）：下面这行 `{ ...fields }`
+ * 对字符串会按字符展开成 `{0:'{',1:'"',…}`——那正是 fields bug 的现场。
  */
 function withWorkspaceMark(
   mark: { id: string; tag: string } | undefined,
@@ -366,23 +392,47 @@ function rewriteRefs(text: string, oldTitle: string, newTitle: string): { text:
 }
 
 /**
- * Insert `addition` at the end of the section introduced by `heading` (Markdown
- * `#`/`##`… or wikitext `!`/`!!`…). Falls back to appending at the end of the
- * document when the heading is not found. Used by tiddlywiki_append so an agent
- * can add to one section of a long note without rewriting the whole file.
+ * Insert `addition` into the section introduced by `heading` (Markdown `#`/`##`…
+ * or wikitext `!`/`!!`…). Used by tiddlywiki_append so an agent can add to one
+ * section of a long note without rewriting the whole file.
+ *
+ * **落点语义**：插在「该标题之后、**下一个任意级别的标题**之前」。所以当标题后面
+ * 紧跟子标题时（`## 4. 定时任务` + `### 槽位表`），内容落在两者**之间**，也就是
+ * 「章节开头」而不是「整节末尾」——这一点以前只在 schema 里写成「段落的末尾」，
+ * 容易让调用方误会（v0.26.6 起描述与回执都写清楚了）。
+ *
+ * **返回 `matched`**：`false` = 没找到该标题，文本被追加到**文末**。调用方**必须**
+ * 把它透出去（v0.26.6 之前这个回退是静默的，回执照样打「段落「X」」，
+ * 于是一次定位失败看起来像成功——Agent 没有任何办法自检）。
+ *
+ * **CRLF（v0.26.6 修复）**：tiddler 正文可能是 CRLF（Windows 上写的/同步来的笔记），
+ * 而 `split('\n')` 会让每行结尾都留着 `\r`。JS 里 `(.*)` 不匹配 `\r`、`$` 也不匹配
+ * `\r` 之前的位置，于是 `/^#{1,6}\s+(.*)$/` 对**每一个**标题都匹配失败 ⇒ 所有带
+ * `heading` 的 append 都静默落到了文末。**只在 CRLF 笔记上复现**（纯 LF 笔记一切正常），
+ * 这就是它像「偶发」的原因。现在只在**匹配时**剥掉行尾 CR，原文行尾一个字节都不动；
+ * 并且新块用**文档自己的行尾**写入，避免 CRLF 笔记被越写越乱（混入 LF 块）。
  */
-function insertIntoSection(base: string, heading: string, addition: string): string {
+function insertIntoSection(base: string, heading: string, addition: string): { text: string; matched: boolean } {
   const lines = base.split('\n')
   const headingText = (line: string): string | null => {
-    const md = /^#{1,6}\s+(.*)$/.exec(line)
+    // 只在匹配时剥离行尾 CR：CRLF 笔记的每一行都会带上它。
+    const s = line.replace(/\r$/, '')
+    const md = /^#{1,6}\s+(.*)$/.exec(s)
     if (md !== null) return (md[1] ?? '').trim()
-    const tw = /^!{1,6}\s*(.*)$/.exec(line)
+    const tw = /^!{1,6}\s*(.*)$/.exec(s)
     if (tw !== null) return (tw[1] ?? '').trim()
     return null
   }
   const start = lines.findIndex((line) => headingText(line) === heading)
+  // 新块跟随文档主流行尾：CRLF 文档里不要再塞 LF 块。
+  const eol = base.includes('\r\n') ? '\r\n' : '\n'
+  const adapt = (s: string): string => (eol === '\n' ? s.replace(/\r\n/g, '\n') : s.replace(/\r\n/g, '\n').split('\n').join('\r\n'))
+  const block = adapt(addition)
   if (start < 0) {
-    return base.trim().length === 0 ? addition : `${base.replace(/\s+$/, '')}\n\n${addition}`
+    return {
+      text: base.trim().length === 0 ? block : `${base.replace(/\s+$/, '')}${eol}${eol}${block}`,
+      matched: false,
+    }
   }
   let end = lines.length
   for (let i = start + 1; i < lines.length; i++) {
@@ -393,8 +443,11 @@ function insertIntoSection(base: string, heading: string, addition: string): str
   }
   const before = lines.slice(0, end).join('\n').replace(/\s+$/, '')
   const after = lines.slice(end).join('\n')
-  const head = `${before}\n\n${addition}`
-  return after.trim().length === 0 ? head : `${head}\n\n${after.replace(/^\s+/, '')}`
+  const head = `${before}${eol}${eol}${block}`
+  return {
+    text: after.trim().length === 0 ? head : `${head}${eol}${eol}${after.replace(/^\s+/, '')}`,
+    matched: true,
+  }
 }
 
 
@@ -624,11 +677,14 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
       title: { type: 'string', description: 'tiddler 标题（精确匹配，覆盖同名）', required: true },
       text: { type: 'string', description: 'tiddler 全文（默认按 Markdown 解析）', required: true },
       tags: { type: 'array', items: { type: 'string' }, description: '标签数组（可选）。不传 = 保留既有条目的原标签；传空数组 [] = 清空全部标签；有内容 = 整体替换' },
-      fields: { type: 'json', description: '附加自定义字段，如 {"date":"2026-09-02"}（可选）。fields.type 是**改内容类型的正规入口**（如 {"type":"text/css"}）：新建条目未指定时默认 text/markdown，覆盖既有条目时保留原类型。注意不要把业务分类值（如 "meeting"）写进 type——业务分类请放 tags' },
+      fields: { type: 'object', additionalProperties: true, description: '附加自定义字段，如 {"date":"2026-09-02"}（可选）。fields.type 是**改内容类型的正规入口**（如 {"type":"text/css"}）：新建条目未指定时默认 text/markdown，覆盖既有条目时保留原类型。注意不要把业务分类值（如 "meeting"）写进 type——业务分类请放 tags' },
       expectedModified: { type: 'string', description: '可选：乐观并发保护。传 tiddlywiki_get 读到的 modified 值，若该条目已被他人改动则拒绝写入（避免覆盖人类在 TW 编辑器里的修改）' },
       expectedRevision: { type: 'integer', description: '可选：乐观并发保护的另一种令牌——传 tiddlywiki_get 返回字段里的 revision（刚写入、还没落盘的条目没有 modified，此时用 revision）' },
       force: { type: 'boolean', description: '可选：true 时忽略 expectedModified/expectedRevision 强制覆盖（默认 false）' },
     },
+    // v0.26.5: `fields` 是对象，但模型可能按 JSON 字符串发来（历史遗留），
+    // 归一化必须发生在 schema 预校验之前——见 normalizeFieldsArg。
+    normalizeArgs: normalizeFieldsInArgs,
     output: {
       render: (_args, value: PutResult) => {
         const lines = [`已写入 tiddler「${value.title}」`]
@@ -715,13 +771,14 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
             title: { type: 'string', description: '标题（精确匹配，覆盖同名）' },
             text: { type: 'string', description: '全文（默认按 Markdown 解析）' },
             tags: { type: 'array', items: { type: 'string' }, description: '标签数组（可选）。不传 = 保留原标签；传空数组 [] = 清空全部标签' },
-            fields: { type: 'json', description: '附加自定义字段（可选）。注意：fields.type 是 TW 内容类型（保留字段，默认已自动补 text/markdown），不要写业务分类值' },
+            fields: { type: 'object', additionalProperties: true, description: '附加自定义字段（可选）。注意：fields.type 是 TW 内容类型（保留字段，默认已自动补 text/markdown），不要写业务分类值' },
             expectedModified: { type: 'string', description: '可选（v0.25.0）：该条目的乐观并发令牌，来自 tiddlywiki_get 的 modified。覆盖已存在条目时若已被改动，只让这一条失败并说明原因，其余条目照常' },
           },
         },
       },
       overwrite: { type: 'boolean', description: '可选：true=覆盖同名（默认），false=跳过已存在的标题' },
     },
+    normalizeArgs: (args) => ({ ...args, items: normalizeBatchItemsFields(args.items) }),
     output: {
       render: (_args, value: BatchResult) => {
         const lines = [`批量写入完成：成功 ${value.written}，跳过 ${value.skipped}，失败 ${value.failed}，共 ${value.items.length} 条。`]
@@ -1070,22 +1127,30 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
   // ── tiddlywiki_append ────────────────────────────────────────────────────
   register(defineTool({
     name: 'tiddlywiki_append',
-    description: '向已有 tiddler 追加/前插文本，或写入指定标题段落的末尾（无需先读全文、不会整篇覆盖）——适合日志、批注、清单的增量写入。条目不存在时默认新建（createIfMissing=false 则报错）。**写入既有条目走与 tiddlywiki_put 同一套写策略**：原有 tags、自定义字段与**内容类型**全部保留（不会把 Markdown 笔记改成 wikitext、也不会把 CSS 改成 Markdown）；可用 fields 显式覆盖字段/类型。新建条目未指定内容类型时才默认 text/markdown（并像 tiddlywiki_put 一样自动补 agent-written 与 `ws/<项目名>` 工作区标记）。⚠️ 本工具内部是「读全文 → 整篇回写」，属于覆盖写入：改前请先 `tiddlywiki_get`，并把读到的 `modified` 作为 `expectedModified` 传回（v0.25.0 起支持），否则人类在 TW 编辑器里的并发修改会被静默回滚。',
+    description: '向已有 tiddler 追加/前插文本，或写入指定标题段落的末尾（无需先读全文、不会整篇覆盖）——适合日志、批注、清单的增量写入。条目不存在时默认新建（createIfMissing=false 则报错）。**写入既有条目走与 tiddlywiki_put 同一套写策略**：原有 tags、自定义字段与**内容类型**全部保留（不会把 Markdown 笔记改成 wikitext、也不会把 CSS 改成 Markdown）；可用 fields 显式覆盖字段/类型。新建条目未指定内容类型时才默认 text/markdown（并像 tiddlywiki_put 一样自动补 agent-written 与 `ws/<项目名>` 工作区标记）。⚠️ 本工具内部是「读全文 → 整篇回写」，属于覆盖写入：改前请先 `tiddlywiki_get`，并把读到的 `modified` 作为 `expectedModified` 传回（v0.25.0 起支持），否则人类在 TW 编辑器里的并发修改会被静默回滚。带 `heading` 时返回 `headingMatched`：`false` = 没找到该标题、文本已追加到**文末**（CRLF 行尾的笔记也能正确定位）。',
     parameters: {
       title: { type: 'string', description: 'tiddler 标题', required: true },
       text: { type: 'string', description: '要追加/前插的文本（默认按 Markdown 写；既有条目保持它自己的内容类型）', required: true },
       mode: { type: 'string', enum: ['append', 'prepend'], description: '可选：append（默认，追加到末尾）/ prepend（插到开头）' },
-      heading: { type: 'string', description: '可选：append 时改为插入到该标题（Markdown # 或 wikitext ! 标题，按标题文本匹配）对应段落的末尾' },
+      heading: { type: 'string', description: '可选：append 时改为写入指定标题的位置（Markdown # 或 wikitext ! 标题，按标题文本匹配、忽略标题级别）。**落点 = 该标题之后、下一个任意级别标题之前**：若该标题后紧跟子标题，内容插在两者之间（即章节开头），**不是整节末尾**。标题不存在时不报错，改为追加到文末，并在回执与返回的 headingMatched=false 里明确说明（别把「没命中」当「写进去了」）' },
       createIfMissing: { type: 'boolean', description: '可选：条目不存在时是否新建（默认 true）' },
       tags: { type: 'array', items: { type: 'string' }, description: '可选：标签（不传则保留既有条目的原标签，传空数组 [] 表示清空全部标签；新建条目会额外自动补 agent-written）' },
-      fields: { type: 'json', description: '可选：显式覆盖的自定义字段（如 {"type":"text/css"}）。不传则保留既有条目的原字段与内容类型' },
+      fields: { type: 'object', additionalProperties: true, description: '可选：显式覆盖的自定义字段（如 {"type":"text/css"}）。不传则保留既有条目的原字段与内容类型' },
       expectedModified: { type: 'string', description: '可选：乐观并发保护。传 tiddlywiki_get 读到的 modified；若条目在你读取之后被改动（人类在 TW 编辑器里改过）则拒绝写入——本工具是整篇回写，这一步能防止吞掉别人的修改' },
       expectedRevision: { type: 'integer', description: '可选：乐观并发保护的另一种令牌——传 tiddlywiki_get 返回字段里的 revision（注意 revision 是 TW 的内存计数器，重启后会复位，长时间跨度请用 expectedModified）' },
       force: { type: 'boolean', description: '可选：true 时忽略 expectedModified/expectedRevision 强制写入（默认 false）' },
     },
+    normalizeArgs: normalizeFieldsInArgs,
     output: {
       render: (_args, value: AppendResult) => {
-        const lines = [`${value.created ? '已新建并写入' : '已增量写入'} tiddler「${value.title}」（${value.mode}${value.heading !== null ? ` · 段落「${value.heading}」` : ''}）：新增 ${value.added} 字符，现共 ${value.total} 字符。`]
+        // v0.26.6：标题没定位到时必须说出来。以前回执无条件打「段落「X」」，
+        // 于是「静默追加到文末」看起来跟「精确写进那一节」一模一样。
+        const headingNote = value.heading === null
+          ? ''
+          : value.headingMatched === false
+            ? ` · ⚠️ 未找到标题「${value.heading}」，已改为追加到文末`
+            : ` · 段落「${value.heading}」`
+        const lines = [`${value.created ? '已新建并写入' : '已增量写入'} tiddler「${value.title}」（${value.mode}${headingNote}）：新增 ${value.added} 字符，现共 ${value.total} 字符。`]
         if (value.type !== null) lines.push(`类型: ${value.type}${value.typeDefaulted === true ? '（新建且未指定，已默认 markdown）' : ''}`)
         if (value.typeChanged !== undefined) lines.push(`⚠️ 内容类型已从 ${value.typeChanged.from} 改为 ${value.typeChanged.to}`)
         if (value.workspace !== undefined) lines.push(`已自动标记工作区: ${WORKSPACE_TAG_PREFIX}${value.workspace}（字段 ${WORKSPACE_FIELD}）`)
@@ -1114,8 +1179,11 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
       const base = existing?.text ?? ''
       const addition = args.text
       let next: string
+      let headingMatched: boolean | undefined
       if (mode === 'append' && typeof args.heading === 'string' && args.heading.trim().length > 0) {
-        next = insertIntoSection(base, args.heading.trim(), addition)
+        const placed = insertIntoSection(base, args.heading.trim(), addition)
+        next = placed.text
+        headingMatched = placed.matched
       } else if (mode === 'prepend') {
         next = base.trim().length === 0 ? addition : `${addition}\n\n${base}`
       } else {
@@ -1146,6 +1214,10 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
         heading: mode === 'append' && typeof args.heading === 'string' && args.heading.trim().length > 0
           ? args.heading.trim()
           : null,
+        // v0.26.6：给了 heading 时它到底有没有定位成功。false = 没找到该标题、文本被
+        // 追加到了**文末**。此前这个回退是静默的，回执还照打「段落「X」」，
+        // 导致一次定位失败看起来完全像成功（Agent 无法自检）。
+        ...(headingMatched !== undefined ? { headingMatched } : {}),
         created: existing === undefined,
         added: addition.length,
         total: next.length,
@@ -1685,7 +1757,7 @@ interface RenameResult { ok: boolean; from: string; to: string; refsUpdated: num
 interface DeleteResult { ok: boolean; title: string; /** true = moved to the trash (recoverable). */ trashed?: boolean; trashTitle?: string }
 interface TrashItem { title: string; at?: string; of?: string }
 interface TrashResult { action: string; message: string; items?: TrashItem[] }
-interface AppendResult { ok: boolean; title: string; mode: 'append' | 'prepend'; heading: string | null; created: boolean; added: number; total: number; type?: string | null; typeDefaulted?: boolean; typeChanged?: { from: string; to: string }; /** 新建时自动打上的工作区标记（v0.24.0）。 */ workspace?: string }
+interface AppendResult { ok: boolean; title: string; mode: 'append' | 'prepend'; heading: string | null; /** v0.26.6：给了 heading 时该标题是否真的定位成功（false = 未找到，文本已追加到文末）。 */ headingMatched?: boolean; created: boolean; added: number; total: number; type?: string | null; typeDefaulted?: boolean; typeChanged?: { from: string; to: string }; /** 新建时自动打上的工作区标记（v0.24.0）。 */ workspace?: string }
 interface BacklinkHit { title: string; refs: number; via: 'link' | 'tag'; modified: string | null }
 interface BacklinkResult { title: string; total: number; linkCount: number; tagCount: number; items: BacklinkHit[] }
 interface AttachResult { ok: boolean; title: string; mime: string; bytes: number; chars: number; source: string | null; embedInto: string | null }