web-search

网页搜索技能

何时使用此技能

在以下情况下使用网页搜索技能：

• 当前信息——2025 年 1 月之后的事件、新闻或数据
• 最新文档——最新的框架/库文档（React 19、Next.js 15 等）
• 实时数据——股价、天气、体育赛事比分等
• 事实核查——查看项目、公司或技术的当前状态
• 近期讨论——社区观点、GitHub 问题、Stack Overflow 答案
• 产品比较——最新的评测和比较
• 故障排除——搜索特定错误消息或解决方案

使用示例：

• 用户：“React 19 有哪些新功能？”
• 用户：“搜索最新的 Next.js App Router 文档”
• 用户：“Rust async 项目目前进展如何？”
• 用户：“查找近期关于 Vue 3 性能的讨论”

工作原理

┌──────────┐    Bash    ┌─────────┐    HTTP    ┌──────────────┐    CDP    ┌────────┐
│  Claude  │───────────▶│ CLI.sh  │───────────▶│ Bridge Server│──────────▶│ Chrome │
│          │            │         │            │ (localhost)  │ Playwright│        │
└──────────┘            └─────────┘            └──────────────┘            └────────┘
                                                      │
                                                  ▼
                                             Google/Bing Search
                                                Extract Results

架构：

1. CLI 脚本——供 Claude 使用的简单 bash 接口
2. 桥接服务——Express HTTP API（由 Electron 自动启动）
3. Playwright 管理器——浏览器连接和会话管理
4. 搜索引擎层——优先使用 Google，备用使用 Bing
5. Chrome 浏览器——可见的浏览器窗口（所有操作均透明可见）

基本用法

简单搜索（推荐）

**重要：**始终使用 $SKILLS_ROOT 环境变量来定位技能脚本。这可确保该技能在开发和生产环境中均能正常工作。

bash "$SKILLS_ROOT/web-search/scripts/search.sh" "search query" [max_results]

对于非 ASCII 查询（中文/日语等），建议使用 UTF-8 文件输入，以避免 Windows 上的 shell 编码问题：

cat > /tmp/web-query.txt <<'TXT'
苹果 Siri AI 2026 发布计划
TXT

bash "$SKILLS_ROOT/web-search/scripts/search.sh" @/tmp/web-query.txt 10

示例：

# Search with default 10 results
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "TypeScript 5.0 new features"

# Limit to 5 results
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "React Server Components guide" 5

# Search for recent news
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "AI news January 2026" 10

输出格式：

脚本会返回 Markdown 格式的结果：

# Search Results: TypeScript 5.0 new features

**Query:** TypeScript 5.0 new features
**Results:** 5
**Time:** 834ms

---

## TypeScript 5.0 Release Notes

**URL:** [https://www.typescriptlang.org/docs/...]

TypeScript 5.0 introduces decorators, const type parameters...

---

## (More results...)

工作流示例

# 1. Search for topic
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "Next.js 14 features" 5

# 2. Analyze results and answer user

# 3. Follow-up search if needed
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "Next.js Server Actions tutorial" 3

高级用法

服务管理

桥接服务由 Electron 自动管理。通常无需手动启动或停止。

不过，也可以手动控制：

# Start server (if not already running)
bash "$SKILLS_ROOT/web-search/scripts/start-server.sh"

# Stop server
bash "$SKILLS_ROOT/web-search/scripts/stop-server.sh"

# Check health (start script will print endpoint status)
bash "$SKILLS_ROOT/web-search/scripts/start-server.sh"

直接调用 API

对于高级用例，可以直接调用 HTTP API：

# Get or create connection
CONNECTION_ID=$(curl -s -X POST http://127.0.0.1:8923/api/browser/connect \
  -H "Content-Type: application/json" \
  -d '{}' | grep -o '"connectionId":"[^"]*"' | cut -d'"' -f4)

# Perform search
curl -X POST http://127.0.0.1:8923/api/search \
  -H "Content-Type: application/json" \
  -d "{
    \"connectionId\": \"$CONNECTION_ID\",
    \"query\": \"Playwright tutorial\",
    \"maxResults\": 5
  }"

# Navigate to specific URL
curl -X POST http://127.0.0.1:8923/api/page/navigate \
  -H "Content-Type: application/json" \
  -d "{
    \"connectionId\": \"$CONNECTION_ID\",
    \"url\": \"https://example.com\"
  }"

# Take screenshot
curl -X POST http://127.0.0.1:8923/api/page/screenshot \
  -H "Content-Type: application/json" \
  -d "{
    \"connectionId\": \"$CONNECTION_ID\",
    \"format\": \"png\"
  }"

最佳实践

1. 使用具体的查询

❌ 不佳：bash scripts/search.sh "react" ✅ 良好：bash scripts/search.sh "React 19 new features and breaking changes"

2. 合理限制结果数量

• 快速查询：3-5 条结果
• 全面研究：10 条结果
• 不要请求超出所需的结果（速度更快，干扰更少）

3. 先检查服务状态

如果搜索失败，请确认服务正在运行：

bash "$SKILLS_ROOT/web-search/scripts/start-server.sh" || echo "Server not running"

4. 重用连接

CLI 脚本会自动缓存连接。同一会话中的多次搜索会重用同一个浏览器连接，以提升性能。

5. 清理输出

解析 Markdown 输出，提取关键信息提供给用户。不要直接倾倒所有结果，而应综合整理并概括。

常见模式

模式 1：最新文档

# User asks about latest framework features
bash SKILLs/web-search/scripts/search.sh "Next.js 15 documentation" 5

# Parse results, find official docs, summarize features

模式 2：故障排除

# User reports an error
bash SKILLs/web-search/scripts/search.sh "TypeError: Cannot read property of undefined React" 5

# Find Stack Overflow answers and GitHub issues, provide solution

模式 3：当前事件

# User asks about recent news
bash SKILLs/web-search/scripts/search.sh "AI developments January 2026" 10

# Summarize key news items from results

模式 4：比较研究

# User wants to compare technologies
bash SKILLs/web-search/scripts/search.sh "Vue 3 vs React 18 performance 2026" 5

# Synthesize comparison from multiple sources

模式 5：API/库用法

# User needs specific API documentation
bash SKILLs/web-search/scripts/search.sh "Playwright page.evaluate examples" 5

# Extract code examples and usage patterns

错误处理

服务未运行

错误：✗ Bridge Server is not running

解决方案：

• 服务应随 Electron 自动启动
• 如果需要手动启动：bash SKILLs/web-search/scripts/start-server.sh
• 查看日志：cat SKILLs/web-search/.server.log

浏览器启动失败

错误：Failed to launch browser

**原因：**未安装 Chrome 或找不到 Chrome

解决方案：

• macOS：从 https://www.google.com/chrome/ 安装
• Linux：sudo apt install chromium-browser
• Windows：从 https://www.google.com/chrome/ 安装

连接超时

错误：CDP port not ready 或 Connection timeout

解决方案：

# Stop server
bash SKILLs/web-search/scripts/stop-server.sh

# Clear cache
rm SKILLs/web-search/.connection

# Restart
bash SKILLs/web-search/scripts/start-server.sh

没有搜索结果

错误：Found 0 results

可能原因：

• 查询过于具体或不常见
• Bing 更改了页面结构（罕见）
• 网络问题

解决方案：

• 尝试更宽泛的查询
• 检查互联网连接
• 在 bing.com 手动确认页面能否加载

搜索超时

错误： Search failed: timeout

解决方案：

• 检查互联网连接
• 减少最大结果数
• 重试（可能是暂时的网络问题）

理解结果

结果结构

每条搜索结果包含：

## [Title of Result]

**URL:** [https://example.com/page]

[Snippet/description from search results]

字段：

• Title - 页面／文章标题
• URL - 直接链接（可能包含 Bing 跟踪信息）
• Snippet - 页面预览文本

解析结果

搜索输出为 Markdown。提取：

1. 结果总数
2. 搜索耗时
3. 各条结果的标题和 URL
4. 用于了解上下文的摘要

结果质量

• 官方文档 - 通常出现在前 3 条结果中
• Stack Overflow - 会出现在技术问题的搜索结果中
• 近期文章 - Bing 会优先显示近期内容
• 中文内容 - Bing 在中国表现良好，包含中文来源

性能注意事项

典型延迟

• 服务启动：约 2 秒（仅首次，自动启动）
• 浏览器启动：约 3 秒（仅首次，后续搜索中保持运行）
• 首次搜索：约 2-3 秒（包括浏览器连接设置）
• 后续搜索：约 1 秒（复用浏览器和连接）

优化提示

1. 保持浏览器运行 - 默认情况下，浏览器会在搜索期间保持运行。连接和页面会自动复用。如有需要，可设置 WEB_SEARCH_CLEANUP=1，在每次搜索后关闭浏览器。
2. 限制结果数量 - 只请求所需的结果（通常 5-10 条就足够）
3. 批量搜索 - 如果需要多次搜索，请连续进行，以复用连接
4. 使用具体的查询 - 查询越具体，速度越快，结果也越好

安全与隐私

安全措施

• 仅限本地主机 - Bridge Server 绑定到 127.0.0.1（不允许外部访问）
• 不暴露于网络 - 其他机器无法访问
• 隔离的浏览器 - 使用独立的 Chrome 配置文件，不会影响用户的主浏览器
• 操作可见 - 所有浏览器操作都会显示在可见窗口中（透明可见）
• 无凭据 - 此 Skill 不会处理密码或敏感数据

隐私注意事项

• 搜索查询会根据可用性通过 Google 和／或 Bing 发送
• Google／Bing 可能会跟踪搜索（适用其标准隐私政策）
• 此 Skill 不会在本地存储搜索历史
• 用户可以实时查看所有浏览器活动

限制

当前限制

1. 不处理 CAPTCHA - 如果 Google 或 Bing 显示 CAPTCHA，用户必须手动解决
2. 搜索引擎的可用性因网络／地区而异 - 自动模式会在 Google 和 Bing 之间切换
3. 侧重英语／中文 - 针对英语和中文搜索结果进行了优化
4. 基础提取 - 提取标题和摘要，而非完整页面内容
5. 无身份验证 - 无法搜索需要登录的页面

不适用的场景

• 需要身份验证的搜索
• 填写表单或提交数据
• 需要解决 CAPTCHA 的操作（除非用户手动解决）
• 大规模抓取或自动批量搜索
• 访问付费墙后的页面

故障排除指南

快速诊断

# 1. Check server health
curl http://127.0.0.1:8923/api/health

# 2. Check server logs
cat SKILLs/web-search/.server.log | tail -50

# 3. Test basic search
bash SKILLs/web-search/scripts/search.sh "test" 1

# 4. Check Chrome installation
which google-chrome || which chromium || which chromium-browser

常见问题

问题	症状	解决方案
服务停止	Connection refused	启动服务或重启 Electron
找不到浏览器	Chrome not found	安装 Chrome/Chromium
端口冲突	Address already in use	停止占用端口 8923 的冲突进程
连接过期	Connection not found	删除 .connection 缓存文件
网络问题	Search timeout	检查互联网连接

重置所有内容

如果其他方法都无效，请执行完整重置：

cd SKILLs/web-search

# Stop server
bash scripts/stop-server.sh

# Clean cache and state
rm -f .connection .server.pid .server.log

# Rebuild
npm run build

# Restart
bash scripts/start-server.sh

# Test
bash scripts/search.sh "test" 1

Claude 示例

示例 1：用户询问最新的框架

用户：“Next.js 15 有哪些新功能？”

Claude 的处理方式：

# Search for Next.js 15 features
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "Next.js 15 new features" 5

**然后：**解析结果，找出 Next.js 官方博客／文档，并为用户总结主要功能。

示例 2：排查错误

用户：“我在 TypeScript 中遇到了 ‘Cannot find module’ 错误”

Claude 的处理方式：

# Search for the specific error
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "TypeScript Cannot find module error solution" 5

**然后：**从 Stack Overflow 的搜索结果中提取解决方案，并提供逐步修复步骤。

示例 3：时事

用户：“这个月 AI 领域发生了什么？”

Claude 的处理方式：

# Search for recent AI news
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "AI news January 2026" 10

**然后：**综合多个来源的新闻，并总结重要事件。

示例 4：查找文档

用户：“如何使用 React Server Components？”

Claude 的处理方式：

# Search for RSC documentation and tutorials
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "React Server Components guide tutorial" 5

**然后：**查找 React 官方文档和优质教程，并通过示例进行说明。

示例 5：对比研究

用户：“2026 年我应该使用 Vite 还是 webpack？”

Claude 的处理方式：

# Search for recent comparisons
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "Vite vs webpack 2026 comparison" 5

**然后：**分析多方观点，并给出平衡的建议。

高效使用技巧

1. 让查询更具体——包含版本号、日期或具体方面
2. 仔细解析结果——不要只是复制粘贴，而要综合信息
3. 通过多个来源验证——交叉核对重要信息
4. 注明来源——告诉用户你使用了哪些来源
5. 说明局限性——如果搜索没有找到优质结果，请告知用户
6. 进行后续搜索——一次搜索可能不够，需要时进行多次搜索
7. 检查结果日期——查询当前信息时优先选择近期文章
8. 寻找官方来源——优先选择官方文档和权威来源

技术详情

使用的技术

• Playwright Core——浏览器自动化框架
• Chrome DevTools Protocol——底层浏览器控制
• Express.js——HTTP API 服务
• Google + Bing Search——多搜索引擎备用搜索策略
• Bash Scripts——简易命令行接口

系统要求

• Node.js 18+
• 已安装 Google Chrome 或 Chromium
• 用于搜索的互联网连接
• Bridge Server 约需 100MB RAM
• Chrome 实例约需 200MB RAM

文件位置

• 服务：SKILLs/web-search/dist/server/index.js
• 日志：SKILLs/web-search/.server.log
• PID：SKILLs/web-search/.server.pid
• 连接缓存：SKILLs/web-search/.connection

更多资源

• 完整文档：SKILLs/web-search/README.md
• 使用示例：SKILLs/web-search/examples/basic-search.md
• **API 参考：**请参阅 README.md，查看完整的 API 文档
• **故障排查：**请参阅 examples/basic-search.md

支持

遇到问题时：

1. 检查 .server.log 中的错误
2. 运行基本测试：node SKILLs/web-search/scripts/test-basic.js
3. 确认 Chrome 已安装
4. 检查互联网连接
5. 查看上方的故障排查部分

---

**请记住：**此技能可实时获取当前信息。当用户需要了解超出你的知识截止范围的信息，或当前数据的准确性很重要时，请使用此技能。