# dsh-wigolo 使用场景指南

> **一句话**：让 DSH 里的 AI 拥有 18+ 搜索引擎融合、站点爬取、结构化提取、多步深度研究、本地缓存复用、URL 变化监控——**搜索不再是一次性的，而是可积累、可复用、可监控的知识管线**。
>
> 本指南按真实工作流组织，每个场景讲「适合谁、能做什么、怎么用、会得到什么」。
>
> 相关文档：[中文 README](README.zh.md) · [English README](README.md) · [工具详解](docs/TOOLS.md) · [架构说明](docs/ARCHITECTURE.md) · [更新日志](CHANGELOG.md)

---

## 快速开始（安装）

插件包内自带 `cordis.patch.yml`（`dsh.bundle.patch` 声明），`dsh plugin add` 安装后 **host 端自动注册，无需手动配置路由**。以 web profile 为例：

```sh
# 1. 安装到 profile
dsh plugin --profile web add github:tianjiqx/dsh-wigolo

# 2. 把 wigolo daemon 的 bearer token 写入安全文件
echo "YOUR_TOKEN" > ~/.dsh/wigolo-token && chmod 600 ~/.dsh/wigolo-token

# 3. 重启 dsh web 即生效
```

打开侧边栏 **Wigolo** 入口，点 **Test connection** 验证连通性。

**前置条件**：一个运行中的 [wigolo daemon](https://knockoutez.github.io/wigolo/docs/)（v0.2+），HTTP + Bearer token 可达。本机 `127.0.0.1:3333` 是默认值，零额外配置。

**修改配置**（如调整工具超时、开启接管）：在侧边栏 Wigolo 面板的「连接配置」和「接管与工具」Tab 中操作，保存即生效（连接/token 变更即时热更新，接管开关需重启 DSH）。

**直接编辑配置文件**（高级用户）：配置存于 `~/.dsh/wigolo.json`（v2，原子写入）：

```jsonc
{
  "version": 2,
  "connection": {
    "host": "127.0.0.1",       // daemon 地址
    "port": 3333,
    "hostHeader": "auto",       // auto | none | "<字面值>"
    "tokenFile": ""             // "" = ~/.dsh/wigolo-token
  },
  "takeover": false,            // true = wigolo 驱动 web_search + web_fetch
  "tools": {
    "wigolo_search":  { "enabled": true,  "defaults": { "max_results": 10 } },
    "wigolo_crawl":   { "enabled": true,  "defaults": { "max_pages": 50 }, "timeoutMs": 300000 },
    "wigolo_extract": { "enabled": true },
    "wigolo_research":{ "enabled": true,  "timeoutMs": 600000 },
    "wigolo_find_similar": { "enabled": false },
    "wigolo_cache":   { "enabled": true },
    "wigolo_watch":   { "enabled": true }
  },
  "announceToAgent": true
}
```

卸载：`dsh plugin --profile web remove @tianjiqx/dsh-wigolo`，一切效果随插件卸载自动清理。

---

## 认识它（30 秒）

装上插件后，打开任意会话，AI 侧多了一批工具：**wigolo_search · wigolo_crawl · wigolo_extract · wigolo_research · wigolo_find_similar · wigolo_cache · wigolo_watch**。侧边栏多了一个 **Wigolo** 面板，含三个 Tab：**连接配置 · 接管与工具 · 关于**。可选开启「Wigolo 缓存」会话 Tab，只读浏览 daemon 缓存库。

一句话概括这些能力：**让 AI 的搜索从「用完即弃」变成「越搜越有」——搜过的内容自动缓存、站点可以整站爬取、网页可以结构化提取、复杂问题可以多步研究、URL 可以持续监控变化。**

> 小提示：`wigolo_find_similar` 默认关闭（使用频率低），需要时在「接管与工具」Tab 打开即可。其他六个工具默认全部启用。

---

## 场景一：搜索前先翻翻「笔记本」（缓存优先）

**适合谁**：经常让 AI 搜同一个话题、同一批文档的人——不想每次都重新搜一遍。

wigolo daemon 会自动缓存搜索和爬取过的网页全文 markdown。**AI 搜过的东西，下次不用再搜**——直接查本地缓存，秒回、零网络开销。

**怎么用**：

1. 对 AI 说「**搜一下 React 19 的新特性**」——AI 用 `wigolo_search` 搜索，结果自动进缓存；
2. 过了几天，又问「**上次搜的 React 19 那篇文档说了什么**」——AI 先用 `wigolo_cache` 查本地缓存，命中则秒回完整 markdown，不命中才触网；
3. 想看缓存有多大：「**缓存里有多少东西**」——AI 调 `wigolo_cache stats` 返回 URL 数、总大小、时间跨度；
4. 缓存太旧了想清：「**清一下缓存**」——AI 会先跟你确认（这是破坏性操作），确认后才清。

**会得到什么**：重复搜索零延迟，调研过的文档随时可复查全文——AI 的搜索从「金鱼记忆」变成「过目不忘」。

---

## 场景二：把一整个文档站搬进本地（站点爬取）

**适合谁**：需要反复查阅某个文档站（React 文档、Rust 圣经、公司内部 Wiki）的人——不想每次都让 AI 一个个 URL 去抓。

**怎么用**：

1. 对 AI 说「**把 React 官方文档爬下来**」——AI 用 `wigolo_crawl` 从种子 URL 出发，按链接深度自动展开，每页内容都进本地缓存；
2. 可以指定范围：「**只爬 /docs/ 下面的页面，最多 100 页**」——AI 设置 `include_patterns` 和 `max_pages`；
3. 爬完后，后续所有关于 React 文档的问题，AI 都先从缓存找——**离线也能用**（缓存已在本地）；
4. 也可以爬竞品文档、技术规范、API 参考——任何静态站点都行。

**会得到什么**：一整个文档站变成 AI 的「私人图书馆」——首次爬取花几分钟，之后所有查阅都是毫秒级本地检索。

---

## 场景三：从网页里「抠」出结构化数据（结构化提取）

**适合谁**：需要从网页中提取表格、价格列表、API 字段等结构化信息的人——不想手动复制粘贴再整理格式。

**怎么用**：

1. 对 AI 说「**把这个页面的价格表提取出来**」——AI 用 `wigolo_extract` + CSS 选择器（如 `table`、`.price`）提取结构化数据；
2. 更复杂的场景：「**从这个产品页提取名称、价格、评分**」——AI 用字段 schema（JSON 对象）定义提取规则，一次拿到结构化结果；
3. 注意：extract 只支持服务端渲染的 DOM。如果遇到 SPA 页面提取不到内容，AI 会明确告诉你，并建议先用 `wigolo_crawl` 爬取再解析 markdown。

**会得到什么**：网页里的表格、列表、关键字段直接变成结构化 JSON——AI 帮你完成「打开网页 → 找到目标 → 复制整理」的繁琐流程。

---

## 场景四：复杂问题交给「研究员」做多步调研（深度研究）

**适合谁**：需要 AI 对开放性、多面性问题做深度调研的人——「比较 X 和 Y 的优劣」「分析某技术的生态现状」这类需要多方信息综合的问题。

**怎么用**：

1. 对 AI 说「**调研一下 Rust 和 Go 做后端服务的优劣**」——AI 用 `wigolo_research`，自动分解成多个子查询（性能对比、生态对比、学习曲线……），并行搜索多个来源，最后合成一份带引用的研究报告；
2. 可以指定深度：「**快速调研一下**」（`quick`）或「**深入研究**」（`deep`，最多咨询 30 个来源）；
3. 可以限定来源：「**只看 GitHub 和 Stack Overflow 上的内容**」——AI 设置 `include_domains`；
4. 报告自动带回引用链接——每个结论都能溯源。

> 提示：简单事实性问题（「今天有什么新闻」）用 `wigolo_search` 就够了，`wigolo_research` 适合需要多角度综合分析的开放性问题。

**会得到什么**：一份带引用的调研报告——AI 替你完成了「搜十个页面 → 逐个阅读 → 交叉比对 → 总结成文」的繁重工作。

---

## 场景五：让搜索更精准——分类、时效、域名过滤（高级搜索）

**适合谁**：对搜索结果有精确要求的人——只要新闻、只要代码、只要某个域名下的内容、只要最近一周的。

`wigolo_search` 不是普通的关键词搜索，它是一个 **18+ 搜索引擎融合** 的元搜索引擎，支持：

- **分类搜索**：`category` 指定 general / news / code / docs / papers / images——「**搜最新的论文**」自动走 papers 类；
- **时效过滤**：`time_range`（day/week/month/year）或精确日期范围（`from_date` / `to_date`）——「**本周的技术新闻**」；
- **域名过滤**：`include_domains` / `exclude_domains`——「**只搜 GitHub 上的，不要 CSDN 的**」；
- **多变体查询**：用 `|` 分隔多个查询变体——「**搜 rust async | tokio vs async-std**」，并行搜索并去重；
- **深度档位**：`search_depth` 四档——`ultra-fast`（仅缓存）/ `fast`（仅引擎）/ `balanced`（默认）/ `deep`（全文 enrichment，落缓存）；
- **强制刷新**：`force_refresh` 绕过缓存——查实时信息（股价、状态页）时用。

**怎么用**：

1. 直接用自然语言描述需求，AI 自动选择合适的参数；
2. 也可以更精确：「**搜最近一周 github.com 上关于 bun runtime 的 issues**」——AI 组合 `time_range: week` + `include_domains: ["github.com"]` + `category: code`。

**会得到什么**：搜索结果精准度大幅提升——不再被无关内容淹没，不再被过时信息误导。

---

## 场景六：接管官方搜索——让 web_search 也走 wigolo（搜索接管）

**适合谁**：想让 DSH 里所有搜索（包括官方 `web_search` / `web_fetch`）都走 wigolo 的 18+ 引擎融合和本地缓存的人。

默认情况下，`web_search` 走 DSH 官方提供商，`wigolo_search` 是独立的增强工具。开启**接管**后，`web_search` 和 `web_fetch` 也全部由 wigolo 驱动——**所有搜索统一走 wigolo，所有结果自动进缓存**。

**怎么用**：

1. 侧边栏 Wigolo 面板 → 「接管与工具」Tab → 打开「**使用 wigolo 接管 web_search 和 web_fetch**」开关；
2. 重启 DSH 生效（面板会提示）；
3. 之后 AI 调用 `web_search` 时，底层走的是 wigolo 的 18+ 引擎融合——搜索结果更丰富、自动缓存；
4. 想切回官方：关掉开关，重启即可。

> 技术说明：接管开关会自动管理 `~/.dsh/cordis.patch.yml` 中的路由配置（`searchProvider: wigolo`），避免多 provider 冲突（`WEB_PROVIDER_AMBIGUOUS`）。

**会得到什么**：一个开关统一所有搜索入口——无论 AI 用 `web_search` 还是 `wigolo_search`，底层都是同一套 18+ 引擎 + 缓存管线。

---

## 场景七：盯着某个网页，变了就告诉我（URL 变化监控）

**适合谁**：需要持续关注某个网页变化的人——价格页、发布页、状态页、竞品动态——不想每天手动去刷。

**怎么用**：

1. 对 AI 说「**帮我盯着这个页面的变化，每天检查一次**」——AI 用 `wigolo_watch` 创建监控任务，设置 `interval_seconds: 86400`；
2. 可以只监控页面局部：「**只看价格表格那块的变化**」——AI 设置 `selector`（CSS 选择器），忽略页面其他部分的噪音；
3. 批量监控：「**把这三个 URL 都加上监控**」——AI 一次创建多个任务；
4. 管理任务：「**列出所有监控任务**」「**暂停那个价格监控**」「**立即检查一下那个页面**」「**删掉那个已下线的监控**」；
5. 监控任务**跨 daemon 重启持久化**——不会因为重启丢失；
6. 配合定时任务实现通知：让 AI 定期检查监控结果，有变化时通过飞书/站内通知告诉你。

**会得到什么**：网页变化自动感知——不用每天手动刷页面，AI 替你盯着，变了就通知。

---

## 场景八：找相似内容——从一篇好文章出发（相似内容查找）

**适合谁**：找到一篇好文章/好文档后，想找更多类似内容的人——「这篇写得真好，还有没有类似的」。

> 注意：`wigolo_find_similar` 默认关闭，需要在「接管与工具」Tab 手动启用。

**怎么用**：

1. 对 AI 说「**找和这篇文章类似的内容**」并给出 URL——AI 用 `wigolo_find_similar` 从本地缓存和网络中找相关内容；
2. 也可以给概念而非 URL：「**找关于 Rust 异步运行时的类似文章**」——AI 用 `concept` 参数搜索；
3. 如果之前爬过某个站点，相似内容查找会**优先从本地缓存找**——秒回、零网络开销。

**会得到什么**：从一篇好内容出发，发现更多好内容——AI 帮你完成「顺藤摸瓜」的信息发现过程。

---

## 场景九：可视化管理——侧边栏面板 + 缓存浏览 Tab

**适合谁**：想直观看到连接状态、管理工具开关、浏览缓存内容的用户。

**侧边栏面板**（三个 Tab）：

- **连接配置**：daemon 地址/端口/Host 头/token 文件，一键 **Test connection** 实时测试连通性（显示延迟和 daemon 版本），token 可直接在面板粘贴写入（无需终端）；
- **接管与工具**：搜索接管开关、缓存 Tab 开关、七个工具各自的启用/禁用开关，保存即生效；
- **关于**：插件版本、相关链接、Host 头技术说明、旧版迁移指引。

**「Wigolo 缓存」会话 Tab**（可选开启）：

- 默认关闭，在「接管与工具」Tab 打开；
- 开启后出现在会话顶部，两个子页：
  - **缓存浏览**：顶部统计条（URL 数 / 总大小 / 时间跨度）+ 关键词过滤 + 「仅看本会话期间」开关 + 列表（URL/标题/抓取时间，倒序）+ 点击展开 markdown 全文（懒加载）；
  - **监控任务**：所有 watch 任务列表 + 行内快捷操作（立即检查 / 暂停 / 恢复）。

**怎么用**：

1. 侧边栏点 Wigolo 图标打开面板；
2. 首次使用：在「连接配置」Tab 填 daemon 地址、写 token、点测试——全 GUI 操作，无需终端；
3. 想浏览缓存：「接管与工具」Tab 打开缓存 Tab 开关 → 会话顶部出现「Wigolo 缓存」Tab。

**会得到什么**：连接状态一目了然、工具开关随手可调、缓存内容可视化浏览——不用全靠对话，GUI 也能管理。

---

## 还有这些能力（一句话索引）

- **参数裁剪设计**：wigolo daemon 的 MCP 工具每个有 15-25 个参数，插件裁剪到 6-10 个高频参数——模型选参数更准、用起来更简单；
- **密钥安全**：token 存于 `~/.dsh/wigolo-token`（0600 权限），永不进配置 JSON，永不回传浏览器；
- **面板回环栅栏**：面板 API 路由仅限回环访问（远端地址 + Host + sec-fetch-site + origin 四重校验），不暴露给 LAN 部署；
- **配置热更新**：连接/token/工具开关变更即时生效（MCP 客户端热重配），仅接管开关需重启 DSH；
- **Fail-loud 配置校验**：配置文件中的未知字段会触发警告并提示「你是不是想写 XX」（编辑距离匹配），不会默默忽略；
- **旧版自动迁移**：环境变量（`WIGOLO_HOST_IP` / `WIGOLO_PORT`）和已有 token 文件在首次运行时自动导入；
- **面板国际化**：侧边栏面板支持中英文双语（跟随 DSH 语言设置）。

---

## 工具速查表

| 工具 | 用途 | 典型触发语 | 超时 |
|------|------|-----------|------|
| `wigolo_search` | 高级搜索（18+ 引擎、分类、时效、域名过滤） | 「搜一下 XX」「最近有什么关于 XX 的新闻」 | 60s |
| `wigolo_crawl` | 站点爬取（入本地缓存） | 「爬一下这个文档站」「把这个 Wiki 抓下来」 | 300s |
| `wigolo_extract` | 结构化提取（CSS 选择器 / 字段 schema） | 「提取这个页面的价格表」「把这个页面的关键字段抠出来」 | 60s |
| `wigolo_research` | 多步深度研究（分解 + 并行 + 综合报告） | 「调研一下 XX 的优劣」「深入分析 XX」 | 600s |
| `wigolo_find_similar` | 相似内容查找 | 「找和这篇类似的文章」（默认关闭） | 120s |
| `wigolo_cache` | 本地缓存搜索/统计/清除 | 「缓存里有什么」「缓存有多大」「清一下缓存」 | 30s |
| `wigolo_watch` | URL 变化监控 | 「盯着这个页面」「每天检查一次这个 URL」 | 120s |

---

## 三条原则

1. **Agent 优先**：写操作（搜索/爬取/清除/创建监控）由 AI 工具承担——模型判断 query 变体、深度、域名过滤更准；GUI 只做只读浏览（缓存浏览/监控状态），且默认关闭；
2. **缓存即资产**：每一次搜索、爬取都在积累本地缓存——后续查阅零延迟、离线可用、跨会话复用；
3. **安全默认**：token 不进配置、面板仅限回环、破坏性操作先确认——开箱即安全，无需额外加固。

---