nolo-cli 0.1.22 → 0.1.26

package/ai/tools/{execBashTool.ts → execShellTool.ts}

@@ -1,9 +1,10 @@
-import { DEFAULT_LOCAL_API_ORIGIN } from "core/localOrigins";
-import { callToolApi } from "./toolApiClient";
+import { DEFAULT_LOCAL_API_ORIGIN } from "core/localOrigins";
+import { callToolApi } from "./toolApiClient";
+import { ToolResultError } from "./toolResultError";
 
 type ExecShellKind = "auto" | "bash" | "powershell";
 
-type ExecBashRequestArgs = {
+type ExecShellRequestArgs = {
   command?: string;
   cwd?: string;
   interactive?: boolean;
@@ -14,58 +15,7 @@ type ExecBashRequestArgs = {
   close?: boolean;
 };
 
-export const execBashFunctionSchema = {
-  name: "execBash",
-  description:
-    "兼容旧 agent 的 shell 执行工具。底层会调用后端 shell 执行接口；在 Windows 上可能自动回退到 PowerShell。环境不明确时，先调用 checkEnv({check:'context'}) 判断当前平台与可用 shell。支持交互式 session：先用 interactive=true 启动，再通过 sessionId + input 继续写入 stdin，或用 sessionId 单独轮询输出。仅用于本地开发环境。对 rm 等危险命令默认拦截，需显式传 unsafe: true 才会执行。不要用它执行 rg/grep 代码搜索；代码搜索请改用 codeSearch。",
-  parameters: {
-    type: "object",
-    properties: {
-      command: {
-        type: "string",
-        description:
-          "要执行的 shell 命令，例如: 'git status --short', 'bun test --watch=false'。",
-      },
-      cwd: {
-        type: "string",
-        description:
-          "可选：命令执行的工作目录（相对于 diff-server 所在机器），默认使用后端的 process.cwd()。",
-      },
-      unsafe: {
-        type: "boolean",
-        description:
-          "可选：是否允许执行被判定为危险的命令（例如 rm -rf）。默认 false；当为 false 且命令被识别为危险时，会直接拦截而不真正执行。",
-      },
-      interactive: {
-        type: "boolean",
-        description:
-          "可选：是否以交互式 session 启动命令。为 true 时接口会立即返回 sessionId，后续可继续写 stdin 或轮询输出。",
-      },
-      pty: {
-        type: "boolean",
-        description:
-          "可选：是否为交互式 session 分配伪终端（PTY）。适合 python -i、bash、node 等真正依赖终端语义的 REPL。",
-      },
-      sessionId: {
-        type: "string",
-        description:
-          "可选：已存在的交互式 sessionId。传入后可继续写入 input、查询最新输出或关闭该 session。",
-      },
-      input: {
-        type: "string",
-        description:
-          "可选：要写入 session stdin 的文本。通常需要自己补换行，例如 'y\\n' 或 'exit\\n'。",
-      },
-      close: {
-        type: "boolean",
-        description:
-          "可选：是否关闭指定 session。通常与 sessionId 搭配使用。",
-      },
-    },
-  },
-};
-
-export const execShellFunctionSchema = {
+export const execShellFunctionSchema = {
   name: "execShell",
   description:
     "跨平台 shell 执行工具。会在 Windows 上优先使用 PowerShell，在 Linux/macOS 上使用 bash。环境不明确时，先调用 checkEnv({check:'context'}) 判断当前平台与可用 shell。支持交互式 session：先用 interactive=true 启动，再通过 sessionId + input 继续写入 stdin，或用 sessionId 单独轮询输出。仅用于本地开发环境。对 rm 等危险命令默认拦截，需显式传 unsafe: true 才会执行。不要用它执行 rg/grep 代码搜索；代码搜索请改用 codeSearch。",
@@ -143,9 +93,9 @@ function isDangerousCommand(rawCommand: string): boolean {
 }
 
 async function requestExec(
-  args: ExecBashRequestArgs,
+  args: ExecShellRequestArgs,
   thunkApi?: any,
-  endpoint = "/api/exec-bash",
+  endpoint = "/api/exec-shell",
   context?: { agentKey?: string },
 ): Promise<any> {
   const payload = Object.fromEntries(
@@ -163,12 +113,16 @@ async function requestExec(
     (typeof process !== "undefined" &&
       (process as any).env?.DIFF_SERVER_ORIGIN) ||
     (typeof window !== "undefined" ? window.location.origin : DEFAULT_LOCAL_API_ORIGIN);
-  const url = `${baseUrl}${endpoint}`;
-  const res = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(payload),
-  });
+  const url = `${baseUrl}${endpoint}`;
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (typeof window !== "undefined" && (window as any).__NOLO_DESKTOP__) {
+    headers["X-Nolo-Desktop-Tool"] = "1";
+  }
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload),
+  });
 
   const text = await res.text();
   try {
@@ -178,7 +132,7 @@ async function requestExec(
   }
 }
 
-function formatExecResult(prefixLabel: string, args: any, json: any, trimmedCommand: string, sessionId?: string) {
+function formatExecResult(prefixLabel: string, args: any, json: any, trimmedCommand: string, sessionId?: string) {
   const prefix = json?.ok === false || json?.error ? `[${prefixLabel} 失败]` : `[${prefixLabel} 成功]`;
   const stdout = json.stdout ?? "";
   const stderr = json.stderr ?? "";
@@ -219,10 +173,20 @@ function formatExecResult(prefixLabel: string, args: any, json: any, trimmedComm
       ...json,
     },
     displayData: displayParts.join("\n"),
-  };
-}
+  };
+}
+
+function throwExecToolError(toolName: "execShell", message: string, rawData?: any): never {
+  const displayData = `${toolName} 调用失败：${message}`;
+  throw new ToolResultError(displayData, {
+    code: "EXEC_TOOL_FAILED",
+    rawData: rawData ?? { error: displayData },
+    displayData,
+    retryable: true,
+  });
+}
 
-function buildBlockedResponse(toolName: "execBash" | "execShell", trimmedCommand: string, cwd?: string, shell?: ExecShellKind) {
+function buildBlockedResponse(toolName: "execShell", trimmedCommand: string, cwd?: string, shell?: ExecShellKind) {
   const lines: string[] = [];
   lines.push(`[${toolName} 拦截] 检测到潜在危险命令，默认不执行。`);
   lines.push(`command: ${trimmedCommand}`);
@@ -247,57 +211,7 @@ function buildBlockedResponse(toolName: "execBash" | "execShell", trimmedCommand
   };
 }
 
-export const startExecBashSession = (
-  thunkApi: any,
-  args: { command: string; cwd?: string; pty?: boolean }
-) =>
-  requestExec(
-    {
-      command: args.command,
-      cwd: args.cwd,
-      interactive: true,
-      pty: args.pty,
-    },
-    thunkApi,
-  );
-
-export const writeExecBashSession = (
-  thunkApi: any,
-  args: { sessionId: string; input: string }
-) =>
-  requestExec(
-    {
-      sessionId: args.sessionId,
-      input: args.input,
-    },
-    thunkApi,
-  );
-
-export const readExecBashSession = (
-  thunkApi: any,
-  args: { sessionId: string }
-) =>
-  requestExec(
-    {
-      sessionId: args.sessionId,
-    },
-    thunkApi,
-  );
-
-export const closeExecBashSession = (
-  thunkApi: any,
-  args: { sessionId: string; input?: string }
-) =>
-  requestExec(
-    {
-      sessionId: args.sessionId,
-      input: args.input,
-      close: true,
-    },
-    thunkApi,
-  );
-
-export const startExecShellSession = (
+export const startExecShellSession = (
   thunkApi: any,
   args: { command: string; cwd?: string; pty?: boolean; shell?: ExecShellKind }
 ) =>
@@ -310,43 +224,8 @@ export const startExecShellSession = (
       shell: args.shell,
     },
     thunkApi,
-    "/api/exec-shell",
-  );
-
-export async function execBashFunc(args: any, thunkApi?: any, context?: { agentKey?: string }): Promise<{
-  rawData: any;
-  displayData: string;
-}> {
-  const { command, cwd, unsafe, interactive, pty, sessionId, input, close } = args || {};
-  const isSessionFollowup = typeof sessionId === "string" && sessionId.trim().length > 0;
-
-  if (!isSessionFollowup && (!command || typeof command !== "string")) {
-    const msg = "execBash 需要提供 command，或提供有效的 sessionId 来继续已有交互式 session。";
-    return { rawData: { error: msg }, displayData: msg };
-  }
-
-  const trimmedCommand = typeof command === "string" ? command.trim() : "";
-  if (!isSessionFollowup && !unsafe && isDangerousCommand(trimmedCommand)) {
-    return buildBlockedResponse("execBash", trimmedCommand, cwd);
-  }
-
-  try {
-    const json = await requestExec({
-      ...(trimmedCommand ? { command: trimmedCommand } : {}),
-      ...(cwd ? { cwd } : {}),
-      ...(interactive ? { interactive: true } : {}),
-      ...(pty ? { pty: true } : {}),
-      ...(isSessionFollowup ? { sessionId } : {}),
-      ...(typeof input === "string" ? { input } : {}),
-      ...(close ? { close: true } : {}),
-    }, thunkApi, "/api/exec-bash", context);
-    return formatExecResult("execBash", { cwd }, json, trimmedCommand, sessionId);
-  } catch (error: any) {
-    const msg = `execBash 调用失败：${error?.message || String(error)}`;
-    return { rawData: { error: msg }, displayData: msg };
-  }
-}
-
+  );
+
 export async function execShellFunc(args: any, thunkApi?: any, context?: { agentKey?: string }): Promise<{
   rawData: any;
   displayData: string;
@@ -375,9 +254,13 @@ export async function execShellFunc(args: any, thunkApi?: any, context?: { agent
       ...(typeof input === "string" ? { input } : {}),
       ...(close ? { close: true } : {}),
     }, thunkApi, "/api/exec-shell", context);
-    return formatExecResult("execShell", { cwd, shell }, json, trimmedCommand, sessionId);
-  } catch (error: any) {
-    const msg = `execShell 调用失败：${error?.message || String(error)}`;
-    return { rawData: { error: msg }, displayData: msg };
-  }
-}
+    if (json?.ok === false || json?.error) {
+      const message = typeof json?.error === "string" ? json.error : JSON.stringify(json?.error ?? json);
+      throwExecToolError("execShell", message, { command: trimmedCommand || null, ...json });
+    }
+    return formatExecResult("execShell", { cwd, shell }, json, trimmedCommand, sessionId);
+  } catch (error: any) {
+    if (error instanceof ToolResultError) throw error;
+    throwExecToolError("execShell", error?.message || String(error));
+  }
+}

package/ai/tools/index.ts

@@ -22,6 +22,7 @@ import {
   createWorkflowFunc,
 } from "./createWorkflowTool";
 import { delayFunctionSchema, delayFunc } from "./delayTool";
+import { canonicalizeToolName } from "./toolNameAliases";
 import {
   completeDialogGoalFunc,
   completeDialogGoalFunctionSchema,
@@ -160,6 +161,10 @@ import {
   fetchWebpageFunctionSchema,
   fetchWebpageFunc,
 } from "./fetchWebpageTool";
+import {
+  convertMarxistsBookToOfflineHtmlFunctionSchema,
+  convertMarxistsBookToOfflineHtmlFunc,
+} from "./convertMarxistsBookTool";
 import {
   readXPostFunctionSchema,
   readXPostFunc,
@@ -281,7 +286,7 @@ import {
   rememberMemoryFunc,
   rememberMemoryFunctionSchema,
 } from "./rememberMemoryTool";
-import { execBashFunctionSchema, execBashFunc, execShellFunctionSchema, execShellFunc } from "./execBashTool";
+import { execShellFunctionSchema, execShellFunc } from "./execShellTool";
 import { checkEnvFunctionSchema, checkEnvFunc } from "./checkEnvTool";
 
 import { agentToolDefinitions } from "./agent/agentTools";
@@ -1464,6 +1469,23 @@ const baseToolDefinitions: ToolDefinition[] = [
     },
     behavior: "data",
   },
+  {
+    id: "convertMarxistsBookToOfflineHtml",
+    schema: convertMarxistsBookToOfflineHtmlFunctionSchema,
+    executor: convertMarxistsBookToOfflineHtmlFunc,
+    description: {
+      name: "convertMarxistsBookToOfflineHtml",
+      description:
+        "将 Marxists.org 中文旧式书籍页面转换成保留原 CSS、背景和排版的离线单 HTML。",
+      category: "网络与智能",
+    },
+    behavior: "data",
+    capability: "web_access",
+    riskLevel: "low",
+    costLevel: "medium",
+    defaultConsent: "auto",
+    cancelable: true,
+  },
   {
     id: "readXPost",
     schema: readXPostFunctionSchema,
@@ -1837,18 +1859,6 @@ const baseToolDefinitions: ToolDefinition[] = [
     behavior: "data",
     uiGroup: "general",
   },
-  {
-    id: "execBash",
-    schema: execBashFunctionSchema,
-    executor: execBashFunc,
-    description: {
-      name: "exec_bash",
-      description:
-        "通过后端 diff-server 的 /api/exec-bash 接口执行一条 bash 命令，仅用于本地开发调试。",
-      category: "网络与智能",
-    },
-    behavior: "action",
-  },
   {
     id: "execShell",
     schema: execShellFunctionSchema,
@@ -2070,7 +2080,7 @@ export const findToolExecutor = (
   executor: ToolDefinition["executor"];
   canonicalName: string;
 } => {
-  const normalizedRawName = normalizeToolName(rawName);
+  const normalizedRawName = normalizeToolName(canonicalizeToolName(rawName));
   const canonicalName = Object.keys(toolExecutors).find(
     (key) => normalizeToolName(key) === normalizedRawName
   );

package/ai/tools/marxistsOfflineBook.ts

@@ -0,0 +1,253 @@
+export type MarxistsOfflineBookPage = {
+  name: string;
+  url: string;
+  title: string;
+};
+
+export type MarxistsOfflineBookResult = {
+  title: string;
+  startUrl: string;
+  indexUrl: string;
+  stylesheetUrl: string | null;
+  pages: MarxistsOfflineBookPage[];
+  html: string;
+  validation: {
+    pageCount: number;
+    hasEmbeddedAssets: boolean;
+    hasNetworkUrls: boolean;
+    hasUtf8Meta: boolean;
+    byteLength: number;
+  };
+};
+
+export type ConvertMarxistsBookArgs = {
+  startUrl: string;
+  encoding?: string;
+  fetchImpl?: typeof fetch;
+  maxPages?: number;
+};
+
+const DEFAULT_ENCODING = "gb2312";
+const USER_AGENT =
+  "Mozilla/5.0 (compatible; NoloMarxistsOfflineBook/1.0; +https://nolo.chat)";
+
+const normalizeBookBaseUrl = (startUrl: string): URL => {
+  const parsed = new URL(startUrl);
+  if (!/^https?:$/i.test(parsed.protocol)) {
+    throw new Error("startUrl must be an http or https URL.");
+  }
+  return new URL("./", parsed);
+};
+
+const decodeBytes = (bytes: ArrayBuffer, encoding: string): string => {
+  try {
+    return new TextDecoder(encoding).decode(bytes);
+  } catch {
+    return new TextDecoder(DEFAULT_ENCODING).decode(bytes);
+  }
+};
+
+const fetchBytes = async (
+  url: string,
+  fetchImpl: typeof fetch,
+): Promise<ArrayBuffer> => {
+  const response = await fetchImpl(url, {
+    headers: {
+      "user-agent": USER_AGENT,
+      accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+  }
+  return response.arrayBuffer();
+};
+
+const extractTitle = (html: string): string => {
+  return (
+    html.match(/<title>([\s\S]*?)<\/title>/i)?.[1]
+      ?.replace(/<[^>]+>/g, " ")
+      .replace(/\s+/g, " ")
+      .trim() || ""
+  );
+};
+
+const extractBody = (html: string): string => {
+  return html.match(/<body[^>]*>([\s\S]*?)<\/body>/i)?.[1] ?? html;
+};
+
+export const discoverMarxistsBookPageNames = (
+  indexHtml: string,
+  maxPages = 80,
+): string[] => {
+  const pageNames = [...indexHtml.matchAll(/href=["']?([^"' >#]+\.htm)(#[^"' >]*)?["']?/gi)]
+    .map((match) => match[1])
+    .filter((href) => !href.includes("/") && !href.startsWith(".."))
+    .map((href) => href.trim())
+    .filter(Boolean)
+    .sort();
+
+  const uniqueNames = Array.from(new Set(["index.htm", ...pageNames]));
+  if (uniqueNames.length <= 1) {
+    throw new Error("No same-directory .htm chapter links were found in index.htm.");
+  }
+  if (uniqueNames.length > maxPages) {
+    throw new Error(
+      `Refusing to download ${uniqueNames.length} pages; maxPages is ${maxPages}.`,
+    );
+  }
+  return uniqueNames;
+};
+
+const extractStylesheetHref = (html: string): string | null => {
+  return (
+    html.match(/<link[^>]+href=["']([^"']+\.css)["'][^>]*>/i)?.[1] ?? null
+  );
+};
+
+const guessMimeType = (url: string): string => {
+  const pathname = new URL(url).pathname.toLowerCase();
+  if (pathname.endsWith(".gif")) return "image/gif";
+  if (pathname.endsWith(".png")) return "image/png";
+  if (pathname.endsWith(".jpg") || pathname.endsWith(".jpeg")) return "image/jpeg";
+  if (pathname.endsWith(".webp")) return "image/webp";
+  if (pathname.endsWith(".css")) return "text/css";
+  return "application/octet-stream";
+};
+
+export const inlineCssUrlAssets = async (args: {
+  css: string;
+  cssUrl: string;
+  fetchImpl: typeof fetch;
+}): Promise<string> => {
+  const replacements = new Map<string, string>();
+  const matches = [...args.css.matchAll(/url\((['"]?)([^)'"]+)\1\)/gi)];
+
+  for (const match of matches) {
+    const rawRef = match[2].trim();
+    if (!rawRef || /^(data:|https?:)/i.test(rawRef)) continue;
+    const assetUrl = new URL(rawRef, args.cssUrl).toString();
+    if (!replacements.has(rawRef)) {
+      const bytes = await fetchBytes(assetUrl, args.fetchImpl);
+      const base64 = Buffer.from(bytes).toString("base64");
+      replacements.set(
+        rawRef,
+        `data:${guessMimeType(assetUrl)};base64,${base64}`,
+      );
+    }
+  }
+
+  return args.css.replace(/url\((['"]?)([^)'"]+)\1\)/gi, (full, quote, rawRef) => {
+    const replacement = replacements.get(String(rawRef).trim());
+    return replacement ? `url('${replacement}')` : full;
+  });
+};
+
+const rewriteLocalChapterLinks = (body: string): string => {
+  return body.replace(
+    /href=["']([^"']+\.htm)(#[^"']*)?["']/gi,
+    (_full, href: string, hash: string | undefined) => {
+      const anchor = href.replace(/\.htm$/i, "");
+      return `href="#${anchor}${hash ? `-${hash.replace(/^#/, "")}` : ""}"`;
+    },
+  );
+};
+
+const buildSingleHtml = (args: {
+  title: string;
+  css: string;
+  pages: Array<MarxistsOfflineBookPage & { body: string }>;
+}): string => {
+  const sections = args.pages.map((page) => {
+    const anchor = page.name.replace(/\.htm$/i, "");
+    return `<section class="chapter" id="${anchor}"><div class="chapter-source">${page.title}</div>${rewriteLocalChapterLinks(page.body)}</section>`;
+  });
+
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${args.title}</title>
+<style>
+${args.css}
+body { margin: 0 10px; }
+.table1 { max-width: 960px; width: min(960px, calc(100vw - 20px)); }
+.chapter { page-break-after: always; break-after: page; }
+.chapter-source { display: none; }
+@media screen and (max-width: 700px) {
+  html { margin-left: 8px !important; margin-right: 8px !important; }
+  body { margin-left: 8px !important; margin-right: 8px !important; }
+  .table1 { width: 100% !important; max-width: 100% !important; }
+  table { max-width: 100% !important; }
+}
+@media print {
+  .chapter { page-break-after: always; }
+}
+</style>
+</head>
+<body id="top">
+${sections.join("\n")}
+</body>
+</html>`;
+};
+
+export async function convertMarxistsBookToOfflineHtml(
+  args: ConvertMarxistsBookArgs,
+): Promise<MarxistsOfflineBookResult> {
+  const startUrl = args.startUrl?.trim();
+  if (!startUrl) throw new Error("startUrl is required.");
+
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const encoding = args.encoding || DEFAULT_ENCODING;
+  const bookBaseUrl = normalizeBookBaseUrl(startUrl);
+  const indexUrl = new URL("index.htm", bookBaseUrl).toString();
+  const indexHtml = decodeBytes(await fetchBytes(indexUrl, fetchImpl), encoding);
+  const pageNames = discoverMarxistsBookPageNames(indexHtml, args.maxPages);
+
+  const pages: Array<MarxistsOfflineBookPage & { body: string }> = [];
+  for (const name of pageNames) {
+    const pageUrl = new URL(name, bookBaseUrl).toString();
+    const html = decodeBytes(await fetchBytes(pageUrl, fetchImpl), encoding);
+    pages.push({
+      name,
+      url: pageUrl,
+      title: extractTitle(html),
+      body: extractBody(html),
+    });
+  }
+
+  const stylesheetHref =
+    extractStylesheetHref(indexHtml) ||
+    pages.map((page) => extractStylesheetHref(page.body)).find(Boolean) ||
+    "../../MIA01.css";
+  const stylesheetUrl = stylesheetHref
+    ? new URL(stylesheetHref, indexUrl).toString()
+    : null;
+  const rawCss = stylesheetUrl
+    ? decodeBytes(await fetchBytes(stylesheetUrl, fetchImpl), encoding)
+    : "";
+  const css = stylesheetUrl
+    ? await inlineCssUrlAssets({ css: rawCss, cssUrl: stylesheetUrl, fetchImpl })
+    : rawCss;
+
+  const title = extractTitle(indexHtml) || pages[0]?.title || "Offline Book";
+  const html = buildSingleHtml({ title, css, pages });
+  const byteLength = new TextEncoder().encode(html).byteLength;
+
+  return {
+    title,
+    startUrl,
+    indexUrl,
+    stylesheetUrl,
+    pages: pages.map(({ body: _body, ...page }) => page),
+    html,
+    validation: {
+      pageCount: pages.length,
+      hasEmbeddedAssets: html.includes("data:image/"),
+      hasNetworkUrls: /https?:\/\//i.test(html),
+      hasUtf8Meta: html.includes('<meta charset="utf-8">'),
+      byteLength,
+    },
+  };
+}

package/ai/tools/modelUsageTools.ts

@@ -52,11 +52,13 @@ export const queryModelUsageFunctionSchema = {
       },
       thresholdCredits: {
         type: "number",
-        description: "可选阈值，单位 credits；返回 threshold.exceeded。",
+        description:
+          "可选阈值，单位 credits；返回 threshold.exceeded 与 0-100 的 threshold.usedPercent。",
       },
       thresholdUsd: {
         type: "number",
-        description: "可选阈值，单位 USD；会按 creditsPerUsd 换算。",
+        description:
+          "可选阈值，单位 USD；会按 creditsPerUsd 换算，并返回 0-100 的 threshold.usedPercent。",
       },
     },
   },
@@ -179,6 +181,11 @@ export const notifyUserFunctionSchema = {
         type: "string",
         description: "可选跳转链接。",
       },
+      targetUserId: {
+        type: "string",
+        description:
+          "可选目标用户 ID。默认通知当前用户；只有受信任的系统 agent 或管理员可以通知其他用户。",
+      },
     },
     required: ["title", "message"],
   },

package/ai/tools/readTool.ts

@@ -9,6 +9,7 @@ import { isTableMetaKey, rowKey, isAgentKey } from "database/keys";
 import { DataType } from "create/types";
 import { TableMeta } from "render/table/types";
 import { fetchAndSerializeTable } from "render/table/utils/tableSerialization";
+import { readFileFunc } from "./readFileTool";
 
 // ---- Types ----
 
@@ -24,6 +25,13 @@ export type ReadArgs = {
    * - true：使用 readAndWaitAction，等待远程与本地决策后返回“权威”结果
    */
   waitRemote?: boolean;
+
+  /**
+   * Backward-compatible escape hatch for models that call read with a local
+   * file path even when the readFile tool is available.
+   */
+  filePath?: string;
+  path?: string;
 };
 
 // ---- 工具 Schema，供 LLM 调用 ----
@@ -68,6 +76,29 @@ export async function readFunc(
   context?: { parentMessageId?: string; signal?: AbortSignal }
 ): Promise<{ rawData: any; displayData?: string }> {
   const { dbKey, waitRemote = false } = args || {};
+  const localFilePath =
+    typeof args?.filePath === "string"
+      ? args.filePath
+      : typeof args?.path === "string"
+        ? args.path
+        : "";
+
+  if (!dbKey && localFilePath) {
+    const result = await readFileFunc(
+      {
+        filePath: localFilePath,
+        startLine: (args as any).startLine,
+        endLine: (args as any).endLine,
+      },
+      thunkApi,
+      context
+    );
+    return {
+      rawData: result,
+      displayData:
+        typeof result === "string" ? result : JSON.stringify(result, null, 2),
+    };
+  }
 
   if (!dbKey || typeof dbKey !== "string") {
     throw new Error("read 工具需要提供字符串类型的 id（dbKey）。");