dsh-plugin-workbench 0.0.11 → 0.0.13

package/lib/index.js

@@ -9,7 +9,9 @@ const name = "dsh-plugin-workbench";
 const inject = [
 	"fs",
 	"connection",
-	"webServer"
+	"webServer",
+	"systemPrompt",
+	"agents"
 ];
 /** Loopback-only logical RPC channel. */
 const CHANNEL = "/dsh-plugin-files";
@@ -229,11 +231,43 @@ function ensureLayoutPatch() {
 	}
 }
 /**
+* Stable system-prompt section teaching the model the workbench `@.\` mention
+* grammar. The core already contributes a generic "paths prefixed with @ are
+* files referenced by the user" section (dsh-file-reference-local, order 99);
+* this one documents the actual syntax the GUI inserts (the `.\` workspace
+* marker, quoted form for paths with spaces) so the model resolves mentions
+* against the session workspace root instead of treating `@.\…` as noise.
+* Static text only — the string is identical on every assembly (KV-cache safe).
+*/
+const FILE_MENTION_PROMPT = "Workspace file mentions written by the file panel use the form `@.<relative-path>` (a `.` or `./` prefix marks a path relative to the current session workspace root; both `\\` and `/` separators are accepted, and paths with spaces use the quoted form `@\"<relative-path>\"`, for example `@\"\\.\\my plan.md\"`). Treat any such mention as a file the user wants you to read or edit: resolve the path against the workspace root and act on it with the file tools (read, glob, grep, edit, write); never claim to have inspected a file you did not actually open.";
+/**
+* File-mention grammar taught to the model (see the FILE_MENTION_PROMPT doc).
+* One section per agent fiber: existing agents at apply time plus every agent
+* created later (agent/created). The core already contributes a generic "paths
+* prefixed with @ are files" section (dsh-file-reference-local, order 99);
+* order 100 puts this more specific grammar right after it.
+*/
+function installMentionPrompt(ctx) {
+	const teach = (agent) => {
+		agent.ctx.systemPrompt.section({
+			name: "dsh-plugin-workbench:file-mention",
+			order: 100,
+			text: FILE_MENTION_PROMPT
+		});
+	};
+	for (const agent of ctx.agents.list()) teach(agent);
+	ctx.on("agent/created", (payload) => {
+		const { agent } = payload;
+		teach(agent);
+	});
+}
+/**
 * One filesystem-backed RPC endpoint pair. Reads never mutate; `signal`
 * cancels the underlying fs call (or aborts between steps).
 */
 function apply(ctx) {
 	ensureLayoutPatch();
+	installMentionPrompt(ctx);
 	const watchState = {
 		dirs: /* @__PURE__ */ new Map(),
 		files: /* @__PURE__ */ new Map(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-workbench",
   "description": "VS Code-style workspace file explorer + editable preview for the dsh web GUI",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "packageManager": "pnpm@11.21.0",
   "engines": {

package/src/client/FileExplorer.tsx

@@ -10,7 +10,7 @@ import { FileIcon } from './fileIcons'
 import type { FilesKey } from './locales'
 import { cancelCut, clearClipboard, closeFilesUnder, copyToClipboard, expandPreview, openFile, popUndo, pushUndo, retargetFile, setCwd, toggleTheme, useClipboard, useTabsState } from './store'
 import type { ClipboardItem, ClipboardMode, UndoEntry } from './store'
-import { DRAG_TYPE, insertIntoComposer, relPathOf } from './composer'
+import { DRAG_TYPE, composerMention, insertIntoComposer, relPathOf } from './composer'
 
 export interface FsListEntry {
   name: string
@@ -950,11 +950,14 @@ export function FileExplorer({
     setSelected(all)
   }, [children, expanded, root])
 
-  /** Insert `@<relative-workspace-path>` into the composer (Claude Code-style mention). */
+  /**
+   * Insert an `@.\<relative-workspace-path>` mention into the composer (the
+   * `.\` prefix marks the path as workspace-relative; see composerMention).
+   */
   const onMention = useCallback((path: string) => {
     const mention = relPathOf(path, cwd)
     if (mention.length === 0) return
-    insertIntoComposer(`@${mention} `)
+    insertIntoComposer(`${composerMention(mention)} `)
   }, [cwd])
 
   // Explorer-style keyboard: Ctrl/Cmd+C/X copy-cut, Ctrl/Cmd+V paste,

package/src/client/FilePreview.tsx

@@ -47,6 +47,22 @@ const PREVIEW_MIN = 240
 const CHAT_MIN = 240
 const PREVIEW_TOO_LARGE_LABEL = '512KB'
 
+/** Persisted split width (px) — survives reloads so a drag is never lost. */
+const PREVIEW_WIDTH_KEY = 'dsh-plugin-workbench:preview-width'
+
+/** Read the persisted preview width; `null` means "use the default 55%". */
+function storedPreviewWidth(): number | null {
+  try {
+    if (typeof window === 'undefined') return null
+    const raw = window.localStorage.getItem(PREVIEW_WIDTH_KEY)
+    if (raw === null) return null
+    const px = Number(raw)
+    return Number.isFinite(px) && px > 0 ? px : null
+  } catch {
+    return null
+  }
+}
+
 /** Same-origin raw-bytes route registered by the host half (see src/index.ts). */
 const RAW_PREFIX = '/dsh-plugin-files/raw'
 
@@ -108,6 +124,23 @@ function clamp(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, value))
 }
 
+/**
+ * Nearest ancestor that actually takes part in layout. The slot system wraps
+ * each slot's content in a `display: contents` element: children still join
+ * the OUTER flex row, but the wrapper itself reports a 0×0 bounding rect.
+ * Measuring that (the old `handle.parentElement`) made `max` collapse to
+ * `PREVIEW_MIN` on the first move — the pane jumped to its minimum width and
+ * could never be dragged back out. Skip every `display: contents` layer.
+ */
+function laidOutParent(el: HTMLElement | null): HTMLElement | null {
+  let node = el?.parentElement ?? null
+  while (node !== null) {
+    if (getComputedStyle(node).display !== 'contents') return node
+    node = node.parentElement
+  }
+  return null
+}
+
 /** Parent directory of a path ('C:/a/b.md' → 'C:/a'; '' when there is none). */
 function dirnameOf(path: string): string {
   const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
@@ -163,6 +196,10 @@ export function FilePreview({ t, readFile, writeFile, watchFiles }: FilePreviewP
   const highlightRef = useRef<HTMLPreElement>(null)
   const textareaRef = useRef<HTMLTextAreaElement>(null)
   const gutterRef = useRef<HTMLDivElement>(null)
+  // Live drag listeners, kept in refs so a new drag can ALWAYS clear any
+  // leftovers (a lost pointerup must not leak a stale onMove into the page).
+  const dragMoveRef = useRef<(ev: PointerEvent) => void>(() => undefined)
+  const dragUpRef = useRef<() => void>(() => undefined)
 
   const refresh = useCallback(() => bump((v) => v + 1), [])
 
@@ -391,26 +428,89 @@ export function FilePreview({ t, readFile, writeFile, watchFiles }: FilePreviewP
     }
   }, [isOpen])
 
+  // Apply the persisted width once the pane gets its first real layout: the
+  // saved px may exceed the CURRENT center column (window resized since the
+  // last drag), so clamp it against a live measurement before applying —
+  // otherwise a stale wide value would squeeze the chat seat to nothing.
+  useEffect(() => {
+    const saved = storedPreviewWidth()
+    if (saved === null) return
+    const preview = previewRef.current
+    const center = laidOutParent(preview)
+    if (preview === null || preview === undefined || center === null || center === undefined) return
+    const centerWidth = center.getBoundingClientRect().width
+    const max = Math.max(PREVIEW_MIN, centerWidth - CHAT_MIN)
+    setPreviewWidth(clamp(saved, PREVIEW_MIN, max))
+  }, [isOpen])
+
+  // Unmount during a drag (slot removed mid-drag): drop the window listeners
+  // so no stale move handler survives to rewrite widths in the next mount.
+  useEffect(() => () => {
+    window.removeEventListener('pointermove', dragMoveRef.current)
+    window.removeEventListener('pointerup', dragUpRef.current)
+    window.removeEventListener('pointercancel', dragUpRef.current)
+  }, [])
+
+  /**
+   * Start a split-width drag. Robustness notes (the "pane suddenly shrinks
+   * and freezes" bug class):
+   *
+   * - Pointer capture reroutes every later pointer event to the handle, so
+   *   `pointerup` fires EVEN when the mouse is released outside the window.
+   *   Without it the up event is lost, `onUp` never runs, and the leftover
+   *   `onMove` keeps rewriting the width from its stale baseline on every
+   *   mouse move anywhere on the page — that is the "cannot drag / cannot
+   *   restore" state.
+   * - `pointercancel` is cleaned up too (browser steals the pointer, e.g. a
+   *   tablet palm or an OS gesture).
+   * - Pointerdown defensively removes any previous listeners first, so even a
+   *   capture-less leftover cannot survive into a second drag.
+   * - The max is re-measured every move: the chat minimum is relative to the
+   *   CURRENT center column, which can change while the drag is in flight.
+   */
   const onHandleDown = useCallback((e: ReactPointerEvent<HTMLDivElement>) => {
     e.preventDefault()
     const handle = handleRef.current
     const preview = previewRef.current
     if (handle === null || preview === null) return
-    const center = handle.parentElement
+    // NOT handle.parentElement: the slot wrapper is `display: contents` and
+    // measures 0×0 — the flex container to clamp against is one level up (see
+    // laidOutParent). Measuring the wrapper made every drag snap to
+    // PREVIEW_MIN and then stick (the reported "sudden shrink / can't drag").
+    const center = laidOutParent(handle)
     if (center === null) return
     const startX = e.clientX
     const startWidth = preview.getBoundingClientRect().width
-    const centerWidth = center.getBoundingClientRect().width
-    const max = Math.max(PREVIEW_MIN, centerWidth - CHAT_MIN)
     const onMove = (ev: PointerEvent) => {
-      setPreviewWidth(clamp(startWidth + ev.clientX - startX, PREVIEW_MIN, max))
+      const centerWidth = center.getBoundingClientRect().width
+      const max = Math.max(PREVIEW_MIN, centerWidth - CHAT_MIN)
+      const width = clamp(startWidth + ev.clientX - startX, PREVIEW_MIN, max)
+      setPreviewWidth(width)
+      try {
+        window.localStorage.setItem(PREVIEW_WIDTH_KEY, String(width))
+      } catch {
+        // storage unavailable — the width just won't persist across reloads
+      }
     }
     const onUp = () => {
-      window.removeEventListener('pointermove', onMove)
-      window.removeEventListener('pointerup', onUp)
+      window.removeEventListener('pointermove', dragMoveRef.current)
+      window.removeEventListener('pointerup', dragUpRef.current)
+      window.removeEventListener('pointercancel', dragUpRef.current)
     }
+    // Defensive reset of any previous drag (see the doc comment above).
+    window.removeEventListener('pointermove', dragMoveRef.current)
+    window.removeEventListener('pointerup', dragUpRef.current)
+    window.removeEventListener('pointercancel', dragUpRef.current)
+    dragMoveRef.current = onMove
+    dragUpRef.current = onUp
     window.addEventListener('pointermove', onMove)
     window.addEventListener('pointerup', onUp)
+    window.addEventListener('pointercancel', onUp)
+    try {
+      handle.setPointerCapture(e.pointerId)
+    } catch {
+      // Pointer capture unsupported — the window listeners still cover the drag.
+    }
   }, [])
 
   const onSave = useCallback(async () => {

package/src/client/composer.ts

@@ -1,17 +1,24 @@
 /**
  * Composer integration for the workbench file column.
  *
- * Two gestures land text in the chat composer without touching the core:
+ * Three gestures land text in the chat composer without touching the core:
  *
  * 1. Drag & drop — dragging one or more tree rows and dropping ANYWHERE
  *    outside the file column (the chat, the composer, the message list)
- *    inserts the dragged paths into the composer. Dropping INSIDE the file
- *    column still performs the tree's own move operation — the tree's drop
- *    handler runs first and stops propagation, so this document-level
- *    listener never sees those drops.
+ *    inserts the dragged paths into the composer as `@.\` mentions (falling
+ *    back to the absolute path when the file sits outside the workspace).
+ *    Dropping INSIDE the file column still performs the tree's own move
+ *    operation — the tree's drop handler runs first and stops propagation, so
+ *    this document-level listener never sees those drops.
  *
- * 2. Context-menu "@引用" — inserts `@<relative-workspace-path>` at the
- *    composer caret.
+ * 2. Context-menu "@引用" — inserts `@.\<relative-workspace-path>` at the
+ *    composer caret (the `.\` prefix marks the path as workspace-relative; a
+ *    path containing whitespace uses the quoted `@"\.\path with space"` form).
+ *
+ * 3. @-mention resolution — turns a mention token (with or without the `.\`
+ *    prefix, quoted or plain) into an absolute path against the session cwd;
+ *    used by the message linkifier and the composer overlay to open the file
+ *    in the workbench preview.
  *
  * The composer is a controlled React textarea, so the value is updated
  * through the native `value` setter + a bubbling `input` event (the standard
@@ -41,11 +48,23 @@ function onDocumentDrop(e: DragEvent): void {
   if (dt === null || !dt.types.includes(DRAG_TYPE)) return
   const paths = readDraggedPaths(dt)
   if (paths.length === 0) return
-  if (!insertIntoComposer(paths.join('\n'))) return
+  if (!insertIntoComposer(paths.map(dragMentionText).join('\n'))) return
   e.preventDefault()
   e.stopPropagation()
 }
 
+/**
+ * One dropped path as chat text: an `@.\` mention when it lives under the
+ * workspace, the absolute path otherwise (or when no cwd is known yet).
+ */
+function dragMentionText(path: string): string {
+  const { cwd } = getTabsState()
+  if (cwd === undefined) return path
+  const rel = relPathOf(path, cwd)
+  if (rel.length === 0 || rel === path) return path
+  return composerMention(rel)
+}
+
 /** Read the JSON paths from the custom type; falls back to raw text. */
 export function readDraggedPaths(dt: DataTransfer | null): string[] {
   if (dt === null) return []
@@ -118,17 +137,41 @@ export function relPathOf(path: string, cwd: string | undefined): string {
 }
 
 /**
- * Resolve an @-mention path (workspace-relative or absolute) against the
- * current workspace cwd; returns the absolute OS path, or undefined when the
- * mention cannot be resolved (no cwd and the path is not absolute).
+ * Format a workspace-relative path as an `@` mention for the composer: the
+ * `.\` (or `./`) prefix marks the path as relative to the workspace root, and
+ * a path containing whitespace uses the quoted `@"..."` form so it stays one
+ * token in the draft (and one link in the rendered message).
+ */
+export function composerMention(rel: string): string {
+  const sep = rel.includes('\\') ? '\\' : '/'
+  const raw = `@.${sep}${rel}`
+  if (/[\s"]/.test(raw)) return `@"${raw}"`
+  return raw
+}
+
+/** Strip quote wrapping and a leading `.\` / `./` workspace marker. */
+function normalizeMention(mention: string): string {
+  let inner = mention
+  if (inner.startsWith('"') && inner.endsWith('"') && inner.length >= 2) inner = inner.slice(1, -1)
+  if (inner.startsWith('.\\') || inner.startsWith('./')) inner = inner.slice(2)
+  return inner
+}
+
+/**
+ * Resolve an @-mention path (workspace-relative with or without the `.\`
+ * marker, or absolute) against the current workspace cwd; returns the absolute
+ * OS path, or undefined when the mention cannot be resolved (no cwd and the
+ * path is not absolute).
  */
 export function resolveMentionPath(mention: string): string | undefined {
-  const absolute = /^[A-Za-z]:[\\/]/.test(mention) || mention.startsWith('/') || mention.startsWith('\\')
+  const inner = normalizeMention(mention)
+  if (inner.length === 0) return undefined
+  const absolute = /^[A-Za-z]:[\\/]/.test(inner) || inner.startsWith('/') || inner.startsWith('\\')
   const { cwd } = getTabsState()
-  if (absolute) return mention
+  if (absolute) return inner
   if (cwd === undefined) return undefined
   const sep = cwd.includes('\\') ? '\\' : '/'
-  return cwd.endsWith('\\') || cwd.endsWith('/') ? cwd + mention : cwd + sep + mention
+  return cwd.endsWith('\\') || cwd.endsWith('/') ? cwd + inner : cwd + sep + inner
 }
 
 /** Open an @-mention's file in the workbench preview (used by the linkifier). */

package/src/client/composerMentions.ts

@@ -0,0 +1,166 @@
+/**
+ * Composer @-mention hyperlink enhancement.
+ *
+ * The composer's visible text lives in a core-rendered backdrop (`textarea`
+ * text is transparent) that React re-renders on every keystroke, so plugin
+ * code must not mutate it. Instead this module renders its OWN overlay — an
+ * absolutely-positioned copy of the draft, in the same font/padding/wrap
+ * metrics as the textarea (copied from the core `.input,.mirror,.backdrop`
+ * rule), with every `@.\`-style mention drawn in the link color and
+ * underlined. The overlay's plain text is fully transparent, so the visible
+ * glyphs still come from the core backdrop; mention spans paint on top at the
+ * identical position (same metrics => same layout), which shows the mention as
+ * a real hyperlink inside the chat input.
+ *
+ * The overlay is appended directly to the core `.grow` container (a sibling
+ * of the backdrop/mirror) — React never manages nodes it did not create, and
+ * the overlay is `position:absolute;inset:0` so it always tracks the input
+ * box, including scroll inside `[data-input-scroll]`. It re-syncs whenever the
+ * core `[data-input-mirror]` text changes (a React-written text node, so it
+ * updates for typing AND programmatic inserts such as the core `@` menu or
+ * this plugin's own insertIntoComposer).
+ *
+ * Interaction: Ctrl/Cmd+click inside the composer textarea opens the mention
+ * under the caret in the workbench preview (the visible link is a decoration;
+ * the real input gains the click), mirroring the rendered-message linkifier.
+ */
+import { openMention } from './composer'
+import { findMentions } from './mentions'
+
+/** One-time install guard (the client bundle re-applies on HMR). */
+let installed = false
+
+/** Style-tag guard (the bundle may re-apply on HMR). */
+let styleInstalled = false
+
+const OVERLAY_CSS = [
+  // Layout metrics must match the core rule for `.input,.mirror,.backdrop`
+  // exactly, so the overlay's invisible text wraps identically to the visible
+  // backdrop text and mentions paint at the right place.
+  '[data-wb-composer-mention-overlay]{position:absolute;inset:0;overflow:hidden;pointer-events:none;box-sizing:border-box;font-family:var(--dsw-font-family);font-size:inherit;line-height:inherit;white-space:pre-wrap;word-break:break-word;overflow-wrap:anywhere;padding:4px 12px 0 16px;color:transparent}',
+  '[data-wb-composer-mention-overlay][hidden]{display:none}',
+  '.dswb-composer-mention{color:var(--dsw-alias-state-business-primary);-webkit-text-fill-color:var(--dsw-alias-state-business-primary);text-decoration:underline;text-underline-offset:2px}',
+].join('')
+
+function installStyle(): void {
+  if (styleInstalled || typeof document === 'undefined') return
+  styleInstalled = true
+  const tagId = 'dsh-plugin-workbench/composer-mention.module.css'
+  if (document.querySelector(`style[data-plugin-css=${JSON.stringify(tagId)}]`) === null) {
+    const tag = document.createElement('style')
+    tag.dataset.plugin = 'dsh-plugin-workbench'
+    tag.dataset.pluginCss = tagId
+    tag.textContent = OVERLAY_CSS
+    document.head.appendChild(tag)
+  }
+}
+
+/** The overlay element for the currently visible composer, or null. */
+let overlayEl: HTMLElement | null = null
+
+/** Last draft rendered into the overlay (avoids re-rendering on own mutations). */
+let lastDraft: string | null = null
+
+/** Create (once per composer instance) and return the overlay inside `.grow`. */
+function ensureOverlay(): HTMLElement | null {
+  const seat = document.querySelector('[data-composer-seat]')
+  if (seat === null) return null
+  const mirror = seat.querySelector<HTMLElement>('[data-input-mirror]')
+  const grow = mirror?.parentElement
+  if (grow === null || grow === undefined) return null
+  let overlay = grow.querySelector<HTMLElement>('[data-wb-composer-mention-overlay]')
+  if (overlay === null) {
+    overlay = document.createElement('div')
+    overlay.dataset.wbComposerMentionOverlay = ''
+    overlay.setAttribute('aria-hidden', 'true')
+    grow.appendChild(overlay)
+  }
+  if (overlayEl !== overlay) {
+    overlayEl = overlay
+    lastDraft = null
+  }
+  return overlay
+}
+
+/** Render the (transparent) draft with mention spans into the overlay. */
+function render(overlay: HTMLElement, draft: string): void {
+  const hits = findMentions(draft)
+  if (hits.length === 0) {
+    overlay.hidden = true
+    return
+  }
+  overlay.hidden = false
+  const frag = document.createDocumentFragment()
+  let cursor = 0
+  for (const hit of hits) {
+    if (hit.start > cursor) frag.appendChild(document.createTextNode(draft.slice(cursor, hit.start)))
+    const span = document.createElement('span')
+    span.className = 'dswb-composer-mention'
+    span.dataset.wbMention = hit.mention
+    span.textContent = draft.slice(hit.start, hit.end)
+    frag.appendChild(span)
+    cursor = hit.end
+  }
+  if (cursor < draft.length) frag.appendChild(document.createTextNode(draft.slice(cursor)))
+  overlay.replaceChildren(frag)
+}
+
+/** Re-sync the overlay with the composer draft (cheap no-op when unchanged). */
+function sync(): void {
+  const seat = document.querySelector('[data-composer-seat]')
+  if (seat === null) return
+  // Skip the hero workspace picker / disabled states — only a usable input gets decorated.
+  if (seat.querySelector('textarea:not([disabled]):not([readonly])') === null) return
+  const mirror = seat.querySelector<HTMLElement>('[data-input-mirror]')
+  const overlay = ensureOverlay()
+  if (mirror === null || overlay === null) return
+  // The mirror renders `${draft}\n`; strip exactly that trailing newline.
+  const draft = (mirror.textContent ?? '').replace(/\n$/, '')
+  if (draft === lastDraft) return
+  lastDraft = draft
+  render(overlay, draft)
+}
+
+/** Ctrl/Cmd+click on the composer: open the mention under the caret. */
+function onDocumentClick(e: MouseEvent): void {
+  if (!(e.ctrlKey || e.metaKey)) return
+  const target = e.target
+  if (!(target instanceof HTMLTextAreaElement)) return
+  if (target.closest('[data-composer-seat]') === null) return
+  // The caret has already moved to the clicked character when click fires.
+  const pos = target.selectionStart
+  const draft = target.value
+  const hits = findMentions(draft)
+  let hit = hits.find((h) => pos >= h.start && pos <= h.end)
+  if (hit === undefined) hit = hits.find((h) => pos - 1 >= h.start && pos - 1 < h.end)
+  if (hit === undefined) return
+  e.preventDefault()
+  e.stopPropagation()
+  openMention(hit.mention)
+}
+
+/** Start the composer mention overlay + Ctrl+click opener (idempotent). */
+export function installComposerMentions(): () => void {
+  if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') return () => undefined
+  if (installed) return () => undefined
+  installed = true
+  installStyle()
+  document.addEventListener('click', onDocumentClick)
+  let pending = false
+  const scan = (): void => {
+    pending = false
+    sync()
+  }
+  const observer = new MutationObserver(() => {
+    if (pending) return
+    pending = true
+    requestAnimationFrame(scan)
+  })
+  observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+  scan()
+  return () => {
+    observer.disconnect()
+    document.removeEventListener('click', onDocumentClick)
+    installed = false
+  }
+}

package/src/client/index.ts

@@ -13,6 +13,7 @@ import { FilePreview } from './FilePreview'
 import { NS, zh, en } from './locales'
 import { installComposerDrops } from './composer'
 import { installMentionLinkifier } from './mentions'
+import { installComposerMentions } from './composerMentions'
 
 const CHANNEL = '/dsh-plugin-files'
 
@@ -22,9 +23,11 @@ export const inject = ['slots', 'sessions', 'workspaces', 'locale', 'connection'
 export function apply(ctx: Context): void {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'files-explorer: dictionaries')
 
-  // Drag-to-chat + @-mention linkifier: DOM-level integrations, one-time
-  // install (module guards make re-applies on HMR idempotent).
+  // Drag-to-chat, @-mention linkifier, and composer mention hyperlinks:
+  // DOM-level integrations, one-time install (module guards make re-applies on
+  // HMR idempotent).
   installComposerDrops()
+  installComposerMentions()
   ctx.effect(() => installMentionLinkifier(), 'files-explorer: @mention linkifier')
 
   const listDir = (path: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'list', { path }, signal))

package/src/client/locales.ts

@@ -18,7 +18,7 @@ export const zh = {
   'tab.expand': '弹出文件详情',
   'tab.diskChanged': '文件已在磁盘上被修改，点击重新加载（会放弃未保存的编辑）',
   'menu.open': '打开预览',
-  'menu.atFile': '@ 在消息中引用',
+  'menu.atFile': '@.\ 在消息中引用',
   'menu.newFile': '新建文件',
   'menu.newFolder': '新建文件夹',
   'menu.rename': '重命名',
@@ -79,7 +79,7 @@ export const en: Record<FilesKey, string> = {
   'tab.expand': 'Expand file details',
   'tab.diskChanged': 'File changed on disk — click to reload (discards unsaved edits)',
   'menu.open': 'Open preview',
-  'menu.atFile': '@ Mention in message',
+  'menu.atFile': '@.\ Mention in message',
   'menu.newFile': 'New File',
   'menu.newFolder': 'New Folder',
   'menu.rename': 'Rename',

package/src/client/mentions.ts

@@ -1,11 +1,11 @@
 /**
  * @-mention linkifier for the conversation.
  *
- * The workbench inserts `@<relative-workspace-path>` into the composer (menu
- * gesture "在消息中引用"), and this module makes the mention VISIBLE as a
- * hyperlink once the message is rendered: any `@` followed by a token that
- * matches the mention grammar is wrapped in an anchor, and clicking it opens
- * the file in the workbench preview.
+ * The workbench inserts `@.\<relative-workspace-path>` into the composer (menu
+ * gesture "在消息中引用"; the `.\` prefix marks a workspace-relative path), and
+ * this module makes the mention VISIBLE as a hyperlink once the message is
+ * rendered: any `@`-prefixed token that matches the mention grammar is wrapped
+ * in an anchor, and clicking it opens the file in the workbench preview.
  *
  * Grammar (anything else stays plain text with no special meaning):
  *   - `@` must sit at a token boundary (start of text, whitespace, or
@@ -14,8 +14,12 @@
  *   - the token is the longest run of non-whitespace, non-`@` characters,
  *     with trailing sentence punctuation trimmed (`.。 ,， ;； :： !！ ?？ )）`…);
  *   - the remaining token must be a RELATIVE path (never drive-absolute or
- *     leading-slash), and path-shaped: either contains a `/` or `\` directory
- *     separator, or is a single segment ending in a file extension.
+ *     leading-slash) — optionally prefixed with a `.\` or `./` workspace
+ *     marker — and path-shaped: either contains a `/` or `\` directory
+ *     separator, or is a single segment ending in a file extension;
+ *   - a path containing whitespace may instead use the quoted `@"token"` form
+ *     (the workbench writes it when the rel path has spaces, e.g.
+ *     `@"\.\my plan.md"`).
  *
  * Scanning mirrors the table-zoom enhancer: a MutationObserver on
  * `document.body`, rAF-coalesced, walks the text nodes of every
@@ -28,6 +32,9 @@ import { openMention } from './composer'
 /** Mention pattern: `@` + token (no whitespace, no embedded `@`). */
 const MENTION_RE = /@([^\s@]+)/g
 
+/** Quoted mention pattern: `@"token"` — used when the path contains whitespace. */
+const QUOTED_MENTION_RE = /@"([^"@]+)"/g
+
 /** Trailing characters trimmed from a mention token before validation. */
 const TRAILING = new Set(['.', ',', ';', ':', '!', '?', '。', '，', '；', '：', '！', '？', ')', '）', ']', '】', '}', '》', '」', '』', '"', "'"])
 
@@ -51,9 +58,10 @@ export function isMentionToken(token: string): boolean {
   if (token.startsWith('/') || token.startsWith('\\')) return false
   if (token.startsWith('..')) return false
   // Path-shaped: a directory separator anywhere, or a single file segment
-  // with an extension.
+  // with an extension. Spaces are allowed in the extension part — unquoted
+  // tokens never contain whitespace anyway, but `@"..."` paths may.
   if (token.includes('/') || token.includes('\\')) return true
-  return /^[^\\/]+\.[A-Za-z0-9_][A-Za-z0-9._~+-]*$/.test(token)
+  return /^[^\\/]+\.[A-Za-z0-9_][A-Za-z0-9._~+ -]*$/.test(token)
 }
 
 /** Trim trailing sentence punctuation from a raw mention token. */
@@ -68,7 +76,9 @@ export function trimMentionToken(raw: string): string {
 /**
  * Extract every valid mention from `text` as [start, end, mention] ranges.
  * `end` covers `@` + the TRIMMED token (trailing punctuation stays outside the
- * link). Pure and testable: the DOM walk uses it and then splits the text node.
+ * link). For the quoted `@"..."` form the span covers `@"..."` including both
+ * quotes, while `mention` carries the inner path (used for resolution).
+ * Pure and testable: the DOM walk uses it and then splits the text node.
  */
 export function findMentions(text: string): Array<{ start: number; end: number; mention: string }> {
   const hits: Array<{ start: number; end: number; mention: string }> = []
@@ -82,7 +92,30 @@ export function findMentions(text: string): Array<{ start: number; end: number;
     if (!isMentionToken(token)) continue
     hits.push({ start: at, end: at + 1 + token.length, mention: token })
   }
-  return hits
+  QUOTED_MENTION_RE.lastIndex = 0
+  let quoted: RegExpExecArray | null
+  while ((quoted = QUOTED_MENTION_RE.exec(text)) !== null) {
+    const at = quoted.index
+    const inner = quoted[1]
+    if (!isBoundaryBefore(at > 0 ? text[at - 1] : undefined)) continue
+    if (!isMentionToken(inner)) continue
+    hits.push({ start: at, end: at + inner.length + 3, mention: inner })
+  }
+  // Deterministic order, and a quoted span that starts on the same `@` as a
+  // plain one shadows that plain hit (plain hits on `@"` tokens are invalid
+  // and filtered out already, so this only guards future grammar regressions).
+  hits.sort((a, b) => a.start - b.start || a.end - b.end)
+  const merged: Array<{ start: number; end: number; mention: string }> = []
+  for (const hit of hits) {
+    const prev = merged[merged.length - 1]
+    if (prev !== undefined && hit.start === prev.start) {
+      merged[merged.length - 1] = hit
+      continue
+    }
+    if (prev !== undefined && hit.start < prev.end) continue
+    merged.push(hit)
+  }
+  return merged
 }
 
 /** Containers whose text is never linkified (code, existing links, overlays). */