dsh-tiddlywiki 0.2.0 → 0.3.0

package/src/host/config.ts

@@ -23,8 +23,10 @@ export interface PluginConfigShape {
   ui?: {
     /** 是否在界面右下角显示「快速笔记」悬浮按钮（默认 true）。 */
     showQuickNote?: boolean
-    /** 是否启用「侧边移到左侧.css」默认 CSS；被删除后随启动补丁还原（默认 true）。 */
-    sidebarLeftCss?: boolean
+    /** 是否显示 TW 面板右下角的「状态/重载」悬浮按钮（默认 true）。 */
+    showPanelStatus?: boolean
+    /** 是否在界面右下角显示「同步」悬浮按钮（默认 true）。 */
+    showSyncButton?: boolean
   }
   uiLanguage?: string
   [key: string]: unknown

package/src/host/git.ts

@@ -118,10 +118,20 @@ export class GitFace {
     return { exists: true, branch, dirty, dirtyFiles, remote, ...(lastCommit !== undefined ? { lastCommit } : {}), ...(ahead !== undefined ? { ahead } : {}), ...(behind !== undefined ? { behind } : {}) }
   }
 
-  /** `git pull --rebase --autostash`; on conflict: abort + report files. */
-  async pull(dir: string): Promise<GitActionResult> {
+  /** `git pull --rebase --autostash`; on conflict: abort + report files.
+   *  On success, `changed: true` means HEAD actually moved (files came in /
+   *  commits were replayed) — callers use it to decide whether a running TW
+   *  child needs a restart to drop its stale in-memory snapshot. */
+  async pull(dir: string): Promise<GitActionResult & { changed?: boolean }> {
+    const before = await this.exec(['rev-parse', 'HEAD'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    const beforeHead = before.ok ? before.stdout.trim() : ''
     const r = await this.exec(['pull', '--rebase', '--autostash'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
-    if (r.ok) return { ok: true, message: r.stdout.trim() || 'pull ok' }
+    if (r.ok) {
+      const after = await this.exec(['rev-parse', 'HEAD'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+      const afterHead = after.ok ? after.stdout.trim() : ''
+      const changed = beforeHead.length > 0 && beforeHead !== afterHead
+      return { ok: true, message: r.stdout.trim() || 'pull ok', ...(changed ? { changed: true } : {}) }
+    }
     const conflictFiles = await this.unmergedFiles(dir)
     await this.exec(['rebase', '--abort'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
     const reason = (r.stderr.trim() || r.stdout.trim()).slice(0, 500)

package/src/host/routes.ts

@@ -15,6 +15,8 @@
  * @module dsh-tiddlywiki/host/routes
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { mkdir, writeFile, access } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
 import type { TiddlyWebClient } from './tw-api.ts'
 import type { WikiServer } from './wiki.ts'
 import type { GitFace } from './git.ts'
@@ -28,18 +30,28 @@ const MAX_BODY_BYTES = 2 * 1024 * 1024
 /** Max passthrough body (tiddler content can be large). */
 const MAX_PROXY_BODY_BYTES = 16 * 1024 * 1024
 
+/** Max uploaded file body. */
+const MAX_UPLOAD_BYTES = 64 * 1024 * 1024
+
 /** Structural webserver face (a subset of dsh-host-webserver). */
 export interface WebServerFace {
   register(route: { kind: 'exact' | 'prefix'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => void }): () => void
 }
 
+/** Effective UI visibility flags returned by /status (mirror index.ts). */
+export interface UiDefaultsPublic {
+  showQuickNote: boolean
+  showPanelStatus: boolean
+  showSyncButton: boolean
+}
+
 export interface RouteDeps {
   server: WikiServer
   getClient: () => TiddlyWebClient | undefined
   git: GitFace
   autoCommit: () => void
   noteDefaults: () => { tag: string }
-  uiDefaults: () => { showQuickNote: boolean }
+  uiDefaults: () => UiDefaultsPublic
   getWikiPath: () => string
 }
 
@@ -61,6 +73,41 @@ function readBody(req: IncomingMessage, limit = MAX_BODY_BYTES): Promise<string>
   })
 }
 
+/** Read a raw (binary-safe) request body up to `limit` bytes. */
+function readBodyBuffer(req: IncomingMessage, limit = MAX_UPLOAD_BYTES): Promise<Buffer> {
+  return new Promise((resolveP, rejectP) => {
+    let size = 0
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > limit) {
+        rejectP(new Error('file too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolveP(Buffer.concat(chunks)))
+    req.on('error', rejectP)
+  })
+}
+
+/**
+ * Sanitize an uploaded filename into a safe bare name (no path separators,
+ * no `..`, no control characters). Returns '' when nothing usable remains.
+ */
+function sanitizeUploadName(input: unknown): string {
+  if (typeof input !== 'string') return ''
+  const name = basename(input.trim().replace(/[\\/]+/g, '/'))
+    .replace(/[\u0000-\u001f\u007f]/g, '')
+    .replace(/[<>:"|?*]/g, '_')
+    .replace(/^\.+/, '')
+    .trim()
+  if (name.length === 0 || name === '.' || name === '..') return ''
+  if (name.length > 160) return name.slice(0, 160)
+  return name
+}
+
 function json(res: ServerResponse, payload: unknown, status = 200): void {
   const body = JSON.stringify(payload)
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
@@ -216,6 +263,107 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     }
   }
 
+  /** One-click git sync for the floating button / settings page: pull →
+   *  commit → push, then return the fresh status. Mirrors the agent tool's
+   *  `action=sync` (design doc §7 conflict policy — rebase conflict aborts).
+   *  When the pull actually changed the working tree, the running TW child
+   *  still holds the old in-memory snapshot — restart it (same port) so the
+   *  UI reflects the pulled files instead of looking stale. */
+  const handleSync = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const dir = deps.getWikiPath()
+    const status = async (): Promise<GitStatusViewPublic | null> => {
+      try { return await deps.git.status(dir) } catch { return null }
+    }
+    try {
+      const pulled = await deps.git.pull(dir)
+      if (!pulled.ok) {
+        json(res, {
+          ok: false,
+          action: 'sync',
+          message: pulled.message,
+          ...(pulled.conflictFiles !== undefined ? { conflictFiles: pulled.conflictFiles } : {}),
+          status: await status(),
+        }, 409)
+        return
+      }
+      let restarted = false
+      let restartError: string | undefined
+      if (pulled.changed === true) {
+        try {
+          await deps.server.restart()
+          restarted = true
+        } catch (err) {
+          restartError = err instanceof Error ? err.message : String(err)
+        }
+      }
+      const committed = await deps.git.commit(dir, `sync ${new Date().toISOString()}`)
+      const pushed = await deps.git.push(dir)
+      const fresh = await status()
+      json(res, {
+        ok: pushed.ok,
+        action: 'sync',
+        message: pushed.ok ? '同步完成' : pushed.message,
+        pull: 'ok',
+        ...(pulled.changed === true ? { changed: true } : {}),
+        restarted,
+        ...(restartError !== undefined ? { restartError } : {}),
+        commit: committed.message,
+        push: pushed.message,
+        status: fresh,
+        lastSync: new Date().toISOString(),
+      }, pushed.ok ? 200 : 502)
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  /**
+   * Save an uploaded file into the wiki's `files/` folder (git-tracked; TW's
+   * core server serves it at `/files/<name>`, get-file.js — no restart
+   * needed). Body is the raw file; the name arrives in `X-Filename`. A
+   * collision appends `-1`, `-2`, … so nothing is ever overwritten.
+   */
+  const handleUpload = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const buf = await readBodyBuffer(req)
+      // Name comes from ?name= (URL-encoded) or the X-Filename header.
+      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+      const nameParam = url.searchParams.get('name')
+      let name = sanitizeUploadName(nameParam ?? '')
+      if (name.length === 0 && typeof req.headers['x-filename'] === 'string') {
+        let decoded = ''
+        try { decoded = decodeURIComponent(req.headers['x-filename'] as string) } catch { decoded = req.headers['x-filename'] as string }
+        name = sanitizeUploadName(decoded)
+      }
+      if (name.length === 0) {
+        json(res, { ok: false, error: 'missing or invalid filename' }, 400)
+        return
+      }
+      const filesDir = join(deps.getWikiPath(), 'files')
+      await mkdir(filesDir, { recursive: true })
+      const ext = extname(name)
+      const stem = ext.length > 0 ? name.slice(0, -ext.length) : name
+      // Collision avoidance: files/some.txt, files/some-1.txt, …
+      let candidate = name
+      for (let i = 1; ; i++) {
+        try { await access(join(filesDir, candidate)) } catch { break }
+        candidate = `${stem}-${i}${ext}`
+      }
+      await writeFile(join(filesDir, candidate), buf)
+      deps.autoCommit()
+      json(res, {
+        ok: true,
+        name: candidate,
+        path: `files/${candidate}`,
+        url: `/files/${encodeURIComponent(candidate)}`,
+        size: buf.length,
+        type: req.headers['content-type'] ?? 'application/octet-stream',
+      })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, err instanceof Error && /too large/.test(err.message) ? 413 : 500)
+    }
+  }
+
   /** Passthrough /dsh-tiddlywiki/api/<rest> → TW root /<rest>. */
   const handleApiProxy = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     const client = deps.getClient()
@@ -251,6 +399,8 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/note`, handler: (req, res) => { void handleNote(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/edit`, handler: (req, res) => { void handleEdit(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/tags`, handler: (req, res) => { void handleTags(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/sync`, handler: (req, res) => { void handleSync(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/upload`, handler: (req, res) => { void handleUpload(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/restart`, handler: (req, res) => { void handleRestart(req, res) } }),
     ctx.webServer.register({ kind: 'prefix', path: `${ROUTE_PREFIX}/api`, handler: (req, res) => { void handleApiProxy(req, res) } }),
   ]

package/src/host/seed-notes.ts

@@ -1,122 +1,79 @@
-/**
- * Built-in doc note + optional UI-patch seeds for the plugin (design doc §14).
- *
- * Two seeds, deliberately different lifetimes:
- *
- * 1. DOC NOTE (`dsh-tiddlywiki 插件说明`) — ONE-SHOT: seeded only the first
- *    time this plugin runs on a wiki (guarded by a `seed-doc-note` marker
- *    tiddler). After that the note is the user's own content: deleting it and
- *    restarting dsh web does NOT recreate it.
- * 2. SIDEBAR-LEFT CSS (`侧边移到左侧.css`) — PATCH-REPAIR: written whenever
- *    the wiki lacks it while the `ui.sidebarLeftCss` option is enabled
- *    (default on). The user may delete it; a restart with the option still on
- *    re-seeds it (the "补丁选项"). Turning the option off stops re-seeding.
- *
- * @module dsh-tiddlywiki/host/seed-notes
- */
-import type { TiddlyWebClient } from './tw-api.ts'
-
-/** Note tiddler title (a normal, searchable note — not a system tiddler). */
-export const DOC_NOTE_TITLE = 'dsh-tiddlywiki 插件说明'
-
-/** Tag that makes the note easy to find via `tiddlywiki_search tag=docs`. */
-export const DOC_NOTE_TAG = 'docs'
-
-/** One-time marker: its presence means "the note was offered once — hands off". */
-export const SEED_MARKER_TITLE = '$:/plugins/dsh-tiddlywiki/seed-doc-note'
-
-/** The note body, TiddlyWiki wiki-text. */
-export const DOC_NOTE_TEXT = `! dsh-tiddlywiki 插件说明
-
-本插件把 **TiddlyWiki 5** 作为 DSH 的持久知识库（wiki 文件夹本身就是一个 git 仓库，随内容自动提交/同步）。
-
-!! 它能做什么
-
-* **5 个 agent 工具**：\`tiddlywiki_search\`（检索）/ \`tiddlywiki_get\`（读）/ \`tiddlywiki_put\`（写）/ \`tiddlywiki_delete\`（删）/ \`tiddlywiki_git_sync\`（git 同步）。
-* **TW 编辑器面板**：侧边栏「TiddlyWiki」按钮 → 在界面中央打开完整版 TW 编辑器。
-* **快速笔记**：右下角悬浮「📝 快速笔记」写随手记（可多选/自动补全 tag），\`Ctrl+Enter\` 保存；点「✏️ 在 TW 中编辑」会弹出独立小窗用 TW 原生编辑器编辑。
-* **git 同步**：写入自动防抖 commit（默认 60 秒）；手动 \`tiddlywiki_git_sync action=sync\` 做 pull → commit → push。
-* **设置页**：DSH 设置 → 「TiddlyWiki 知识库」管理插件/主题/语言与运行配置（含「快速笔记」显示开关、侧边栏移左 CSS 补丁开关）。
-
-!! 知识库纪律（三条）
-
-1. 开工先 \`tiddlywiki_git_sync action=pull\`（rebase + autostash，真冲突会自动 abort 并报文件）。
-2. 收工 \`tiddlywiki_git_sync action=sync\`。
-3. 插件自动 commit 兜底，手动 sync 用于需要主动推送的场合。
-
-!! 主题与语言
-
-* **主题**分两层：每行一个「☑ 加载」（多选 = TW 里可用的主题，依赖链自动带上）和「◉ 活动」（单选 = 当前视觉主题）。应用后自动重启 TW。
-* **语言**：设置页勾选 \`zh-Hans\`（简体）并应用，TW 界面即切换为中文。
-
-!! 说明
-
-* 本笔记由插件在**首次启动**时自动写入（一次性：只写一次）。删除后重启 dsh web **不会自动恢复**——它从此归你所有。
-* 「\`侧边移到左侧.css\`」是插件默认安装的界面补丁（把 TW 右侧栏移到左边）；可在设置页关闭「侧边栏移左 CSS」开关来停用补丁还原。
-* 更多细节见插件仓库 README。`
-
-/**
- * Seed the doc note exactly once per wiki. A marker tiddler records that the
- * note has been offered; from then on the note is user-owned and is never
- * re-created (deleting it survives restarts). Returns whether a note was
- * written this call. Never throws.
- */
-export async function seedDocNote(client: TiddlyWebClient): Promise<boolean> {
-  const marker = await client.get(SEED_MARKER_TITLE).catch(() => undefined)
-  if (marker !== undefined) return false
-  const existing = await client.get(DOC_NOTE_TITLE).catch(() => undefined)
-  let wrote = false
-  if (existing === undefined) {
-    await client.put({
-      title: DOC_NOTE_TITLE,
-      text: DOC_NOTE_TEXT,
-      type: 'text/vnd.tiddlywiki',
-      tags: [DOC_NOTE_TAG],
-    })
-    wrote = true
-  }
-  // Record the offer regardless, so an existing note (upgrade from an older
-  // create-if-missing version) also becomes user-owned from here on.
-  await client
-    .put({ title: SEED_MARKER_TITLE, text: 'seeded-once', type: 'text/plain', tags: [] })
-    .catch(() => undefined)
-  return wrote
-}
-
-/** Sidebar-left CSS tiddler: moves TW's sidebar to the LEFT (mirror of the
- *  `centralised` default), so dsh-better-sidebar's top-right toggle cluster
- *  no longer sits over TW's own right sidebar. A normal tiddler (tag
- *  `$:/tags/Stylesheet`, type text/css) — same pattern as hand-made
- *  `编辑界面微调：小标题·大编辑器.css`, easy to find and delete. */
-export const SIDEBAR_LEFT_CSS_TITLE = '侧边移到左侧.css'
-
-/** The stylesheet body. Hardcoded 960px breakpoint (vanilla default
- *  sidebarbreakpoint) — plain text/css tiddlers don't process `{{...}}`. */
-export const SIDEBAR_LEFT_CSS = `/* 由 dsh-tiddlywiki 插件默认安装：把 TW 右侧栏镜像到左侧（与 centralised 主题默认对称）。
-   删除后，只要设置页「侧边栏移左 CSS」补丁开关开着，插件会在下次启动时重建本 tiddler。 */
-@media (min-width: 960px) {
-  html .tc-sidebar-scrollable {
-    left: 0 !important;
-    right: 50% !important;
-    margin-left: 0 !important;
-    margin-right: 343px !important;
-  }
-}`
-
-/**
- * Patch-repair the sidebar-left CSS while the option is enabled: write it
- * whenever it is missing (fresh installs and deleted-by-user both re-seed).
- * Returns whether it was written. Never throws.
- */
-export async function seedSidebarLeftCss(client: TiddlyWebClient, enabled: boolean): Promise<boolean> {
-  if (!enabled) return false
-  const existing = await client.get(SIDEBAR_LEFT_CSS_TITLE).catch(() => undefined)
-  if (existing !== undefined) return false
-  await client.put({
-    title: SIDEBAR_LEFT_CSS_TITLE,
-    text: SIDEBAR_LEFT_CSS,
-    type: 'text/css',
-    tags: ['$:/tags/Stylesheet'],
-  })
-  return true
-}
+/**
+ * Built-in doc note for the plugin (design doc §14): a short user-facing
+ * "how to use dsh-tiddlywiki" note seeded into the wiki the first time the
+ * plugin runs on a wiki.
+ *
+ * ONE-SHOT seed: a marker tiddler (`seed-doc-note`) records that the note has
+ * been offered once; after that the note is the user's own content — deleting
+ * it and restarting dsh web does NOT recreate it, and edits are never
+ * overwritten.
+ *
+ * @module dsh-tiddlywiki/host/seed-notes
+ */
+import type { TiddlyWebClient } from './tw-api.ts'
+
+/** Note tiddler title (a normal, searchable note — not a system tiddler). */
+export const DOC_NOTE_TITLE = 'dsh-tiddlywiki 插件说明'
+
+/** Tag that makes the note easy to find via `tiddlywiki_search tag=docs`. */
+export const DOC_NOTE_TAG = 'docs'
+
+/** One-time marker: its presence means "the note was offered once — hands off". */
+export const SEED_MARKER_TITLE = '$:/plugins/dsh-tiddlywiki/seed-doc-note'
+
+/** The note body, TiddlyWiki wiki-text. */
+export const DOC_NOTE_TEXT = `! dsh-tiddlywiki 插件说明
+
+本插件把 **TiddlyWiki 5** 作为 DSH 的持久知识库（wiki 文件夹本身就是一个 git 仓库，随内容自动提交/同步）。
+
+!! 它能做什么
+
+* **5 个 agent 工具**：\`tiddlywiki_search\`（检索）/ \`tiddlywiki_get\`（读）/ \`tiddlywiki_put\`（写）/ \`tiddlywiki_delete\`（删）/ \`tiddlywiki_git_sync\`（git 同步）。
+* **TW 编辑器面板**：侧边栏「TiddlyWiki」按钮 → 在界面中央打开完整版 TW 编辑器。
+* **快速笔记**：右下角悬浮「📝 快速笔记」写随手记（可多选/自动补全 tag），\`Ctrl+Enter\` 保存；点「✏️ 在 TW 中编辑」会弹出独立小窗用 TW 原生编辑器编辑。
+* **git 同步**：写入自动防抖 commit（默认 60 秒）；手动 \`tiddlywiki_git_sync action=sync\` 做 pull → commit → push。
+* **设置页**：DSH 设置 → 「TiddlyWiki 知识库」管理插件/主题/语言与运行配置（含「快速笔记」显示开关、面板「状态/重载」悬浮按钮开关）。
+
+!! 知识库纪律（三条）
+
+1. 开工先 \`tiddlywiki_git_sync action=pull\`（rebase + autostash，真冲突会自动 abort 并报文件）。
+2. 收工 \`tiddlywiki_git_sync action=sync\`。
+3. 插件自动 commit 兜底，手动 sync 用于需要主动推送的场合。
+
+!! 主题与语言
+
+* **主题**分两层：每行一个「☑ 加载」（多选 = TW 里可用的主题，依赖链自动带上）和「◉ 活动」（单选 = 当前视觉主题）。应用后自动重启 TW。
+* **语言**：设置页勾选 \`zh-Hans\`（简体）并应用，TW 界面即切换为中文。
+
+!! 说明
+
+* 本笔记由插件在**首次启动**时自动写入（一次性：只写一次）。删除后重启 dsh web **不会自动恢复**——它从此归你所有。
+* 更多细节见插件仓库 README。`
+
+/**
+ * Seed the doc note exactly once per wiki. A marker tiddler records that the
+ * note has been offered; from then on the note is user-owned and is never
+ * re-created (deleting it survives restarts). Returns whether a note was
+ * written this call. Never throws.
+ */
+export async function seedDocNote(client: TiddlyWebClient): Promise<boolean> {
+  const marker = await client.get(SEED_MARKER_TITLE).catch(() => undefined)
+  if (marker !== undefined) return false
+  const existing = await client.get(DOC_NOTE_TITLE).catch(() => undefined)
+  let wrote = false
+  if (existing === undefined) {
+    await client.put({
+      title: DOC_NOTE_TITLE,
+      text: DOC_NOTE_TEXT,
+      type: 'text/vnd.tiddlywiki',
+      tags: [DOC_NOTE_TAG],
+    })
+    wrote = true
+  }
+  // Record the offer regardless, so an existing note (upgrade from an older
+  // create-if-missing version) also becomes user-owned from here on.
+  await client
+    .put({ title: SEED_MARKER_TITLE, text: 'seeded-once', type: 'text/plain', tags: [] })
+    .catch(() => undefined)
+  return wrote
+}

package/src/host/tools.ts

@@ -27,6 +27,10 @@ export interface ToolsDeps {
   noteTag: () => string
   /** Debounced auto-commit touch (fires after our writes). */
   autoCommit: () => void
+  /** Restart the TW child (same port). Called after a pull that changed the
+   *  working tree, so the server drops its stale in-memory snapshot and the
+   *  agent sees the pulled content. Optional — absent in headless contexts. */
+  restartWiki?: () => Promise<void>
 }
 
 function snippetOf(text: string, max = 160): string {
@@ -180,10 +184,21 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
     },
     execute: async (args: { action: 'pull' | 'push' | 'sync'; message?: string }): Promise<SyncResult> => {
       const dir = deps.wikiPath()
+      /** Restart TW after a pull that changed the tree (stale snapshot drop). */
+      const restartIfChanged = async (pulled: { changed?: boolean }): Promise<{ restarted?: boolean; restartError?: string }> => {
+        if (pulled.changed !== true || deps.restartWiki === undefined) return {}
+        try {
+          await deps.restartWiki()
+          return { restarted: true }
+        } catch (err) {
+          return { restartError: err instanceof Error ? err.message : String(err) }
+        }
+      }
       switch (args.action) {
         case 'pull': {
           const r = await deps.git.pull(dir)
-          return { action: args.action, ok: r.ok, message: r.message, ...(r.conflictFiles !== undefined ? { conflictFiles: r.conflictFiles } : {}) }
+          const restart = await restartIfChanged(r)
+          return { action: args.action, ok: r.ok, message: r.message, ...(r.conflictFiles !== undefined ? { conflictFiles: r.conflictFiles } : {}), ...(r.changed === true ? { changed: true } : {}), ...restart }
         }
         case 'push': {
           const r = await deps.git.push(dir)
@@ -192,6 +207,7 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
         case 'sync': {
           const pulled = await deps.git.pull(dir)
           if (!pulled.ok) return { action: args.action, ok: false, message: pulled.message, ...(pulled.conflictFiles !== undefined ? { conflictFiles: pulled.conflictFiles } : {}) }
+          const restart = await restartIfChanged(pulled)
           const committed = await deps.git.commit(dir, args.message ?? `sync ${new Date().toISOString()}`)
           const pushed = await deps.git.push(dir)
           const status = await deps.git.status(dir)
@@ -200,6 +216,8 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
             ok: pushed.ok,
             message: pushed.ok ? '同步完成' : pushed.message,
             pull: 'ok',
+            ...(pulled.changed === true ? { changed: true } : {}),
+            ...restart,
             commit: committed.message,
             push: pushed.message,
             status,
@@ -227,6 +245,9 @@ interface SyncResult {
   pull?: string
   commit?: string
   push?: string
+  changed?: boolean
+  restarted?: boolean
+  restartError?: string
   status?: { branch: string; dirty: boolean; dirtyFiles: string[]; remote: string; lastCommit?: string; ahead?: number; behind?: number }
 }
 
@@ -240,6 +261,12 @@ function renderSync(value: SyncResult): Array<{ type: 'text'; text: string }> {
   }
   if (value.commit !== undefined) lines.push(`本地 commit: ${value.commit}`)
   if (value.push !== undefined) lines.push(`远端 push: ${value.push}`)
+  if (value.changed === true) {
+    lines.push(value.restarted === true
+      ? '本次 pull 拉取了新内容，TW 服务已自动重启（同端口），读取/搜索均为最新快照。'
+      : '本次 pull 拉取了新内容，但 TW 服务未能自动重启（如需最新快照，请手动重启 TW）。')
+  }
+  if (value.restartError !== undefined) lines.push(`TW 重启失败: ${value.restartError}`)
   if (value.status !== undefined) {
     const s = value.status
     const bits = [`分支 ${s.branch}`]