minimal-agent 0.13.0 → 0.14.0

package/src/tools/computeruse/computerIntent.ts

@@ -0,0 +1,46 @@
+export type ComputerAutomationIntent =
+  | { needed: true; source: 'explicit-current' | 'continuation'; reason: string }
+  | { needed: false; source: 'none'; reason: string };
+
+export interface ComputerAutomationContinuationState {
+  lastUsedAt: number;
+}
+
+const CONTINUATION_WINDOW_MS = 30 * 60_000;
+const CONTINUATION_ONLY = /^(?:请)?(?:继续|接着(?:做|操作)?|重试|再试一次|往下做|恢复操作)[。！!\s]*$/i;
+const DIRECT_DESKTOP = /(?:操作(?:电脑|桌面|屏幕|窗口|系统|本机)|电脑自动化|桌面自动化|查看(?:当前)?(?:桌面|屏幕|前台窗口)|截(?:取)?(?:当前)?屏|系统设置|控制面板|任务管理器|资源管理器|访达|Finder)/i;
+const GUI_ACTION = /(?:点击|双击|右键|拖拽|滚动|输入|粘贴|按(?:键|快捷键)|切换|激活|关闭|移动|调整窗口|发送|发布|上传)/i;
+const APP_TARGET = /(?:在|用|打开|切换到|进入)[^，。\n]{0,28}(?:应用|软件|客户端|微信|WeChat|钉钉|飞书|Slack|QQ|邮件|Outlook|Word|Excel|PowerPoint|设置|窗口)(?:里|中|上|内|给|向|并|，|。|\s|$)/i;
+const DISCUSSION_ONLY = /(?:解释|介绍|讨论|分析|评审|代码|源码|实现|设计|为什么|是什么|如何实现|测试.*ComputerUse|ComputerUse.*测试)/i;
+const DIRECT_TOOL_TASK = /(?:读取|分析|查看|理解).{0,12}(?:图片|照片|截图文件|PDF|文件|附件)|(?:搜索|修改|编写|重构|构建|运行测试|查找).{0,12}(?:代码|文件|网页)|(?:搜索网页|打开网址|访问网站|网页中)/i;
+
+/**
+ * Conservative, deterministic exposure classifier. It only consumes the
+ * current human input and a short-lived record of a real prior ComputerUse
+ * call; model output, page content, and tool arguments can never enable it.
+ */
+export function classifyComputerAutomationIntent(
+  input: string,
+  continuation?: ComputerAutomationContinuationState,
+  now = Date.now(),
+): ComputerAutomationIntent {
+  const text = input.trim();
+  if (
+    continuation
+    && now - continuation.lastUsedAt <= CONTINUATION_WINDOW_MS
+    && CONTINUATION_ONLY.test(text)
+  ) {
+    return { needed: true, source: 'continuation', reason: '继续最近一次桌面自动化任务' };
+  }
+  if (!text) return { needed: false, source: 'none', reason: '没有桌面操作请求' };
+  if (DIRECT_TOOL_TASK.test(text) && !DIRECT_DESKTOP.test(text)) {
+    return { needed: false, source: 'none', reason: '专用文件、图片或 Web 工具可直接完成' };
+  }
+  if (DISCUSSION_ONLY.test(text) && !DIRECT_DESKTOP.test(text) && !GUI_ACTION.test(text)) {
+    return { needed: false, source: 'none', reason: '仅讨论桌面能力，没有要求实际操作' };
+  }
+  if (DIRECT_DESKTOP.test(text) || (GUI_ACTION.test(text) && APP_TARGET.test(text))) {
+    return { needed: true, source: 'explicit-current', reason: '用户明确要求操作原生桌面界面' };
+  }
+  return { needed: false, source: 'none', reason: '未发现明确的原生桌面操作意图' };
+}

package/src/tools/computeruse/telemetryLog.js

@@ -28,6 +28,9 @@ import { CONSECUTIVE_FAILURE_LIMIT, readRecords, record, renderReport, summarize
 function logPath() {
     return join(computerUseStateDir(), 'telemetry.jsonl');
 }
+function exposureLogPath() {
+    return join(computerUseStateDir(), 'exposure.jsonl');
+}
 /**
  * 记一条调用元数据。
  *
@@ -42,6 +45,15 @@ export async function recordComputerUseCall(raw) {
         /* 观测失败不影响功能 */
     }
 }
+/** Records only the boolean exposure decision and a bounded enum source. */
+export async function recordComputerUseExposure(exposed, intentSource) {
+    try {
+        await record(exposureLogPath(), { exposed, intentSource });
+    }
+    catch {
+        /* observability must never affect a turn */
+    }
+}
 export { CONSECUTIVE_FAILURE_LIMIT };
 /**
  * 人类可读的遥测汇总，给 CLI/诊断用。

package/src/tools/computeruse/telemetryLog.ts

@@ -38,6 +38,10 @@ function logPath(): string {
   return join(computerUseStateDir(), 'telemetry.jsonl');
 }
 
+function exposureLogPath(): string {
+  return join(computerUseStateDir(), 'exposure.jsonl');
+}
+
 /**
  * 记一条调用元数据。
  *
@@ -52,6 +56,18 @@ export async function recordComputerUseCall(raw: Record<string, unknown>): Promi
   }
 }
 
+/** Records only the boolean exposure decision and a bounded enum source. */
+export async function recordComputerUseExposure(
+  exposed: boolean,
+  intentSource: 'explicit-current' | 'continuation' | 'none',
+): Promise<void> {
+  try {
+    await record(exposureLogPath(), { exposed, intentSource });
+  } catch {
+    /* observability must never affect a turn */
+  }
+}
+
 export { CONSECUTIVE_FAILURE_LIMIT };
 
 /**

package/src/tools/computeruse/vision/telemetry.js

@@ -30,6 +30,7 @@ const ALLOWED_FIELDS = new Set([
     'changeRatio', 'settled', 'stableMs', 'settleConfidence', 'focusChange',
     'settleMode', 'interrupted', 'refused', 'ok',
     'frames', 'axNodes', 'axTruncated',
+    'exposed', 'intentSource',
     // 不可逆动作审批的结局（短枚举，如 irreversible_approved / irreversible_denied）。
     //
     // 刻意**不**复用 `refused`：那个字段参与连续失败计数，而「用户不批准这次

package/src/tools/computeruse/vision/telemetry.ts

@@ -33,6 +33,7 @@ const ALLOWED_FIELDS = new Set([
   'changeRatio', 'settled', 'stableMs', 'settleConfidence', 'focusChange',
   'settleMode', 'interrupted', 'refused', 'ok',
   'frames', 'axNodes', 'axTruncated',
+  'exposed', 'intentSource',
   // 不可逆动作审批的结局（短枚举，如 irreversible_approved / irreversible_denied）。
   //
   // 刻意**不**复用 `refused`：那个字段参与连续失败计数，而「用户不批准这次

package/src/tools/effectiveToolSet.js

@@ -29,9 +29,13 @@ export function createEffectiveToolSet(input) {
         input.runtime.cwd,
         input.runtime.surface,
         input.runtime.profile,
+        input.runtime.conversationMode ?? 'private',
         input.runtime.memoryAccess,
         input.runtime.browser?.supervised === true ? 'supervised-browser' : 'no-browser',
         input.runtime.computer ? 'computer' : 'no-computer',
+        input.runtime.computerIntent?.needed === true
+            ? `computer-intent:${input.runtime.computerIntent.source}`
+            : 'no-computer-intent',
         input.availableTools.map(identity).join(','),
         availability.join(','),
         input.allowedNames?.join(',') ?? '*',

package/src/tools/effectiveToolSet.ts

@@ -46,9 +46,13 @@ export function createEffectiveToolSet(input: {
     input.runtime.cwd,
     input.runtime.surface,
     input.runtime.profile,
+    input.runtime.conversationMode ?? 'private',
     input.runtime.memoryAccess,
     input.runtime.browser?.supervised === true ? 'supervised-browser' : 'no-browser',
     input.runtime.computer ? 'computer' : 'no-computer',
+    input.runtime.computerIntent?.needed === true
+      ? `computer-intent:${input.runtime.computerIntent.source}`
+      : 'no-computer-intent',
     input.availableTools.map(identity).join(','),
     availability.join(','),
     input.allowedNames?.join(',') ?? '*',

package/src/tools/index.js

@@ -13,10 +13,13 @@
  * ============================================================
  */
 import { advisorTool } from './advisor/advisor.js';
+import { advisorDecisionTool } from './advisor/advisorDecision.js';
+import { applyPatchTool } from './applypatch/applyPatch.js';
 // ⚠️ agent.ts 与本模块构成环（tools/index → agent → loop → tools/index）：
 // agent.ts 顶层不求值本模块/loop 的任何导出、loop.ts 的工具 token 估算已懒化，
 // 环在运行时是安全的（详见 agent.ts 文件头「循环依赖纪律」）。
 import { agentTool } from './agent/agent.js';
+import { agentFollowupTool, agentInterruptTool, agentListTool, agentMessageTool, agentWaitTool, } from './agent/agentControl.js';
 import { askUserQuestionTool } from './ask/ask.js';
 import { bashTool } from './bash/bash.js';
 import { assertCapabilityRegistry } from './capabilities.js';
@@ -40,14 +43,17 @@ import { taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, } from './ta
 import { taskOutputTool } from './tasks/taskOutput.js';
 import { taskStopTool } from './tasks/taskStop.js';
 import { terminalCaptureTool } from './terminal/terminalCapture.js';
+import { attachBuiltinPromptGuides } from './toolPromptGuides.js';
 import { trashTool } from './trash/trash.js';
 import { webbrowserTool } from './webbrowser/webbrowser.js';
+import { browserBatchTool } from './webbrowser/browserBatch.js';
+import { browserCdpTool } from './webbrowser/browserCdp.js';
 import { webfetchTool } from './webfetch/webfetch.js';
 import { webSearchTool } from './websearch/websearch.js';
 import { enterWorktreeTool, exitWorktreeTool, } from './worktree/sessionWorktree.js';
 import { writeTool } from './write/write.js';
 /** 所有内置工具（顺序 = 给 LLM 呈现的顺序，不影响代码执行，但会影响模型的优先级直觉） */
-export const ALL_TOOLS = [
+export const ALL_TOOLS = attachBuiltinPromptGuides([
     readTool,
     editTool,
     multiEditTool,
@@ -79,9 +85,15 @@ export const ALL_TOOLS = [
     taskStopTool,
     askUserQuestionTool,
     advisorTool,
+    advisorDecisionTool,
     computerUseTool,
     // 追加在末尾：主循环 tools schema 的原有前缀字节不动（提示词缓存友好）
     agentTool,
+    agentMessageTool,
+    agentListTool,
+    agentWaitTool,
+    agentInterruptTool,
+    agentFollowupTool,
     // Product tools append at the end to preserve the existing schema prefix cache.
     trashTool,
     taskCreateTool,
@@ -93,7 +105,11 @@ export const ALL_TOOLS = [
     exitWorktreeTool,
     terminalCaptureTool,
     snipTool,
-];
+    applyPatchTool,
+    // Browser extensions append after the stable legacy schema prefix.
+    browserBatchTool,
+    browserCdpTool,
+]);
 assertCapabilityRegistry(ALL_TOOLS.map((tool) => tool.name));
 /** 按名字查表 */
 export function getToolByName(name) {
@@ -197,7 +213,10 @@ export { clearPersonaTool, confirmMemoryTool, forgetMemoryTool, listMemoriesTool
 export { multiEditTool } from './edit/multi-edit.js';
 export { genImageTool } from './genimage/genimage.js';
 export { advisorTool } from './advisor/advisor.js';
+export { advisorDecisionTool } from './advisor/advisorDecision.js';
+export { applyPatchTool } from './applypatch/applyPatch.js';
 export { agentTool } from './agent/agent.js';
+export { agentFollowupTool, agentInterruptTool, agentListTool, agentMessageTool, agentWaitTool, } from './agent/agentControl.js';
 export { createGenerateSpeechTool, generateSpeechTool, } from './genspeech/genspeech.js';
 export { createWebSearchTool } from './websearch/websearch.js';
 export { lspTool } from './lsp/lsp.js';

package/src/tools/index.ts

@@ -15,10 +15,19 @@
 
 import type { Tool, ToolCallContext, ToolResult } from '../types.js';
 import { advisorTool } from './advisor/advisor.js';
+import { advisorDecisionTool } from './advisor/advisorDecision.js';
+import { applyPatchTool } from './applypatch/applyPatch.js';
 // ⚠️ agent.ts 与本模块构成环（tools/index → agent → loop → tools/index）：
 // agent.ts 顶层不求值本模块/loop 的任何导出、loop.ts 的工具 token 估算已懒化，
 // 环在运行时是安全的（详见 agent.ts 文件头「循环依赖纪律」）。
 import { agentTool } from './agent/agent.js';
+import {
+  agentFollowupTool,
+  agentInterruptTool,
+  agentListTool,
+  agentMessageTool,
+  agentWaitTool,
+} from './agent/agentControl.js';
 import { askUserQuestionTool } from './ask/ask.js';
 import { bashTool } from './bash/bash.js';
 import { assertCapabilityRegistry } from './capabilities.js';
@@ -58,8 +67,11 @@ import {
 import { taskOutputTool } from './tasks/taskOutput.js';
 import { taskStopTool } from './tasks/taskStop.js';
 import { terminalCaptureTool } from './terminal/terminalCapture.js';
+import { attachBuiltinPromptGuides } from './toolPromptGuides.js';
 import { trashTool } from './trash/trash.js';
 import { webbrowserTool } from './webbrowser/webbrowser.js';
+import { browserBatchTool } from './webbrowser/browserBatch.js';
+import { browserCdpTool } from './webbrowser/browserCdp.js';
 import { webfetchTool } from './webfetch/webfetch.js';
 import { webSearchTool } from './websearch/websearch.js';
 import {
@@ -69,7 +81,7 @@ import {
 import { writeTool } from './write/write.js';
 
 /** 所有内置工具（顺序 = 给 LLM 呈现的顺序，不影响代码执行，但会影响模型的优先级直觉） */
-export const ALL_TOOLS: Tool[] = [
+export const ALL_TOOLS: Tool[] = attachBuiltinPromptGuides([
   readTool,
   editTool,
   multiEditTool,
@@ -101,9 +113,15 @@ export const ALL_TOOLS: Tool[] = [
   taskStopTool,
   askUserQuestionTool,
   advisorTool,
+  advisorDecisionTool,
   computerUseTool,
   // 追加在末尾：主循环 tools schema 的原有前缀字节不动（提示词缓存友好）
   agentTool,
+  agentMessageTool,
+  agentListTool,
+  agentWaitTool,
+  agentInterruptTool,
+  agentFollowupTool,
   // Product tools append at the end to preserve the existing schema prefix cache.
   trashTool,
   taskCreateTool,
@@ -115,7 +133,11 @@ export const ALL_TOOLS: Tool[] = [
   exitWorktreeTool,
   terminalCaptureTool,
   snipTool,
-];
+  applyPatchTool,
+  // Browser extensions append after the stable legacy schema prefix.
+  browserBatchTool,
+  browserCdpTool,
+]);
 
 assertCapabilityRegistry(ALL_TOOLS.map((tool) => tool.name));
 
@@ -263,7 +285,16 @@ export {
 export { multiEditTool } from './edit/multi-edit.js';
 export { genImageTool } from './genimage/genimage.js';
 export { advisorTool } from './advisor/advisor.js';
+export { advisorDecisionTool } from './advisor/advisorDecision.js';
+export { applyPatchTool } from './applypatch/applyPatch.js';
 export { agentTool } from './agent/agent.js';
+export {
+  agentFollowupTool,
+  agentInterruptTool,
+  agentListTool,
+  agentMessageTool,
+  agentWaitTool,
+} from './agent/agentControl.js';
 export {
   createGenerateSpeechTool,
   generateSpeechTool,

package/src/tools/presentresult/presentresult.js

@@ -91,21 +91,12 @@ async function call(input) {
         return { ok: false, error: '网页结果只支持 http 或 https 链接' };
     }
     const hasFailedFile = files.some((file) => file.verification === 'failed');
-    const allFilesVerified = files.length > 0 && files.every((file) => file.verification === 'passed');
-    // `final` means the result is safe to present as the completed delivery. A file
-    // with `not_run` verification is still useful, but it must remain an honest draft.
-    const status = hasFailedFile
-        ? 'draft'
-        : allFilesVerified
-            ? 'final'
-            : files.length === 0 && links.length > 0
-                ? 'final'
-                : 'draft';
-    const warnings = files.some((file) => file.verification === 'not_run')
-        ? ['文件已提交，但尚未通过结构化验证。']
-        : hasFailedFile
-            ? ['至少一个文件未通过结构化验证。']
-            : [];
+    // `not_run` means no *additional* format/content validator was available. It
+    // is not a failed delivery: this tool has already verified that the file exists,
+    // is inside the workspace, and captured its size and SHA-256. Only an explicit
+    // failed validator should turn an otherwise usable result into a warning.
+    const status = hasFailedFile ? 'draft' : 'final';
+    const warnings = hasFailedFile ? ['至少一个文件未通过结构化验证。'] : [];
     const manifest = {
         status,
         summary: input.summary?.trim() || (files.length ? `已提交 ${files.length} 个文件` : `已提交 ${links.length} 个网页结果`),

package/src/tools/presentresult/presentresult.ts

@@ -101,21 +101,12 @@ async function call(input: PresentResultInput): Promise<ToolResult> {
     return { ok: false, error: '网页结果只支持 http 或 https 链接' };
   }
   const hasFailedFile = files.some((file) => file.verification === 'failed');
-  const allFilesVerified = files.length > 0 && files.every((file) => file.verification === 'passed');
-  // `final` means the result is safe to present as the completed delivery. A file
-  // with `not_run` verification is still useful, but it must remain an honest draft.
-  const status = hasFailedFile
-    ? 'draft'
-    : allFilesVerified
-      ? 'final'
-      : files.length === 0 && links.length > 0
-        ? 'final'
-        : 'draft';
-  const warnings = files.some((file) => file.verification === 'not_run')
-    ? ['文件已提交，但尚未通过结构化验证。']
-    : hasFailedFile
-      ? ['至少一个文件未通过结构化验证。']
-      : [];
+  // `not_run` means no *additional* format/content validator was available. It
+  // is not a failed delivery: this tool has already verified that the file exists,
+  // is inside the workspace, and captured its size and SHA-256. Only an explicit
+  // failed validator should turn an otherwise usable result into a warning.
+  const status = hasFailedFile ? 'draft' : 'final';
+  const warnings = hasFailedFile ? ['至少一个文件未通过结构化验证。'] : [];
   const manifest: DeliverableManifest = {
     status,
     summary: input.summary?.trim() || (files.length ? `已提交 ${files.length} 个文件` : `已提交 ${links.length} 个网页结果`),

package/src/tools/read/read.js

@@ -8,6 +8,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
+import { dlog } from '../../utils/debugLog.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS, MAX_FILE_SIZE_BYTES, MAX_LINES_TO_READ, } from '../types.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
@@ -15,6 +16,7 @@ import { hashFileBytes, recordRead, } from '../shared/fileState.js';
 import { hasBinaryExtension, isBlockedDevicePath, readTextFile, resolveToolPath, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
 import { pruneRuntimeOutputs, sessionRuntimeDir, } from '../../session/runtimeStore.js';
+import { detectImageMime, resolveLocalImage, } from '../../images/imageResolver.js';
 const inputSchema = z.object({
     file_path: filePathField('读取'),
     offset: z
@@ -46,6 +48,12 @@ const IMAGE_EXTENSIONS = new Set([
     '.gif',
     '.webp',
     '.bmp',
+    '.tif',
+    '.tiff',
+    '.avif',
+    '.heic',
+    '.heif',
+    '.svg',
 ]);
 const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
 const MAX_NOTEBOOK_BYTES = 32 * 1024 * 1024;
@@ -225,16 +233,29 @@ async function call(input, state, cwd, runtimeIdentity) {
             };
         }
     }
-    if (IMAGE_EXTENSIONS.has(ext)) {
+    const imageBytes = info.size <= MAX_IMAGE_BYTES
+        ? await readFile(filePath).catch(() => null)
+        : null;
+    const detectedImage = imageBytes ? detectImageMime(imageBytes) : null;
+    if (IMAGE_EXTENSIONS.has(ext) || detectedImage) {
         if (info.size > MAX_IMAGE_BYTES)
             return { ok: false, error: `图片超过 ${MAX_IMAGE_BYTES} 字节上限` };
-        const bytes = await readFile(filePath);
+        let resolvedImage;
+        try {
+            resolvedImage = await resolveLocalImage(filePath, {
+                maxInputBytes: MAX_IMAGE_BYTES,
+            });
+        }
+        catch (error) {
+            return { ok: false, error: `图片读取失败：${error.message}` };
+        }
+        const bytes = imageBytes ?? await readFile(filePath);
         recordRead(filePath, { contentHash: hashFileBytes(bytes) }, state);
         return {
             ok: true,
-            content: `已读取图片：${filePath}（${info.size} 字节）。图像已附加供视觉模型检查；非视觉模型只能确认文件元数据，不能解读像素内容。`,
+            content: `已读取图片：${filePath}（${info.size} 字节，实际格式 ${resolvedImage.originalMime}）${resolvedImage.transformed ? `；已规范化为 ${resolvedImage.mime}` : ''}。图像已附加供视觉模型直接检查。`,
             metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd),
-            visionImages: [{ source: filePath }],
+            visionImages: [{ source: resolvedImage.path }],
             visionNote: '这是 Read 工具读取的本地图片，请直接检查图像内容。',
         };
     }
@@ -352,10 +373,30 @@ async function renderPdfPages(document, filePath, pages, identity) {
     const dynamicImport = new Function('specifier', 'return import(specifier)');
     let createCanvas;
     try {
-        ({ createCanvas } = await dynamicImport('@napi-rs/canvas'));
+        const napi = await dynamicImport('@napi-rs/canvas');
+        createCanvas = napi.createCanvas;
+        // ⚠️ **必须在 pdfjs 之前把这几个全局占住**，否则 PDF 转图 100% 失败。
+        //
+        // pdfjs 的 legacy 构建在 Node 环境下自己往 globalThis 装一套 Path2D /
+        // DOMMatrix / ImageData polyfill。渲染时它 `new Path2D()` 拿到的是**它自己那份**，
+        // 转手调 `ctx.fill(path, 'evenodd')` 交给 @napi-rs/canvas —— 而 napi 的原生绑定
+        // 只认自己的 `Path`，于是每一页都抛
+        //   `Value is none of these types \`String\`, \`Path\``
+        // 两份 polyfill 撞车，谁都没错，就是不是同一个对象。
+        //
+        // 实测：五种 render 参数组合（canvas / canvasContext / canvas:null / 带不带
+        // standardFontDataUrl）全部同样失败 —— 也就是说 `canvas` 那个类型错**不是**病因，
+        // 修类型并不能让它跑起来。把全局换成 napi 的实现之后第 1 页立刻渲染出 137KB PNG。
+        for (const name of ['Path2D', 'DOMMatrix', 'ImageData']) {
+            const impl = napi[name];
+            if (impl)
+                globalThis[name] = impl;
+        }
     }
-    catch {
-        /* optional adapter */
+    catch (e) {
+        // optional adapter：没装 @napi-rs/canvas 就回落 pdftoppm。
+        // 但「没装」和「装了却加载失败」对用户是两件事，别都吞成前者。
+        dlog('read:pdf', `@napi-rs/canvas 不可用：${e instanceof Error ? e.message : e}`);
     }
     if (createCanvas) {
         try {
@@ -363,8 +404,13 @@ async function renderPdfPages(document, filePath, pages, identity) {
                 const page = await document.getPage(pageNumber);
                 const viewport = page.getViewport({ scale: 2 });
                 const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+                // ⚠️ pdfjs v6 的 RenderParameters 里 `canvas` 是**必填**、`canvasContext`
+                // 反而降级为可选且不推荐；文档明说「若必须用 context，canvas 必须为 null」。
+                // 只给 canvasContext 会类型不过（`bun run typecheck` 唯一的红）。
+                // 运行时它有默认值 `canvas = canvasContext.canvas` 所以不炸 —— 但类型要对。
                 await page.render({
-                    canvas: canvas.getContext('2d'),
+                    canvasContext: canvas.getContext('2d'),
+                    canvas: null,
                     viewport,
                 }).promise;
                 const target = join(outputDir, `${outputPrefix}-page-${pageNumber}.png`);
@@ -374,7 +420,14 @@ async function renderPdfPages(document, filePath, pages, identity) {
             void pruneRuntimeOutputs();
             return images;
         }
-        catch {
+        catch (e) {
+            // ⚠️ 别把这里改回裸 catch。上面那个 Path2D 冲突就是被它藏住的：
+            // Canvas 每页都抛 → images 清空 → 回落 pdftoppm。装了 poppler 的机器照样
+            // 出图（只是分辨率更低、多一次进程），**完全看不出来**；没装 poppler 的机器
+            // （多数 Windows、绿色版 U 盘）则返回 `ok:true` + 0 张图 + 一句
+            // 「视觉渲染不可用（Canvas 与 pdftoppm 均不可用）」——而 Canvas 明明可用，
+            // 只是抛了。错误文案把人指向「装依赖」，真因一个字都查不到。
+            dlog('read:pdf', `Canvas 渲染失败：${e instanceof Error ? e.message : e}`);
             images.length = 0;
         }
     }

package/src/tools/read/read.ts

@@ -10,6 +10,7 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 
 import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { dlog } from '../../utils/debugLog.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import {
   DEFAULT_MAX_RESULT_SIZE_CHARS,
@@ -34,6 +35,10 @@ import {
   sessionRuntimeDir,
   type RuntimeIdentity,
 } from '../../session/runtimeStore.js';
+import {
+  detectImageMime,
+  resolveLocalImage,
+} from '../../images/imageResolver.js';
 
 const inputSchema = z.object({
   file_path: filePathField('读取'),
@@ -70,6 +75,12 @@ const IMAGE_EXTENSIONS = new Set([
   '.gif',
   '.webp',
   '.bmp',
+  '.tif',
+  '.tiff',
+  '.avif',
+  '.heic',
+  '.heif',
+  '.svg',
 ]);
 const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
 const MAX_NOTEBOOK_BYTES = 32 * 1024 * 1024;
@@ -295,14 +306,26 @@ async function call(
     }
   }
 
-  if (IMAGE_EXTENSIONS.has(ext)) {
+  const imageBytes = info.size <= MAX_IMAGE_BYTES
+    ? await readFile(filePath).catch(() => null)
+    : null;
+  const detectedImage = imageBytes ? detectImageMime(imageBytes) : null;
+  if (IMAGE_EXTENSIONS.has(ext) || detectedImage) {
     if (info.size > MAX_IMAGE_BYTES)
       return { ok: false, error: `图片超过 ${MAX_IMAGE_BYTES} 字节上限` };
-    const bytes = await readFile(filePath);
+    let resolvedImage;
+    try {
+      resolvedImage = await resolveLocalImage(filePath, {
+        maxInputBytes: MAX_IMAGE_BYTES,
+      });
+    } catch (error) {
+      return { ok: false, error: `图片读取失败：${(error as Error).message}` };
+    }
+    const bytes = imageBytes ?? await readFile(filePath);
     recordRead(filePath, { contentHash: hashFileBytes(bytes) }, state);
     return {
       ok: true,
-      content: `已读取图片：${filePath}（${info.size} 字节）。图像已附加供视觉模型检查；非视觉模型只能确认文件元数据，不能解读像素内容。`,
+      content: `已读取图片：${filePath}（${info.size} 字节，实际格式 ${resolvedImage.originalMime}）${resolvedImage.transformed ? `；已规范化为 ${resolvedImage.mime}` : ''}。图像已附加供视觉模型直接检查。`,
       metadata: await fileActivityMetadata(
         filePath,
         'read',
@@ -310,7 +333,7 @@ async function call(
         'source',
         cwd,
       ),
-      visionImages: [{ source: filePath }],
+      visionImages: [{ source: resolvedImage.path }],
       visionNote: '这是 Read 工具读取的本地图片，请直接检查图像内容。',
     };
   }
@@ -475,9 +498,28 @@ async function renderPdfPages(
   }>;
   let createCanvas: Awaited<ReturnType<typeof dynamicImport>>['createCanvas'];
   try {
-    ({ createCanvas } = await dynamicImport('@napi-rs/canvas'));
-  } catch {
-    /* optional adapter */
+    const napi = await dynamicImport('@napi-rs/canvas');
+    createCanvas = napi.createCanvas;
+    // ⚠️ **必须在 pdfjs 之前把这几个全局占住**，否则 PDF 转图 100% 失败。
+    //
+    // pdfjs 的 legacy 构建在 Node 环境下自己往 globalThis 装一套 Path2D /
+    // DOMMatrix / ImageData polyfill。渲染时它 `new Path2D()` 拿到的是**它自己那份**，
+    // 转手调 `ctx.fill(path, 'evenodd')` 交给 @napi-rs/canvas —— 而 napi 的原生绑定
+    // 只认自己的 `Path`，于是每一页都抛
+    //   `Value is none of these types \`String\`, \`Path\``
+    // 两份 polyfill 撞车，谁都没错，就是不是同一个对象。
+    //
+    // 实测：五种 render 参数组合（canvas / canvasContext / canvas:null / 带不带
+    // standardFontDataUrl）全部同样失败 —— 也就是说 `canvas` 那个类型错**不是**病因，
+    // 修类型并不能让它跑起来。把全局换成 napi 的实现之后第 1 页立刻渲染出 137KB PNG。
+    for (const name of ['Path2D', 'DOMMatrix', 'ImageData'] as const) {
+      const impl = (napi as Record<string, unknown>)[name];
+      if (impl) (globalThis as Record<string, unknown>)[name] = impl;
+    }
+  } catch (e) {
+    // optional adapter：没装 @napi-rs/canvas 就回落 pdftoppm。
+    // 但「没装」和「装了却加载失败」对用户是两件事，别都吞成前者。
+    dlog('read:pdf', `@napi-rs/canvas 不可用：${e instanceof Error ? e.message : e}`);
   }
   if (createCanvas) {
     try {
@@ -488,8 +530,13 @@ async function renderPdfPages(
           Math.ceil(viewport.width),
           Math.ceil(viewport.height),
         );
+        // ⚠️ pdfjs v6 的 RenderParameters 里 `canvas` 是**必填**、`canvasContext`
+        // 反而降级为可选且不推荐；文档明说「若必须用 context，canvas 必须为 null」。
+        // 只给 canvasContext 会类型不过（`bun run typecheck` 唯一的红）。
+        // 运行时它有默认值 `canvas = canvasContext.canvas` 所以不炸 —— 但类型要对。
         await page.render({
-          canvas: canvas.getContext('2d') as unknown as Parameters<typeof page.render>[0]['canvas'],
+          canvasContext: canvas.getContext('2d') as never,
+          canvas: null,
           viewport,
         }).promise;
         const target = join(
@@ -501,7 +548,14 @@ async function renderPdfPages(
       }
       void pruneRuntimeOutputs();
       return images;
-    } catch {
+    } catch (e) {
+      // ⚠️ 别把这里改回裸 catch。上面那个 Path2D 冲突就是被它藏住的：
+      // Canvas 每页都抛 → images 清空 → 回落 pdftoppm。装了 poppler 的机器照样
+      // 出图（只是分辨率更低、多一次进程），**完全看不出来**；没装 poppler 的机器
+      // （多数 Windows、绿色版 U 盘）则返回 `ok:true` + 0 张图 + 一句
+      // 「视觉渲染不可用（Canvas 与 pdftoppm 均不可用）」——而 Canvas 明明可用，
+      // 只是抛了。错误文案把人指向「装依赖」，真因一个字都查不到。
+      dlog('read:pdf', `Canvas 渲染失败：${e instanceof Error ? e.message : e}`);
       images.length = 0;
     }
   }

package/src/tools/shared/fileUtils.js

@@ -115,7 +115,7 @@ export function applyLineEnding(content, ending) {
 // -------------------- 3.5 二进制扩展名拦截 --------------------
 // 上游 D:\code\kakadeai\constants\files.ts:5-112 BINARY_EXTENSIONS Set 的裁剪版：
 // 故意剔除 .log / .csv / .tsv / .dat / .data / .lock —— 这些经常被人当文本读。
-// 保留纯二进制：图片 / 文档 / 可执行 / 编译产物 / 压缩包 / 多媒体 / 字体 / 数据库 / wasm。
+// 保留纯二进制：图片 / 文档 / 可执行 / 编译产物 / 压缩包 / 多媒体 / 字体 / wasm。
 export const BINARY_EXTENSIONS = new Set([
     '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.tiff', '.tif',
     '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
@@ -124,7 +124,6 @@ export const BINARY_EXTENSIONS = new Set([
     '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar', '.iso',
     '.mp3', '.mp4', '.mov', '.avi', '.mkv', '.wav', '.flac', '.ogg',
     '.ttf', '.otf', '.woff', '.woff2',
-    '.sqlite', '.sqlite3', '.db',
     '.psd', '.ai', '.bin', '.wasm',
 ]);
 export function hasBinaryExtension(filePath) {