dsh-prompt-shelf 0.1.0 → 0.1.1

package/README.en.md

@@ -27,6 +27,7 @@ New-session blank pages show it too.
 
 Write `{{name}}` or `{{name=default}}` in the body and that spot becomes an input field on the card:
 inserting substitutes the filled value, falling back to the default, and same-named variables share one value.
+A variable box also accepts `@` to reference workspace files (see below).
 
 Editing a card shows the raw `{{…}}` template, which is where you change it. While creating or editing,
 "＋ Variable" below the body box inserts `{{variable}}` at the cursor and selects the word, so typing renames it.
@@ -38,6 +39,9 @@ In that body box, **Alt+V** (or Ctrl+Alt+V) does the same; it only works there,
 - In the card editor's inputs, typing `@` lists workspace files and folders (arrow keys to move, Enter or Tab
   to pick, Esc to close); picking inserts `@path` (folders end with a slash, and a path containing spaces
   is written as `@"path"`).
+- In a card's **variable box**, typing `@` lists the same files, sessions and plugins (the list floats below
+  the input and flips above when there is no room); picking fills `@path` into that variable's value, so after
+  inserting or replacing into the composer the model reads the file as an @ reference.
 
 ## Where the data lives
 
@@ -62,7 +66,7 @@ dsh plugin --profile desktop add dsh-prompt-shelf
 ```
 
 Restart DSH afterwards. Replace `desktop` with your own profile name if you use another one.
-Requirements: the DSH 0.2.1 line, desktop app or `dsh web`. Compatible with DSH 0.2.1; 0.3 and later are not guaranteed.
+Requirements: DSH 0.2.1 or later, desktop app or `dsh web` (verified on 0.2.1-alpha.3 and 0.2.2-rc.1). Requires DSH >= 0.2.1-alpha.3; verified on 0.2.1-alpha.3 and 0.2.2-rc.1, later versions untested.
 
 ## How it works
 

package/README.md

@@ -24,7 +24,7 @@
 ## 变量
 
 正文里写 `{{名称}}` 或 `{{名称=默认值}}`，这张卡片的正文里那个位置就变成一个输入框：
-插入时用填的值替换，不填就用默认值，同名变量共用一份值。
+插入时用填的值替换，不填就用默认值，同名变量共用一份值。变量框里打 `@` 可以引用工作区文件（见下）。
 
 编辑卡片时看到的是带 `{{…}}` 的原文——改模板在那里改。新建或编辑时正文框下方有「＋ 变量」，
 把光标放到要放变量的位置点它就在光标处插入 `{{变量}}` 并选中「变量」两字，直接打字就是改名。
@@ -35,6 +35,8 @@
 - **任务输入框**里打 `@`：菜单里多出「常用提示词」一组，选中一条把正文落到光标处。
 - **新建 / 编辑卡片的输入框**里打 `@`：列出工作区文件与文件夹（上下键选、回车或 Tab 选中、Esc 关），
   选中插入 `@路径`（目录带尾斜杠，路径含空格时用 `@"路径"`）。
+- **卡片上的变量框**里打 `@`：同样列出文件、对话、插件（浮层出现在输入框下方，放不下时翻到上方），
+  选中把 `@路径` 填进这个变量的值；插入或替换进任务输入框后，模型按 @ 引用去读这个文件。
 
 ## 数据存哪
 
@@ -57,7 +59,7 @@ dsh plugin --profile desktop add dsh-prompt-shelf
 ```
 
 装完重启 DSH。用别的 profile 就把 `desktop` 换成你的 profile 名。
-要求：DSH 0.2.1 系列的桌面端或 `dsh web`。兼容：DSH 0.2.1 系列；0.3 起不保证。
+要求：DSH 0.2.1 及以上的桌面端或 `dsh web`（0.2.1-alpha.3、0.2.2-rc.1 验证通过）。要求 DSH >= 0.2.1-alpha.3；实测 0.2.1-alpha.3、0.2.2-rc.1，更高版本未验证。
 
 ## 机制
 

package/lib/client.js

@@ -39,7 +39,7 @@ var API_URL = "/dsh-prompt-shelf/api/state";
 var FILES_API = "/dsh-prompt-shelf/api/files";
 var PLUGINS_API = "/dsh-prompt-shelf/api/plugins";
 var TITLE_MAX = 28;
-var TEMPLATE_HINT = "\u6B63\u6587\u91CC\u5199 {{\u53D8\u91CF\u540D}}\uFF0C\u6216 {{\u53D8\u91CF\u540D=\u9ED8\u8BA4\u503C}}\uFF1B\u63D2\u5165\u65F6\u7528\u5361\u7247\u91CC\u586B\u7684\u503C\u66FF\u6362\uFF08\u4E0D\u586B\u5C31\u7528\u9ED8\u8BA4\u503C\uFF09\u3002\u6B63\u6587\u6846\u91CC\u6309 Alt+V\uFF08\u6216 Ctrl+Alt+V\uFF09\u4E5F\u80FD\u63D2\u5165\u53D8\u91CF\u3002";
+var TEMPLATE_HINT = "\u6B63\u6587\u91CC\u5199 {{\u53D8\u91CF\u540D}}\uFF0C\u6216 {{\u53D8\u91CF\u540D=\u9ED8\u8BA4\u503C}}\uFF1B\u63D2\u5165\u65F6\u7528\u5361\u7247\u91CC\u586B\u7684\u503C\u66FF\u6362\uFF08\u4E0D\u586B\u5C31\u7528\u9ED8\u8BA4\u503C\uFF09\u3002\u6B63\u6587\u6846\u91CC\u6309 Alt+V\uFF08\u6216 Ctrl+Alt+V\uFF09\u4E5F\u80FD\u63D2\u5165\u53D8\u91CF\uFF1B\u5361\u7247\u4E0A\u7684\u53D8\u91CF\u6846\u91CC\u6253 @ \u53EF\u5F15\u7528\u5DE5\u4F5C\u533A\u6587\u4EF6\u3002";
 var EMPTY_INPUT = { draft: "" };
 var CSS = `
 .zps-root {
@@ -213,13 +213,13 @@ var CSS = `
 }
 /* \u6709\u53D8\u91CF\u7684\u5361\u7247\uFF1A\u6B63\u6587\u6309\u6BB5\u6E32\u67D3\uFF0C\u53D8\u91CF\u4F4D\u7F6E\u662F\u5C0F\u8F93\u5165\u6846\uFF0C\u76F4\u63A5\u539F\u4F4D\u6539\u3002 */
 .zps-cardtext-vars { display: block; cursor: default; }
+.zps-varwrap { display: inline-block; margin: 0 2px; vertical-align: baseline; }
 .zps-var {
   display: inline-block;
   box-sizing: border-box;
   min-width: 84px;
   max-width: 260px;
   height: 22px;
-  margin: 0 2px;
   padding: 0 6px;
   border: 1px solid var(--dsw-alias-border-l2);
   border-radius: var(--dsw-radius-xs);
@@ -230,6 +230,15 @@ var CSS = `
   vertical-align: baseline;
 }
 .zps-var:focus { outline: none; border-color: var(--dsw-alias-brand-primary); }
+/* \u53D8\u91CF\u6846\u7684 @ \u5019\u9009\uFF1Aportal \u5230 body \u7684\u6D6E\u5C42\uFF0C\u4E0D\u88AB\u5361\u7247\u6EDA\u52A8\u5BB9\u5668\u88C1\u6389\u3002 */
+.zps-varmenu {
+  position: fixed;
+  z-index: 1100;
+  width: 360px;
+  max-width: calc(100vw - 16px);
+  border-radius: 10px;
+  box-shadow: var(--dsw-elevation-prominent);
+}
 .zps-varbadge { flex: none; font-size: 11px; color: var(--dsw-alias-label-secondary); }
 .zps-placeholder {
   flex: 1 1 auto;
@@ -522,7 +531,8 @@ function createPromptSource() {
   return {
     trigger: "@",
     name: "\u5E38\u7528\u63D0\u793A\u8BCD",
-    order: 10,
+    // 20：排在「工作区文件」(10) 之后、「历史会话」(30) 之前，和别的 @ 源同序时顺序稳定。
+    order: 20,
     async candidates(_session, req) {
       const keyword = String(req.query || "").trim().toLowerCase();
       const used = /* @__PURE__ */ new Map();
@@ -537,6 +547,9 @@ function createPromptSource() {
         };
       });
     },
+    // 纯文本出口：返回 { text } 换掉触发词，草稿里只有文字、不生成引用卡片——
+    // 所以这个源不需要 codec。哪天改成返回 { insert: { source: … } } 插卡片，
+    // 就必须同时补 codec，否则发送会报 slash: no serializer for reference source "常用提示词"。
     onPick(pick) {
       const id = pick.candidate.value;
       const item = knownItems().find((it) => it.id === id);
@@ -603,6 +616,9 @@ function mentionAt(value, caret) {
   if (at > 0 && !/\s/.test(before[at - 1])) return null;
   return { start: at, end: pos, query };
 }
+function typedAtChar(previous, next, caret) {
+  return String(next || "").length === String(previous || "").length + 1 && String(next || "").charAt(caret - 1) === "@";
+}
 function MentionIcon(props) {
   const kind = props.kind;
   const d = kind === "folder" ? "M1.8 4.2h3.4l1.2 1.3h5.8v6.1H1.8z" : kind === "session" ? "M2 3.6h10v6.1H6.6L4.2 11.7V9.7H2z" : kind === "plugin" ? "M3.2 3.2h7.6v7.6H3.2zM3.2 6.4h7.6M6.4 3.2v7.6" : "M4 1.9h4.4L10.9 4.4v7.7H4z";
@@ -690,26 +706,18 @@ function MentionMenu(props) {
     }) })
   ] });
 }
-function TemplateEditor(props) {
-  const editing = props.editing;
-  const onTitle = props.onTitle;
-  const onText = props.onText;
-  const onCancel = props.onCancel;
-  const onSave = props.onSave;
-  const titleRef = (0, import_react.useRef)(null);
-  const textareaRef = (0, import_react.useRef)(null);
+function useMentionField(listFiles, applyPick) {
   const [menu, setMenu] = (0, import_react.useState)(null);
   const [chosen, setChosen] = (0, import_react.useState)(0);
   const [activeSection, setActiveSection] = (0, import_react.useState)(null);
   const [hits, setHits] = (0, import_react.useState)([]);
   const fetchTimer = (0, import_react.useRef)(0);
   const fetchSeq = (0, import_react.useRef)(0);
-  const prevValue = (0, import_react.useRef)("");
   const refreshHits = (0, import_react.useCallback)((query) => {
     window.clearTimeout(fetchTimer.current);
     const seq = ++fetchSeq.current;
     fetchTimer.current = window.setTimeout(() => {
-      const ask = props.listFiles;
+      const ask = listFiles;
       if (typeof ask !== "function") {
         setHits([]);
         return;
@@ -721,71 +729,51 @@ function TemplateEditor(props) {
         if (seq === fetchSeq.current) setHits([]);
       });
     }, 120);
-  }, [props.listFiles]);
+  }, [listFiles]);
   (0, import_react.useEffect)(() => () => window.clearTimeout(fetchTimer.current), []);
-  const rows = hits;
-  const visibleRows = activeSection ? rows.filter((row) => row.section === activeSection) : rows;
-  const openMention = (0, import_react.useCallback)((field, value, caret, element) => {
-    if (!element) {
-      setMenu(null);
-      return;
-    }
-    let pos = typeof caret === "number" && caret > 0 ? caret : 0;
-    if (pos === 0 && typeof element.selectionStart === "number" && element.selectionStart > 0) {
-      pos = element.selectionStart;
-    }
-    if (pos === 0) pos = String(value || "").length;
+  const track = (0, import_react.useCallback)((field, value, caret, typedAt) => {
+    const pos = typeof caret === "number" && caret > 0 ? caret : String(value || "").length;
     const hit = mentionAt(value, pos);
-    if (!hit) {
-      setMenu(null);
+    if (typedAt) {
+      if (!hit) {
+        setMenu(null);
+        return;
+      }
+      setMenu({ field, start: hit.start, end: hit.end, query: hit.query });
+      setChosen(0);
+      setActiveSection(null);
+      refreshHits(hit.query);
       return;
     }
-    setMenu({ field, start: hit.start, end: hit.end, query: hit.query });
-    setChosen(0);
-    setActiveSection(null);
-    refreshHits(hit.query);
-  }, [refreshHits]);
-  const followMention = (0, import_react.useCallback)((field, value, caret) => {
     setMenu((prev) => {
       if (!prev || prev.field !== field) return prev;
-      const pos = typeof caret === "number" && caret > 0 ? caret : String(value || "").length;
-      const hit = mentionAt(value, pos);
       if (!hit) return null;
       refreshHits(hit.query);
-      return { ...prev, start: hit.start, end: hit.end, query: hit.query };
+      return { field, start: hit.start, end: hit.end, query: hit.query };
     });
   }, [refreshHits]);
-  const pickMention = (0, import_react.useCallback)((row) => {
+  const close = (0, import_react.useCallback)(() => setMenu(null), []);
+  const rows = activeSection ? hits.filter((row) => row.section === activeSection) : hits;
+  const pick = (0, import_react.useCallback)((row) => {
     if (!menu || !row) return;
-    const isTitle = menu.field === "title";
-    const current = isTitle ? String(editing.title || "") : String(editing.text || "");
-    const next = current.slice(0, menu.start) + row.mention + current.slice(menu.end);
-    if (isTitle) onTitle(next);
-    else onText(next);
-    const caret = menu.start + row.mention.length;
-    prevValue.current = next;
+    const settled = menu;
     setMenu(null);
-    window.requestAnimationFrame(() => {
-      const el = isTitle ? titleRef.current : textareaRef.current;
-      if (!el) return;
-      el.focus();
-      el.setSelectionRange(caret, caret);
-    });
-  }, [editing, menu, onText, onTitle]);
-  const menuKey = (0, import_react.useCallback)((event) => {
+    applyPick(row, settled);
+  }, [applyPick, menu]);
+  const onKeyDown = (0, import_react.useCallback)((event) => {
     if (!menu) return false;
     if (event.key === "ArrowDown" || event.key === "ArrowUp") {
       event.preventDefault();
-      if (visibleRows.length > 0) {
+      if (rows.length > 0) {
         const step = event.key === "ArrowDown" ? 1 : -1;
-        setChosen((prev) => (prev + step + visibleRows.length) % visibleRows.length);
+        setChosen((prev) => (prev + step + rows.length) % rows.length);
       }
       return true;
     }
     if (event.key === "Enter" || event.key === "Tab") {
       event.preventDefault();
-      const row = visibleRows[Math.min(chosen, Math.max(0, visibleRows.length - 1))] || visibleRows[0];
-      if (row) pickMention(row);
+      const row = rows[Math.min(chosen, Math.max(0, rows.length - 1))] || rows[0];
+      if (row) pick(row);
       return true;
     }
     if (event.key === "Escape") {
@@ -794,7 +782,34 @@ function TemplateEditor(props) {
       return true;
     }
     return false;
-  }, [chosen, menu, pickMention, visibleRows]);
+  }, [chosen, menu, pick, rows]);
+  return { menu, rows, chosen, activeSection, setActiveSection, setChosen, track, onKeyDown, close };
+}
+function TemplateEditor(props) {
+  const editing = props.editing;
+  const onTitle = props.onTitle;
+  const onText = props.onText;
+  const onCancel = props.onCancel;
+  const onSave = props.onSave;
+  const titleRef = (0, import_react.useRef)(null);
+  const textareaRef = (0, import_react.useRef)(null);
+  const prevValue = (0, import_react.useRef)("");
+  const applyMention = (0, import_react.useCallback)((row, menu) => {
+    const isTitle = menu.field === "title";
+    const current = isTitle ? String(editing.title || "") : String(editing.text || "");
+    const next = current.slice(0, menu.start) + row.mention + current.slice(menu.end);
+    if (isTitle) onTitle(next);
+    else onText(next);
+    const caret = menu.start + row.mention.length;
+    prevValue.current = next;
+    window.requestAnimationFrame(() => {
+      const el = isTitle ? titleRef.current : textareaRef.current;
+      if (!el) return;
+      el.focus();
+      el.setSelectionRange(caret, caret);
+    });
+  }, [editing, onText, onTitle]);
+  const mention = useMentionField(props.listFiles, applyMention);
   const insertVariable = (0, import_react.useCallback)(() => {
     const node = textareaRef.current;
     const text = String(editing.text || "");
@@ -820,14 +835,13 @@ function TemplateEditor(props) {
         onChange: (event) => {
           const value = event.target.value;
           const caret = event.target.selectionStart || 0;
-          const typedAt = value.length === prevValue.current.length + 1 && value.charAt(caret - 1) === "@";
+          const typedAt = typedAtChar(prevValue.current, value, caret);
           prevValue.current = value;
           onTitle(value);
-          if (typedAt) openMention("title", value, caret, event.target);
-          else followMention("title", value, caret);
+          mention.track("title", value, caret, typedAt);
         },
         onKeyDown: (event) => {
-          menuKey(event);
+          mention.onKeyDown(event);
         }
       }
     ),
@@ -841,14 +855,13 @@ function TemplateEditor(props) {
         onChange: (event) => {
           const value = event.target.value;
           const caret = event.target.selectionStart || 0;
-          const typedAt = value.length === prevValue.current.length + 1 && value.charAt(caret - 1) === "@";
+          const typedAt = typedAtChar(prevValue.current, value, caret);
           prevValue.current = value;
           onText(value);
-          if (typedAt) openMention("text", value, caret, event.target);
-          else followMention("text", value, caret);
+          mention.track("text", value, caret, typedAt);
         },
         onKeyDown: (event) => {
-          if (menuKey(event)) return;
+          if (mention.onKeyDown(event)) return;
           if (event.isComposing || event.repeat) return;
           const key = String(event.key || "").toLowerCase();
           if (key !== "v" || event.shiftKey || !event.altKey) return;
@@ -873,21 +886,109 @@ function TemplateEditor(props) {
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", className: "zps-btn", onClick: onCancel, children: "\u53D6\u6D88" }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", className: "zps-btn primary", onClick: onSave, children: "\u4FDD\u5B58" })
     ] }),
-    menu ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    mention.menu ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       MentionMenu,
       {
-        rows: visibleRows,
-        active: activeSection,
+        rows: mention.rows,
+        active: mention.activeSection,
         onSelect: (key) => {
-          setActiveSection(key);
-          setChosen(0);
+          mention.setActiveSection(key);
+          mention.setChosen(0);
         },
-        chosen,
-        onPick: pickMention
+        chosen: mention.chosen,
+        onPick: (row) => mention.pick(row)
       }
     ) : null
   ] });
 }
+function VarField(props) {
+  const value = String(props.value || "");
+  const onChange = props.onChange;
+  const inputRef = (0, import_react.useRef)(null);
+  const prevValue = (0, import_react.useRef)(value);
+  const [anchor, setAnchor] = (0, import_react.useState)(null);
+  const applyMention = (0, import_react.useCallback)((row, menu) => {
+    const current = String(props.value || "");
+    const next = current.slice(0, menu.start) + row.mention + current.slice(menu.end);
+    onChange(next);
+    prevValue.current = next;
+    const caret = menu.start + row.mention.length;
+    window.requestAnimationFrame(() => {
+      const el = inputRef.current;
+      if (!el) return;
+      el.focus();
+      el.setSelectionRange(caret, caret);
+    });
+  }, [onChange, props.value]);
+  const mention = useMentionField(props.listFiles, applyMention);
+  const open = mention.menu !== null;
+  (0, import_react.useEffect)(() => {
+    if (!open) {
+      setAnchor(null);
+      return void 0;
+    }
+    const place = () => {
+      const el = inputRef.current;
+      if (!el) return;
+      const rect = el.getBoundingClientRect();
+      const width = Math.max(280, Math.min(420, rect.width + 240));
+      const height = 248;
+      const below = rect.bottom + 4 + height <= window.innerHeight;
+      setAnchor({
+        left: Math.max(8, Math.min(rect.left, window.innerWidth - width - 8)),
+        top: below ? rect.bottom + 4 : Math.max(8, rect.top - 4 - height),
+        width
+      });
+    };
+    place();
+    window.addEventListener("resize", place);
+    window.addEventListener("scroll", place, true);
+    return () => {
+      window.removeEventListener("resize", place);
+      window.removeEventListener("scroll", place, true);
+    };
+  }, [open]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "zps-varwrap", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "input",
+      {
+        ref: inputRef,
+        className: "zps-var",
+        value,
+        placeholder: props.name,
+        title: "\u53D8\u91CF\uFF1A" + props.name + "\uFF08\u9ED8\u8BA4\u503C\uFF1A" + (props.fallback || "\u7A7A") + "\uFF1B\u6253 @ \u53EF\u5F15\u7528\u5DE5\u4F5C\u533A\u6587\u4EF6\uFF09",
+        onMouseDown: (event) => event.stopPropagation(),
+        onClick: (event) => event.stopPropagation(),
+        onBlur: () => mention.close(),
+        onChange: (event) => {
+          const next = event.target.value;
+          const caret = event.target.selectionStart || 0;
+          const typedAt = typedAtChar(prevValue.current, next, caret);
+          prevValue.current = next;
+          onChange(next);
+          mention.track("var", next, caret, typedAt);
+        },
+        onKeyDown: (event) => mention.onKeyDown(event)
+      }
+    ),
+    open && anchor ? (0, import_react_dom.createPortal)(
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "zps-varmenu", style: { left: anchor.left, top: anchor.top, width: anchor.width }, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        MentionMenu,
+        {
+          rows: mention.rows,
+          active: mention.activeSection,
+          onSelect: (key) => {
+            mention.setActiveSection(key);
+            mention.setChosen(0);
+          },
+          chosen: mention.chosen,
+          onPick: (row) => mention.pick(row)
+        }
+      ) }),
+      document.body
+    ) : null
+  ] });
+}
 function PromptShelf(props) {
   const useInput = props && typeof props.useInput === "function" ? props.useInput : null;
   const inputActions = props ? props.inputActions : void 0;
@@ -1242,15 +1343,13 @@ function PromptShelf(props) {
                   listFiles: props.listFiles
                 }
               ) : varNames.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "zps-cardtext zps-cardtext-vars", children: parts.map((part, index) => part.type === "text" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: part.value }, index) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-                "input",
+                VarField,
                 {
-                  className: "zps-var",
                   value: templateValue(varValues[item.id], part.name, part.fallback),
-                  placeholder: part.name,
-                  title: "\u53D8\u91CF\uFF1A" + part.name + "\uFF08\u9ED8\u8BA4\u503C\uFF1A" + (part.fallback || "\u7A7A") + "\uFF09",
-                  onMouseDown: (event) => event.stopPropagation(),
-                  onClick: (event) => event.stopPropagation(),
-                  onChange: (event) => setVar(item.id, part.name, event.target.value)
+                  name: part.name,
+                  fallback: part.fallback,
+                  onChange: (value) => setVar(item.id, part.name, value),
+                  listFiles: props.listFiles
                 },
                 index
               )) }) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-prompt-shelf",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "在输入框工具行里存常用提示词：搜索、插入或整框替换，带变量与回收站。",
   "type": "module",
   "main": "index.js",
@@ -23,7 +23,7 @@
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.2.1-0 <0.3.0-0"
+    "dsh": ">=0.2.1-0"
   },
   "dsh": {
     "client": {

package/src/entry.jsx

@@ -31,7 +31,7 @@ const PLUGINS_API = '/dsh-prompt-shelf/api/plugins'
 /** 没写标题时，取正文首行前多少字当标题。 */
 const TITLE_MAX = 28
 /** 编辑表单下的占位符写法说明。 */
-const TEMPLATE_HINT = '正文里写 {{变量名}}，或 {{变量名=默认值}}；插入时用卡片里填的值替换（不填就用默认值）。正文框里按 Alt+V（或 Ctrl+Alt+V）也能插入变量。'
+const TEMPLATE_HINT = '正文里写 {{变量名}}，或 {{变量名=默认值}}；插入时用卡片里填的值替换（不填就用默认值）。正文框里按 Alt+V（或 Ctrl+Alt+V）也能插入变量；卡片上的变量框里打 @ 可引用工作区文件。'
 
 /** 输入框不可用时的兜底状态（dock 是 session 范围，理论上永远有输入框）。 */
 const EMPTY_INPUT = { draft: '' }
@@ -208,13 +208,13 @@ const CSS = `
 }
 /* 有变量的卡片：正文按段渲染，变量位置是小输入框，直接原位改。 */
 .zps-cardtext-vars { display: block; cursor: default; }
+.zps-varwrap { display: inline-block; margin: 0 2px; vertical-align: baseline; }
 .zps-var {
   display: inline-block;
   box-sizing: border-box;
   min-width: 84px;
   max-width: 260px;
   height: 22px;
-  margin: 0 2px;
   padding: 0 6px;
   border: 1px solid var(--dsw-alias-border-l2);
   border-radius: var(--dsw-radius-xs);
@@ -225,6 +225,15 @@ const CSS = `
   vertical-align: baseline;
 }
 .zps-var:focus { outline: none; border-color: var(--dsw-alias-brand-primary); }
+/* 变量框的 @ 候选：portal 到 body 的浮层，不被卡片滚动容器裁掉。 */
+.zps-varmenu {
+  position: fixed;
+  z-index: 1100;
+  width: 360px;
+  max-width: calc(100vw - 16px);
+  border-radius: 10px;
+  box-shadow: var(--dsw-elevation-prominent);
+}
 .zps-varbadge { flex: none; font-size: 11px; color: var(--dsw-alias-label-secondary); }
 .zps-placeholder {
   flex: 1 1 auto;
@@ -561,7 +570,8 @@ function createPromptSource() {
   return {
     trigger: '@',
     name: '常用提示词',
-    order: 10,
+    // 20：排在「工作区文件」(10) 之后、「历史会话」(30) 之前，和别的 @ 源同序时顺序稳定。
+    order: 20,
     async candidates(_session, req) {
       const keyword = String(req.query || '').trim().toLowerCase()
       const used = new Map()
@@ -580,6 +590,9 @@ function createPromptSource() {
           }
         })
     },
+    // 纯文本出口：返回 { text } 换掉触发词，草稿里只有文字、不生成引用卡片——
+    // 所以这个源不需要 codec。哪天改成返回 { insert: { source: … } } 插卡片，
+    // 就必须同时补 codec，否则发送会报 slash: no serializer for reference source "常用提示词"。
     onPick(pick) {
       const id = pick.candidate.value
       const item = knownItems().find((it) => it.id === id)
@@ -689,6 +702,11 @@ function mentionAt(value, caret) {
   return { start: at, end: pos, query }
 }
 
+/** 刚敲下一个 @：长度只多 1，且新字符就是 @。打开候选菜单的时机只认这个。 */
+function typedAtChar(previous, next, caret) {
+  return String(next || '').length === String(previous || '').length + 1 && String(next || '').charAt(caret - 1) === '@'
+}
+
 /** 行首图标：文件 / 文件夹 / 对话 / 插件（与输入框 @ 菜单同一套观感）。 */
 function MentionIcon(props) {
   const kind = props.kind
@@ -773,39 +791,26 @@ function MentionMenu(props) {
 }
 
 /**
- * 一张卡片的编辑表单（新建与编辑共用）：标题 + 正文 +「＋ 变量」。
- * 两个输入框里都能打 @ 选已有常用提示词：标题框插「名」，正文框插「整段正文」。
- * 「＋ 变量」把 {{变量}} 插到正文编辑框的光标处，并把「变量」两字选中——直接打字就是改名。
- * @param props.editing - 正在编辑的草稿 {id, title, text}。
- * @param props.onTitle - 标题变更。
- * @param props.onText - 正文变更。
- * @param props.onCancel - 退出编辑。
- * @param props.onSave - 保存。
+ * 输入框里的 @ 候选状态：标题框、正文框、卡片上的变量框共用同一套。
+ * 触发规则与宿主一致：@ 在行首或空白之后、@ 后不含空白，才算触发词。
+ * @param listFiles - 查候选：query → 行数组（[{ id, label, desc, section, mention }]）。
+ * @param applyPick - 选中一行后怎么改值：applyPick(row, menu)，menu 带 { field, start, end, query }。
+ * @returns track（输入变化时喂）、onKeyDown（键盘）、rows / chosen / activeSection / setActiveSection / setChosen（菜单渲染）、close。
  */
-function TemplateEditor(props) {
-  const editing = props.editing
-  const onTitle = props.onTitle
-  const onText = props.onText
-  const onCancel = props.onCancel
-  const onSave = props.onSave
-  const titleRef = useRef(null)
-  const textareaRef = useRef(null)
+function useMentionField(listFiles, applyPick) {
   const [menu, setMenu] = useState(null)
   const [chosen, setChosen] = useState(0)
-  /** 类别栏的当前选择：null = 全部。 */
   const [activeSection, setActiveSection] = useState(null)
-  /** @ 候选：宿主给的工作区文件/文件夹。 */
   const [hits, setHits] = useState([])
   const fetchTimer = useRef(0)
   const fetchSeq = useRef(0)
-  const prevValue = useRef('')
 
   /** 按查询词问一下宿主：工作区里有哪些文件/文件夹。 */
   const refreshHits = useCallback((query) => {
     window.clearTimeout(fetchTimer.current)
     const seq = ++fetchSeq.current
     fetchTimer.current = window.setTimeout(() => {
-      const ask = props.listFiles
+      const ask = listFiles
       if (typeof ask !== 'function') {
         setHits([])
         return
@@ -817,83 +822,67 @@ function TemplateEditor(props) {
         if (seq === fetchSeq.current) setHits([])
       })
     }, 120)
-  }, [props.listFiles])
+  }, [listFiles])
 
   useEffect(() => () => window.clearTimeout(fetchTimer.current), [])
 
-  /** 候选行由 lister 直接给（文件与文件夹在前、对话、插件），这里不再加工。 */
-  const rows = hits
-  /** 类别栏筛选后的可见行。 */
-  const visibleRows = activeSection ? rows.filter((row) => row.section === activeSection) : rows
-
-  /** 输入变化后看一眼光标前是不是 @ 触发词；光标位置拿不到就按文本末尾算。 */
-  const openMention = useCallback((field, value, caret, element) => {
-    if (!element) {
-      setMenu(null)
-      return
-    }
-    let pos = typeof caret === 'number' && caret > 0 ? caret : 0
-    if (pos === 0 && typeof element.selectionStart === 'number' && element.selectionStart > 0) {
-      pos = element.selectionStart
-    }
-    if (pos === 0) pos = String(value || '').length
+  /**
+   * 喂一次输入变化。
+   * @param field - 哪个输入框（同一个 hook 服务多个框时用来隔离）。
+   * @param value - 变化后的整段文字。
+   * @param caret - 光标位置。
+   * @param typedAt - 本次变化是不是刚敲下 @。
+   */
+  const track = useCallback((field, value, caret, typedAt) => {
+    const pos = typeof caret === 'number' && caret > 0 ? caret : String(value || '').length
     const hit = mentionAt(value, pos)
-    if (!hit) {
-      setMenu(null)
+    if (typedAt) {
+      if (!hit) {
+        setMenu(null)
+        return
+      }
+      setMenu({ field, start: hit.start, end: hit.end, query: hit.query })
+      setChosen(0)
+      setActiveSection(null)
+      refreshHits(hit.query)
       return
     }
-    setMenu({ field, start: hit.start, end: hit.end, query: hit.query })
-    setChosen(0)
-    setActiveSection(null)
-    refreshHits(hit.query)
-  }, [refreshHits])
-
-  /** 菜单已打开时跟随输入更新查询词；不再处于触发态就关掉。 */
-  const followMention = useCallback((field, value, caret) => {
     setMenu((prev) => {
       if (!prev || prev.field !== field) return prev
-      const pos = typeof caret === 'number' && caret > 0 ? caret : String(value || '').length
-      const hit = mentionAt(value, pos)
       if (!hit) return null
       refreshHits(hit.query)
-      return { ...prev, start: hit.start, end: hit.end, query: hit.query }
+      return { field, start: hit.start, end: hit.end, query: hit.query }
     })
   }, [refreshHits])
 
-  /** 选中一行：把 @查询段换成 @路径。 */
-  const pickMention = useCallback((row) => {
+  const close = useCallback(() => setMenu(null), [])
+
+  /** 类别栏筛选后的可见行。 */
+  const rows = activeSection ? hits.filter((row) => row.section === activeSection) : hits
+
+  /** 选中一行：关菜单，把「@查询段」交给调用方替换成 row.mention。 */
+  const pick = useCallback((row) => {
     if (!menu || !row) return
-    const isTitle = menu.field === 'title'
-    const current = isTitle ? String(editing.title || '') : String(editing.text || '')
-    const next = current.slice(0, menu.start) + row.mention + current.slice(menu.end)
-    if (isTitle) onTitle(next)
-    else onText(next)
-    const caret = menu.start + row.mention.length
-    prevValue.current = next
+    const settled = menu
     setMenu(null)
-    window.requestAnimationFrame(() => {
-      const el = isTitle ? titleRef.current : textareaRef.current
-      if (!el) return
-      el.focus()
-      el.setSelectionRange(caret, caret)
-    })
-  }, [editing, menu, onText, onTitle])
+    applyPick(row, settled)
+  }, [applyPick, menu])
 
   /** 菜单打开时的键盘：上下选、回车/制表选中、Esc 关。返回 true 表示已处理。 */
-  const menuKey = useCallback((event) => {
+  const onKeyDown = useCallback((event) => {
     if (!menu) return false
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault()
-      if (visibleRows.length > 0) {
+      if (rows.length > 0) {
         const step = event.key === 'ArrowDown' ? 1 : -1
-        setChosen((prev) => (prev + step + visibleRows.length) % visibleRows.length)
+        setChosen((prev) => (prev + step + rows.length) % rows.length)
       }
       return true
     }
     if (event.key === 'Enter' || event.key === 'Tab') {
       event.preventDefault()
-      const row = visibleRows[Math.min(chosen, Math.max(0, visibleRows.length - 1))] || visibleRows[0]
-      if (row) pickMention(row)
+      const row = rows[Math.min(chosen, Math.max(0, rows.length - 1))] || rows[0]
+      if (row) pick(row)
       return true
     }
     if (event.key === 'Escape') {
@@ -902,7 +891,49 @@ function TemplateEditor(props) {
       return true
     }
     return false
-  }, [chosen, menu, pickMention, visibleRows])
+  }, [chosen, menu, pick, rows])
+
+  return { menu, rows, chosen, activeSection, setActiveSection, setChosen, track, onKeyDown, close }
+}
+
+/**
+ * 一张卡片的编辑表单（新建与编辑共用）：标题 + 正文 +「＋ 变量」。
+ * 两个输入框里都能打 @ 选已有常用提示词：标题框插「名」，正文框插「整段正文」。
+ * 「＋ 变量」把 {{变量}} 插到正文编辑框的光标处，并把「变量」两字选中——直接打字就是改名。
+ * @param props.editing - 正在编辑的草稿 {id, title, text}。
+ * @param props.onTitle - 标题变更。
+ * @param props.onText - 正文变更。
+ * @param props.onCancel - 退出编辑。
+ * @param props.onSave - 保存。
+ */
+function TemplateEditor(props) {
+  const editing = props.editing
+  const onTitle = props.onTitle
+  const onText = props.onText
+  const onCancel = props.onCancel
+  const onSave = props.onSave
+  const titleRef = useRef(null)
+  const textareaRef = useRef(null)
+  const prevValue = useRef('')
+
+  /** 选中一行：把「@查询段」换成 row.mention，光标落在插入内容之后。 */
+  const applyMention = useCallback((row, menu) => {
+    const isTitle = menu.field === 'title'
+    const current = isTitle ? String(editing.title || '') : String(editing.text || '')
+    const next = current.slice(0, menu.start) + row.mention + current.slice(menu.end)
+    if (isTitle) onTitle(next)
+    else onText(next)
+    const caret = menu.start + row.mention.length
+    prevValue.current = next
+    window.requestAnimationFrame(() => {
+      const el = isTitle ? titleRef.current : textareaRef.current
+      if (!el) return
+      el.focus()
+      el.setSelectionRange(caret, caret)
+    })
+  }, [editing, onText, onTitle])
+
+  const mention = useMentionField(props.listFiles, applyMention)
 
   const insertVariable = useCallback(() => {
     const node = textareaRef.current
@@ -929,13 +960,12 @@ function TemplateEditor(props) {
         onChange={(event) => {
           const value = event.target.value
           const caret = event.target.selectionStart || 0
-          const typedAt = value.length === prevValue.current.length + 1 && value.charAt(caret - 1) === '@'
+          const typedAt = typedAtChar(prevValue.current, value, caret)
           prevValue.current = value
           onTitle(value)
-          if (typedAt) openMention('title', value, caret, event.target)
-          else followMention('title', value, caret)
+          mention.track('title', value, caret, typedAt)
         }}
-        onKeyDown={(event) => { menuKey(event) }}
+        onKeyDown={(event) => { mention.onKeyDown(event) }}
       />
       <textarea
         ref={textareaRef}
@@ -945,14 +975,13 @@ function TemplateEditor(props) {
         onChange={(event) => {
           const value = event.target.value
           const caret = event.target.selectionStart || 0
-          const typedAt = value.length === prevValue.current.length + 1 && value.charAt(caret - 1) === '@'
+          const typedAt = typedAtChar(prevValue.current, value, caret)
           prevValue.current = value
           onText(value)
-          if (typedAt) openMention('text', value, caret, event.target)
-          else followMention('text', value, caret)
+          mention.track('text', value, caret, typedAt)
         }}
         onKeyDown={(event) => {
-          if (menuKey(event)) return
+          if (mention.onKeyDown(event)) return
           if (event.isComposing || event.repeat) return
           const key = String(event.key || '').toLowerCase()
           // Alt+V（两键最省力）；Ctrl+Alt+V 是备用（输入法拦 Alt 时用）。
@@ -975,14 +1004,14 @@ function TemplateEditor(props) {
         <button type="button" className="zps-btn" onClick={onCancel}>取消</button>
         <button type="button" className="zps-btn primary" onClick={onSave}>保存</button>
       </div>
-      {menu
+      {mention.menu
         ? (
           <MentionMenu
-            rows={visibleRows}
-            active={activeSection}
-            onSelect={(key) => { setActiveSection(key); setChosen(0) }}
-            chosen={chosen}
-            onPick={pickMention}
+            rows={mention.rows}
+            active={mention.activeSection}
+            onSelect={(key) => { mention.setActiveSection(key); mention.setChosen(0) }}
+            chosen={mention.chosen}
+            onPick={(row) => mention.pick(row)}
           />
         )
         : null}
@@ -990,6 +1019,108 @@ function TemplateEditor(props) {
   )
 }
 
+/**
+ * 卡片正文里的一个变量输入框：直接填值；打 @ 也能选工作区文件、对话、插件。
+ * 候选浮层 portal 到 document.body——卡片列表是滚动容器，就地渲染会被裁掉。
+ * @param props.value - 当前取值。
+ * @param props.name - 变量名（占位文字）。
+ * @param props.fallback - 默认值。
+ * @param props.onChange - 值变化。
+ * @param props.listFiles - @ 候选来源。
+ */
+function VarField(props) {
+  const value = String(props.value || '')
+  const onChange = props.onChange
+  const inputRef = useRef(null)
+  const prevValue = useRef(value)
+  /** 候选浮层的位置：相对视口的 fixed 坐标。 */
+  const [anchor, setAnchor] = useState(null)
+
+  /** 选中一行：把「@查询段」换成 row.mention。 */
+  const applyMention = useCallback((row, menu) => {
+    const current = String(props.value || '')
+    const next = current.slice(0, menu.start) + row.mention + current.slice(menu.end)
+    onChange(next)
+    prevValue.current = next
+    const caret = menu.start + row.mention.length
+    window.requestAnimationFrame(() => {
+      const el = inputRef.current
+      if (!el) return
+      el.focus()
+      el.setSelectionRange(caret, caret)
+    })
+  }, [onChange, props.value])
+
+  const mention = useMentionField(props.listFiles, applyMention)
+  const open = mention.menu !== null
+
+  /** 菜单打开时按输入框的位置摆浮层：下方放不下就翻到上方。 */
+  useEffect(() => {
+    if (!open) {
+      setAnchor(null)
+      return undefined
+    }
+    const place = () => {
+      const el = inputRef.current
+      if (!el) return
+      const rect = el.getBoundingClientRect()
+      const width = Math.max(280, Math.min(420, rect.width + 240))
+      const height = 248
+      const below = rect.bottom + 4 + height <= window.innerHeight
+      setAnchor({
+        left: Math.max(8, Math.min(rect.left, window.innerWidth - width - 8)),
+        top: below ? rect.bottom + 4 : Math.max(8, rect.top - 4 - height),
+        width,
+      })
+    }
+    place()
+    window.addEventListener('resize', place)
+    window.addEventListener('scroll', place, true)
+    return () => {
+      window.removeEventListener('resize', place)
+      window.removeEventListener('scroll', place, true)
+    }
+  }, [open])
+
+  return (
+    <div className="zps-varwrap">
+      <input
+        ref={inputRef}
+        className="zps-var"
+        value={value}
+        placeholder={props.name}
+        title={'变量：' + props.name + '（默认值：' + (props.fallback || '空') + '；打 @ 可引用工作区文件）'}
+        onMouseDown={(event) => event.stopPropagation()}
+        onClick={(event) => event.stopPropagation()}
+        onBlur={() => mention.close()}
+        onChange={(event) => {
+          const next = event.target.value
+          const caret = event.target.selectionStart || 0
+          const typedAt = typedAtChar(prevValue.current, next, caret)
+          prevValue.current = next
+          onChange(next)
+          mention.track('var', next, caret, typedAt)
+        }}
+        onKeyDown={(event) => mention.onKeyDown(event)}
+      />
+      {open && anchor
+        ? createPortal(
+          <div className="zps-varmenu" style={{ left: anchor.left, top: anchor.top, width: anchor.width }}>
+            <MentionMenu
+              rows={mention.rows}
+              active={mention.activeSection}
+              onSelect={(key) => { mention.setActiveSection(key); mention.setChosen(0) }}
+              chosen={mention.chosen}
+              onPick={(row) => mention.pick(row)}
+            />
+          </div>,
+          document.body,
+        )
+        : null}
+    </div>
+  )
+}
+
 /**
  * 输入栏下方的入口与独立大窗口（窗口内一条提示词一张卡片）。
  * @param props - slot 标准 props：useInput（草稿选择器）与 inputActions（输入动作）。
@@ -1397,15 +1528,13 @@ export function PromptShelf(props) {
                           part.type === 'text' ? (
                             <span key={index}>{part.value}</span>
                           ) : (
-                            <input
+                            <VarField
                               key={index}
-                              className="zps-var"
                               value={templateValue(varValues[item.id], part.name, part.fallback)}
-                              placeholder={part.name}
-                              title={'变量：' + part.name + '（默认值：' + (part.fallback || '空') + '）'}
-                              onMouseDown={(event) => event.stopPropagation()}
-                              onClick={(event) => event.stopPropagation()}
-                              onChange={(event) => setVar(item.id, part.name, event.target.value)}
+                              name={part.name}
+                              fallback={part.fallback}
+                              onChange={(value) => setVar(item.id, part.name, value)}
+                              listFiles={props.listFiles}
                             />
                           )
                         ))}