web-access git:20260821.23fede5B

Immutable. This exact content is served forever at /api/v1/blob/99b6cc5aadf5fceb.

---
name: web-access
license: MIT
description:
  复杂 web 任务的方法论与跨 session 站点经验库。Use when：抓取反爬或需登录态的平台（小红书、微信公众号、微博、推特、知乎等）、
  目标站点结构未知需要边看边探索、多来源交叉核实信息、分析页面里的图片/视频内容、并行调研多个独立来源、
  或 web_search/web_fetch 拿不到目标内容需要升级到真实浏览器时。
  简单的已知 URL 抓取或单步页面操作（无登录/反爬因素）不需要加载本 skill——直接用 web_fetch / browser 工具即可。
metadata:
  origin: 浏览方法论改编自 web-access（一泽 Eze，MIT）；执行层改用 octo 原生 browser 工具，无 Node 依赖
---

# Skill: web-access

复杂 web 任务的方法论：把内置的 `web_search` / `web_fetch` 与 `browser` 工具（驱动你日常的、已登录的 Chrome/Edge）按场景编排起来，并跨 session 积累站点经验。

## 前置：浏览器自动化

`web_search` / `web_fetch` 开箱即用，不需要任何配置。

只有当任务需要**操作浏览器界面 / 登录态 / 动态渲染页面**时，才需要 `browser` 工具能连上你日常的浏览器。一次性配置：

1. 在要用的浏览器打开 inspect 页面并勾选 **Allow remote debugging for this browser instance**（可能需重启浏览器）：
   - Chrome：`chrome://inspect/#remote-debugging`
   - Edge：`edge://inspect`，然后点左侧 **Remote debugging**
2. 或直接运行 `octo browser setup`，它会给出上面的步骤、验证连接、并把端口写进配置。

连上后 `browser` 工具天然携带登录态——大多数常用网站都已登录。无独立浏览器、无需命令行参数。

> 部分站点对浏览器自动化检测严格，存在账号限流/封禁风险。操作社交平台（小红书等）**强烈建议用小号**。Agent 继续操作即视为接受。

## 浏览哲学

**像人一样思考，兼顾高效与适应性地完成任务。**

带着目标进入，边看边判断，遇到阻碍就解决，发现内容不够就深入——全程围绕「我要达成什么」做决策。

**① 拿到请求** — 先明确成功标准：什么算完成？需要获取什么信息、执行什么操作、达到什么结果？这是后续所有判断的锚点。

**② 选择起点** — 根据任务性质、平台特征、达成条件，选一个最可能直达的方式作为第一步去验证。需要操作页面、需要登录态、已知静态方式不可达的平台（小红书、微信公众号等）→ 直接用 `browser`。

**③ 过程校验** — 每一步的结果都是证据。用结果对照①的成功标准：路径在推进吗？结果的质量、相关度、量级是否指向目标可达？发现方向错了立即调整，不在同一方式上反复重试——搜索没命中不等于"还没找对方法"，也可能是"目标不存在"。遇到弹窗、登录墙，先判断它是否真的挡住了目标：内容可能已在 DOM 中，交互只是展示手段。

**④ 完成判断** — 对照成功标准确认完成才停止；但也不为了"完整"过度操作、浪费代价。

## 联网工具选择

确保信息真实性，一手信息优于二手。搜索引擎和聚合平台是**发现入口**，不是真伪的**证明**。

| 场景 | 工具 |
|------|------|
| 搜索摘要、关键词结果、发现信息来源 | **web_search** |
| URL 已知，按 prompt 从页面提取信息 | **web_fetch**（直接传原始 URL；HTML 自动转成干净 Markdown，正文优先、链接绝对化） |
| URL 已知，需要页面原始 HTML（meta、JSON-LD 等结构化字段） | **web_fetch** 加 `clean=false` |
| 非公开内容，或已知静态层无效的平台（小红书、公众号等） | **browser**（直接，跳过静态层） |
| 需要登录态、交互操作，或要像人一样在浏览器内自由导航探索 | **browser** |

`web_search` / `web_fetch` 都不处理登录态。`browser` 不要求 URL 已知——可从任意入口出发，靠页面内搜索、点击、跳转找到目标。

## browser 工具要点

action 级用法（observe / click / eval / record / replay 等的参数与语义）以 `browser` 工具自身的 schema 描述为准，此处不重复。schema 之外的判断准则：

- 重复性流程（批量操作、定期取数）优先录制回放（record → replay），而非每次盲驱动。
- 收尾用 `close` 关闭自己开的标签页，保留用户原有标签页。

### 程序化 vs GUI 交互

- **程序化**（navigate 构造 URL、eval 操作 DOM）：快、精确，但对网站不是正常用户行为，可能触发反爬。
- **GUI 交互**（observe→click→type→scroll）：网站不限制正常 UI 操作，确定性最高，但步骤多、慢。

根据对平台的了解灵活选择。GUI 交互也是有效探测：一次真实交互能观察站点实际行为（URL 模式、必需参数、跳转逻辑），为后续程序化操作提供依据；程序化受阻时它是可靠兜底。

**站点内交互产生的链接是可靠的**：通过卡片/条目/按钮等可交互单元自然到达的 URL，天然携带平台所需的完整上下文。手动构造的 URL 可能缺隐式必要参数，导致被拦截、错误页、触发反爬。提取 URL 时保留完整地址，不裁剪参数。

### 媒体与视频

- 内容在图片里时，用 `eval` 从 DOM 直接拿图片 URL，比全页截图精准。公开资源直接下载本地读取；需登录态的资源才在浏览器内 navigate + screenshot。
- 提图前先 `scroll` 到底触发懒加载，否则部分图片未加载。
- 视频：用 `eval` 操控 `<video>`（取时长、seek、播放/暂停），配合 `screenshot` 离散采帧分析。

### 技术事实
- 页面中有大量已加载但未展示的内容（轮播非当前帧、折叠区块、懒加载占位），存在于 DOM 但不可见。以数据结构（容器、属性、节点关系）为单位思考可直接触达。
- 平台返回的"内容不存在""页面不见了"不一定真实，也可能是访问方式问题（URL 缺参数、触发反爬）。
- 短时间密集打开大量页面可能触发反爬风控。

### 登录判断

浏览器天然携带登录态，大多数常用网站已登录。核心问题只有一个：**目标内容拿到了吗？**

先尝试获取目标内容。只有确认**拿不到**且判断登录能解决时，才告诉用户：
> "当前页面在未登录状态下无法获取[具体内容]，请在你的浏览器中登录 [网站名]，完成后告诉我继续。"

登录后无需重启任何东西，直接刷新页面继续。

## 并行调研：子 Agent 分治

任务含多个**独立**目标时（同时调研 N 个来源），分治给子 Agent 并行。

- **搜索/抓取类**（web_search / web_fetch，无状态）：天然适合并行，互不干扰。
- **browser 浏览器操作**：当前会话是单页面、进程级共享的——**不要让多个子 Agent 同时驱动浏览器**，会互相抢同一个页面。浏览器交互保持单序列；把并行留给无状态的搜索/抓取。

子 Agent prompt 写法：**目标导向，而非步骤指令**。
- 写 `必须加载 web-access skill 并遵循指引`，子 Agent 会自动加载，无需复制内容或指定路径。
- 描述目标（「获取」「调研」「了解」），避免暗示手段的动词（「搜索」「抓取」）——「搜索 xx」会把子 Agent 锚定到 web_search，而有些反爬站点要 browser 直接访问主站才有效。

| 适合分治 | 不适合分治 |
|----------|-----------|
| 目标相互独立，结果互不依赖 | 目标有依赖，下一个需要上一个的结果 |
| 每个子任务量足够大（多页抓取、多轮搜索） | 简单单页查询，分治开销大于收益 |
| 几次 web_search / web_fetch 能完成的并行查询 | 需要连续浏览器交互的有状态流程（保持单序列） |

## 信息核实

核实的目标是**一手来源**，而非更多二手报道。多个媒体引用同一错误会造成循环印证假象。搜索/聚合平台用于**定位**，不用于**证明**。找到来源后直接访问读原文。同一原则适用于工具能力/用法——官方文档/源码是一手来源，不确定先查，不猜测。

| 信息类型 | 一手来源 |
|----------|---------|
| 政策/法规 | 发布机构官网 |
| 企业公告 | 公司官方新闻页 |
| 学术声明 | 原始论文/机构官网 |
| 工具能力/用法 | 官方文档、源码 |

**找不到官网时**：权威媒体的原创报道（非转载）可作次级依据，但需声明："未找到官方原文，以下核实来自[媒体名]报道，存在转述误差可能。"单一来源时同样声明。

## 站点经验

操作中积累的特定网站经验，按域名存在 `~/.octo/site-patterns/<domain>.md`（本地目录，独立于技能文件，跨 session 与版本升级持久复用）。

确定目标网站后，若已有对应站点经验文件，读取它获取先验（平台特征、有效模式、已知陷阱）。经验标注发现日期，当作"可能有效的提示"而非"保证正确的事实"——按经验失败就回退通用模式并更新文件。

`browser` 操作成功后，若发现值得记录的新站点/新模式（URL 结构、平台特征、操作策略），主动写入对应文件。只写验证过的事实，不写猜测。

格式：
```markdown
---
domain: example.com
aliases: [示例, Example]
updated: 2026-03-19
---
## 平台特征
架构、反爬行为、登录需求、内容加载方式等事实

## 有效模式
已验证的 URL 模式、操作策略、选择器

## 已知陷阱
什么会失败以及为什么
```