zapmyco 0.2.1 → 0.3.0

package/dist/cli/index.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { E as __VERSION__, T as APP_NAME, h as createLlmBasedAgent, o as logger, t as loadConfig, w as eventBus } from "../loader-BVZ993Oq.mjs";
+import { D as __VERSION__, E as APP_NAME, T as eventBus, f as WebError, g as createLlmBasedAgent, m as ZapmycoErrorCode, o as logger, t as loadConfig } from "../loader-BNgN6Pz5.mjs";
 import chalk, { Chalk } from "chalk";
 import { Command } from "commander";
 import { getModel } from "@mariozechner/pi-ai";
-import { Container, Editor, Key, ProcessTerminal, TUI, Text, matchesKey, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import { Container, Editor, Key, ProcessTerminal, TUI, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import TurndownService from "turndown";
+import { lookup } from "node:dns/promises";
 
 //#region src/cli/repl/command-registry.ts
 const log$1 = logger.child("repl:command-registry");
@@ -309,7 +311,34 @@ function createStatusCommand() {
 * - Ctrl+C: 取消任务 / 二次退出
 * - Ctrl+D: 退出
 * - Escape: 取消当前输入
+*
+* 同时 override render() 以：
+* - 去掉 Editor 默认的上下边框（───）
+* - 添加简洁的输入提示符（❯ ）
+* - 执行中时显示 loading spinner
 */
+/** 输入提示符 */
+const PROMPT_PREFIX = "❯ ";
+/** loading 动画帧 */
+const LOADING_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/** ANSI 转义码正则（用于从渲染行中剥离颜色标记） */
+const ANSI_RE = new RegExp(`\\x1b\\[[0-9;]*m`, "g");
+/** 判断一行是否为 Editor 的 border 行（去除 ANSI 转义码后判断） */
+function isBorderLine(line) {
+	const stripped = line.replace(ANSI_RE, "");
+	return /^[\s─┌┐├┤└┘↑↓\-0-9a-zA-Z]+$/.test(stripped);
+}
 var ZapmycoEditor = class extends Editor {
 	/** Escape 键回调 */
 	onEscape;
@@ -317,6 +346,12 @@ var ZapmycoEditor = class extends Editor {
 	onCtrlC;
 	/** Ctrl+D 回调 */
 	onCtrlD;
+	/** 是否正在执行（用于显示 loading） */
+	#executing = false;
+	/** loading 动画帧索引 */
+	#loadingFrame = 0;
+	/** loading 动画定时器 */
+	#loadingTimer;
 	handleInput(data) {
 		if (matchesKey(data, Key.escape) && this.onEscape) {
 			this.onEscape();
@@ -332,6 +367,51 @@ var ZapmycoEditor = class extends Editor {
 		}
 		super.handleInput(data);
 	}
+	/**
+	* 设置执行状态（控制 loading spinner 显示）
+	*/
+	setExecuting(executing) {
+		if (this.#executing === executing) return;
+		this.#executing = executing;
+		if (executing) {
+			this.#loadingFrame = 0;
+			this.#loadingTimer = setInterval(() => {
+				this.#loadingFrame = (this.#loadingFrame + 1) % LOADING_FRAMES.length;
+				this.tui?.requestRender();
+			}, 100);
+		} else if (this.#loadingTimer) {
+			clearInterval(this.#loadingTimer);
+			this.#loadingTimer = void 0;
+		}
+		this.tui?.requestRender();
+	}
+	get executing() {
+		return this.#executing;
+	}
+	/**
+	* Override render(): 去掉默认的上下边框，添加输入提示符和 loading 状态。
+	*
+	* 策略：调用 super.render() 获取完整的带边框输出，
+	* 然后移除首尾 border 行，再在内容行前添加提示符前缀。
+	*/
+	render(width) {
+		const rawLines = super.render(width);
+		if (rawLines.length < 3) return rawLines;
+		let startIndex = 0;
+		if (isBorderLine(rawLines[0] ?? "")) startIndex = 1;
+		let endIndex = rawLines.length;
+		if (isBorderLine(rawLines[rawLines.length - 1] ?? "")) endIndex = rawLines.length - 1;
+		const contentLines = rawLines.slice(startIndex, endIndex);
+		const promptWidth = [...PROMPT_PREFIX].length;
+		for (let i = 0; i < contentLines.length; i++) {
+			const prefix = i === 0 ? PROMPT_PREFIX : " ".repeat(promptWidth);
+			let line;
+			if (i === 0 && this.#executing) line = `${prefix}${LOADING_FRAMES[this.#loadingFrame]} ${contentLines[i]}`;
+			else line = prefix + contentLines[i];
+			contentLines[i] = truncateToWidth(line, width);
+		}
+		return contentLines;
+	}
 };
 
 //#endregion
@@ -748,16 +828,1045 @@ var Renderer = class {
 	}
 };
 
+//#endregion
+//#region src/cli/repl/tools/cache.ts
+const DEFAULT_TTL_MS = 900 * 1e3;
+const DEFAULT_MAX_ENTRIES = 100;
+/**
+* 创建内存缓存实例
+*
+* @param options - 缓存配置
+* @returns 缓存操作对象
+*/
+function createCache(options = {}) {
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+	const store = /* @__PURE__ */ new Map();
+	return {
+		/**
+		* 读取缓存
+		*
+		* @param key - 缓存 key
+		* @returns 命中返回 { value, cached: true }，未命中返回 null
+		*/
+		get(key) {
+			const entry = store.get(key);
+			if (!entry) return null;
+			if (Date.now() > entry.expiresAt) {
+				store.delete(key);
+				return null;
+			}
+			return {
+				value: entry.value,
+				cached: true
+			};
+		},
+		/**
+		* 写入缓存
+		*
+		* @param key - 缓存 key
+		* @param value - 要缓存的值
+		* @param customTtlMs - 自定义 TTL（覆盖默认值）
+		*/
+		set(key, value, customTtlMs) {
+			const effectiveTtl = customTtlMs ?? ttlMs;
+			if (effectiveTtl <= 0) return;
+			if (store.size >= maxEntries && !store.has(key)) {
+				const oldestKey = store.keys().next().value;
+				if (oldestKey !== void 0) store.delete(oldestKey);
+			}
+			store.set(key, {
+				value,
+				expiresAt: Date.now() + effectiveTtl,
+				insertedAt: Date.now()
+			});
+		},
+		/**
+		* 删除指定 key 的缓存
+		*/
+		delete(key) {
+			return store.delete(key);
+		},
+		/**
+		* 清空所有缓存
+		*/
+		clear() {
+			store.clear();
+		},
+		/**
+		* 获取当前缓存条目数
+		*/
+		get size() {
+			return store.size;
+		}
+	};
+}
+
+//#endregion
+//#region src/cli/repl/tools/html-to-markdown.ts
+/**
+* HTML → Markdown 转换模块
+*
+* 使用 turndown 库进行转换，附带启发式正文提取。
+*
+* 参考实现: Claude Code WebFetchTool (turndown 封装模式)
+*
+* @module cli/repl/tools/html-to-markdown
+*/
+let turndownInstance = null;
+/**
+* 获取 turndown 实例（懒加载单例）
+*/
+function getTurndown() {
+	if (!turndownInstance) turndownInstance = new TurndownService({
+		headingStyle: "atx",
+		codeBlockStyle: "fenced",
+		bulletListMarker: "-",
+		linkStyle: "inlined"
+	});
+	return turndownInstance;
+}
+/** 正文提取候选选择器（按优先级排序） */
+const MAIN_CONTENT_SELECTORS = [
+	"main",
+	"article",
+	"[role=\"main\"]",
+	".content",
+	".article",
+	".post",
+	".entry",
+	"#content",
+	"#article",
+	"#post",
+	"#main"
+];
+/**
+* 从 HTML 中启发式提取正文内容
+*/
+function extractMainContent(html) {
+	const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim() ?? "";
+	const description = html.match(/<meta[^>]+name=["']description["'][^>]+content=["']([^"']*)/i)?.[1]?.trim() ?? "";
+	for (const selector of MAIN_CONTENT_SELECTORS) {
+		const content = extractBySelector(html, selector);
+		if (content != null && content.length > 100) return buildOutput(title, description, content);
+	}
+	return buildOutput(title, description, html.match(/<body[^>]*>([\s\S]*)<\/body>/i)?.[1] ?? html);
+}
+/**
+* 用正则从 HTML 中提取匹配选择器的元素内容
+*/
+function extractBySelector(html, selector) {
+	if (selector.startsWith("#")) {
+		const id = selector.slice(1);
+		const regex = new RegExp(`<[^>]+id=["']${escapeRegex(id)}["'][^>]*>([\\s\\S]*?)</\\s*\\1>`, "i");
+		return html.match(regex)?.[1] ?? null;
+	}
+	if (selector.match(/^([a-z][\w-]*)$/i)) {
+		const regex = new RegExp(`<${escapeRegex(selector)}[^>]*>([\\s\\S]*?)<\\/\\s*${escapeRegex(selector)}>`, "i");
+		return html.match(regex)?.[1] ?? null;
+	}
+	const classMatch = selector.match(/^\.([\w-]+)$/);
+	if (classMatch?.[1]) {
+		const cls = classMatch[1];
+		const regex = new RegExp(`<[^>]+class=["'][^"']*${escapeRegex(cls)}[^"']*["'][^>]*>([\\s\\S]*?)<\\/[^>]+>`, "i");
+		return html.match(regex)?.[1] ?? null;
+	}
+	const roleMatch = selector.match(/^\[role=["'](\w+)["']\]$/);
+	if (roleMatch?.[1]) {
+		const role = roleMatch[1];
+		const regex = new RegExp(`<[^>]+role=["']${escapeRegex(role)}["'][^>]*>([\\s\\S]*?)<\\/[^>]+>`, "i");
+		return html.match(regex)?.[1] ?? null;
+	}
+	return null;
+}
+/** 转义正则特殊字符 */
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* 组装最终输出
+*/
+function buildOutput(title, description, content) {
+	let result = "";
+	if (title) result += `# ${title}\n\n`;
+	if (description) result += `> ${description}\n\n`;
+	result += content;
+	return result;
+}
+/**
+* 将 HTML 转换为 Markdown
+*/
+function htmlToMarkdown(html) {
+	return getTurndown().turndown(html);
+}
+/**
+* 提取正文并转换为 Markdown
+*/
+function extractAndConvert(html) {
+	return htmlToMarkdown(extractMainContent(html));
+}
+
+//#endregion
+//#region src/cli/repl/tools/ssrf-guard.ts
+/**
+* SSRF（服务器端请求伪造）防护模块
+*
+* 三层防护策略：
+* 1. URL 解析层 — hostname 黑名单匹配
+* 2. DNS 解析层 — DNS 查询后检查 IP 是否属于保留地址段
+* 3. 协议层 — 仅允许 http/https
+*
+* 参考实现: OpenClaw src/infra/net/ssrf.ts
+*
+* @module cli/repl/tools/ssrf-guard
+*/
+/** 默认被阻止的 hostname */
+const BLOCKED_HOSTNAMES = new Set([
+	"localhost",
+	"localhost.localdomain",
+	"ip6-localhost",
+	"ip6-loopback",
+	"metadata.google.internal"
+]);
+/**
+* IPv4/IPv6 保留和特殊用途地址段 (CIDR)
+*
+* 格式: [networkAddress, prefixBits]
+*/
+const PRIVATE_IP_RANGES = [
+	["127.0.0.0", 8],
+	["10.0.0.0", 8],
+	["172.16.0.0", 12],
+	["192.168.0.0", 16],
+	["169.254.0.0", 16],
+	["100.64.0.0", 10],
+	["198.18.0.0", 15],
+	["0.0.0.0", 8],
+	["::1", 128],
+	["fc00::", 7],
+	["fe80::", 10],
+	["::ffff:0:0", 96],
+	["64:ff9b::", 96]
+];
+/**
+* 检查 hostname 是否在黑名单中
+*/
+function isBlockedHostname(hostname) {
+	const lower = hostname.toLowerCase();
+	if (BLOCKED_HOSTNAMES.has(lower)) return true;
+	if (lower.endsWith(".localhost") || lower.endsWith(".local") || lower.endsWith(".internal")) return true;
+	return false;
+}
+/**
+* 通配符域名匹配
+*
+* 支持 *.example.com 格式
+*/
+function matchDomainPattern(hostname, pattern) {
+	if (pattern.startsWith("*.")) {
+		const suffix = pattern.slice(2);
+		if (!suffix || hostname === suffix) return false;
+		return hostname === suffix || hostname.endsWith(`.${suffix}`);
+	}
+	return hostname === pattern;
+}
+/**
+* 检查 hostname 是否匹配白名单/黑名单
+*/
+function checkHostnamePolicy(hostname, options) {
+	if (isBlockedHostname(hostname)) return {
+		allowed: false,
+		reason: `被阻止的 hostname: ${hostname}`
+	};
+	const allowedList = options.allowedDomains ?? [];
+	const blockedList = options.blockedDomains ?? [];
+	for (const pattern of blockedList) if (matchDomainPattern(hostname, pattern)) return {
+		allowed: false,
+		reason: `域名黑名单匹配: ${hostname} 匹配 ${pattern}`
+	};
+	if (allowedList.length > 0) {
+		if (!allowedList.some((pattern) => matchDomainPattern(hostname, pattern))) return {
+			allowed: false,
+			reason: `不在域名白名单中: ${hostname}`
+		};
+	}
+	return { allowed: true };
+}
+/**
+* 将 IPv4 地址字符串转为 32 位整数
+*/
+function ipv4ToInt(ip) {
+	const parts = ip.split(".");
+	if (parts.length !== 4) return null;
+	let result = 0;
+	for (const part of parts) {
+		const num = parseInt(part, 10);
+		if (Number.isNaN(num) || num < 0 || num > 255) return null;
+		result = result << 8 | num;
+	}
+	return result >>> 0;
+}
+/**
+* 检查 IP 地址是否在给定的 CIDR 范围内
+*/
+function ipInCidr(ip, cidr) {
+	const parts = cidr.split("/");
+	if (parts.length < 2) return false;
+	const range = parts[0] ?? "";
+	const prefix = parseInt(parts[1] ?? "32", 10);
+	if (Number.isNaN(prefix)) return false;
+	if (ip.includes(":")) try {
+		const ipBigInt = parseIpv6ToBigInt(ip);
+		const rangeBigInt = parseIpv6ToBigInt(range);
+		if (ipBigInt === null || rangeBigInt === null) return false;
+		const mask = prefix === 0 ? 0n : 2n ** BigInt(128) - 1n << BigInt(128 - prefix);
+		return (ipBigInt & mask) === (rangeBigInt & mask);
+	} catch {
+		return false;
+	}
+	const ipInt = ipv4ToInt(ip);
+	if (ipInt === null) return false;
+	const rangeInt = ipv4ToInt(range);
+	if (rangeInt === null) return false;
+	if (prefix === 0) return true;
+	const mask = prefix >= 32 ? 4294967295 : -1 << 32 - prefix >>> 0;
+	return (ipInt & mask) === (rangeInt & mask);
+}
+/**
+* 简化的 IPv6 → BigInt 转换（处理标准格式）
+*/
+function parseIpv6ToBigInt(ip) {
+	try {
+		const parts = (ip.includes("::") ? ip.replace("::", `::${":".repeat(ip.split(":").length < 8 ? 8 - ip.split(":").length : 0)}`) : ip).split(":");
+		if (parts.length !== 8) return null;
+		let result = 0n;
+		for (const part of parts) {
+			const value = part === "" ? 0 : parseInt(part, 16);
+			if (Number.isNaN(value)) return null;
+			result = (result << 16n) + BigInt(value);
+		}
+		return result;
+	} catch {
+		return null;
+	}
+}
+/**
+* 检查 IP 地址是否为私有/保留地址
+*/
+function isPrivateIp(ip) {
+	for (const entry of PRIVATE_IP_RANGES) {
+		const range = entry[0];
+		const prefix = entry[1] ?? 32;
+		if (range && ipInCidr(ip, `${range}/${String(prefix)}`)) return true;
+	}
+	return false;
+}
+/**
+* 检查 DNS 解析结果中的 IP 是否全部为公网地址
+*/
+async function checkResolvedAddresses(addresses, options) {
+	if (options.allowPrivateNetwork) return { allowed: true };
+	for (const addr of addresses) if (isPrivateIp(addr)) return {
+		allowed: false,
+		reason: `DNS 解析到私有/保留 IP 地址: ${addr}（可能为 SSRF 攻击）`
+	};
+	return { allowed: true };
+}
+/**
+* 检查 URL 是否可安全访问（SSRF 防护）
+*
+* @param url - 要检查的 URL
+* @param options - 防护选项
+* @returns 检查结果
+*/
+async function checkUrlSafety(url, options = {}) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return {
+			allowed: false,
+			reason: `无效的 URL: ${url}`
+		};
+	}
+	if (!["http:", "https:"].includes(parsed.protocol)) return {
+		allowed: false,
+		reason: `不允许的协议: ${parsed.protocol}（仅支持 http/https）`
+	};
+	const hostname = parsed.hostname;
+	const hostnameResult = checkHostnamePolicy(hostname, options);
+	if (!hostnameResult.allowed) return hostnameResult;
+	try {
+		const rawAddress = (await lookup(hostname, { verbatim: true })).address;
+		const ipResult = await checkResolvedAddresses(Array.isArray(rawAddress) ? rawAddress : [rawAddress], options);
+		if (!ipResult.allowed) return ipResult;
+	} catch (_err) {
+		if (!options.allowPrivateNetwork) return {
+			allowed: false,
+			reason: `DNS 解析失败且不允许私有网络访问: ${hostname}`
+		};
+	}
+	return { allowed: true };
+}
+
+//#endregion
+//#region src/cli/repl/tools/web-fetch.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const DEFAULT_MAX_RESPONSE_BYTES = 512e3;
+const DEFAULT_MAX_CHARS = 2e4;
+const DEFAULT_USER_AGENT = "ZapmycoBot/0.2 (https://github.com/shenjingnan/zapmyco)";
+const DEFAULT_MAX_REDIRECTS = 3;
+let fetchCache = null;
+function getFetchCache(ttlMinutes = 15) {
+	if (!fetchCache) fetchCache = createCache({
+		ttlMs: ttlMinutes * 60 * 1e3,
+		maxEntries: 100
+	});
+	return fetchCache;
+}
+/**
+* 构建缓存 key
+*/
+function buildCacheKey$1(url, extractMain, maxChars) {
+	return `fetch:${url}:${extractMain ? "main" : "full"}:${maxChars}`;
+}
+/**
+* 截断文本到指定字符数
+*/
+function truncateText(text, maxChars) {
+	if (text.length <= maxChars) return {
+		text,
+		truncated: false
+	};
+	const lastSpace = text.slice(0, maxChars).lastIndexOf(" ");
+	const cutAt = lastSpace > maxChars * .8 ? lastSpace : maxChars;
+	return {
+		text: `${text.slice(0, cutAt)}\n\n... [内容已截断]`,
+		truncated: true
+	};
+}
+/**
+* 根据 Content-Type 判断响应类型
+*/
+function getContentType(headers) {
+	return headers.get("content-type") ?? "application/octet-stream";
+}
+/**
+* 判断是否为 HTML 内容
+*/
+function isHtmlContent(contentType) {
+	return contentType.toLowerCase().includes("text/html");
+}
+/**
+* 判断是否为 JSON 内容
+*/
+function isJsonContent(contentType) {
+	return contentType.toLowerCase().includes("application/json");
+}
+/**
+* 执行 HTTP 抓取（含重定向跟踪）
+*/
+async function doFetch(url, options, ssrfOptions, signal) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+	const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+	const userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+	signal?.addEventListener("abort", () => controller.abort(), { once: true });
+	try {
+		let currentUrl = url;
+		let redirectCount = 0;
+		while (redirectCount <= maxRedirects) {
+			const response = await fetch(currentUrl, {
+				method: "GET",
+				headers: { "User-Agent": userAgent },
+				signal: controller.signal,
+				redirect: "manual"
+			});
+			if ([
+				301,
+				302,
+				303,
+				307,
+				308
+			].includes(response.status)) {
+				const location = response.headers.get("location");
+				if (!location) throw new WebError("WEB_FETCH_FAILED", `重定向但无 Location 头: ${currentUrl}`);
+				currentUrl = new URL(location, currentUrl).href;
+				const safetyResult = await checkUrlSafety(currentUrl, ssrfOptions);
+				if (!safetyResult.allowed) throw new WebError("WEB_FETCH_BLOCKED", safetyResult.reason ?? `重定向目标 URL 未通过安全检查: ${currentUrl}`, {
+					url: currentUrl,
+					reason: safetyResult.reason
+				});
+				redirectCount++;
+				continue;
+			}
+			if (!response.ok) throw new WebError("WEB_FETCH_FAILED", `HTTP ${response.status}: ${currentUrl}`, {
+				statusCode: response.status,
+				url: currentUrl
+			});
+			const contentLength = parseInt(response.headers.get("content-length") ?? "0", 10);
+			if (contentLength > maxBytes) throw new WebError("WEB_FETCH_TOO_LARGE", `响应过大: ${contentLength} 字节（限制 ${maxBytes}）`, {
+				contentLength,
+				maxBytes,
+				url: currentUrl
+			});
+			const buffer = await response.arrayBuffer();
+			if (buffer.byteLength > maxBytes) throw new WebError("WEB_FETCH_TOO_LARGE", `响应体过大: ${buffer.byteLength} 字节（限制 ${maxBytes}）`, {
+				actualSize: buffer.byteLength,
+				maxBytes,
+				url: currentUrl
+			});
+			return {
+				buffer,
+				contentType: getContentType(response.headers),
+				statusCode: response.status,
+				finalUrl: currentUrl
+			};
+		}
+		throw new WebError("WEB_FETCH_FAILED", `重定向次数超过上限 (${maxRedirects})`, {
+			maxRedirects,
+			url
+		});
+	} catch (err) {
+		if (err instanceof WebError) throw err;
+		if (err instanceof DOMException && err.name === "AbortError") throw new WebError("WEB_FETCH_TIMEOUT", `请求超时 (${timeoutMs}ms): ${url}`, {
+			timeoutMs,
+			url
+		});
+		throw new WebError("WEB_FETCH_FAILED", `抓取失败: ${err instanceof Error ? err.message : String(err)}`, { url });
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+/**
+* 处理响应内容并转换为文本
+*/
+function processResponse(buffer, contentType, extractMain) {
+	const rawText = new TextDecoder("utf-8", { fatal: false }).decode(buffer);
+	if (isHtmlContent(contentType)) {
+		if (extractMain) return {
+			text: extractAndConvert(rawText),
+			extractionMethod: "main-content"
+		};
+		return {
+			text: htmlToMarkdown(rawText),
+			extractionMethod: "full"
+		};
+	}
+	if (isJsonContent(contentType)) try {
+		const parsed = JSON.parse(rawText);
+		return {
+			text: JSON.stringify(parsed, null, 2),
+			extractionMethod: "raw"
+		};
+	} catch {}
+	return {
+		text: rawText,
+		extractionMethod: "raw"
+	};
+}
+/**
+* 创建 web_fetch 工具注册信息
+*/
+function createWebFetchTool(webConfig) {
+	const fetchOptions = webConfig?.fetch ?? {};
+	const ssrfOptions = webConfig?.ssrf ?? {};
+	const cacheTtlMinutes = fetchOptions.cacheTtlMinutes ?? 15;
+	return {
+		id: "web_fetch",
+		label: "网页抓取",
+		description: "抓取指定 URL 的网页内容并转换为 Markdown 格式。支持 HTML 正文提取、JSON 美化、内容截断。当用户需要访问网页获取信息时调用此工具。",
+		parameters: {
+			type: "object",
+			properties: {
+				url: {
+					type: "string",
+					description: "要抓取的 URL（必须 http:// 或 https:// 开头）"
+				},
+				extractMainContent: {
+					type: "boolean",
+					description: "是否只提取正文内容（默认根据全局配置）"
+				},
+				maxChars: {
+					type: "number",
+					description: "返回内容的最大字符数（默认使用全局配置，最大 100000）"
+				}
+			},
+			required: ["url"]
+		},
+		async execute(_toolCallId, params, signal) {
+			const startTime = Date.now();
+			const { url } = params;
+			const extractMain = params.extractMainContent ?? fetchOptions.extractMainContent ?? true;
+			const maxChars = Math.min(params.maxChars ?? fetchOptions.maxChars ?? DEFAULT_MAX_CHARS, 1e5);
+			const cache = getFetchCache(cacheTtlMinutes);
+			const cacheKey = buildCacheKey$1(url, extractMain, maxChars);
+			const cached = cache.get(cacheKey);
+			if (cached) return {
+				content: [{
+					type: "text",
+					text: cached.value
+				}],
+				details: {
+					url,
+					statusCode: 200,
+					contentLength: cached.value.length,
+					truncated: false,
+					extractionMethod: "full",
+					cached: true,
+					elapsedMs: Date.now() - startTime
+				}
+			};
+			const safetyResult = await checkUrlSafety(url, ssrfOptions);
+			if (!safetyResult.allowed) throw new WebError("WEB_FETCH_BLOCKED", safetyResult.reason ?? "URL 未通过安全检查", {
+				url,
+				reason: safetyResult.reason
+			});
+			const { buffer, contentType, statusCode, finalUrl } = await doFetch(url, fetchOptions, ssrfOptions, signal);
+			const { text: rawOutput, extractionMethod } = processResponse(buffer, contentType, extractMain);
+			const { text, truncated } = truncateText(rawOutput, maxChars);
+			cache.set(cacheKey, text);
+			const details = {
+				url,
+				...finalUrl !== url ? { finalUrl } : {},
+				statusCode,
+				contentType,
+				contentLength: text.length,
+				truncated,
+				extractionMethod,
+				cached: false,
+				elapsedMs: Date.now() - startTime
+			};
+			return {
+				content: [{
+					type: "text",
+					text
+				}],
+				details
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/cli/repl/tools/search-providers.ts
+/**
+* 搜索引擎 Provider 插件系统
+*
+* 提供插件化搜索引擎接口，内置 4 种实现：
+* - TavilyProvider    — 默认，高质量 AI 搜索（需 API Key）
+* - SerpApiProvider   — Google/Bing 等多引擎（需 API Key）
+* - DuckDuckGoProvider — HTML 抓取兜底（免费，无需 Key）
+* - CustomProvider    — 用户自建端点
+*
+* @module cli/repl/tools/search-providers
+*/
+/**
+* 构建 fetch options（处理 exactOptionalPropertyTypes 下 signal 不可为 undefined 的问题）
+*
+* signal 作为独立参数传入，避免对象字面量类型推断问题
+*/
+function buildFetchOptions(init, signal) {
+	const opts = {};
+	if (init.method) opts.method = init.method;
+	if (init.headers) opts.headers = init.headers;
+	if (init.body != null) opts.body = init.body;
+	if (signal !== void 0) opts.signal = signal;
+	return opts;
+}
+/**
+* 判断 URL 是否为 DuckDuckGo 内部跳转链接
+*
+* 使用 URL 构造器解析 hostname，避免子串匹配被绕过
+*/
+function isDuckDuckGoInternalUrl(rawUrl) {
+	try {
+		const host = new URL(rawUrl).hostname.toLowerCase();
+		return host === "duckduckgo.com" || host.endsWith(".duckduckgo.com");
+	} catch {
+		return true;
+	}
+}
+var TavilyProvider = class {
+	name = "tavily";
+	label = "Tavily";
+	requiresApiKey = true;
+	isAvailable(config) {
+		return !!config.apiKey;
+	}
+	async search(query, options, config, signal) {
+		const apiKey = config.apiKey;
+		if (!apiKey) throw new Error("Tavily 搜索需要 API Key。请配置 web.search.apiKey 或设置 TAVILY_API_KEY 环境变量。\n获取免费 API Key: https://tavily.com");
+		const maxResults = Math.min(options.maxResults, 20);
+		const response = await fetch("https://api.tavily.com/search", buildFetchOptions({
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				api_key: apiKey,
+				query,
+				max_results: maxResults,
+				include_answer: false,
+				search_depth: "basic"
+			})
+		}, signal));
+		if (!response.ok) throw new Error(`Tavily API 错误 (${response.status})`);
+		const data = await response.json();
+		if (!data.results?.length) return [];
+		return data.results.map((r) => ({
+			title: r.title,
+			url: r.url,
+			snippet: r.content.slice(0, 300)
+		}));
+	}
+};
+var SerpApiProvider = class {
+	name = "serpapi";
+	label = "SerpAPI";
+	requiresApiKey = true;
+	isAvailable(config) {
+		return !!config.apiKey;
+	}
+	async search(query, options, config, signal) {
+		const apiKey = config.apiKey;
+		if (!apiKey) throw new Error("SerpAPI 搜索需要 API Key。请配置 web.search.apiKey 或设置 SERPAPI_API_KEY 环境变量。\n获取 API Key: https://serpapi.com");
+		const maxResults = Math.min(options.maxResults, 20);
+		const params = new URLSearchParams({
+			api_key: apiKey,
+			q: query,
+			num: String(maxResults),
+			engine: "google",
+			hl: options.language ?? "zh-cn"
+		});
+		const response = await fetch("https://serpapi.com/search", buildFetchOptions({
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: params.toString()
+		}, signal));
+		if (!response.ok) throw new Error(`SerpAPI 错误 (${response.status})`);
+		const data = await response.json();
+		if (data.error) throw new Error(`SerpAPI: ${data.error}`);
+		if (!data.organic_results?.length) return [];
+		return data.organic_results.map((r) => ({
+			title: r.title,
+			url: r.link,
+			snippet: r.snippet.slice(0, 300)
+		}));
+	}
+};
+var DuckDuckGoProvider = class {
+	name = "duckduckgo";
+	label = "DuckDuckGo";
+	requiresApiKey = false;
+	isAvailable() {
+		return true;
+	}
+	async search(query, options, _config, signal) {
+		const maxResults = Math.min(options.maxResults, 20);
+		const response = await fetch(`https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`, buildFetchOptions({ headers: { "User-Agent": "Mozilla/5.0 (compatible; ZapmycoBot/0.2)" } }, signal));
+		if (!response.ok) throw new Error(`DuckDuckGo 请求失败 (${response.status})`);
+		const html = await response.text();
+		return this.parseDdgHtml(html, maxResults);
+	}
+	/**
+	* 解析 DuckDuckGo HTML 结果页面
+	*/
+	parseDdgHtml(html, maxResults) {
+		const results = [];
+		const resultBlocks = html.split(/<div[^>]+class="[^"]*result[^"]*"[^>]*>/i);
+		for (const block of resultBlocks) {
+			if (results.length >= maxResults) break;
+			const titleMatch = block.match(/<a[^>]+class="[^"]*result__title[^"]*"[^>]*>([\s\S]*?)<\/a>/i);
+			const title = titleMatch ? this.stripHtmlTags(titleMatch[1] ?? "").trim() : "";
+			const urlMatch = block.match(/<a[^>]+class="[^"]*result__url[^"]*"[^>]*href="([^"]*)"/i);
+			const url = urlMatch ? this.decodeDdgUrl(urlMatch[1] ?? "") : "";
+			const snippetMatch = block.match(/<a[^>]+class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/i);
+			const snippet = snippetMatch ? this.stripHtmlTags(snippetMatch[1] ?? "").trim().slice(0, 300) : "";
+			if (title && url) results.push({
+				title,
+				url,
+				snippet
+			});
+		}
+		if (results.length === 0) return this.fallbackParseDdgHtml(html, maxResults);
+		return results;
+	}
+	/**
+	* 备用解析：更宽松的正则匹配
+	*/
+	fallbackParseDdgHtml(html, maxResults) {
+		const results = [];
+		const linkRegex = /<a[^>]+(class="[^"]*(?:result|snippet)[^"]*")[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+		let match = linkRegex.exec(html);
+		while (match !== null && results.length < maxResults) {
+			const rawUrl = match[2];
+			const rawText = match[3];
+			if (rawUrl == null || rawText == null) continue;
+			if (rawUrl.startsWith("/") || isDuckDuckGoInternalUrl(rawUrl)) continue;
+			const text = this.stripHtmlTags(rawText).trim();
+			if (text.length > 10) results.push({
+				title: text.slice(0, 120),
+				url: this.decodeDdgUrl(rawUrl),
+				snippet: ""
+			});
+			match = linkRegex.exec(html);
+		}
+		return results;
+	}
+	/** 移除 HTML 标签并解码 HTML 实体 */
+	stripHtmlTags(html) {
+		let text = html;
+		text = text.replace(/&nbsp;/g, " ").replace(/&(amp|lt|gt|quot|#\d+|#x[0-9a-fA-F]+);/g, (_, token) => {
+			const entityMap = {
+				amp: "&",
+				lt: "<",
+				gt: ">",
+				quot: "\""
+			};
+			if (token in entityMap) return entityMap[token];
+			if (token.startsWith("#x")) {
+				const cp = parseInt(token.slice(2), 16);
+				return Number.isNaN(cp) ? _ : String.fromCharCode(cp);
+			}
+			if (token.startsWith("#")) {
+				const cp = parseInt(token.slice(1), 10);
+				return Number.isNaN(cp) ? _ : String.fromCharCode(cp);
+			}
+			return _;
+		});
+		text = text.replace(/[<>]/g, "");
+		return text;
+	}
+	/** 解码 DuckDuckGo 跳转 URL */
+	decodeDdgUrl(url) {
+		try {
+			if (url.includes("uddg=")) {
+				const uddgMatch = url.match(/uddg=([^&]+)/);
+				if (uddgMatch?.[1]) return decodeURIComponent(uddgMatch[1]);
+			}
+			return decodeURIComponent(url);
+		} catch {
+			return url;
+		}
+	}
+};
+var CustomProvider = class {
+	name = "custom";
+	label = "自定义端点";
+	requiresApiKey = false;
+	isAvailable(config) {
+		return !!config.endpointUrl;
+	}
+	async search(query, options, config, signal) {
+		const endpointUrl = config.endpointUrl;
+		if (!endpointUrl) throw new Error("自定义搜索需要配置 endpointUrl。请在 web.search.endpointUrl 中指定端点地址。");
+		const maxResults = Math.min(options.maxResults, 20);
+		const safetyResult = await checkUrlSafety(endpointUrl);
+		if (!safetyResult.allowed) throw new Error(`自定义搜索端点 URL 未通过安全检查: ${safetyResult.reason ?? endpointUrl}`);
+		const headers = { "Content-Type": "application/json" };
+		if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
+		const response = await fetch(endpointUrl, buildFetchOptions({
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				query,
+				max_results: maxResults,
+				language: options.language ?? "zh-cn"
+			})
+		}, signal));
+		if (!response.ok) throw new Error(`自定义搜索端点错误 (${response.status}): ${endpointUrl}`);
+		const data = await response.json();
+		if (data.error) throw new Error(`自定义搜索端点返回错误: ${data.error}`);
+		return data.results ?? [];
+	}
+};
+const PROVIDER_REGISTRY = new Map([
+	["tavily", () => new TavilyProvider()],
+	["serpapi", () => new SerpApiProvider()],
+	["duckduckgo", () => new DuckDuckGoProvider()],
+	["custom", () => new CustomProvider()]
+]);
+/**
+* 根据 provider 名称解析对应的 Provider 实例
+*/
+function resolveSearchProvider(providerName) {
+	const factory = PROVIDER_REGISTRY.get(providerName);
+	if (!factory) {
+		const available = [...PROVIDER_REGISTRY.keys()].join(", ");
+		throw new Error(`未知搜索引擎: "${providerName}"，可用的 Provider: ${available}`);
+	}
+	return factory();
+}
+/**
+* 获取所有已注册的 Provider 名称列表
+*/
+function getAvailableProviders() {
+	return [...PROVIDER_REGISTRY.keys()];
+}
+
+//#endregion
+//#region src/cli/repl/tools/web-search.ts
+const DEFAULT_MAX_RESULTS = 8;
+const DEFAULT_LANGUAGE = "zh-cn";
+let searchCache = null;
+function getSearchCache(ttlMinutes = 15) {
+	if (!searchCache) searchCache = createCache({
+		ttlMs: ttlMinutes * 60 * 1e3,
+		maxEntries: 100
+	});
+	return searchCache;
+}
+/**
+* 构建缓存 key
+*/
+function buildCacheKey(query, provider, numResults) {
+	return `search:${query}:${provider}:${numResults}`;
+}
+/**
+* 格式化搜索结果为 Markdown 文本
+*/
+function formatResults(results, query, provider) {
+	if (results.length === 0) return `未找到与 "${query}" 相关的搜索结果（来源: ${provider}）。`;
+	const lines = [`找到 ${results.length} 条搜索结果 (来源: ${provider}):`, ""];
+	for (let i = 0; i < results.length; i++) {
+		const r = results[i];
+		lines.push(`${i + 1}. **${r.title}**`);
+		lines.push(`   ${r.url}`);
+		if (r.snippet) lines.push(`   ${r.snippet}`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/**
+* 创建 web_search 工具注册信息
+*/
+function createWebSearchTool(webConfig) {
+	const searchOptions = webConfig?.search ?? {};
+	const cacheTtlMinutes = searchOptions.cacheTtlMinutes ?? 15;
+	return {
+		id: "web_search",
+		label: "网页搜索",
+		description: "在互联网上搜索信息。支持多种搜索引擎后端。当用户需要查找最新信息、技术文档、新闻等时调用此工具。",
+		parameters: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "搜索关键词或自然语言查询"
+				},
+				numResults: {
+					type: "number",
+					description: "返回结果数量（1-20，默认 8）"
+				}
+			},
+			required: ["query"]
+		},
+		async execute(_toolCallId, params, signal) {
+			const startTime = Date.now();
+			const { query } = params;
+			const numResults = Math.min(params.numResults ?? searchOptions.maxResults ?? DEFAULT_MAX_RESULTS, 20);
+			const providerName = searchOptions.provider ?? "tavily";
+			const language = searchOptions.language ?? DEFAULT_LANGUAGE;
+			const cache = getSearchCache(cacheTtlMinutes);
+			const cacheKey = buildCacheKey(query, providerName, numResults);
+			const cached = cache.get(cacheKey);
+			if (cached) return {
+				content: [{
+					type: "text",
+					text: cached.value
+				}],
+				details: {
+					query,
+					provider: providerName,
+					resultCount: 0,
+					cached: true,
+					elapsedMs: Date.now() - startTime
+				}
+			};
+			let provider;
+			try {
+				provider = resolveSearchProvider(providerName);
+			} catch (err) {
+				throw new WebError("WEB_SEARCH_NOT_CONFIGURED", err instanceof Error ? err.message : String(err), { requestedProvider: providerName });
+			}
+			const providerConfig = {};
+			if (searchOptions.apiKey) providerConfig.apiKey = searchOptions.apiKey;
+			if (searchOptions.endpointUrl) providerConfig.endpointUrl = searchOptions.endpointUrl;
+			if (!await provider.isAvailable(providerConfig)) {
+				const available = getAvailableProviders().filter((name) => name !== providerName).join(", ");
+				if (providerName === "tavily") throw new WebError("WEB_SEARCH_NOT_CONFIGURED", `Tavily 搜索未配置 API Key。
+
+**解决方案：**
+1. 获取免费 Tavily API Key: https://tavily.com
+2. 设置环境变量: export TAVILY_API_KEY=tvly-xxxxx
+3. 或在配置文件中设置: web.search.apiKey
+
+**替代方案：** 切换到 DuckDuckGo（免费无需 Key）:
+在配置文件中设置 web.search.provider = "duckduckgo"
+
+可用搜索引擎: ${available}, ${providerName}`, {
+					requestedProvider: providerName,
+					availableProviders: getAvailableProviders()
+				});
+				throw new WebError("WEB_SEARCH_NOT_CONFIGURED", `${provider.label} 搜索不可用。请检查 API Key 配置。\n\n可用替代引擎: ${available}`, {
+					requestedProvider: providerName,
+					availableProviders: getAvailableProviders()
+				});
+			}
+			let results;
+			try {
+				results = await provider.search(query, {
+					maxResults: numResults,
+					language
+				}, providerConfig, signal);
+			} catch (err) {
+				if (err instanceof Error && err.message.includes("quota")) throw new WebError("WEB_SEARCH_QUOTA_EXCEEDED", err.message, { provider: providerName });
+				throw new WebError("WEB_SEARCH_FAILED", `搜索失败: ${err instanceof Error ? err.message : String(err)}`, {
+					provider: providerName,
+					query
+				});
+			}
+			const text = formatResults(results, query, provider.label);
+			cache.set(cacheKey, text);
+			const details = {
+				query,
+				provider: providerName,
+				resultCount: results.length,
+				cached: false,
+				elapsedMs: Date.now() - startTime
+			};
+			return {
+				content: [{
+					type: "text",
+					text
+				}],
+				details
+			};
+		}
+	};
+}
+
 //#endregion
 //#region src/cli/repl/repl-agent-tools.ts
 /**
+* REPL Agent 工具注册表
+*
+* 定义 REPL 场景下 Agent 可用的工具集合。
+* 工具按能力域分组，支持按需加载。
+*
+* @module cli/repl/repl-agent-tools
+*/
+/**
 * 创建 REPL 基础工具集
 *
 * 第一阶段工具：验证 Agent 工具调用链路的端到端连通性。
 * 后续阶段在此基础扩展：文件读写、Shell 执行、Git 操作等。
+*
+* @param webConfig - Web 工具配置（可选），传入时启用 web_fetch 和 web_search
 */
-function createReplBuiltinTools() {
-	return [
+function createReplBuiltinTools(webConfig) {
+	const tools = [
 		{
 			id: "get_current_time",
 			label: "获取当前时间",
@@ -831,6 +1940,11 @@ function createReplBuiltinTools() {
 			}
 		}
 	];
+	if (webConfig?.enabled !== false) {
+		tools.push(createWebFetchTool(webConfig));
+		tools.push(createWebSearchTool(webConfig));
+	}
+	return tools;
 }
 
 //#endregion
@@ -939,8 +2053,6 @@ var ReplSession = class {
 	tui;
 	editor;
 	outputArea;
-	header;
-	footer;
 	options;
 	_state = "idle";
 	parser;
@@ -974,14 +2086,10 @@ var ReplSession = class {
 		const theme = createTheme(this.options.color);
 		const terminal = new ProcessTerminal();
 		this.tui = new TUI(terminal);
-		this.header = new Text("", 1, 0);
 		this.outputArea = new OutputArea();
-		this.footer = new Text("", 1, 0);
 		this.editor = new ZapmycoEditor(this.tui, theme.editorTheme);
 		const root = new Container();
-		root.addChild(this.header);
 		root.addChild(this.outputArea);
-		root.addChild(this.footer);
 		root.addChild(this.editor);
 		this.tui.addChild(root);
 		this.tui.setFocus(this.editor);
@@ -1006,10 +2114,7 @@ var ReplSession = class {
 	async start() {
 		this._state = "idle";
 		this.updateStatsState();
-		const welcomeLines = this.renderer.renderWelcome(__VERSION__);
-		this.outputArea.append(welcomeLines);
-		this.updateHeader();
-		this.updateFooter();
+		this.outputArea.append(["ZapMyco: 欢迎回来!", ""]);
 		this.tui.start();
 	}
 	/** 优雅关闭会话 */
@@ -1058,7 +2163,7 @@ var ReplSession = class {
 		try {
 			this._state = "executing";
 			this.updateStatsState();
-			this.updateFooter();
+			this.editor.setExecuting(true);
 			this.currentTaskAbort = new AbortController();
 			historyEntry = this.history.push({
 				timestamp: Date.now(),
@@ -1068,12 +2173,7 @@ var ReplSession = class {
 				goalId: `goal-${startTime}`,
 				rawInput
 			});
-			const goalLines = [
-				"",
-				`  🎯 ${rawInput}`,
-				"",
-				"  💬 "
-			];
+			const goalLines = [`Me: ${rawInput}`, "ZapMyco: "];
 			this.outputArea.append(goalLines);
 			const outputHandler = (event) => {
 				if (event.taskId === taskId) {
@@ -1117,8 +2217,8 @@ var ReplSession = class {
 					error: taskResult.error,
 					status: taskResult.status
 				});
-			} else if (outputText) this.outputArea.appendText(outputText);
-			this.outputArea.append(["", ""]);
+			}
+			this.outputArea.append([""]);
 			const duration = Date.now() - startTime;
 			const result = {
 				goalId: `goal-${startTime}`,
@@ -1183,7 +2283,7 @@ var ReplSession = class {
 		} finally {
 			this._state = "idle";
 			this.updateStatsState();
-			this.updateFooter();
+			this.editor.setExecuting(false);
 			this.currentTaskAbort = null;
 			this.currentTaskId = null;
 		}
@@ -1281,7 +2381,7 @@ var ReplSession = class {
 	* 注册 REPL 场景下的基础工具
 	*/
 	registerBuiltinTools() {
-		this.agent.registerTools(createReplBuiltinTools());
+		this.agent.registerTools(createReplBuiltinTools(this.config.web));
 	}
 	/** 设置编辑器事件绑定 */
 	setupEditorHandlers() {
@@ -1293,24 +2393,19 @@ var ReplSession = class {
 				this.cancelCurrentTask();
 				this.outputArea.append([
 					"",
-					"  任务已取消",
+					"任务已取消",
 					""
 				]);
 				return;
 			}
 			ctrlCPressCount++;
 			if (ctrlCPressCount >= 2) {
-				this.outputArea.append([
-					"",
-					"  再见！",
-					""
-				]);
 				this.shutdown("用户连续按下 Ctrl+C");
 				return;
 			}
 			this.outputArea.append([
 				"",
-				"  (再次按下 Ctrl+C 可强制退出)",
+				"(再次按下 Ctrl+C 可强制退出)",
 				""
 			]);
 			clearTimeout(ctrlCTimer);
@@ -1319,11 +2414,6 @@ var ReplSession = class {
 			}, 3e3);
 		};
 		this.editor.onCtrlD = () => {
-			this.outputArea.append([
-				"",
-				"  再见！",
-				""
-			]);
 			this.shutdown("收到 EOF (Ctrl+D)");
 		};
 	}
@@ -1352,17 +2442,6 @@ var ReplSession = class {
 	updateStatsState() {
 		this.stats.state = this._state;
 	}
-	/** 更新 header 文本 */
-	updateHeader() {
-		const theme = createTheme(this.options.color);
-		this.header.setText(theme.heading(`  zapmyco@${__VERSION__}`));
-	}
-	/** 更新 footer 文本 */
-	updateFooter() {
-		const theme = createTheme(this.options.color);
-		const stateLabel = this._state === "idle" ? theme.success("空闲") : this._state === "executing" ? theme.warning("执行中") : theme.dim("关闭中");
-		this.footer.setText(`  ${stateLabel}`);
-	}
 };
 
 //#endregion