功能规格说明：WebFetch 工具

创建日期：2026-03-31
更新日期：2026-04-21

用户场景与测试 （必填）

用户故事：基本网页内容提取（优先级：P1）

作为用户，我希望能够从 URL 获取内容并提问，以便在不离开终端的情况下快速获取网页信息。

为什么是这个优先级：这是工具的核心功能。

独立测试：可以通过使用简单 URL 和提示调用 WebFetch 工具，并验证工具基于页面内容返回相关响应来测试。

验收场景：

1. 假设URL https://example.com 和提示"What is the title of this page?"，当WebFetch 工具执行时，则它应该返回包含"Example Domain"的响应
2. 假设URL 不可达，当WebFetch 工具执行时，则它应该返回 success: false 结果和适当的错误消息

---

用户故事：重定向处理（优先级：P2）

作为用户，我希望在 URL 重定向到不同主机时被通知，并且同主机重定向被自动跟随，这样我不必为每次重定向手动重新获取。

为什么是这个优先级：这确保访问网页内容时的透明度和安全性，同时减少不必要的工具调用。

验收场景：

1. 假设URL http://short.url 重定向到 https://another-domain.com/page，当WebFetch 工具执行时，则它应该返回以 REDIRECT_TO: https://another-domain.com/page 开头的消息并通知用户主机变更
2. 假设URL 重定向到同一主机的不同路径，当WebFetch 工具执行时，则它应该自动跟随重定向并返回页面内容，不带 REDIRECT_TO 消息
3. 假设URL 从 example.com 重定向到 www.example.com，当WebFetch 工具执行时，则它应该自动跟随重定向

---

用户故事：GitHub URL 处理（优先级：P2）

作为用户，我希望在尝试获取 GitHub URL 时被建议使用 gh CLI，以便我可以使用更专业和认证的 GitHub 内容工具。

为什么是这个优先级：GitHub 内容通常通过其官方 CLI 访问更好，它比通用网页获取器更好地处理认证和结构化数据。

验收场景：

1. 假设GitHub URL https://github.com/netease-lcap/wave-agent，当WebFetch 工具执行时，则它应该返回建议使用 Bash 工具的 gh CLI 的错误消息

---

用户故事：缓存（优先级：P3）

作为用户，我希望重复请求同一 URL 时速度更快，这样我不会浪费时间和 token 重新获取和处理相同内容。

为什么是这个优先级：提高性能并减少资源使用。

验收场景：

1. 假设URL 已被获取一次，当它在 15 分钟内再次被获取，使用相同或不同的提示时，则工具应该使用缓存的 Markdown 内容而不是发起新的网络请求

---

用户故事：安全性与健壮性（优先级：P2）

作为用户，我希望工具防止过度资源使用并提供清晰的错误消息，这样我不会遇到挂起或内存问题。

为什么是这个优先级：防止工具消耗过多资源或无限挂起。

验收场景：

1. 假设URL 超过 2000 个字符，当WebFetch 工具执行时，则它应该返回关于 URL 长度的错误
2. 假设URL 包含用户名/密码凭证，当WebFetch 工具执行时，则它应该拒绝该 URL
3. 假设localhost URL，当WebFetch 工具执行时，则它应该拒绝该 URL
4. 假设响应超过 10MB，当WebFetch 工具执行时，则它应该拒绝该响应
5. 假设获取时间超过 60 秒，当达到超时时，则请求应该被中止
6. 假设重定向循环，当重定向计数超过 10 时，则工具应该返回错误

非功能需求

• 工具必须是只读的，不修改任何文件
• 工具必须快速高效
• 工具必须通过截断和必要时总结来处理大内容
• 工具必须提供清晰的错误消息和诊断输出（HTTP 状态码、内容大小）
• 缓存必须使用 LRU 驱逐策略和自动过期（无手动清理间隔）