@tachu/extensions 1.0.0-alpha.1

package/dist/tools/search-code/descriptor.md

@@ -0,0 +1,31 @@
+---
+kind: tool
+name: search-code
+description: 在工作区内按模式搜索代码
+sideEffect: readonly
+idempotent: true
+requiresApproval: false
+timeout: 10000
+inputSchema:
+  type: object
+  properties:
+    pattern:
+      type: string
+    path:
+      type: string
+    fileGlob:
+      type: string
+    maxResults:
+      type: number
+    caseSensitive:
+      type: boolean
+  required: [pattern]
+outputSchema:
+  type: object
+  properties:
+    matches:
+      type: array
+execute: search-code
+---
+
+优先使用 ripgrep 搜索；若系统不存在 rg，则回退到 JS 递归搜索。

package/dist/tools/search-code/executor.d.ts

@@ -0,0 +1,23 @@
+import type { ToolExecutor } from "../shared";
+interface SearchCodeInput {
+    pattern: string;
+    path?: string;
+    fileGlob?: string;
+    maxResults?: number;
+    caseSensitive?: boolean;
+}
+interface SearchCodeMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+interface SearchCodeOutput {
+    matches: SearchCodeMatch[];
+    truncated: boolean;
+}
+/**
+ * 搜索代码 Tool 执行器。
+ */
+export declare const searchCodeExecutor: ToolExecutor<SearchCodeInput, SearchCodeOutput>;
+export {};
+//# sourceMappingURL=executor.d.ts.map

package/dist/tools/search-code/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/tools/search-code/executor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAI9C,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,gBAAgB;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;CACpB;AA0BD;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,YAAY,CAAC,eAAe,EAAE,gBAAgB,CAkG9E,CAAC"}

package/dist/tools/search-code/executor.js

@@ -0,0 +1,122 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { assertNotAborted, resolveSandboxPolicy } from "../shared";
+import { resolveAllowedPath, toWorkspaceRelativePath } from "../../common/path";
+const parseRgOutput = (output, maxResults) => {
+    const matches = [];
+    const lines = output.split("\n").filter((line) => line.length > 0);
+    for (const line of lines) {
+        const first = line.indexOf(":");
+        const second = first >= 0 ? line.indexOf(":", first + 1) : -1;
+        if (first <= 0 || second <= first + 1) {
+            continue;
+        }
+        matches.push({
+            file: line.slice(0, first),
+            line: Number(line.slice(first + 1, second)),
+            text: line.slice(second + 1),
+        });
+        if (matches.length >= maxResults) {
+            return { matches, truncated: true };
+        }
+    }
+    return { matches, truncated: false };
+};
+/**
+ * 搜索代码 Tool 执行器。
+ */
+export const searchCodeExecutor = async (input, context) => {
+    assertNotAborted(context.abortSignal);
+    const root = resolveAllowedPath(input.path ?? ".", resolveSandboxPolicy(context));
+    const maxResults = input.maxResults ?? 100;
+    try {
+        const args = [
+            "--line-number",
+            "--no-heading",
+            "--color",
+            "never",
+            input.caseSensitive ? "--case-sensitive" : "--ignore-case",
+            "--max-count",
+            String(maxResults),
+        ];
+        if (input.fileGlob) {
+            args.push("--glob", input.fileGlob);
+        }
+        args.push(input.pattern, root);
+        const process = Bun.spawn({
+            cmd: ["rg", ...args],
+            stdout: "pipe",
+            stderr: "pipe",
+            cwd: root,
+        });
+        const [stdout, stderr] = await Promise.all([
+            new Response(process.stdout).text(),
+            new Response(process.stderr).text(),
+        ]);
+        const code = await process.exited;
+        if (code !== 0 && code !== 1) {
+            throw new Error(stderr || `rg exited with code ${code}`);
+        }
+        const parsed = parseRgOutput(stdout, maxResults);
+        return {
+            matches: parsed.matches.map((item) => ({
+                ...item,
+                file: toWorkspaceRelativePath(context.workspaceRoot, join(root, item.file)),
+            })),
+            truncated: parsed.truncated,
+        };
+    }
+    catch {
+        const matcher = new RegExp(input.pattern, input.caseSensitive ? "g" : "gi");
+        const matches = [];
+        let truncated = false;
+        const walk = async (dir) => {
+            // D1-LOW-10：进入新目录前先检查取消，避免在大型仓库里无休止递归。
+            assertNotAborted(context.abortSignal);
+            const children = await readdir(dir, { withFileTypes: true });
+            for (const child of children) {
+                // 每个子条目都做一次取消检查，粒度足够细而开销极低。
+                assertNotAborted(context.abortSignal);
+                if (matches.length >= maxResults) {
+                    truncated = true;
+                    return;
+                }
+                const target = join(dir, child.name);
+                if (child.isDirectory()) {
+                    await walk(target);
+                    continue;
+                }
+                if (!child.isFile()) {
+                    continue;
+                }
+                if (input.fileGlob && !target.endsWith(input.fileGlob.replace("*", ""))) {
+                    continue;
+                }
+                const content = await readFile(target, "utf8").catch(() => "");
+                const lines = content.split("\n");
+                for (let index = 0; index < lines.length; index += 1) {
+                    // 大文件按行遍历时同样做细粒度取消检查。
+                    if (index % 256 === 0) {
+                        assertNotAborted(context.abortSignal);
+                    }
+                    if (matches.length >= maxResults) {
+                        truncated = true;
+                        break;
+                    }
+                    const line = lines[index] ?? "";
+                    if (matcher.test(line)) {
+                        matches.push({
+                            file: toWorkspaceRelativePath(context.workspaceRoot, target),
+                            line: index + 1,
+                            text: line,
+                        });
+                    }
+                    matcher.lastIndex = 0;
+                }
+            }
+        };
+        await walk(root);
+        return { matches, truncated };
+    }
+};
+//# sourceMappingURL=executor.js.map

package/dist/tools/search-code/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/tools/search-code/executor.ts"],"names":[],"mappings":"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"}

package/dist/tools/shared.d.ts

@@ -0,0 +1,47 @@
+import type { Session } from "@tachu/core";
+/**
+ * Tool 执行时上下文。
+ *
+ * 字段语义：
+ *   - `workspaceRoot`：工作区根目录（绝对路径）。向后兼容保留，路径校验不再
+ *     直接依赖它，而是以 {@link allowedRoots} 为准。
+ *   - `allowedRoots`：允许读写的根目录列表；由宿主在 engine-factory 层组装，
+ *     通常包含 `workspaceRoot`、平台临时目录（`os.tmpdir()`），以及用户通过
+ *     `safety.allowedWriteRoots` 配置扩展的路径。长度 ≥ 1。
+ *   - `sandboxWaived`：本次调用是否豁免沙箱（审批已通过）。见
+ *     `@tachu/core` 的 `TaskNode.metadata.approvalGranted`：宿主在审批通过后
+ *     把它翻译成这里的布尔值。
+ *   - `session`：当前会话引用。
+ *
+ * 兼容性：历史代码读 `workspaceRoot` 仍然可用；新代码请走 {@link resolveAllowedPath}
+ * + `allowedRoots` + `sandboxWaived` 三件套。
+ */
+export interface ToolExecutionContext {
+    abortSignal: AbortSignal;
+    workspaceRoot: string;
+    allowedRoots?: readonly string[];
+    sandboxWaived?: boolean;
+    session: Session;
+}
+/**
+ * Tool 执行器签名。
+ */
+export type ToolExecutor<TInput = unknown, TOutput = unknown> = (input: TInput, context: ToolExecutionContext) => Promise<TOutput>;
+/**
+ * 检查中断状态。
+ *
+ * @param signal 取消信号
+ * @throws Error 当已中断
+ */
+export declare const assertNotAborted: (signal: AbortSignal) => void;
+/**
+ * 从 `ToolExecutionContext` 推导出本次工具调用的沙箱策略。
+ *
+ * 老版本 context 只有 `workspaceRoot`；本函数做一次规范化，让工具执行器
+ * 不必关心调用方是否已经迁移到新字段。
+ */
+export declare const resolveSandboxPolicy: (context: ToolExecutionContext) => {
+    allowedRoots: readonly string[];
+    sandboxWaived: boolean;
+};
+//# sourceMappingURL=shared.d.ts.map

package/dist/tools/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAC9D,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,WAAW,KAAG,IAItD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,SAAS,oBAAoB,KAC5B;IAAE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAQ3D,CAAC"}

package/dist/tools/shared.js

@@ -0,0 +1,27 @@
+/**
+ * 检查中断状态。
+ *
+ * @param signal 取消信号
+ * @throws Error 当已中断
+ */
+export const assertNotAborted = (signal) => {
+    if (signal.aborted) {
+        throw signal.reason ?? new Error("aborted");
+    }
+};
+/**
+ * 从 `ToolExecutionContext` 推导出本次工具调用的沙箱策略。
+ *
+ * 老版本 context 只有 `workspaceRoot`；本函数做一次规范化，让工具执行器
+ * 不必关心调用方是否已经迁移到新字段。
+ */
+export const resolveSandboxPolicy = (context) => {
+    const roots = context.allowedRoots && context.allowedRoots.length > 0
+        ? context.allowedRoots
+        : [context.workspaceRoot];
+    return {
+        allowedRoots: roots,
+        sandboxWaived: context.sandboxWaived === true,
+    };
+};
+//# sourceMappingURL=shared.js.map

package/dist/tools/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAmCA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAmB,EAAQ,EAAE;IAC5D,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,OAA6B,EACgC,EAAE;IAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;QACnE,CAAC,CAAC,OAAO,CAAC,YAAY;QACtB,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,OAAO;QACL,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,OAAO,CAAC,aAAa,KAAK,IAAI;KAC9C,CAAC;AACJ,CAAC,CAAC"}

package/dist/tools/web-fetch/descriptor.md

@@ -0,0 +1,198 @@
+---
+kind: tool
+id: web-fetch
+name: web-fetch
+version: "0.1.0"
+category: "web"
+dangerous: true
+description: |
+  通过 @tachu/web-fetch-server 远程渲染并结构化抓取 URL：服务端以 Bun.fetch（静态）或 Playwright（浏览器）拉取页面，经 Readability/Turndown 等管线输出标题、正文与可选链接/图片/JSON-LD；`renderMode` 为 auto 时可在静态不足时自动升级到浏览器重试一次。
+sideEffect: readonly
+idempotent: false
+requiresApproval: true
+timeout: 120000
+inputSchema:
+  type: object
+  properties:
+    url:
+      type: string
+      description: 目标 http(s) URL（协议层唯一必填；将发往服务端并由 SSRF 规则校验）
+    renderMode:
+      type: string
+      enum: [static, browser, auto]
+      description: 渲染模式；默认 auto（先 static，不满足条件时浏览器重试一次）
+    waitFor:
+      description: |
+        仅 browser 模式：等待策略。可为 load / domcontentloaded / networkidle，
+        或 { "selector": "<css>" } 等待元素可见，或 { "timeMs": <number> } 固定等待。
+      oneOf:
+        - type: string
+          enum: [load, domcontentloaded, networkidle]
+        - type: object
+          required: [selector]
+          properties:
+            selector:
+              type: string
+        - type: object
+          required: [timeMs]
+          properties:
+            timeMs:
+              type: number
+    waitTimeoutMs:
+      type: number
+      description: 渲染等待超时（毫秒）；默认 15000，硬上限 60000
+    scroll:
+      description: |
+        仅 browser：是否滚动以触发懒加载。false | true |
+        { "steps": number, "delayMs": number }
+      oneOf:
+        - type: boolean
+        - type: object
+          required: [steps, delayMs]
+          properties:
+            steps:
+              type: number
+            delayMs:
+              type: number
+    userAgent:
+      type: string
+      description: 覆盖 User-Agent；请求中可省略或显式传 null 以使用服务端 UA 池
+    extraHeaders:
+      type: object
+      additionalProperties:
+        type: string
+      description: 额外 HTTP 头；静态模式直传；浏览器模式作为 route 注入
+    cookies:
+      type: array
+      description: 注入 Cookie 列表（仅 browser 模式生效；元素形状由服务端解析）
+      items:
+        type: object
+        additionalProperties: true
+    blockResources:
+      type: array
+      description: |
+        仅 browser：资源拦截类型。未传时服务端默认 ["image","font","media"]；传 [] 表示不拦截。
+      items:
+        type: string
+        enum: [image, font, media, stylesheet, other]
+    stealth:
+      type: boolean
+      description: 可省略或传 null 继承服务级；传 true/false 为请求级覆盖
+    outputFormat:
+      type: string
+      enum: [markdown, text, html, structured]
+      description: 正文形态；markdown 为默认 GFM
+    includeLinks:
+      type: boolean
+      description: 是否在输出中包含 links[]
+    includeImages:
+      type: boolean
+      description: 是否在输出中包含 images[]
+    includeStructured:
+      type: boolean
+      description: 是否包含 JSON-LD structured 字段
+    maxBodyChars:
+      type: number
+      description: body 字符上限；默认 32768，硬上限 524288
+    traceId:
+      type: string
+      description: 可选追踪 ID；省略或 null 时由服务端生成
+  required: [url]
+outputSchema:
+  type: object
+  description: 对应 POST /v1/extract 200 响应（字段随选项省略）
+  properties:
+    url:
+      type: string
+    finalUrl:
+      type: string
+    status:
+      type: number
+    renderedWith:
+      type: string
+      enum: [static, browser]
+    renderedAtMs:
+      type: number
+    title:
+      type: string
+    description:
+      type: string
+    siteName:
+      type: string
+    lang:
+      type: string
+    byline:
+      type: string
+    publishedTime:
+      type: string
+    body:
+      type: string
+    wordCount:
+      type: number
+    truncated:
+      type: boolean
+    links:
+      type: array
+    images:
+      type: array
+    structured:
+      type: object
+      additionalProperties: true
+    warnings:
+      type: array
+      items:
+        type: string
+    traceId:
+      type: string
+execute: web-fetch
+---
+
+## 常用字段说明
+
+协议上仅 **`url`** 必填。实际调用中常与其他字段组合使用，例如：
+
+- **`renderMode`**：静态站用 `static` 省资源，强 JS 页用 `browser` 或默认 `auto`
+- **`outputFormat`**：需要 Markdown 摘要时用 `markdown`（默认），只要纯文本用 `text`
+- **`waitTimeoutMs` / `waitFor`**：浏览器渲染时的超时与就绪条件
+- **`maxBodyChars`**：控制返回给模型的正文长度，避免上下文爆炸
+- **`includeLinks` / `includeImages` / `includeStructured`**：按需打开结构化附属字段
+
+## 输出结构示例（200 成功，节选）
+
+```json
+{
+  "url": "https://example.com/article",
+  "finalUrl": "https://example.com/article",
+  "status": 200,
+  "renderedWith": "browser",
+  "renderedAtMs": 234,
+  "title": "示例文章",
+  "description": "页面 meta 描述",
+  "siteName": "Example",
+  "lang": "zh",
+  "byline": null,
+  "publishedTime": "2026-04-20T00:00:00.000Z",
+  "body": "# 示例文章\n\n正文 Markdown …",
+  "wordCount": 1234,
+  "truncated": false,
+  "links": [{ "text": "下一页", "href": "https://example.com/next" }],
+  "images": [],
+  "structured": null,
+  "warnings": [],
+  "traceId": "req_01HY..."
+}
+```
+
+## 安全提示
+
+1. **客户端须配置 Web Fetch Server 的 endpoint 与鉴权**：工具通过 HTTP 调用服务端；需正确设置服务地址与 `Authorization: Bearer <token>` 所用 token（与部署环境一致）。未配置 token 时服务端仅允许绑定本机回环，运维需按环境变量与网络策略部署。
+2. **URL 会经服务端 SSRF 校验**：私网、元数据地址、黑名单域名等会被拒绝（如 `SSRF_BLOCKED` / `DOMAIN_NOT_ALLOWED`）；请勿将本工具用于探测内网。
+3. **robots.txt 与爬取礼仪**：是否遵守 robots 及额外策略由 **服务端实现与配置** 决定，本工具不在客户端重复裁决。
+
+## 与 `fetch-url` 的区别
+
+| 维度 | `web-fetch` | `fetch-url` |
+| --- | --- | --- |
+| 数据形态 | 结构化正文（标题、Markdown/文本/HTML、可选链接与 JSON-LD） | 原始响应体 + 简单 HTML 清洗 |
+| 依赖 | 需要可用的 `@tachu/web-fetch-server` | 仅需受控直连，无需独立 fetch 服务 |
+| 渲染 | 支持静态与浏览器渲染管线 | 单次 HTTP，无浏览器渲染 |

package/dist/tools/web-fetch/errors.d.ts

@@ -0,0 +1,32 @@
+import type { ErrorResponseBody, WebFetchErrorCode } from "./types";
+/**
+ * 客户端在解析失败或网络层错误时使用的扩展码（契约 §3 行为要求；不在纯 HTTP 错误体中出现）。
+ */
+export type WebFetchClientOnlyErrorCode = "MALFORMED_RESPONSE" | "NETWORK_ERROR";
+export type WebFetchClientErrorCode = WebFetchErrorCode | WebFetchClientOnlyErrorCode;
+/**
+ * `web-fetch` / `web-search` 工具在客户端抛出的统一错误类型。
+ *
+ * @see docs/adr/decisions/0003d-web-fetch-errors.md §4
+ */
+export declare class WebFetchClientError extends Error {
+    readonly code: WebFetchClientErrorCode;
+    readonly userMessage: string;
+    readonly detail?: unknown | undefined;
+    readonly name = "WebFetchClientError";
+    constructor(code: WebFetchClientErrorCode, userMessage: string, detail?: unknown | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 将服务端错误响应映射为 {@link WebFetchClientError}。
+ *
+ * @see docs/adr/decisions/0003d-web-fetch-errors.md §4.2
+ */
+export declare function mapServerErrorToClient(httpStatus: number, body: ErrorResponseBody | null, ctx: {
+    endpoint: string;
+}): WebFetchClientError;
+export declare function getMalformedResponseError(): WebFetchClientError;
+export declare function getNetworkError(endpoint: string, originalError: unknown): WebFetchClientError;
+export declare function getTimeoutError(timeoutMs: number): WebFetchClientError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/tools/web-fetch/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/tools/web-fetch/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAEjF,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,2BAA2B,CAAC;AAEtF;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAI1B,IAAI,EAAE,uBAAuB;aAC7B,WAAW,EAAE,MAAM;aACnB,MAAM,CAAC,EAAE,OAAO;IALlC,QAAQ,CAAC,IAAI,yBAAyB;gBAGpB,IAAI,EAAE,uBAAuB,EAC7B,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,OAAO,YAAA,EAChC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC;AAkDD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,iBAAiB,GAAG,IAAI,EAC9B,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxB,mBAAmB,CAUrB;AAED,wBAAgB,yBAAyB,IAAI,mBAAmB,CAM/D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,mBAAmB,CAO7F;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAMtE"}

package/dist/tools/web-fetch/errors.js

@@ -0,0 +1,91 @@
+/**
+ * `web-fetch` / `web-search` 工具在客户端抛出的统一错误类型。
+ *
+ * @see docs/adr/decisions/0003d-web-fetch-errors.md §4
+ */
+export class WebFetchClientError extends Error {
+    code;
+    userMessage;
+    detail;
+    name = "WebFetchClientError";
+    constructor(code, userMessage, detail, options) {
+        super(userMessage, options);
+        this.code = code;
+        this.userMessage = userMessage;
+        this.detail = detail;
+    }
+}
+/** @see docs/adr/decisions/0003d-web-fetch-errors.md §5 */
+const HTTP_STATUS_TO_CODE = {
+    400: "INVALID_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "INVALID_REQUEST",
+    408: "REQUEST_TIMEOUT",
+    413: "REQUEST_TOO_LARGE",
+    422: "RENDER_FAILED",
+    429: "RATE_LIMITED",
+    500: "INTERNAL_ERROR",
+    502: "UPSTREAM_ERROR",
+    503: "BROWSER_POOL_EXHAUSTED",
+    504: "PROVIDER_TIMEOUT",
+};
+function inferCodeFromStatus(httpStatus) {
+    return HTTP_STATUS_TO_CODE[httpStatus] ?? "INTERNAL_ERROR";
+}
+const USER_MESSAGE_ZH = {
+    INVALID_REQUEST: "请求格式无效。请检查参数后重试。",
+    INVALID_URL: "URL 无效。请使用合法的 http/https 地址。",
+    UNAUTHORIZED: "鉴权失败。请检查 Web Fetch 服务的访问令牌配置。",
+    FORBIDDEN: "访问被拒绝。请确认令牌与权限配置是否正确。",
+    SSRF_BLOCKED: "出于安全策略，无法访问该地址。请仅使用允许的公网 URL。",
+    DOMAIN_NOT_ALLOWED: "域名不在允许列表中。请调整白名单或更换 URL。",
+    REQUEST_TIMEOUT: "请求处理超时。请稍后重试，或尝试缩短等待时间。",
+    REQUEST_TOO_LARGE: "请求体过大。请减小提交内容后重试。",
+    RESPONSE_TOO_LARGE: "目标页面响应过大。请尝试降低正文长度上限或更换页面。",
+    RENDER_FAILED: "页面渲染失败。可尝试更换渲染模式或稍后重试。",
+    RATE_LIMITED: "触发限流。请稍后再试或降低请求频率。",
+    INTERNAL_ERROR: "服务端出现内部错误。请稍后重试或联系管理员。",
+    UPSTREAM_ERROR: "上游站点返回异常。请稍后重试。",
+    BROWSER_POOL_EXHAUSTED: "浏览器资源繁忙。请降低并发或稍后重试。",
+    BROWSER_CRASHED: "浏览器进程异常。请立即重试，通常可以恢复。",
+    PROVIDER_NOT_CONFIGURED: "搜索提供方未配置。请检查搜索相关环境变量。",
+    PROVIDER_UPSTREAM_ERROR: "搜索提供方返回异常。请稍后重试。",
+    PROVIDER_TIMEOUT: "搜索提供方调用超时。请稍后重试。",
+    TIMEOUT_WEB_FETCH: "网页抓取超时。请缩短正文长度上限或更换 URL 后重试。",
+    TIMEOUT_WEB_SEARCH: "搜索超时。请缩短查询或减少抓取条数后重试。",
+    WEB_FETCH_SERVER_UNREACHABLE: "渲染服务不可达。请检查网络或服务端状态。",
+    WEB_FETCH_ENDPOINT_NOT_CONFIGURED: "未能连接到 Web Fetch 服务。请先启动渲染服务，或通过 TACHU_WEB_FETCH_ENDPOINT 配置远端地址。",
+    MALFORMED_RESPONSE: "服务返回了无法解析的响应。请检查服务端版本或稍后重试。",
+    NETWORK_ERROR: "网络请求失败。请检查网络连接与服务是否可用。",
+};
+/**
+ * 将服务端错误响应映射为 {@link WebFetchClientError}。
+ *
+ * @see docs/adr/decisions/0003d-web-fetch-errors.md §4.2
+ */
+export function mapServerErrorToClient(httpStatus, body, ctx) {
+    const code = body?.error.code ?? inferCodeFromStatus(httpStatus);
+    const userMessage = USER_MESSAGE_ZH[code] ?? body?.error.message ?? USER_MESSAGE_ZH.INTERNAL_ERROR;
+    const detail = {
+        ...(body?.error.detail ?? {}),
+        httpStatus,
+        endpoint: ctx.endpoint,
+        requestId: body?.error.requestId,
+    };
+    return new WebFetchClientError(code, userMessage, detail);
+}
+export function getMalformedResponseError() {
+    return new WebFetchClientError("MALFORMED_RESPONSE", USER_MESSAGE_ZH.MALFORMED_RESPONSE, undefined);
+}
+export function getNetworkError(endpoint, originalError) {
+    const original = originalError instanceof Error ? originalError.message : String(originalError);
+    return new WebFetchClientError("NETWORK_ERROR", USER_MESSAGE_ZH.NETWORK_ERROR, {
+        endpoint,
+        originalError: original,
+    }, { cause: originalError instanceof Error ? originalError : undefined });
+}
+export function getTimeoutError(timeoutMs) {
+    return new WebFetchClientError("REQUEST_TIMEOUT", USER_MESSAGE_ZH.REQUEST_TIMEOUT, { timeoutMs, phase: "fetch" });
+}
+//# sourceMappingURL=errors.js.map

package/dist/tools/web-fetch/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/tools/web-fetch/errors.ts"],"names":[],"mappings":"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"}

package/dist/tools/web-fetch/executor.d.ts

@@ -0,0 +1,10 @@
+import type { WebFetchToolInput, WebFetchToolOutput } from "./types";
+import type { ToolExecutionContext } from "../shared";
+/**
+ * 调用 Web Fetch Server `/v1/extract`，返回正文与元数据。
+ *
+ * @see docs/adr/decisions/0003c-web-fetch-config.md §5.1
+ * @see docs/adr/decisions/0003d-web-fetch-errors.md §4
+ */
+export declare function executeWebFetch(input: WebFetchToolInput, ctx: ToolExecutionContext): Promise<WebFetchToolOutput>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/tools/web-fetch/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/tools/web-fetch/executor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAsD,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACzH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAuHtD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,iBAAiB,EACxB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAmD7B"}