Web Assistant

核心规则

1. 先 API 后 UI

API 直调 > URL 参数驱动 > UI 交互驱动。

2. 登录态先行

涉及需登录站点，先校验/恢复登录态。

3. 探索驱动提取

新站点先做六步探索（site-exploration.md），再编写提取逻辑。

4. 知识固化为站点指南

调研完成生成 references/sites/<site>/guide.md。创建文件前先询问用户。

5. 渐进披露

详细信息在 references/ 中按需加载。

6. 用户指令优先

evaluate 确认 → API 直调 → Playwright 选择器 → snapshot 重试。

何时使用

• 探索新网站结构（页面布局、URL 模式、API 端点）
• 提取数据（搜索 / 翻页 / 列表 / 详情）
• 处理防盗链下载
• 固化调研知识为站点指南

所需权限

| 权限 | 用途 | |------|------| | filesystem.write | 读写站点指南 | | filesystem.read | 读取站点指南 | | browser | navigate / evaluate / snapshot / run_code_unsafe | | skill | 调用 opencode-creator |

数据存储

| 路径 | 用途 | |------|------| | auth/<site>.json | 登录态持久化 | | ./Downloads/<site>/ | 下载文件 | | references/sites/<site>/guide.md | 站点指南 |

工作流

A. 登录态管理

evaluate 检测登录 → run_code_unsafe 注入 cookie → 保存 auth/<site>.json。

B. 网站探索（六步）

navigate + snapshot → 捕获网络请求 → evaluate 验证 → 记录选择器 → 测试边界 → 生成 guide.md。详见 references/site-exploration.md。

C. 数据提取

API 直调 > URL 驱动 > UI 交互。详见 references/data-extraction.md。

D. 文件下载

navigate 同域 → evaluate fetch (credentials: include) → blob → 触发下载。详见 references/download-patterns.md。

E. 生成站点指南

创建 references/sites/<site>/guide.md，含 API/选择器/URL 模式。

F. 互动浏览

确认有头可见 → navigate → 等待指令 → 按规则 6 执行。详见 references/interactive-browsing.md。

G. AI 辅助提取

snapshot → AI 分析 → evaluate 提取 → 验证 → 固化到 guide.md。

快速参考

| 任务 | 参考 | |------|------| | 网站探索 | references/site-exploration.md | | 数据提取 | references/data-extraction.md | | 防盗链下载 | references/download-patterns.md | | 互动浏览 | references/interactive-browsing.md |

常见陷阱

| 陷阱 | 原因 | 解决 | |------|------|------| | SPA URL 导航不渲染 | SPA 路由由 JS 驱动 | 用 API 直调 | | HttpOnly cookie 读不到 | document.cookie 不暴露 | page.context().cookies() | | 下载 URL 403 | CDN 防盗链 | 同域 navigate 再 fetch | | API 端点写死 | 接口版本更新 | 每次 evaluate 确认 |

边界

• 支持 Firefox 浏览器
• 下载文件存 ./Downloads/<site>/
• 不暴力爬取