web-search

Files (2)

• .gitignore
• SKILL.md

SKILL.md (first lines)

# Web Search 工具决策

> 完整 Tradeoff 矩阵和经验沉淀参考 Obsidian 文章 OBA-w8s3k7p2。
> `${CLAUDE_SKILL_DIR}` 指本 SKILL.md 所在目录。

## 0. 一句话决策（90% 场景）

```
拿到信息获取请求
  │
  ├─ GitHub URL？────────→ 原生 `gh` 结构化获取
  │                          ↓ `gh` 确实无法获取所需内容
  │                         Layer 3 / Layer 4 网页降级
  │
  ├─ 其他 URL？──────────→ Layer 1（OpenCLI 路由）
  │                          ├─ 内置 100+ 站点
  │                          ├─ External CLI 桥接（lark/notion/...）
  │                          └─ 本机扩展 CLI（yuque-cli/linear/...）
  │                          ↓ 全部未命中
  │                         Layer 3（已知 URL 读取）
  │                          ↓ 需要登录/SPA 失败
  │                         Layer 4（浏览器 CDP 兜底）
  │
  └─ 没有 URL ───────────→ Layer 2（通用搜索降级链）
                             WebSearch → Tavily → DuckDuckGo
```

**核心原则**：零成本优先、按需升级、一工具失败立即换下一级，**不要在同一工具反复重试**。

## 1. 首次使用提示（仅出现一次）

进入 skill 时先读 `${CLAUDE_SKILL_DIR}/experience.local.md` 顶部。如果**没有** `setup-completed: ` 标记：

> 💡 提示：跑 `/web-search setup` 可一次性完成 Tavily API Key 配置 + 扫描本机的搜索/采集 CLI 工具（语雀/Linear/Notion 等）。配好后下次自动用上，不会有打断。

跑过一次后，setup 命令会在 experience.local.md 顶部写入 `setup-completed: {ISO 时间}`，从此不再提示。

## 1.5 GitHub 特殊路由：原生 `gh` 绝对优先

当 URL 为 `github.com` 或任务明确涉及 GitHub 仓库、文件、PR、Issue、Release、Actions 等信息时：

1. **必须首先使用本机原生 `gh` CLI**，优先调用 `gh api`，或使用 `gh repo` / `gh pr` / `gh issue` / `gh release` / `gh run` 等结构化命令。
2. 需要阅读仓库源码时，优先用 `gh api repos/<owner>/<repo>/contents/<path>` 、Git Trees API 或临时 clone，不先抓 GitHub HTML 页面。
3. 只有在 `gh` 已证明无法取得目标内容时（例如 GitHub 之外的嵌入页面、必须渲染的视觉内容），才降级到 Layer 3 网页读取，再必要时进入 Layer 4 浏览器。
4. 不得因为 OpenCLI 未安装、daemon 异常或 Extension 未连接而跳过 `gh`；GitHub 路由不依赖 OpenCLI。

## 2. Layer 1：OpenCLI 站点路由（URL 已知）

### 2.1 依赖检查

> GitHub 任务不执行本节的 OpenCLI 前置检查，直接按 1.5 节调用原生 `gh`。

```bash
which opencli >/dev/null && opencli doctor 2>&1 | head -3
```

期望三项全绿（Daemon / Extension / Connectivity）。未安装时跳过 Layer 1，**不引导安装**。

### 2.2 高频站点清单（覆盖 80% 场景）

> 域名命中此表 → **必须**用 OpenCLI 对应命令；不命中 → 进 2.4/2.5/2.6。

| 类别 | 域名 | 命令 | 认证 |
|------|------|------|------|
| **视频/播客** | youtube.com / youtu.be | `youtube search/transcript/video/download` | 🔐 |
| | bilibili.com | `bilibili search/subtitle/video/favorite` | 🔐 |
| | xiaoyuzhou.fm | `xiaoyuzhou transcript/episode/search` | 🌐 |
| | apple-podcasts | `apple-podcasts episodes/search/top` | 🌐 |
| | spotify | `spotify ...` | 🌐 |
| **社交** | twitter.com / x.com | `twitter search/thread/bookmarks` | 🔐 |
| | reddit.com | `reddit search/read` | 🔐 |
| | xiaohongshu.com | `xiaohongshu search/note` | 🔐 |
| | weibo.com | `weibo search/post` | 🔐 |
| | bsky.app | `bluesky ...` | 🌐 |
| | jike (即刻) | `jike ...` | 🔐 |
| **技术社区** | news.ycombinator.com | `hackernews search/read` | 🌐 |
| | stackoverflow.com | `stackoverflow search` | 🌐 |
| | v2ex.com | `v2ex topic/search` | 🌐/🔐 |
| | linux.do | `linux-do ...` | 🔐 |
| | dev.to | `devto ...` | 🌐 |
| | huggingface.co | `hf search/dataset/model` | 🌐 |
| **资讯/内容** | zhihu.com | `zhihu answer/search` | 🔐 |
| | 36kr.com | `36kr article/search/hot` | 🌐 |
| | medium.com | `medium ...` | 🔐 |
| | substack.com | `substack ...` | 🌐/🔐 |
| | mp.weixin.qq.com | `weixin article/account` | 🔐 |
| | douban.com | `douban subject/search` | 🔐 |
| **学术** | arxiv.org | `arxiv search/paper` | 🌐 |
| | wikipedia.org | `wikipedia ...` | 🌐 |
| | scholar.google.com | `google-scholar search` | 🌐 |
| **财经** | eastmoney.com | `eastmoney ...` | 🌐/🔐 |
| | xueqiu.com | `xueqiu ...` | 🔐 |
| **AI 平台** | chatgpt.com | `chatgpt ...` | 🔐 |
| | gemini.google.com | `gemini ...` | 🔐 |
| | doubao.com | `doubao ...` | 🔐 |
| | deepseek.com | `deepseek ...` | 🔐 |
| | Google 搜索（无登录）| `opencli google search "<keyword>"` | 🌐 |

**认证标识**：🌐 public（无需登录） / 🔐 cookie（需本机 Chrome 已登录该站点） / 🔧 ui（需本机已装对应桌面应用）

### 2.3 重操作确认

执行前**必须询问用户**：字幕提取（`youtube transcript` / `bilibili subtitle`）、下载媒体（`<site> download`）、批量搜索（多个 opencli 组合）。

不需要确认：单次 search、获取详情、热门趋势。

### 2.4 未命中 → grep 兜底

URL 域名不在 2.2 表里时：

```bash
opencli list 2>&1 | grep -i <域名前缀或关键词>
```

命中 → 用该命令；未命中 → 进 2.5 / 2.6。

### 2.5 External CLI 桥接

OpenCLI 主命令下挂载了第三方工具，与内置站点同等优先级：

From wangjs-jacky/jacky-skills, MIT.

More from wangjs-jacky/jacky-skills