tavern-harness 0.1.26 → 0.1.27

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 > 本文件由 `scripts/changelog.mjs` 从 `changelog/v*.md` 生成，请勿手动编辑。
 > 版本对比链接见文末；源文件位于仓库 `changelog/` 目录。
 
+## [0.1.27] - 2026-10-28
+
+### 中文
+
+#### 新增
+
+- 新增 `get_skill_info` 工具：模型可以先查看技能的完整定义（参数、实现方式、执行配置），再决定如何调用
+- 技能里的 JavaScript 执行新增 `$display` 助手：生成报告、图表或网页后可以直接在弹窗中展示给用户（每次执行只展示一个文件）
+
+#### 改进
+
+- 工作区文件管理里每个文件都多了下载按钮，可以直接保存到本地
+- 文件预览会按文件记住缩放比例，切到别的文件再回来不用重新调整
+- 技能的 shell 脚本允许把输出重定向到 /dev/null（Windows 为 NUL），常见的静默输出写法不再被误判为越权
+
+#### 修复
+
+- 修复画中画中的 HTML 预览不会随文件更新而自动刷新、必须关闭重开才能看到最新内容的问题
+
+#### 内部
+
+- 技能的文件读写统一走 JavaScript 助手（`$read` / `$write` / `$append` / `$list`），移除 `file_read` / `file_write` 执行类型
+
+### English
+
+#### Added
+
+- Added `get_skill_info`, so the model can inspect a skill's full definition (parameters, implementation, execution config) before deciding how to call it
+- JavaScript skills can now call `$display` to show a generated report, chart, or page in a popup for the user (one file per execution)
+
+#### Changed
+
+- Every file in the workspace file manager can now be downloaded directly
+- File previews remember the zoom level per file, so switching back no longer resets the view
+- Skill shell scripts may redirect output to /dev/null (NUL on Windows), so common quiet-command patterns are no longer rejected as unsafe writes
+
+#### Fixed
+
+- Fixed HTML previews in picture-in-picture not refreshing when the file changed; the latest content now appears without closing and reopening the preview
+
+#### Internal
+
+- Skill file access now goes through the JavaScript helpers (`$read` / `$write` / `$append` / `$list`); the `file_read` and `file_write` execution types were removed
+
 ## [0.1.26] - 2026-10-27
 
 ### 中文
@@ -742,6 +786,7 @@
 - Vite + React + Zustand + Dexie stack with browser-side local persistence
 
 <!-- 链接定义 -->
+[0.1.27]: https://github.com/Rannichan/Tavern-Harness/compare/v0.1.26...v0.1.27
 [0.1.26]: https://github.com/Rannichan/Tavern-Harness/compare/v0.1.25...v0.1.26
 [0.1.25]: https://github.com/Rannichan/Tavern-Harness/compare/v0.1.24...v0.1.25
 [0.1.24]: https://github.com/Rannichan/Tavern-Harness/compare/v0.1.23...v0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tavern-harness",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Tavern Harness — 酒馆模式下的本地 AI Agent 助手（MyAgent-Android 的 Web 复刻）",
   "private": false,
   "type": "module",

package/sandbox-server.mjs

@@ -877,6 +877,18 @@ function isPublicLinkReadPath(value, sessionBase) {
   return normalized === 'public' || normalized.startsWith('public/');
 }
 
+/** Only the platform null device may be used outside the workspace, and only as a redirect sink. */
+function isNullDeviceSink(value) {
+  const candidate = extractPathCandidate(value);
+  if (!candidate) return false;
+  const normalized = candidate.replace(/\\/g, '/').trim();
+  return IS_WIN ? normalized.toUpperCase() === 'NUL' : normalized === '/dev/null';
+}
+
+function redirectWritePath(value, sessionBase) {
+  return isNullDeviceSink(value) ? (IS_WIN ? 'NUL' : '/dev/null') : join(sessionBase, value);
+}
+
 function resolvesOutsideSession(value, sessionBase) {
   const candidate = extractPathCandidate(value);
   if (!candidate) return false;
@@ -1082,8 +1094,14 @@ function validateScript(script, sessionBase) {
     if (commandCount > MAX_LINES) return 'Script contains more than 20 commands';
     for (const { cmd, args, input, output, errorOutput } of commands) {
       if (!SHELL_ALLOWED_REAL.has(cmd)) hasNonAllowlistedCommand = true;
-      const writeTargets = [...shellWriteTargets(cmd, args), ...(output ? [output.path] : []), ...(errorOutput ? [errorOutput.path] : [])];
-      if (writeTargets.some((arg) => resolvesOutsideSession(arg, sessionBase) || isPublicLinkReadPath(arg, sessionBase))) {
+      const commandWriteTargets = shellWriteTargets(cmd, args);
+      const redirectWriteTargets = [...(output ? [output.path] : []), ...(errorOutput ? [errorOutput.path] : [])];
+      if (
+        commandWriteTargets.some((arg) => resolvesOutsideSession(arg, sessionBase) || isPublicLinkReadPath(arg, sessionBase))
+        || redirectWriteTargets.some((arg) => (
+          !isNullDeviceSink(arg) && (resolvesOutsideSession(arg, sessionBase) || isPublicLinkReadPath(arg, sessionBase))
+        ))
+      ) {
         hasExternalWrite = true;
       }
       const readTargets = [...shellReadTargets(cmd, args), ...(input ? [input] : [])];
@@ -1147,10 +1165,10 @@ function runCommandGroup(group, sessionBase) {
       : null;
     const last = commands.at(-1);
     const output = last.output
-      ? createWriteStream(join(sessionBase, last.output.path), { flags: last.output.append ? 'a' : 'w' })
+      ? createWriteStream(redirectWritePath(last.output.path, sessionBase), { flags: last.output.append ? 'a' : 'w' })
       : null;
     const errorOutput = last.errorOutput
-      ? createWriteStream(join(sessionBase, last.errorOutput.path), { flags: last.errorOutput.append ? 'a' : 'w' })
+      ? createWriteStream(redirectWritePath(last.errorOutput.path, sessionBase), { flags: last.errorOutput.append ? 'a' : 'w' })
       : null;
     let stdout = '';
     let stderr = '';

package/src/components/FileDisplayModal.tsx

@@ -79,7 +79,8 @@ export function FileDisplayModal() {
   const [loadState, setLoadState] = useState<'loading' | 'ok' | 'error'>('loading');
   const [imgError, setImgError] = useState(false);
   const [htmlZoom, setHtmlZoom] = useState(1);
-  const lastModalHtmlZoomRef = useRef(1);
+  const [htmlPreviewVersion, setHtmlPreviewVersion] = useState(0);
+  const htmlZoomByFileRef = useRef(new Map<string, number>());
   const [textWrap, setTextWrap] = useState(true);
   const [isPictureInPicture, setIsPictureInPicture] = useState(true);
   const [pipRect, setPipRect] = useState<PipRect>(createPipRect);
@@ -128,12 +129,10 @@ export function FileDisplayModal() {
     setTextWrap(true);
     if (isNewDisplay) {
       const opensInPictureInPicture = active.presentation === 'pip' || active.presentation == null;
-      setHtmlZoom(opensInPictureInPicture ? lastModalHtmlZoomRef.current : 1);
       setPipRect(createPipRect());
       setIsPictureInPicture(opensInPictureInPicture);
-    } else {
-      setHtmlZoom(1);
     }
+    setHtmlZoom(htmlZoomByFileRef.current.get(active.path) ?? 1);
   }, [active]);
 
   useEffect(() => {
@@ -152,6 +151,7 @@ export function FileDisplayModal() {
         if (contentRef.current !== text) {
           contentRef.current = text;
           setContent(text);
+          if (active.kind === 'html') setHtmlPreviewVersion((version) => version + 1);
         }
         setLoadState('ok');
         setImgError(false);
@@ -324,7 +324,7 @@ export function FileDisplayModal() {
   const updateHtmlZoom = (update: (zoom: number) => number) => {
     setHtmlZoom((zoom) => {
       const nextZoom = update(zoom);
-      if (!isPictureInPicture) lastModalHtmlZoomRef.current = nextZoom;
+      htmlZoomByFileRef.current.set(active.path, nextZoom);
       return nextZoom;
     });
   };
@@ -402,7 +402,7 @@ export function FileDisplayModal() {
               className="display-iframe ready"
               sandbox="allow-scripts allow-pointer-lock"
               title={title}
-              src={previewUrl(active.path, workspaceDir)}
+              src={`${previewUrl(active.path, workspaceDir)}?v=${htmlPreviewVersion}`}
               style={{
                 width: `calc(${100 / htmlZoom}% + ${2 / htmlZoom}px)`,
                 height: `calc(${100 / htmlZoom}% + ${2 / htmlZoom}px)`,
@@ -466,10 +466,15 @@ export function FileDisplayModal() {
       >
         <span className="display-modal-title">
           <Icon name="file" size={15} />
-          <span className="mono typo-body-sm text-secondary">{active.path}</span>
           <span className="display-title-text">{title}</span>
         </span>
         <div className="display-head-actions">
+          {active.kind === 'html' && isPictureInPicture && (
+            <span className="display-auto-refresh-badge" role="status">
+              <span className="display-auto-refresh-dot" aria-hidden="true" />
+              {t('display.autoRefreshing')}
+            </span>
+          )}
           {active.kind === 'image' && loadState === 'ok' && !imgError && (
             <span className="display-zoom-group">
               <button className="icon-btn" title={t('display.zoomOut')} onClick={zoomOut}><Icon name="zoom-out" size={15} /></button>
@@ -504,7 +509,7 @@ export function FileDisplayModal() {
             aria-label={t(isPictureInPicture ? 'display.exitPictureInPicture' : 'display.pictureInPicture')}
             onClick={() => isPictureInPicture ? exitPictureInPicture() : enterPictureInPicture()}
           >
-            <Icon name={isPictureInPicture ? 'pip-exit' : 'pip'} size={17} />
+            <Icon name="pip" size={17} />
           </button>
           <button className="icon-btn" title={t('common.close')} onClick={close}><Icon name="x" size={17} /></button>
         </div>

package/src/components/WorkspaceFileManagerModal.tsx

@@ -56,6 +56,7 @@ export function WorkspaceFileManagerModal({ sessionId, onClose }: { sessionId: n
   const usesPublicWorkspace = session?.mode === 'NPC' && associatedNpc?.isBuiltIn === true;
   const rootLabel = usesPublicWorkspace ? t('header.workspaceRoot') : session?.workspaceDir?.trim() || `session-${sessionId}`;
   const [files, setFiles] = useState<string[] | null>(null);
+  const [workspaceDir, setWorkspaceDir] = useState<string | null>(null);
   const [loadState, setLoadState] = useState<'loading' | 'ok' | 'empty' | 'error'>('loading');
   const [pendingDelete, setPendingDelete] = useState<Node | null>(null);
   const [deleting, setDeleting] = useState(false);
@@ -73,6 +74,7 @@ export function WorkspaceFileManagerModal({ sessionId, onClose }: { sessionId: n
         const workspaceDir = await applySessionWorkspace(sessionId);
         const list = await listSessionWorkspaceFiles(workspaceDir);
         if (cancelled) return;
+        setWorkspaceDir(workspaceDir);
         setFiles(list);
         setLoadState(list.length === 0 ? 'empty' : 'ok');
       } catch {
@@ -116,6 +118,15 @@ export function WorkspaceFileManagerModal({ sessionId, onClose }: { sessionId: n
     });
   };
 
+  const downloadFile = (node: Node) => {
+    if (!workspaceDir) return;
+    const url = `/api-v2/preview/${encodeURIComponent(workspaceDir)}/${node.path.split('/').map(encodeURIComponent).join('/')}`;
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = node.name;
+    anchor.click();
+  };
+
   const confirmDelete = async () => {
     if (!pendingDelete || deleting) return;
     setDeleting(true);
@@ -217,8 +228,17 @@ export function WorkspaceFileManagerModal({ sessionId, onClose }: { sessionId: n
                   <span className="ws-fm-arrow" />
                   <Icon name={n.isDir ? 'folder' : 'file'} size={14} />
                   <span className={`ws-fm-name${n.isDir ? '' : ' mono'}`}>{n.name}{n.isDir ? '/' : ''}</span>
-                  {!isPublicLink && (
+                  {!n.isDir && (
                     <span className="ws-fm-actions">
+                      <button
+                        className="icon-btn ws-fm-download"
+                        title={t('common.download')}
+                        aria-label={t('common.download')}
+                        onClick={(event) => {
+                          event.stopPropagation();
+                          downloadFile(n);
+                        }}
+                      ><span aria-hidden="true">↓</span></button>
                       <button
                         className="icon-btn ws-fm-delete"
                         title={t('common.delete')}
@@ -230,6 +250,27 @@ export function WorkspaceFileManagerModal({ sessionId, onClose }: { sessionId: n
                       ><Icon name="trash" size={13} /></button>
                     </span>
                   )}
+                  {n.isDir && (
+                    <span className="ws-fm-actions">
+                      <button
+                        className="icon-btn ws-fm-download"
+                        title={t('common.download')}
+                        aria-label={t('common.download')}
+                        disabled
+                      ><span aria-hidden="true">↓</span></button>
+                      {!isPublicLink && (
+                        <button
+                          className="icon-btn ws-fm-delete"
+                          title={t('common.delete')}
+                          aria-label={t('common.delete')}
+                          onClick={(event) => {
+                            event.stopPropagation();
+                            setPendingDelete(n);
+                          }}
+                        ><Icon name="trash" size={13} /></button>
+                      )}
+                    </span>
+                  )}
                 </div>
               );
             })}

package/src/core/i18n.ts

@@ -20,6 +20,7 @@ const MESSAGES: Record<LangKey, Record<string, string>> = {
     'common.cancel': '取消',
     'common.delete': '删除',
     'common.save': '保存',
+    'common.download': '下载',
     'common.ok': '确定',
     'common.clear': '清除',
     'common.close': '关闭',
@@ -538,6 +539,7 @@ const MESSAGES: Record<LangKey, Record<string, string>> = {
     'display.pictureInPicture': '画中画',
     'display.exitPictureInPicture': '退出画中画',
     'display.resizePictureInPicture': '调整画中画大小',
+    'display.autoRefreshing': '自动刷新中',
     'display.htmlSandboxNote': 'HTML 应用在受限沙箱中运行，并可加载同目录资源',
     'display.openHtmlInNewPage': '在新页面打开 HTML',
 
@@ -552,6 +554,7 @@ const MESSAGES: Record<LangKey, Record<string, string>> = {
     'common.cancel': '取消',
     'common.delete': '刪除',
     'common.save': '儲存',
+    'common.download': '下載',
     'common.ok': '確定',
     'common.clear': '清除',
     'common.close': '關閉',
@@ -1055,6 +1058,7 @@ const MESSAGES: Record<LangKey, Record<string, string>> = {
     'display.pictureInPicture': '畫中畫',
     'display.exitPictureInPicture': '退出畫中畫',
     'display.resizePictureInPicture': '調整畫中畫大小',
+    'display.autoRefreshing': '自動重新整理中',
     'display.htmlSandboxNote': 'HTML 應用程式在受限沙箱中執行，並可載入同目錄資源',
     'display.openHtmlInNewPage': '在新頁面開啟 HTML',
 
@@ -1068,6 +1072,7 @@ const MESSAGES: Record<LangKey, Record<string, string>> = {
     'common.cancel': 'Cancel',
     'common.delete': 'Delete',
     'common.save': 'Save',
+    'common.download': 'Download',
     'common.ok': 'OK',
     'common.clear': 'Clear',
     'common.close': 'Close',
@@ -1571,6 +1576,7 @@ const MESSAGES: Record<LangKey, Record<string, string>> = {
     'display.pictureInPicture': 'Picture in picture',
     'display.exitPictureInPicture': 'Exit picture in picture',
     'display.resizePictureInPicture': 'Resize picture in picture',
+    'display.autoRefreshing': 'Auto-refreshing',
     'display.htmlSandboxNote': 'HTML application runs in a restricted sandbox with same-directory resources available',
     'display.openHtmlInNewPage': 'Open HTML in a new page',
 

package/src/core/toolDefinitions.ts

@@ -18,6 +18,7 @@ export const BUILTIN_TOOL_NAMES = [
   'get_tavern_info',
   'get_character_info',
   'get_lorebook_info',
+  'get_skill_info',
   'file_display',
   'create_character',
   'update_character',
@@ -197,7 +198,7 @@ export const BUILTIN_TOOLS: ChatCompletionTool[] = [
   ),
   fn(
     'get_tavern_info',
-    'Read-only snapshot of the tavern: characters, Lorebooks, skills and career statistics.',
+    'Read a read-only tavern overview: characters, Lorebooks, skill summaries, and career statistics.',
     {
       type: 'object',
       properties: {
@@ -233,6 +234,16 @@ export const BUILTIN_TOOLS: ChatCompletionTool[] = [
       additionalProperties: false,
     }
   ),
+  fn(
+    'get_skill_info',
+    'Get the full definition of a skill by name, including generated skill parameters and execution configuration.',
+    {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Existing skill name' } },
+      required: ['name'],
+      additionalProperties: false,
+    }
+  ),
   fn(
     'file_display',
     'Display any file from the current workspace to the user in a popup. Useful for inspecting existing files, reviewing generated output (reports, dashboards, images, HTML pages), or browsing the workspace content. Only shows the file in the UI — it does NOT return the file content; use file_read to actually read the content.',
@@ -371,15 +382,10 @@ export const BUILTIN_TOOLS: ChatCompletionTool[] = [
 
 function executionProperties(): Record<string, unknown> {
   return {
-    type: { type: 'string', enum: ['template', 'http_get', 'javascript', 'file_read', 'file_write', 'shell'] },
+    type: { type: 'string', enum: ['template', 'http_get', 'javascript', 'shell'] },
     template: { type: 'string', description: 'template type: result template with {{param}} placeholders' },
     url: { type: 'string', description: "http_get type: public https URL with {{param}} placeholders" },
-    code: { type: 'string', maxLength: 20000, description: "javascript type: JS code. Reads 'input' (args object), assigns JSON-safe 'result'. Supports async/await. Injected helpers: await $read(path)->string, $write(path, content), $append(path, content), $list()->[paths]. Helper paths must be relative to the current session workspace; absolute paths and parent traversal (..) are rejected." },
-    path: { type: 'string', description: 'file_read/file_write: relative path inside the current session workspace' },
-    content: { type: 'string', description: 'file_write: text content with {{param}} placeholders' },
-    json_content: { type: 'object', description: 'file_write: JSON content, interpolated recursively' },
-    append: { type: 'boolean', description: 'file_write: append instead of overwrite' },
-    append_newline: { type: 'boolean', description: 'file_write: append a trailing newline to the written content' },
+    code: { type: 'string', maxLength: 20000, description: "javascript type: JS code. Reads 'input' (args object), assigns JSON-safe 'result'. Supports async/await. Injected helpers: await $read(path)->string, $write(path, content), $append(path, content), $list()->[paths], and $display(path, { title? }) to open a workspace file in a popup. Helper paths must be relative to the current session workspace; absolute paths and parent traversal (..) are rejected. Only one file may be displayed per execution." },
     script: { type: 'string', maxLength: 8000, description: 'shell: local command script (max 20 commands) executed in the current session workspace. Unsupported: shell expansion, command substitution, heredocs, background execution, arbitrary file-descriptor operations, and interactive commands.' },
   };
 }
@@ -389,9 +395,7 @@ function getExecutionDescription(): string {
     'Declarative implementation of the skill. One of:',
     '- template: `{template: "As of {{date}}, the price is {{price}}"}`, placeholders interpolated from args',
     '- http_get: `{url: "https://public.example.com/api?q={{q}}"}`, public HTTPS hostname required',
-    '- javascript: `{code: "result = { sum: input.a + input.b }"}`, reads `input`, assigns JSON-safe `result`; supports async/await and can read or write workspace files via `await $read/$write/$append/$list`. These helpers only accept relative paths in the current session workspace; absolute paths and `..` are rejected',
-    '- file_read: `{path: "notes.md"}` — read a file from the current session workspace through the required local workspace service (100KB cap)',
-    '- file_write: `{path: "notes.jsonl", json_content: {...}, append: true, append_newline: true}` — write to the current session workspace through the required local workspace service',
+    '- javascript: `{code: "await $display(\'dashboard.html\', { title: \'Dashboard\' }); result = { ok: true };"}`, reads `input`, assigns JSON-safe `result`; supports async/await and can access the workspace through `await $read/$write/$append/$list/$display`. `$display` opens one existing text, image, or HTML file in a popup. Helpers only accept relative paths in the current session workspace; absolute paths and `..` are rejected',
     '- shell: `{script: "..."}` — execute a local command script in the current session workspace (max 20 commands). Unsupported: shell expansion, command substitution, heredocs, background execution, arbitrary file-descriptor operations, and interactive commands.',
   ].join(' ');
 }

package/src/core/tools/generatedSkillExecutor.ts

@@ -108,10 +108,6 @@ export async function executeGeneratedSkill(
       return execHttpGet(execution, args);
     case 'javascript':
       return execJavaScript(execution, args, workspaceDir);
-    case 'file_read':
-      return execFileRead(execution, args, workspaceDir);
-    case 'file_write':
-      return execFileWrite(execution, args, workspaceDir);
     case 'shell':
       return execShell(execution, args, confirm, workspaceDir);
     default:
@@ -186,9 +182,10 @@ self.__run = async (ev) => {
   const $write = async (p, c) => (await self.__req('write', { path: p, content: c })).result;
   const $append = async (p, c) => (await self.__req('append', { path: p, content: c })).result;
   const $list = async () => (await self.__req('list', {})).files;
+  const $display = async (p, options = {}) => (await self.__req('display', { path: p, options })).result;
   try {
-    const fn = new Function('input', '$read', '$write', '$append', '$list', CODE_FN);
-    const result = await fn(input, $read, $write, $append, $list);
+    const fn = new Function('input', '$read', '$write', '$append', '$list', '$display', CODE_FN);
+    const result = await fn(input, $read, $write, $append, $list, $display);
     let safe;
     try {
       safe = JSON.parse(JSON.stringify(result ?? null));
@@ -223,6 +220,16 @@ function createSandboxWorker(code: string): Worker {
   return new Worker(URL.createObjectURL(blob));
 }
 
+const DISPLAY_REF_PREFIX = 'DISPLAY_REF: ';
+
+type DisplayKind = 'text' | 'image' | 'html';
+
+interface DisplayPayload {
+  path: string;
+  kind: DisplayKind;
+  title?: string;
+}
+
 async function execJavaScript(
   execution: GeneratedSkillExecution,
   args: Record<string, unknown>,
@@ -234,6 +241,7 @@ async function execJavaScript(
 
   return new Promise((resolve) => {
     let worker: Worker;
+    let displayPayload: DisplayPayload | null = null;
     try {
       worker = createSandboxWorker(code);
     } catch (e) {
@@ -250,8 +258,11 @@ async function execJavaScript(
       const d = ev.data;
       if (!d) return;
       if (d.__bridge__) {
-        void handleBridgeCall(d, workspaceDir).then(
-          (result) => worker.postMessage({ __bridge_resp__: true, id: d.id, ok: true, result }),
+        void handleBridgeCall(d, workspaceDir, displayPayload).then(
+          (result) => {
+            if (d.method === 'display' && result.ok === true && result.payload) displayPayload = result.payload;
+            worker.postMessage({ __bridge_resp__: true, id: d.id, ok: true, result });
+          },
           (err) => worker.postMessage({ __bridge_resp__: true, id: d.id, ok: false, error: String((err && err.message) || err) })
         );
         return;
@@ -265,7 +276,8 @@ async function execJavaScript(
       if ('__result__' in d) {
         clearTimeout(timer);
         worker.terminate();
-        resolve(truncateToolOutput(JSON.stringify(d.__result__ ?? null)));
+        const result = truncateToolOutput(JSON.stringify(d.__result__ ?? null));
+        resolve(displayPayload ? `${DISPLAY_REF_PREFIX}${JSON.stringify(displayPayload)}\n${result}` : result);
         return;
       }
     };
@@ -278,15 +290,25 @@ async function execJavaScript(
   });
 }
 
+interface BridgeResponse {
+  ok: boolean;
+  content?: string;
+  result?: string;
+  files?: string[];
+  payload?: DisplayPayload;
+  error?: string;
+}
+
 /**
  * 主线程侧桥接实现：全部复用已验证的文件沙箱逻辑。
- * 统一返回 { ok, content?/result?/files?, error? }，Worker 内 $read 等
+ * 统一返回 { ok, content?/result?/files?/payload?, error? }，Worker 内 $read 等
  * 在失败时 reject 成 Error，技能代码用 try/catch 接住。
  */
 async function handleBridgeCall(
   req: { method: string; payload: Record<string, unknown> },
   workspaceDir?: string | null,
-): Promise<unknown> {
+  existingDisplay?: DisplayPayload | null,
+): Promise<BridgeResponse> {
   const { method, payload } = req;
   switch (method) {
     case 'read': {
@@ -313,6 +335,26 @@ async function handleBridgeCall(
       const files = await diskFileList(workspaceDir!);
       return { ok: true, files: files.slice(0, 500) };
     }
+    case 'display': {
+      if (existingDisplay) return { ok: false, error: 'Only one file can be displayed per script execution' };
+      const path = sanitizeRelativePath(String(payload.path ?? ''));
+      await requireFileServer(workspaceDir);
+      if (await diskFileRead(path, workspaceDir!) === null) return { ok: false, error: `File not found: ${path}` };
+      const rawOptions = payload.options;
+      const options = rawOptions && typeof rawOptions === 'object' && !Array.isArray(rawOptions)
+        ? rawOptions as Record<string, unknown>
+        : {};
+      const rawTitle = options.title;
+      const title = typeof rawTitle === 'string' && rawTitle.trim() ? rawTitle.trim() : undefined;
+      const extension = /\.([A-Za-z0-9]+)$/.exec(path)?.[1]?.toLowerCase() ?? '';
+      const kind: DisplayKind = /^(html?)$/.test(extension)
+        ? 'html'
+        : /^(png|jpe?g|gif|webp|svg|bmp|ico)$/.test(extension)
+          ? 'image'
+          : 'text';
+      const displayPayload: DisplayPayload = { path, kind, title };
+      return { ok: true, result: `Displayed ${path} in a popup`, payload: displayPayload };
+    }
     default:
       return { ok: false, error: `Unknown bridge method ${method}` };
   }
@@ -455,11 +497,12 @@ export async function writeWorkspaceFileTextFor(
   path: string,
   content: string,
   workspaceDir: string,
+  append = false,
 ): Promise<string> {
   const normalizedPath = normalizePath(path);
   if (!normalizedPath) throw new Error('Invalid path');
   await requireFileServer(workspaceDir);
-  return diskFileWrite(normalizedPath, content, false, workspaceDir);
+  return diskFileWrite(normalizedPath, content, append, workspaceDir);
 }
 
 /** 删除工作区中的文件或目录。 */
@@ -480,57 +523,6 @@ export async function listSessionWorkspaceFiles(workspaceDir: string): Promise<s
   return (await diskFileList(workspaceDir)).slice(0, 500);
 }
 
-async function execFileRead(
-  execution: GeneratedSkillExecution,
-  args: Record<string, unknown>,
-  workspaceDir?: string | null,
-): Promise<string> {
-  try {
-    const path = normalizePath(interpolate(execution.path ?? '', args));
-    if (!path) throw new Error('Invalid path');
-    const text = await readWorkspaceFileText(path, normalizeWorkspaceDir(workspaceDir) ?? '');
-    if (text === null) return `ERROR: File not found: ${path}`;
-    return truncateToolOutput(text);
-  } catch (e) {
-    return `ERROR: ${(e as Error).message}`;
-  }
-}
-
-// ---------- file_write ----------
-async function execFileWrite(
-  execution: GeneratedSkillExecution,
-  args: Record<string, unknown>,
-  workspaceDir?: string | null,
-): Promise<string> {
-  try {
-    const path = normalizePath(interpolate(execution.path ?? '', args));
-    if (!path) throw new Error('Invalid path');
-    let content: string;
-    if (execution.json_content != null) {
-      content = JSON.stringify(interpolateDeep(execution.json_content, args), null, 2);
-    } else {
-      content = interpolate(execution.content ?? '', args);
-    }
-    const safeWorkspaceDir = normalizeWorkspaceDir(workspaceDir);
-    await requireFileServer(safeWorkspaceDir);
-    const diskContent = execution.append && execution.append_newline ? `${content}\n` : content;
-    return await diskFileWrite(path, diskContent, execution.append ?? false, safeWorkspaceDir!);
-  } catch (e) {
-    return `ERROR: ${(e as Error).message}`;
-  }
-}
-
-function interpolateDeep(value: unknown, args: Record<string, unknown>): unknown {
-  if (typeof value === 'string') return interpolate(value, args);
-  if (Array.isArray(value)) return value.map((v) => interpolateDeep(v, args));
-  if (value && typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[k] = interpolateDeep(v, args);
-    return out;
-  }
-  return value;
-}
-
 // ---------- shell（真实执行：白名单直执 + 其它命令确认）----------
 
 /** 按服务端规则统计换行、连接符和管道分隔的命令，忽略引号和转义内的连接符。 */

package/src/core/tools/toolExecutor.ts

@@ -131,6 +131,8 @@ async function runNativeTool(
 
     case 'get_tavern_info':
       return await handleGetTavernInfo(args);
+    case 'get_skill_info':
+      return await handleGetSkillInfo(args);
     case 'get_character_info':
       return await handleGetCharacterInfo(args);
     case 'get_lorebook_info':
@@ -222,6 +224,34 @@ async function handleGetTavernInfo(args: Record<string, unknown>): Promise<strin
   return JSON.stringify(out, null, 2);
 }
 
+async function handleGetSkillInfo(args: Record<string, unknown>): Promise<string> {
+  const name = String(args.name ?? '').trim();
+  if (!name) return 'ERROR: Missing name';
+  const tool = await db.tools.where('name').equals(name).first();
+  if (!tool) return `ERROR: Skill ${name} does not exist`;
+
+  const definition = safeJsonParse<ChatCompletionTool>(tool.jsonContent);
+  if (!definition?.function) return `ERROR: Skill ${name} has an invalid definition`;
+
+  const result: Record<string, unknown> = {
+    name: tool.name,
+    description: definition.function.description ?? '',
+    parameters: definition.function.parameters,
+    is_default: tool.isBuiltIn,
+  };
+
+  if (tool.isBuiltIn) {
+    result.implementation_type = 'native';
+  } else {
+    const execution = safeJsonParse<GeneratedSkillExecution>(tool.executionJson);
+    if (!execution) return `ERROR: Skill ${name} has an invalid implementation`;
+    result.implementation_type = execution.type;
+    result.execution = execution;
+  }
+
+  return JSON.stringify(result, null, 2);
+}
+
 async function handleGetCharacterInfo(args: Record<string, unknown>): Promise<string> {
   const name = String(args.name ?? '').trim();
   if (!name) return 'ERROR: Missing name';
@@ -322,13 +352,14 @@ async function handleFileRead(args: Record<string, unknown>, ctx: ToolExecutionC
 }
 
 async function handleFileWrite(args: Record<string, unknown>, ctx: ToolExecutionContext): Promise<string> {
-  const workspaceDir = await applySessionWorkspace(ctx.sessionId, ctx.npcId);
-  return executeGeneratedSkill(
-    { type: 'file_write', path: String(args.path ?? ''), content: String(args.content ?? ''), append: args.append === true },
-    args,
-    ctx.requestConfirmation,
-    workspaceDir,
-  );
+  try {
+    const workspaceDir = await applySessionWorkspace(ctx.sessionId, ctx.npcId);
+    const path = String(args.path ?? '').replace(/\\/g, '/').trim();
+    if (!path) return 'ERROR: Invalid path';
+    return await writeWorkspaceFileTextFor(path, String(args.content ?? ''), workspaceDir, args.append === true);
+  } catch (e) {
+    return `ERROR: ${(e as Error).message}`;
+  }
 }
 
 async function handleFileEdit(args: Record<string, unknown>, ctx: ToolExecutionContext): Promise<string> {

package/src/generated/changelog.json

@@ -1,7 +1,73 @@
 {
-  "latest": "0.1.26",
+  "latest": "0.1.27",
   "repo": "https://github.com/Rannichan/Tavern-Harness",
   "entries": [
+    {
+      "version": "0.1.27",
+      "date": "2026-10-28",
+      "breaking": false,
+      "compare": "v0.1.26...v0.1.27",
+      "groups": {
+        "zh-CN": [
+          {
+            "kind": "added",
+            "items": [
+              "新增 `get_skill_info` 工具：模型可以先查看技能的完整定义（参数、实现方式、执行配置），再决定如何调用",
+              "技能里的 JavaScript 执行新增 `$display` 助手：生成报告、图表或网页后可以直接在弹窗中展示给用户（每次执行只展示一个文件）"
+            ]
+          },
+          {
+            "kind": "changed",
+            "items": [
+              "工作区文件管理里每个文件都多了下载按钮，可以直接保存到本地",
+              "文件预览会按文件记住缩放比例，切到别的文件再回来不用重新调整",
+              "技能的 shell 脚本允许把输出重定向到 /dev/null（Windows 为 NUL），常见的静默输出写法不再被误判为越权"
+            ]
+          },
+          {
+            "kind": "fixed",
+            "items": [
+              "修复画中画中的 HTML 预览不会随文件更新而自动刷新、必须关闭重开才能看到最新内容的问题"
+            ]
+          },
+          {
+            "kind": "internal",
+            "items": [
+              "技能的文件读写统一走 JavaScript 助手（`$read` / `$write` / `$append` / `$list`），移除 `file_read` / `file_write` 执行类型"
+            ]
+          }
+        ],
+        "en": [
+          {
+            "kind": "added",
+            "items": [
+              "Added `get_skill_info`, so the model can inspect a skill's full definition (parameters, implementation, execution config) before deciding how to call it",
+              "JavaScript skills can now call `$display` to show a generated report, chart, or page in a popup for the user (one file per execution)"
+            ]
+          },
+          {
+            "kind": "changed",
+            "items": [
+              "Every file in the workspace file manager can now be downloaded directly",
+              "File previews remember the zoom level per file, so switching back no longer resets the view",
+              "Skill shell scripts may redirect output to /dev/null (NUL on Windows), so common quiet-command patterns are no longer rejected as unsafe writes"
+            ]
+          },
+          {
+            "kind": "fixed",
+            "items": [
+              "Fixed HTML previews in picture-in-picture not refreshing when the file changed; the latest content now appears without closing and reopening the preview"
+            ]
+          },
+          {
+            "kind": "internal",
+            "items": [
+              "Skill file access now goes through the JavaScript helpers (`$read` / `$write` / `$append` / `$list`); the `file_read` and `file_write` execution types were removed"
+            ]
+          }
+        ]
+      }
+    },
     {
       "version": "0.1.26",
       "date": "2026-10-27",

package/src/store/store.ts

@@ -2322,13 +2322,13 @@ async function performAssistantTurn(
           modelUsed: null,
           attachments: [],
           attachmentInfos: [],
-          displayRef: displayRefForToolName(tc.name, result),
+          displayRef: displayRefForResult(result, sessionId),
           rawRequestBody: null,
           rawResponseBody: null,
         });
 
-        // 展示类工具（file_display）：执行成功后自动打开展示弹窗
-        const displayPayload = tc.name === 'file_display' ? parseDisplayRef(result) : null;
+        // 展示工具与 JavaScript 的 $display：执行成功后自动打开展示弹窗
+        const displayPayload = parseDisplayRef(result);
         if (displayPayload) {
           useStore.getState().setActiveDisplay({
             path: displayPayload.path,
@@ -2678,17 +2678,12 @@ function requestLimitConfirmation(
 }
 
 /**
- * 展示类工具（file_display）的结果会携带展示引用（DISPLAY_REF 前缀）。
- * 解析成功 → 返回序列化后的 DisplayFileRef（写入工具结果消息的 displayRef 字段，
- * 供对话流中的「查看」按钮回看）；其他工具一律返回 null。
+ * 展示工具与 JavaScript 的 $display 都以 DISPLAY_REF 前缀返回展示引用。
+ * 解析成功后将最小展示信息持久化，供对话流的「查看」按钮回看。
  */
-function displayRefForToolName(toolName: string, result: string): string | null {
-  if (toolName !== 'file_display') return null;
+function displayRefForResult(result: string, sessionId: number): string | null {
   const payload = parseDisplayRef(result);
   if (!payload) return null;
-  // path 前面去展示前缀的剩余文本是给模型看的（留在 content 中）。
-  // displayRef 只保存展示所需的最小信息；sessionId 用于回看时定位会话工作目录。
-  const sessionId = useStore.getState().activeSessionId;
   return JSON.stringify({
     path: payload.path,
     kind: payload.kind,

package/src/theme/views.css

@@ -1621,6 +1621,24 @@
   gap: 6px;
   margin-left: auto;
 }
+.display-auto-refresh-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 3px 7px;
+  border: 1px solid color-mix(in srgb, var(--primary) 30%, var(--border-soft));
+  border-radius: 999px;
+  color: var(--text-secondary);
+  font-size: var(--font-size-caption);
+  font-weight: var(--font-weight-semibold);
+  white-space: nowrap;
+}
+.display-auto-refresh-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--primary);
+}
 .display-zoom-group {
   display: flex;
   align-items: center;
@@ -1916,11 +1934,23 @@
   align-items: center;
   gap: 4px;
 }
+.ws-fm-download,
 .ws-fm-delete {
   width: 26px;
   height: 26px;
   color: var(--text-muted);
 }
+.ws-fm-download:hover {
+  color: var(--text-accent);
+}
+.ws-fm-download:disabled {
+  color: var(--text-muted);
+  opacity: 0.35;
+  cursor: not-allowed;
+}
+.ws-fm-download:disabled:hover {
+  color: var(--text-muted);
+}
 .ws-fm-delete:hover {
   color: var(--text-danger);
 }

package/src/types/models.ts

@@ -368,19 +368,13 @@ export interface ToolConfirmationRequest {
 }
 
 export interface GeneratedSkillExecution {
-  type: 'template' | 'http_get' | 'javascript' | 'file_read' | 'file_write' | 'shell';
+  type: 'template' | 'http_get' | 'javascript' | 'shell';
   // template
   template?: string;
   // http_get
   url?: string;
   // javascript
   code?: string;
-  // file_read / file_write
-  path?: string;
-  content?: string;
-  json_content?: unknown;
-  append?: boolean;
-  append_newline?: boolean;
   // shell
   script?: string;
   [k: string]: unknown;