minimal-agent 0.18.11 → 0.18.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.18.11",
+  "version": "0.18.12",
   "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/src/loop.js

@@ -1111,7 +1111,7 @@ export async function* runQuery(userInput, options) {
             const rawContent = result.ok ? result.content : `Error: ${result.error}`;
             const basePolicy = result.policy ?? getToolResultPolicy(tc.function.name);
             // 超大结果先归档再压缩：归档失败时保留原文，绝不因为磁盘问题破坏上下文。
-            const archived = result.ok && sessionState
+            const archived = result.ok && sessionState && !(basePolicy.boundedWindow && basePolicy.archiveRef)
                 ? await archiveToolResult(rawContent, sessionState.microCompact.archiveKey, tc.function.name)
                 : { content: rawContent, originalChars: rawContent.length };
             // 归档退化必须发声：撞会话上限后每条超长结果都退回原文塞进上下文，

package/src/loop.ts

@@ -1193,7 +1193,7 @@ export async function* runQuery(userInput: string, options: RunQueryOptions): As
       const basePolicy = result.policy ?? getToolResultPolicy(tc.function.name);
       // 超大结果先归档再压缩：归档失败时保留原文，绝不因为磁盘问题破坏上下文。
       const archived =
-        result.ok && sessionState
+        result.ok && sessionState && !(basePolicy.boundedWindow && basePolicy.archiveRef)
           ? await archiveToolResult(rawContent, sessionState.microCompact.archiveKey, tc.function.name)
           : { content: rawContent, originalChars: rawContent.length };
       // 归档退化必须发声：撞会话上限后每条超长结果都退回原文塞进上下文，

package/src/tools/toolPromptGuides.js

@@ -114,7 +114,7 @@ export const CONTRACT_DESCRIPTION_OVERRIDES = {
     AdvisorDecision: '记录主 Agent 对顾问第二意见的 accept、partial 或 reject 判断；是否采纳由主 Agent 决定，登记不是执行许可。partial 同时填 acceptedPoints/rejectedPoints；reject 填 rejectedPoints，列出被拒绝点及依据；evidenceRefs 只引用真实 tool_call_id，没有引用则记录待验证。登记失败不阻止任务继续。',
     MultiEdit: '同文件有序批量精确替换，先 Read 相关范围；全部匹配成功才写盘。old_string 非空且唯一，或显式 replace_all。后续匹配前序生成文本会被拒绝，请合并 edits。操作条数不等于替换次数，diff 预览可能不完整。',
     LSP: '查询定义、引用、类型、符号和诊断。line/character 为 1-based UTF-16；尚未收到诊断不等于没有错误，编辑前读取源码。',
-    WebFetch: '读取已知 HTTP(S) URL 的静态文本，HTML 转 Markdown；不执行 JavaScript、不继承登录态。PDF/图片用 Download 后 Read；动态页面用 WebBrowser。',
+    WebFetch: '读取已知 HTTP(S) URL 的静态文本并完整保存会话快照，HTML 转 Markdown；结果仅为窗口，使用 snapshot_id + next_offset 续读，query 在全文中精确搜索，max_chars 可扩大读取预算。不要重复读取同一窗口或声称已读未展示部分。不执行 JavaScript、不继承登录态。PDF/图片用 Download 后 Read；动态页面用 WebBrowser。',
     WebSearch: 'Tavily 搜索返回标题、URL、片段及可选综合答案，不是完整原文或浏览器。重要结论读取来源正文；按子问题查询，重试改变关键词或来源。recency 控制时效，历史范围用 start_date/end_date，none 关闭自动时效；advanced 更慢，news 偏新闻。需配置 Tavily。',
     PowerShell: '运行宿主 PowerShell 独立进程并检查结果；长任务用 TaskOutput/TaskStop。永久删除用 Trash；不可逆操作先确认，非交互时取消。',
     Download: '下载 HTTP(S) 原始字节到指定路径；相对路径基于工作目录，会覆盖已有文件；失败或中断不保留部分下载。',

package/src/tools/toolPromptGuides.ts

@@ -132,7 +132,7 @@ export const CONTRACT_DESCRIPTION_OVERRIDES: Readonly<Record<string, string | ((
   AdvisorDecision: '记录主 Agent 对顾问第二意见的 accept、partial 或 reject 判断；是否采纳由主 Agent 决定，登记不是执行许可。partial 同时填 acceptedPoints/rejectedPoints；reject 填 rejectedPoints，列出被拒绝点及依据；evidenceRefs 只引用真实 tool_call_id，没有引用则记录待验证。登记失败不阻止任务继续。',
   MultiEdit: '同文件有序批量精确替换，先 Read 相关范围；全部匹配成功才写盘。old_string 非空且唯一，或显式 replace_all。后续匹配前序生成文本会被拒绝，请合并 edits。操作条数不等于替换次数，diff 预览可能不完整。',
   LSP: '查询定义、引用、类型、符号和诊断。line/character 为 1-based UTF-16；尚未收到诊断不等于没有错误，编辑前读取源码。',
-  WebFetch: '读取已知 HTTP(S) URL 的静态文本，HTML 转 Markdown；不执行 JavaScript、不继承登录态。PDF/图片用 Download 后 Read；动态页面用 WebBrowser。',
+  WebFetch: '读取已知 HTTP(S) URL 的静态文本并完整保存会话快照，HTML 转 Markdown；结果仅为窗口，使用 snapshot_id + next_offset 续读，query 在全文中精确搜索，max_chars 可扩大读取预算。不要重复读取同一窗口或声称已读未展示部分。不执行 JavaScript、不继承登录态。PDF/图片用 Download 后 Read；动态页面用 WebBrowser。',
   WebSearch: 'Tavily 搜索返回标题、URL、片段及可选综合答案，不是完整原文或浏览器。重要结论读取来源正文；按子问题查询，重试改变关键词或来源。recency 控制时效，历史范围用 start_date/end_date，none 关闭自动时效；advanced 更慢，news 偏新闻。需配置 Tavily。',
   PowerShell: '运行宿主 PowerShell 独立进程并检查结果；长任务用 TaskOutput/TaskStop。永久删除用 Trash；不可逆操作先确认，非交互时取消。',
   Download: '下载 HTTP(S) 原始字节到指定路径；相对路径基于工作目录，会覆盖已有文件；失败或中断不保留部分下载。',

package/src/tools/webfetch/pageSnapshot.js

@@ -0,0 +1,56 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sessionRuntimeDir } from '../../session/runtimeStore.js';
+function directory(identity) { return join(sessionRuntimeDir(identity), 'web-pages'); }
+export function pageSnapshotPath(id, identity) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        throw new Error('无效的 snapshot_id');
+    return join(directory(identity), `${id}.txt`);
+}
+export async function savePageSnapshot(page, identity) {
+    const id = createHash('sha256').update(JSON.stringify(page)).digest('hex');
+    const dir = directory(identity);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // Publish the metadata last. Readers never observe a half-written snapshot.
+    const path = join(dir, `${id}.txt`);
+    const temp = join(dir, `.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, page.text, { mode: 0o600 });
+        await rename(temp, path);
+        const { text, ...metadata } = page;
+        await writeFile(temp, JSON.stringify(metadata), { mode: 0o600 });
+        await rename(temp, join(dir, `${id}.json`));
+    }
+    finally {
+        await unlink(temp).catch(() => undefined);
+    }
+    return { id, path };
+}
+export async function loadPageSnapshot(id, url, identity) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        throw new Error('无效的 snapshot_id');
+    const page = JSON.parse(await readFile(join(directory(identity), `${id}.json`), 'utf8'));
+    if (page.url !== url)
+        throw new Error('快照 URL 不匹配');
+    page.text = await readFile(join(directory(identity), `${id}.txt`), 'utf8');
+    if (createHash('sha256').update(JSON.stringify({ url: page.url, text: page.text, format: page.format, fetchedAt: page.fetchedAt })).digest('hex') !== id)
+        throw new Error('快照完整性检查失败，请重新抓取');
+    return page;
+}
+/** UTF-16 offsets match JS slicing and Read.column; never split a surrogate pair. */
+export function pageWindow(text, offset, budget, query) {
+    let start = Math.min(offset, text.length);
+    if (query) {
+        const hit = text.indexOf(query, start);
+        if (hit < 0)
+            return { text: '', start, end: start, next: null, found: false };
+        start = hit;
+    }
+    if (start > 0 && /[\uDC00-\uDFFF]/.test(text[start] ?? '') && /[\uD800-\uDBFF]/.test(text[start - 1]))
+        start--;
+    let end = Math.min(text.length, start + budget);
+    if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1] ?? ''))
+        end--;
+    return { text: text.slice(start, end), start, end, next: end < text.length ? end : null, found: true };
+}

package/src/tools/webfetch/pageSnapshot.ts

@@ -0,0 +1,51 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sessionRuntimeDir, type RuntimeIdentity } from '../../session/runtimeStore.js';
+
+/** Immutable, session-local source. Preview limits never truncate this copy. */
+export interface PageSnapshot { url: string; text: string; format: string; fetchedAt: number }
+function directory(identity: RuntimeIdentity) { return join(sessionRuntimeDir(identity), 'web-pages'); }
+export function pageSnapshotPath(id: string, identity: RuntimeIdentity) {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('无效的 snapshot_id');
+  return join(directory(identity), `${id}.txt`);
+}
+export async function savePageSnapshot(page: PageSnapshot, identity: RuntimeIdentity) {
+  const id = createHash('sha256').update(JSON.stringify(page)).digest('hex');
+  const dir = directory(identity);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // Publish the metadata last. Readers never observe a half-written snapshot.
+  const path = join(dir, `${id}.txt`);
+  const temp = join(dir, `.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temp, page.text, { mode: 0o600 });
+    await rename(temp, path);
+    const { text, ...metadata } = page;
+    await writeFile(temp, JSON.stringify(metadata), { mode: 0o600 });
+    await rename(temp, join(dir, `${id}.json`));
+  } finally { await unlink(temp).catch(() => undefined); }
+  return { id, path };
+}
+export async function loadPageSnapshot(id: string, url: string, identity: RuntimeIdentity): Promise<PageSnapshot> {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('无效的 snapshot_id');
+  const page = JSON.parse(await readFile(join(directory(identity), `${id}.json`), 'utf8')) as PageSnapshot;
+  if (page.url !== url) throw new Error('快照 URL 不匹配');
+  page.text = await readFile(join(directory(identity), `${id}.txt`), 'utf8');
+  if (createHash('sha256').update(JSON.stringify({ url: page.url, text: page.text, format: page.format, fetchedAt: page.fetchedAt })).digest('hex') !== id)
+    throw new Error('快照完整性检查失败，请重新抓取');
+  return page;
+}
+
+/** UTF-16 offsets match JS slicing and Read.column; never split a surrogate pair. */
+export function pageWindow(text: string, offset: number, budget: number, query?: string) {
+  let start = Math.min(offset, text.length);
+  if (query) {
+    const hit = text.indexOf(query, start);
+    if (hit < 0) return { text: '', start, end: start, next: null, found: false };
+    start = hit;
+  }
+  if (start > 0 && /[\uDC00-\uDFFF]/.test(text[start] ?? '') && /[\uD800-\uDBFF]/.test(text[start - 1]!)) start--;
+  let end = Math.min(text.length, start + budget);
+  if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1] ?? '')) end--;
+  return { text: text.slice(start, end), start, end, next: end < text.length ? end : null, found: true };
+}

package/src/tools/webfetch/webfetch.js

@@ -6,17 +6,18 @@
  *
  *  输入：
  *    url    必填，要获取内容的 URL
+ *    snapshot_id / offset / max_chars / query 用于稳定续读与搜索
  *    prompt 可选，旧版兼容字段，运行时忽略
  *
  *  输出：
- *    { bytes, code, codeText, result, durationMs, url }
+ *    完整快照引用、字符范围、下一段游标与本次正文窗口
  *
  *  流程：
  *    1. URL 验证（合法格式、2000字符以内、无凭据）
  *    2. fetch（保持 HTTP(S) 协议，超时 60s）
  *    3. 检测跨 host 重定向，返回提示而非自动跟随
  *    4. HTML → Markdown（turndown）；非 HTML 原样返回
- *    5. 输出截断到 30K chars（超长内容直接截断）
+ *    5. 完整正文保存为本机会话快照，按字符游标读取或搜索
  * ============================================================
  */
 import { z } from 'zod';
@@ -24,6 +25,7 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { isPreapprovedDomain } from './preapproved.js';
 import { readHttpBody } from '../shared/httpBody.js';
+import { loadPageSnapshot, savePageSnapshot, pageSnapshotPath, pageWindow } from './pageSnapshot.js';
 // ---------------- 1. 常量 ----------------
 const MAX_URL_LENGTH = 2000;
 const FETCH_TIMEOUT_MS = 60_000;
@@ -58,14 +60,16 @@ function cleanCache() {
 // ---------------- 3. Zod 输入 schema ----------------
 const inputSchema = z.object({
     url: z.string().describe('要获取内容的 URL'),
+    snapshot_id: z.string().regex(/^[a-f0-9]{64}$/).optional().describe('续读时使用上次返回的快照 ID，保证读取同一版本。'),
+    offset: z.number().int().nonnegative().optional().describe('0-based UTF-16 字符位置；使用 next_offset 续读，不是行号。'),
+    max_chars: z.number().int().min(1000).max(1_000_000).optional().describe('本次正文字符预算，Runtime 按剩余上下文收紧。'),
+    query: z.string().min(1).max(500).optional().describe('在完整快照中从 offset 开始查找精确文本（区分大小写，非正则），返回命中处正文。'),
     /** @deprecated Accepted for callers compiled against the legacy contract. */
     prompt: z.string().optional(),
 });
-// Model-visible v2 contract. WebFetch returns the page body and does not run a
+// Model-visible snapshot contract. WebFetch returns the page body and does not run a
 // hidden extraction model; the runtime schema still accepts legacy `prompt`.
-const parameters = toToolParameters(z.object({
-    url: z.string().describe('要读取正文的已知 URL'),
-}));
+const parameters = toToolParameters(inputSchema.omit({ prompt: true }));
 // ---------------- 4. Description ----------------
 const description = `Reads the full text content of a known URL without opening a browser.
 - Takes a URL, fetches its response body, and converts HTML to Markdown.
@@ -74,8 +78,11 @@ const description = `Reads the full text content of a known URL without opening
 - It does not discover sources, authenticate, click, upload, or operate an interactive page.
 - HTTP and HTTPS URLs are fetched as supplied, including local development servers.
 - When a URL redirects to a different host, returns a warning with the redirect URL.
-- This tool is read-only and does not modify any files.
-- Very large results may be truncated with an explicit marker.
+- Read-only with respect to the source/workspace; complete extracted text is saved in a private local runtime snapshot.
+- Results are windows, not the whole page. Continue with the same url + snapshot_id + next_offset until next_offset=null. Use query for exact-text search anywhere in the snapshot.
+- max_chars can request larger windows for large-context models; the runtime may reduce the per-call budget.
+- A complete snapshot means the fetched/extracted body, not authenticated or JavaScript-rendered content. Do not claim unread ranges were inspected.
+- Conversion failures return clearly labeled raw HTML. If dynamic content is missing, use available browser tools; do not repeat the same window or invent missing content.
 - ⚠️ IMPORTANT: This tool WILL FAIL for authenticated or private URLs.
   Do not claim access to private content when the current tool catalog does not
   contain an authenticated integration for that service.
@@ -192,123 +199,76 @@ async function htmlToMarkdown(html) {
     return td.turndown(html);
 }
 // ---------------- 6. call() 实现 ----------------
-async function call(input, signal) {
+async function call(input, signal, context = {}) {
     if (signal?.aborted)
         return { ok: false, error: '请求被中断' };
-    const { url } = input;
-    const start = Date.now();
-    const cacheKey = url;
-    let targetHostname;
+    const valid = validateURL(input.url);
+    if (!valid.ok)
+        return { ok: false, error: valid.error };
+    if ((input.offset ?? 0) > 0 && !input.snapshot_id)
+        return { ok: false, error: '续读需要 snapshot_id；先读取 URL 获取稳定快照，避免拼接不同版本。' };
+    const budget = context.reserveReadChars?.(input.max_chars) ?? input.max_chars ?? DEFAULT_MAX_RESULT_SIZE_CHARS;
+    if (budget < 1000)
+        return { ok: false, error: '本批读取预算已用完，请处理已有结果或压缩上下文后续读。' };
     try {
-        targetHostname = new URL(url).hostname;
-    }
-    catch {
-        targetHostname = '';
-    }
-    const preapproved = isPreapprovedDomain(targetHostname);
-    // 检查缓存
-    const cached = URL_CACHE.get(cacheKey);
-    if (cached && Date.now() - cached.fetchedAt <= CACHE_TTL_MS) {
-        let content = cached.content;
-        const contentType = cached.contentType;
-        if (contentType.includes('text/html')) {
-            try {
-                content = await htmlToMarkdown(content);
+        let page;
+        let status = '';
+        if (input.snapshot_id) {
+            page = await loadPageSnapshot(input.snapshot_id, input.url, context);
+        }
+        else {
+            const cached = URL_CACHE.get(input.url);
+            const hit = cached && Date.now() - cached.fetchedAt <= CACHE_TTL_MS;
+            const fetched = hit ? { type: 'success', ...cached } : await fetchURL(input.url, signal ?? new AbortController().signal);
+            if (fetched.type === 'error')
+                return { ok: false, error: fetched.error };
+            if (fetched.type === 'redirect')
+                return { ok: true, content: `【重定向检测】\n原始 URL: ${fetched.originalUrl}\n重定向到: ${fetched.redirectUrl}\n状态: ${fetched.statusCode}\n请使用重定向后的 URL 再次调用 WebFetch 工具。` };
+            const fetchedAt = hit ? cached.fetchedAt : Date.now();
+            if (!hit) {
+                URL_CACHE.set(input.url, { ...fetched, fetchedAt });
+                cleanCache();
             }
-            catch (e) {
-                console.warn(`turndown 失败: ${e.message}`);
+            let text = fetched.content;
+            let format = 'text';
+            if (fetched.contentType.includes('text/html')) {
+                try {
+                    text = await htmlToMarkdown(text);
+                    format = 'markdown';
+                }
+                catch {
+                    format = 'raw-html (正文转换失败，保留原始 HTML)';
+                }
             }
+            page = { url: input.url, text, format, fetchedAt };
+            status = `状态: ${fetched.code} ${fetched.codeText}${hit ? ' (缓存命中)' : ''}\n`;
         }
-        const formattedSize = cached.bytes < 1024
-            ? `${cached.bytes} B`
-            : cached.bytes < 1024 * 1024
-                ? `${(cached.bytes / 1024).toFixed(1)} KB`
-                : `${(cached.bytes / 1024 / 1024).toFixed(1)} MB`;
-        const domainNote = preapproved
+        signal?.throwIfAborted();
+        const snapshot = input.snapshot_id
+            ? { id: input.snapshot_id, path: pageSnapshotPath(input.snapshot_id, context) }
+            : await savePageSnapshot(page, context);
+        signal?.throwIfAborted();
+        const window = pageWindow(page.text, input.offset ?? 0, budget, input.query);
+        const domain = isPreapprovedDomain(valid.parsed.hostname)
             ? '[网络访问：预批准域名]'
             : '[网络访问：普通域名；请按来源本身评估证据质量]';
-        const output = `【WebFetch 结果】
-URL: ${url}
-状态: ${cached.code} ${cached.codeText}
-大小: ${formattedSize}
-耗时: 0.00s (缓存命中)
-${domainNote}
-[📦 来自缓存（15分钟 TTL）]
-
---- 内容 ---
-${content}`;
-        let final = output;
-        if (final.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-            final = final.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) + `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
-        }
-        return { ok: true, content: final };
-    }
-    // 1. fetch
-    const fetched = await fetchURL(url, signal ?? new AbortController().signal);
-    const durationMs = Date.now() - start;
-    if (fetched.type === 'redirect') {
-        const statusText = fetched.statusCode === 301 ? 'Moved Permanently' :
-            fetched.statusCode === 308 ? 'Permanent Redirect' :
-                fetched.statusCode === 307 ? 'Temporary Redirect' : 'Found';
-        return {
-            ok: true,
-            content: `【重定向检测】
-
-原始 URL: ${fetched.originalUrl}
-重定向到: ${fetched.redirectUrl}
-状态: ${fetched.statusCode} ${statusText}
-
-请使用重定向后的 URL 再次调用 WebFetch 工具。`,
-        };
-    }
-    if (fetched.type === 'error') {
-        return { ok: false, error: fetched.error };
-    }
-    let { content, bytes, code, codeText, contentType } = fetched;
-    // 写入缓存
-    URL_CACHE.set(cacheKey, {
-        bytes,
-        code,
-        codeText,
-        content,
-        contentType,
-        fetchedAt: Date.now(),
-    });
-    cleanCache();
-    // 2. HTML → Markdown
-    if (contentType.includes('text/html')) {
-        try {
-            content = await htmlToMarkdown(content);
-        }
-        catch (e) {
-            console.warn(`turndown 失败: ${e.message}`);
-        }
+        return { ok: true, policy: { highValue: true, reclaimable: false, boundedWindow: true,
+                archiveRef: snapshot.path, originalChars: page.text.length }, content: `【WebFetch 结果】
+URL: ${page.url}
+${status}${domain}
+snapshot_id: ${snapshot.id}
+snapshot_complete: true (完整抓取正文，不代表动态页面内容完整)
+format: ${page.format}
+total_chars: ${page.text.length}
+range: [${window.start}, ${window.end})
+next_offset: ${window.next ?? 'null'}
+完整正文文件: ${snapshot.path}
+${window.found ? '' : '未找到指定文本（精确匹配，区分大小写）。\n'}--- 内容 ---
+${window.text}` };
     }
-    // 3. 内容直接返回（超长内容在这里直接截断）
-    // 4. 追加 metadata
-    const formattedSize = bytes < 1024
-        ? `${bytes} B`
-        : bytes < 1024 * 1024
-            ? `${(bytes / 1024).toFixed(1)} KB`
-            : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-    const domainNote = preapproved
-        ? '[网络访问：预批准域名]'
-        : '[网络访问：普通域名；请按来源本身评估证据质量]';
-    const output = `【WebFetch 结果】
-URL: ${url}
-状态: ${code} ${codeText}
-大小: ${formattedSize}
-耗时: ${(durationMs / 1000).toFixed(2)}s
-${domainNote}
-
---- 内容 ---
-${content}`;
-    // 5. 截断
-    let final = output;
-    if (final.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-        final = final.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) + `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+    catch (error) {
+        return { ok: false, error: `网页快照读取失败：${error.message}。未返回不完整正文；请重试原 URL 或检查本地存储。` };
     }
-    return { ok: true, content: final };
 }
 // ---------------- 7. 导出 ----------------
 export const webfetchTool = {
@@ -318,7 +278,8 @@ export const webfetchTool = {
     parameters,
     isReadOnly: true,
     isConcurrencySafe: true,
-    maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    maxResultSizeChars: 1_010_000,
     interruptBehavior: () => 'cancel',
     call,
+    callWithContext: (input, signal, context) => call(input, signal, context),
 };

package/src/tools/webfetch/webfetch.ts

@@ -6,27 +6,29 @@
  *
  *  输入：
  *    url    必填，要获取内容的 URL
+ *    snapshot_id / offset / max_chars / query 用于稳定续读与搜索
  *    prompt 可选，旧版兼容字段，运行时忽略
  *
  *  输出：
- *    { bytes, code, codeText, result, durationMs, url }
+ *    完整快照引用、字符范围、下一段游标与本次正文窗口
  *
  *  流程：
  *    1. URL 验证（合法格式、2000字符以内、无凭据）
  *    2. fetch（保持 HTTP(S) 协议，超时 60s）
  *    3. 检测跨 host 重定向，返回提示而非自动跟随
  *    4. HTML → Markdown（turndown）；非 HTML 原样返回
- *    5. 输出截断到 30K chars（超长内容直接截断）
+ *    5. 完整正文保存为本机会话快照，按字符游标读取或搜索
  * ============================================================
  */
 
 import { z } from 'zod';
 
-import type { Tool, ToolResult } from '../../types.js';
+import type { Tool, ToolResult, ToolCallContext } from '../../types.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { isPreapprovedDomain } from './preapproved.js';
 import { readHttpBody } from '../shared/httpBody.js';
+import { loadPageSnapshot, savePageSnapshot, pageSnapshotPath, pageWindow, type PageSnapshot } from './pageSnapshot.js';
 
 // ---------------- 1. 常量 ----------------
 const MAX_URL_LENGTH = 2000;
@@ -76,16 +78,18 @@ function cleanCache(): void {
 // ---------------- 3. Zod 输入 schema ----------------
 const inputSchema = z.object({
   url: z.string().describe('要获取内容的 URL'),
+  snapshot_id: z.string().regex(/^[a-f0-9]{64}$/).optional().describe('续读时使用上次返回的快照 ID，保证读取同一版本。'),
+  offset: z.number().int().nonnegative().optional().describe('0-based UTF-16 字符位置；使用 next_offset 续读，不是行号。'),
+  max_chars: z.number().int().min(1000).max(1_000_000).optional().describe('本次正文字符预算，Runtime 按剩余上下文收紧。'),
+  query: z.string().min(1).max(500).optional().describe('在完整快照中从 offset 开始查找精确文本（区分大小写，非正则），返回命中处正文。'),
   /** @deprecated Accepted for callers compiled against the legacy contract. */
   prompt: z.string().optional(),
 });
 type WebFetchInput = z.infer<typeof inputSchema>;
 
-// Model-visible v2 contract. WebFetch returns the page body and does not run a
+// Model-visible snapshot contract. WebFetch returns the page body and does not run a
 // hidden extraction model; the runtime schema still accepts legacy `prompt`.
-const parameters = toToolParameters(z.object({
-  url: z.string().describe('要读取正文的已知 URL'),
-}));
+const parameters = toToolParameters(inputSchema.omit({ prompt: true }));
 
 // ---------------- 4. Description ----------------
 const description = `Reads the full text content of a known URL without opening a browser.
@@ -95,8 +99,11 @@ const description = `Reads the full text content of a known URL without opening
 - It does not discover sources, authenticate, click, upload, or operate an interactive page.
 - HTTP and HTTPS URLs are fetched as supplied, including local development servers.
 - When a URL redirects to a different host, returns a warning with the redirect URL.
-- This tool is read-only and does not modify any files.
-- Very large results may be truncated with an explicit marker.
+- Read-only with respect to the source/workspace; complete extracted text is saved in a private local runtime snapshot.
+- Results are windows, not the whole page. Continue with the same url + snapshot_id + next_offset until next_offset=null. Use query for exact-text search anywhere in the snapshot.
+- max_chars can request larger windows for large-context models; the runtime may reduce the per-call budget.
+- A complete snapshot means the fetched/extracted body, not authenticated or JavaScript-rendered content. Do not claim unread ranges were inspected.
+- Conversion failures return clearly labeled raw HTML. If dynamic content is missing, use available browser tools; do not repeat the same window or invent missing content.
 - ⚠️ IMPORTANT: This tool WILL FAIL for authenticated or private URLs.
   Do not claim access to private content when the current tool catalog does not
   contain an authenticated integration for that service.
@@ -234,140 +241,66 @@ async function htmlToMarkdown(html: string): Promise<string> {
 async function call(
   input: WebFetchInput,
   signal?: AbortSignal,
+  context: ToolCallContext = {},
 ): Promise<ToolResult> {
   if (signal?.aborted) return { ok: false, error: '请求被中断' };
-  const { url } = input;
-  const start = Date.now();
-  const cacheKey = url;
-
-  let targetHostname: string;
+  const valid = validateURL(input.url);
+  if (!valid.ok) return { ok: false, error: valid.error };
+  if ((input.offset ?? 0) > 0 && !input.snapshot_id)
+    return { ok: false, error: '续读需要 snapshot_id；先读取 URL 获取稳定快照，避免拼接不同版本。' };
+  const budget = context.reserveReadChars?.(input.max_chars) ?? input.max_chars ?? DEFAULT_MAX_RESULT_SIZE_CHARS;
+  if (budget < 1000) return { ok: false, error: '本批读取预算已用完，请处理已有结果或压缩上下文后续读。' };
   try {
-    targetHostname = new URL(url).hostname;
-  } catch {
-    targetHostname = '';
-  }
-  const preapproved = isPreapprovedDomain(targetHostname);
-
-  // 检查缓存
-  const cached = URL_CACHE.get(cacheKey);
-  if (cached && Date.now() - cached.fetchedAt <= CACHE_TTL_MS) {
-    let content = cached.content;
-    const contentType = cached.contentType;
-
-    if (contentType.includes('text/html')) {
-      try {
-        content = await htmlToMarkdown(content);
-      } catch (e) {
-        console.warn(`turndown 失败: ${(e as Error).message}`);
+    let page: PageSnapshot;
+    let status = '';
+    if (input.snapshot_id) {
+      page = await loadPageSnapshot(input.snapshot_id, input.url, context);
+    } else {
+      const cached = URL_CACHE.get(input.url);
+      const hit = cached && Date.now() - cached.fetchedAt <= CACHE_TTL_MS;
+      const fetched = hit ? { type: 'success' as const, ...cached } : await fetchURL(input.url, signal ?? new AbortController().signal);
+      if (fetched.type === 'error') return { ok: false, error: fetched.error };
+      if (fetched.type === 'redirect') return { ok: true, content:
+        `【重定向检测】\n原始 URL: ${fetched.originalUrl}\n重定向到: ${fetched.redirectUrl}\n状态: ${fetched.statusCode}\n请使用重定向后的 URL 再次调用 WebFetch 工具。` };
+      const fetchedAt = hit ? cached.fetchedAt : Date.now();
+      if (!hit) {
+        URL_CACHE.set(input.url, { ...fetched, fetchedAt });
+        cleanCache();
       }
+      let text = fetched.content;
+      let format = 'text';
+      if (fetched.contentType.includes('text/html')) {
+        try { text = await htmlToMarkdown(text); format = 'markdown'; }
+        catch { format = 'raw-html (正文转换失败，保留原始 HTML)'; }
+      }
+      page = { url: input.url, text, format, fetchedAt };
+      status = `状态: ${fetched.code} ${fetched.codeText}${hit ? ' (缓存命中)' : ''}\n`;
     }
-
-    const formattedSize = cached.bytes < 1024
-      ? `${cached.bytes} B`
-      : cached.bytes < 1024 * 1024
-        ? `${(cached.bytes / 1024).toFixed(1)} KB`
-        : `${(cached.bytes / 1024 / 1024).toFixed(1)} MB`;
-
-    const domainNote = preapproved
+    signal?.throwIfAborted();
+    const snapshot = input.snapshot_id
+      ? { id: input.snapshot_id, path: pageSnapshotPath(input.snapshot_id, context) }
+      : await savePageSnapshot(page, context);
+    signal?.throwIfAborted();
+    const window = pageWindow(page.text, input.offset ?? 0, budget, input.query);
+    const domain = isPreapprovedDomain(valid.parsed.hostname)
       ? '[网络访问：预批准域名]'
       : '[网络访问：普通域名；请按来源本身评估证据质量]';
-
-    const output = `【WebFetch 结果】
-URL: ${url}
-状态: ${cached.code} ${cached.codeText}
-大小: ${formattedSize}
-耗时: 0.00s (缓存命中)
-${domainNote}
-[📦 来自缓存（15分钟 TTL）]
-
---- 内容 ---
-${content}`;
-
-    let final = output;
-    if (final.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-      final = final.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) + `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
-    }
-
-    return { ok: true, content: final };
+    return { ok: true, policy: { highValue: true, reclaimable: false, boundedWindow: true,
+      archiveRef: snapshot.path, originalChars: page.text.length }, content: `【WebFetch 结果】
+URL: ${page.url}
+${status}${domain}
+snapshot_id: ${snapshot.id}
+snapshot_complete: true (完整抓取正文，不代表动态页面内容完整)
+format: ${page.format}
+total_chars: ${page.text.length}
+range: [${window.start}, ${window.end})
+next_offset: ${window.next ?? 'null'}
+完整正文文件: ${snapshot.path}
+${window.found ? '' : '未找到指定文本（精确匹配，区分大小写）。\n'}--- 内容 ---
+${window.text}` };
+  } catch (error) {
+    return { ok: false, error: `网页快照读取失败：${(error as Error).message}。未返回不完整正文；请重试原 URL 或检查本地存储。` };
   }
-
-  // 1. fetch
-  const fetched = await fetchURL(url, signal ?? new AbortController().signal);
-  const durationMs = Date.now() - start;
-
-  if (fetched.type === 'redirect') {
-    const statusText =
-      fetched.statusCode === 301 ? 'Moved Permanently' :
-      fetched.statusCode === 308 ? 'Permanent Redirect' :
-      fetched.statusCode === 307 ? 'Temporary Redirect' : 'Found';
-
-    return {
-      ok: true,
-      content: `【重定向检测】
-
-原始 URL: ${fetched.originalUrl}
-重定向到: ${fetched.redirectUrl}
-状态: ${fetched.statusCode} ${statusText}
-
-请使用重定向后的 URL 再次调用 WebFetch 工具。`,
-    };
-  }
-
-  if (fetched.type === 'error') {
-    return { ok: false, error: fetched.error };
-  }
-
-  let { content, bytes, code, codeText, contentType } = fetched;
-
-  // 写入缓存
-  URL_CACHE.set(cacheKey, {
-    bytes,
-    code,
-    codeText,
-    content,
-    contentType,
-    fetchedAt: Date.now(),
-  });
-  cleanCache();
-
-  // 2. HTML → Markdown
-  if (contentType.includes('text/html')) {
-    try {
-      content = await htmlToMarkdown(content);
-    } catch (e) {
-      console.warn(`turndown 失败: ${(e as Error).message}`);
-    }
-  }
-
-  // 3. 内容直接返回（超长内容在这里直接截断）
-  // 4. 追加 metadata
-  const formattedSize = bytes < 1024
-    ? `${bytes} B`
-    : bytes < 1024 * 1024
-      ? `${(bytes / 1024).toFixed(1)} KB`
-      : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-
-  const domainNote = preapproved
-    ? '[网络访问：预批准域名]'
-    : '[网络访问：普通域名；请按来源本身评估证据质量]';
-
-  const output = `【WebFetch 结果】
-URL: ${url}
-状态: ${code} ${codeText}
-大小: ${formattedSize}
-耗时: ${(durationMs / 1000).toFixed(2)}s
-${domainNote}
-
---- 内容 ---
-${content}`;
-
-  // 5. 截断
-  let final = output;
-  if (final.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-    final = final.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) + `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
-  }
-
-  return { ok: true, content: final };
 }
 
 // ---------------- 7. 导出 ----------------
@@ -378,7 +311,8 @@ export const webfetchTool: Tool<WebFetchInput> = {
   parameters,
   isReadOnly: true,
   isConcurrencySafe: true,
-  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  maxResultSizeChars: 1_010_000,
   interruptBehavior: () => 'cancel',
   call,
+  callWithContext: (input, signal, context) => call(input, signal, context),
 };

package/src/types.ts

@@ -480,6 +480,9 @@ export type ToolResultMetadata =
 export interface ToolResultPolicy {
   reclaimable: boolean;
   highValue: boolean;
+  /** Tool already budgeted a window backed by a complete local snapshot.
+   * Keep this window inline: re-archiving would invalidate its visible cursor. */
+  boundedWindow?: boolean;
   archiveRef?: string;
   originalChars?: number;
 }