1. 项目概述：一套面向AI Agent的通用网页交互技能库

如果你正在使用GitHub Copilot CLI、OpenClaw/Antigravity、Claude Code或Cursor这类AI Agent，并且经常需要它们帮你浏览网页、搜索信息或整理内容，那你可能和我一样，经历过一个令人头疼的阶段：每次遇到一个新网站，都得从头开始教Agent怎么操作，或者写一堆一次性的、难以复用的指令。这个过程不仅低效，而且Agent的表现也时好时坏，尤其是在处理那些需要登录、有复杂交互或是单页应用（SPA）的网站时，失败率会显著上升。

skill-browser 这个项目，正是为了解决这个痛点而生的。它不是一个独立的工具，而是一套可复用的“技能”（Skills）集合，专门设计来赋予AI Agent“运行时感知”（Runtime-aware）的网页交互能力。简单来说，它教会了Agent一个核心原则： 面对不同的网站，应该选择最优的执行路径，而不是无脑地启动浏览器去抓取 。这套技能库将我在实战中验证过的浏览器工作流，打包成了几个清晰、可分享、能直接安装的Copilot Skills，让Agent能像经验丰富的人类一样，灵活、高效地在不同平台上获取信息。

这套技能的核心价值在于它的“分层”和“通用”设计思想。它不鼓励为每个网站都编写硬编码的规则，而是提供了一套方法论：先尝试通用的适配策略去探索陌生网站；如果发现这个网站的交互模式稳定且值得复用，再将其沉淀为专用的“站点配置”（Site Profile）；最后，在执行具体的搜索、筛选和摘要任务时，智能地选择最可靠、成本最低的执行路径（比如优先使用命令行工具 opencli ，其次用公开API，最后才考虑浏览器自动化）。无论你是想快速了解一个陌生网站的结构，还是想把某个平台的自动化流程固定下来，亦或是需要Agent帮你从B站、YouTube、小红书等平台高效地搜集和总结信息， skill-browser 都提供了现成的、经过实战检验的解决方案。

2. 核心设计理念与架构拆解

2.1 为什么需要“运行时感知”？

传统的AI Agent网页交互，往往存在一个“默认路径依赖”问题：无论目标网站是什么，Agent都倾向于启动一个无头浏览器（如Playwright），然后模拟点击、输入等操作来完成任务。这种方法虽然通用，但存在几个致命缺陷：

1. 性能与成本 ：启动和运行浏览器实例消耗大量计算资源和时间，对于简单的信息获取任务来说过于笨重。
2. 稳定性差 ：网页的动态加载、反爬虫机制、登录状态维护等问题，都会导致自动化脚本非常脆弱，容易失败。
3. 确定性低 ：基于HTML解析和模拟点击的流程，受页面布局变化影响极大，一个CSS类名的改动就可能导致整个流程崩溃。

skill-browser 提出的“运行时感知”架构，从根本上改变了这一思路。它的核心模型分为四层：

• 认知层（Cognition Layer） ：由大语言模型（LLM）担任规划者（Planner）和推理者（Reasoner），负责理解用户意图、分解任务步骤。
• 执行层（Execution Layer） ：提供多种执行引擎。不再是单一的浏览器，而是根据平台特性，智能选择 opencli （命令行工具）、 fetch （调用公开API）或真正的浏览器代理（Browser Agent）。
• 记忆层（Memory Layer） ：存储可复用的“站点配置”（Site Profiles）和一个“平台注册表”（Platform Registry），记录各个平台的最佳接入方式。
• 环境层（Environment Layer） ：即目标网站本身。

这个架构的关键在于， 执行路径的选择权被交给了Agent（基于记忆层的知识），而不是写死的 。Agent需要根据目标平台，动态选择最优解。

2.2 执行路由的智能决策逻辑

具体到代码层面，Agent在面对一个任务（例如“搜索B站关于AI的视频”）时，会遵循一个清晰的决策树：

if (目标平台在 opencli 支持列表中) {
    优先使用 opencli 命令（确定性高、零LLM调用成本、可复用会话）；
} else if (目标平台提供公开API) {
    使用 fetch 调用API（返回结构化JSON，无需渲染页面）；
} else if (网站是服务端渲染且可公开访问) {
    使用 web_fetch 或启动轻量级Playwright（仅提取元数据）；
} else {
    要求提供登录状态的浏览器，或直接声明任务无法执行。
}

这个逻辑确保了效率最大化。以B站为例，直接调用 opencli 内建的 bilibili search 命令，远比启动浏览器、打开B站首页、找到搜索框、输入关键词、点击搜索按钮、等待结果加载、再解析HTML这一系列操作要快得多、稳得多。

2.3 平台接入分级策略

为了将上述逻辑固化下来，项目对常见平台进行了分级，形成了清晰的“平台接入分级表”。这个表是技能库的“知识核心”，它指导Agent在不同场景下做出最佳选择。

平台	opencli支持	公开API	SSR可抓取	分级	推荐路径
Bilibili	✅ bilibili search	✅ api.bilibili.com	部分	T1	opencli
YouTube	✅ youtube search	✅ Data API	部分	T1	opencli
HackerNews	✅ hackernews top	✅ hn.algolia.com	✅ SSR	T1	opencli 或 fetch
Wikipedia	✅ wikipedia search	✅	✅ SSR	T1	任意路径均可
小红书	✅ xiaohongshu search	❌	❌ SPA	T2	仅 opencli
抖音/TikTok	✅ tiktok search	❌	❌ SPA	T2	仅 opencli
知乎	✅ zhihu search	❌	❌ 需登录	T2	仅 opencli
arXiv	❌	✅ export.arxiv.org	✅ SSR	T3	fetch / web_fetch
BBC新闻	✅ bbc news	❌	✅ SSR	T3	fetch / web_fetch

分级定义与实战意义：

• T1 (首选opencli) ：平台有官方或稳定的命令行工具集成。这是最理想的状况，执行速度快、结果稳定、几乎零成本。 在开发自己的技能时，应优先寻找并集成此类平台的CLI工具。
• T2 (依赖opencli) ：平台多为复杂的单页应用(SPA)或需要登录，公开API不可用，SSR抓取困难。 opencli 通过其“浏览器桥接”技术，能复用已登录的浏览器会话，是唯一可靠的自动化途径。 这提示我们，对于主流但封闭的社交/内容平台，逆向工程其网页交互不如寻找成熟的会话复用方案。
• T3 (API/SSR优先) ：平台没有专门的CLI工具，但提供友好的公开API或完整的服务端渲染。此时应避免动用重型浏览器，优先使用 fetch 获取结构化数据或轻量级抓取。 这适用于许多信息型网站，如新闻、论文、文档站点。

注意 ：这个分级表不是静态的，它会随着 opencli 等工具的支持范围扩大而更新。你的团队也可以维护自己的内部版本，加入公司内网系统的接入信息。

3. 三大核心技能详解与实操指南

skill-browser 主要提供了三个核心技能，它们构成了一个从探索到沉淀再到复用的完整工作流。我强烈建议按照这个顺序来使用和理解它们。

3.1 web-adapt ：通用网站适配探索器

当你面对一个全新的、没有现成规则的网站时，第一个念头不应该是“我该怎么写它的爬虫”，而应该是“我能不能先用通用方法把它跑通”。 web-adapt 技能就是为此设计的。

它的核心任务 是引导Agent以“探索者”而非“征服者”的心态去接触陌生网站。技能会指示Agent执行以下步骤：

1. 环境检查 ：首先判断网站是否可公开访问，是否需要登录或存在地域限制。
2. 模式识别 ：尝试识别页面上的关键交互元素，如搜索框、提交按钮、链接（特别是可能打开新标签页或弹窗的链接）。
3. 策略尝试 ：按照成功率递减的顺序尝试通用交互策略：
   • Enter策略 ：在搜索框输入后直接按回车。
   • Click策略 ：寻找并点击明显的“搜索”、“提交”按钮。
   • Opener策略 ：点击可能在新标签页打开结果的链接。
   • Popup策略 ：处理可能出现的弹窗或模态框。
4. 可行性评估 ：根据探索结果，判断该网站是否适合以及有必要被沉淀为一个专用的 site-profile 。

实操示例与心得 ： 假设你想让Agent学习“豆瓣读书”的搜索。你可以对Agent说：“ /web-adapt 豆瓣读书网站，我想搜索书籍。” Agent会打开豆瓣读书页面，尝试找到搜索框，输入关键词，并观察是回车生效还是需要点击搜索按钮。在这个过程中，你可能会发现豆瓣的搜索结果是异步加载的（SPA），直接回车可能无效，需要点击搜索按钮。 web-adapt 会记录下这一发现，并给出建议：“该网站为SPA，交互依赖JavaScript点击事件。通用适配基本成功，但稳定性受前端变化影响。建议考虑沉淀为 site-profile 以固化‘点击搜索按钮’这一步骤。”

关键技巧 ：使用 /web-adapt 时，最好提供明确的目标，比如“搜索功能”或“翻页功能”。这能帮助Agent聚焦，避免在无关的页面元素上浪费时间。

3.2 site-profile ：站点配置沉淀器

当 web-adapt 确认某个网站的交互流程可行且值得复用时，就该 site-profile 上场了。它的目标是将一次性的、脆弱的探索过程，转化为稳定的、可重复使用的“配置”。

它的工作流程如下 ：

1. 选择器调查 ：不再依赖可能变化的文本或直观布局，而是寻找稳定的、语义化的CSS选择器、 data-* 属性或XPath。例如，豆瓣的搜索按钮可能有一个固定的 class="search-btn" 或 data-action="search” 。
2. 失败模式分类 ：分析在 web-adapt 过程中可能失败的原因，并定义应对策略。例如，“如果搜索按钮未加载，等待2秒后重试”；“如果出现登录弹窗，则终止流程并提示需要登录”。
3. 创建配置驱动Profile ：将找到的稳定选择器和处理逻辑，以结构化的方式（如YAML或JSON）保存下来。一个简单的profile可能长这样：

   site: douban_book
   actions:
     search:
       input_selector: 'input[name="q"]'
       submit_selector: 'button[type="submit"]'
       wait_after: 2s # 等待结果加载
   

4. 验证流程 ：用创建好的profile重新运行任务，验证其是否比通用适配更稳定。同时，可以对比基于启发式规则（heuristic）的流程和基于LLM规划的流程，哪种效果更好。

实操心得与避坑指南 ：

• 选择器的稳定性是第一位的 。避免使用包含动态哈希值（如 class=”jsx-abc123” ）或绝对位置的选择器。优先选择 name 、 id （如果稳定）、 data-testid 或具有明确语义的类名。
• 等待策略至关重要 。对于SPA网站，在关键操作（点击、提交）后必须添加合理的等待时间，等待网络请求完成和DOM更新。硬编码的 sleep 不推荐，有条件应使用“等待某元素出现”作为判断标准。
• 不是所有网站都值得做Profile 。如果网站结构过于简单（如一个静态搜索表单），通用适配已经足够稳定；或者网站变化极其频繁，维护Profile的成本会高于收益。 site-profile 技能本身也包含了这种成本效益评估的逻辑。

3.3 content-summary ：内容搜索与摘要生成器

这是最能体现“运行时感知”价值的技能。当你的最终目标是获取信息（如“给我找5个B站上最好的Python教程视频并总结”）时，你并不关心Agent具体如何操作，只关心结果的质量和速度。 content-summary 技能封装了从搜索、排序到摘要的完整高阶工作流。

它的执行步骤 ：

1. 平台识别与路径选择 ：根据用户查询中的关键词（如“B站”、“YouTube”、“小红书”）或URL，自动匹配平台分级表，选择最优执行路径（T1用 opencli ，T3用 fetch ）。
2. 执行搜索与初步筛选 ：使用选定的路径执行搜索，并获取原始结果列表。技能会指示Agent根据相关性、热度、日期等维度对结果进行初步排序。
3. 元数据丰富 ：为了生成高质量的摘要，Agent可能需要打开Top结果（如前5名）的详情页，以获取描述、评论数、时长等更详细的信息。这里同样遵循路径选择原则，详情页的打开也优先使用 opencli 的 open 命令或直接API。
4. 摘要生成与格式化 ：最后，Agent需要为每个筛选出的结果生成一段简洁的摘要，并附上原文链接和关键信息（如作者、时长、置信度说明）。输出格式通常是清晰的Markdown列表。

实操示例 ： 你对Agent说：“ /content-summary 在B站和知乎上搜索‘大语言模型实战’，各找3个最相关的内容，用中文总结。”

1. Agent识别出B站（T1）和知乎（T2）均优先使用 opencli 。
2. 并行或依次执行 opencli bilibili search “大语言模型实战” 和 opencli zhihu search “大语言模型实战” 。
3. 从返回的JSON结果中，分别筛选出3个最相关的内容（可能综合了播放量、点赞数、回答数等）。
4. 为了丰富摘要，对每个视频和回答，再用 opencli 打开其详情页获取描述。
5. 最终生成一份合并的报告，清晰地列出B站视频和知乎回答的标题、链接、作者和核心要点摘要。

重要提示 ：这个技能的强大之处在于其“跨平台统一抽象”。用户无需知道B站和知乎背后截然不同的技术栈，只需发出一个自然语言指令，就能得到格式一致、信息丰富的聚合结果。这极大地降低了使用AI进行信息搜集的门槛。

4. 安装、配置与跨平台使用指南

4.1 一键安装与技能管理

项目提供了极简的安装脚本，这是最推荐的入门方式。

# 1. 克隆仓库
git clone https://github.com/AllenS0104/skill-browser.git
cd skill-browser

# 2. 运行安装脚本（安装4个核心技能别名）
node install.js

安装脚本提供了多个选项，适应不同需求：

• node install.js --cn ：安装核心技能及其中文别名（如 网站适配 ）。
• node install.js --all ：安装仓库中所有的13个别名（适合想要完整集合的用户）。
• node install.js --list ：列出所有可用的技能。
• node install.js --clean ：卸载所有由本仓库安装的技能。

安装完成后，需要在你的AI Agent中重新加载技能列表。以GitHub Copilot CLI为例，在聊天界面输入：

/skills reload
/skills list

你应该能看到 adapt , profile , summary 等技能出现在列表中。

4.2 技能调用方式详解

你不需要每次都死板地使用 /技能名 的格式。Agent对技能调用的理解是分层的，按确定性从高到低排列：

1. 显式斜杠命令 ： /web-adapt 。这是最直接、路由最准确的方式。当你需要确保Agent一定使用某个特定技能时，就用这个。
2. 显式技能名提及 ： Use the web-adapt skill to... 。这种方式也很可靠，Agent能明确识别你的意图。
3. 匹配技能意图的自然语言 ： Please adapt this unfamiliar public website generically first... 。只要你的描述足够清晰地匹配了某个技能的预设场景（如“通用适配陌生网站”），Agent也有可能自动调用正确的技能。但这种方式的确定性不如前两种。

给新手的建议 ：初期为了确保效果，强烈推荐使用第1或第2种方式。等你熟悉了每个技能对应的任务类型后，可以更多尝试第3种，让交互更自然。

4.3 跨AI Agent的兼容性实践

skill-browser 的技能文件（ SKILL.md ）是纯Markdown文本加上YAML前置元数据，里面不包含任何可执行代码或特定于某个Agent的API调用。这种设计使其具备了惊人的可移植性。

在不同Agent中的使用方式 ：

Agent	技能加载机制	如何使用 skill-browser	验证状态
GitHub Copilot CLI	将技能文件夹放入 ~/.copilot/skills/	使用 node install.js 自动部署	✅ 已测试
OpenClaw / Antigravity	通过 AGENTS.md 引用 TOOLS.md 中的技能	将技能文件夹拷贝到工作区，在 AGENTS.md 中引用	✅ 已测试
Claude Code	使用 @import 语法或放入 .claude/rules/	在提示词中 @import SKILL.md 文件，或将其内容粘贴到 .claude/rules/browser.md	✅ 格式兼容
Cursor	使用 .cursorrules 或 .cursor/rules/ 目录	将 SKILL.md 内容复制到 .cursor/rules/browser-skill.md	✅ 格式兼容
其他LLM Agent	系统提示词或上下文注入	将 SKILL.md 的指令文本粘贴到Agent的系统提示词或对话上下文中	✅ 纯文本兼容

核心原理 ：这些技能本质上是“教学文本”。它们不是在“调用”某个函数，而是在“教导”LLM如何思考问题、如何规划步骤、在何种条件下选择何种工具。因此，任何能够理解并遵循长篇文本指令的LLM，都可以成为这些技能的“运行时环境”。

5. 实战进阶：构建自定义技能与排查常见问题

5.1 基于现有技能扩展你的工作流

skill-browser 提供的三个技能是一个强大的基础，但真实世界的工作流往往更复杂。你可以以此为基础，构建属于你自己的复合技能。

案例：创建一个“竞品调研”技能 假设你需要定期从多个平台（产品官网、应用商店、社交媒体）搜集竞品信息。你可以创建一个新的 SKILL.md 文件，其核心思路是：

1. 复用路径选择逻辑 ：继承 content-summary 中根据平台选择 opencli / fetch / browser 的逻辑。
2. 定义信息提取模板 ：为每种类型的网站（官网、App Store、Twitter）定义要提取的字段（如版本号、用户评价、功能列表）。
3. 串联多个技能 ：在技能指令中，可以描述“先使用 web-adapt 探索某个陌生的竞品官网，如果可行，则调用 site-profile 为其创建配置，最后使用配置好的流程定期执行 content-summary 来监控更新”。
4. 输出结构化报告 ：将搜集到的信息整合到一个固定的Markdown或JSON格式报告中。

通过这种方式，你将一个复杂、多步骤的调研任务，封装成了一个简单的指令，如“ /competitor-research 公司A, 公司B”。

5.2 典型问题排查与解决思路

即使有了智能的技能，在实际操作中仍可能遇到问题。以下是一些常见场景及应对策略：

问题1：Agent坚持要启动浏览器，即使平台支持 opencli 。

• 原因 ：Agent的初始规划可能没有正确识别平台，或者技能指令中关于路径选择的逻辑没有被充分强调。
• 解决 ：在用户提示词中更明确地指定平台和路径。例如：“请使用 opencli 的 bilibili search 命令来搜索，不要打开浏览器。” 同时，检查技能的YAML前置元数据中，是否清晰定义了该技能的“能力”和“最佳实践”，以强化LLM的认知。

问题2： site-profile 创建的配置运行几次后就失败了。

• 原因 ：最可能的原因是网页结构发生了变化，导致选择器失效。或者是等待时间不足，在元素加载完成前就进行了操作。
• 解决 ：
  • 选择器优化 ：使用更健壮的选择器组合，如 [data-testid=”search-button”] 或通过父元素关系定位。
  • 增加容错 ：在配置中加入重试逻辑和备用选择器。
  • 动态等待 ：将固定的 sleep 改为等待特定元素出现的条件等待。
  • 定期维护 ：将Profile视为需要维护的代码，建立定期检查更新的机制。

问题3：在需要登录的T2平台（如知乎）上操作失败。

• 原因 ： opencli 的浏览器桥接会话已过期，或从未在该浏览器中登录过目标网站。
• 解决 ：这是 opencli 工作流的关键一环。你需要先手动在浏览器中登录目标网站，并确保浏览器进程保持运行状态。 opencli 的“浏览器桥接”功能会连接到这个已登录的会话进行操作。确保你理解并正确配置了 opencli 的浏览器连接设置。

问题4：技能在Copilot CLI中工作正常，但移植到Claude Code后效果不佳。

• 原因 ：不同Agent的上下文长度、指令遵循能力和工具调用方式有差异。
• 解决 ：进行“技能微调”。可能需要根据目标Agent的特点，调整技能指令的详细程度、步骤分解的粒度或提示词的格式。例如，对于上下文较短的Agent，可能需要将冗长的指令拆分成几个更聚焦的子技能。

5.3 性能优化与最佳实践

1. 建立内部平台注册表 ：将你团队经常访问的内部系统、行业垂直网站也进行分级，并补充到你的技能知识库中。例如，公司内部的Jira、Confluence可以定义为T3（如果有API）或T2（如果需要模拟登录）。
2. 缓存策略 ：对于 content-summary 这类信息获取任务，可以考虑引入简单的缓存机制。例如，相同查询在短时间内（如5分钟）直接返回缓存结果，避免重复调用外部服务，提升响应速度并节省成本。
3. 结果后处理管道 ：技能负责获取原始信息，但你可以在其后添加自定义的后处理步骤。例如，将 content-summary 得到的Markdown列表，自动转换成Notion数据库条目，或发送到Slack频道。
4. 监控与日志 ：对于重要的自动化流程，记录每次技能执行的日志（使用了哪个路径、是否成功、耗时多久）。这能帮助你发现哪个平台接入方式变得不稳定，以便及时调整策略或寻找替代方案。

skill-browser 项目打开了一扇门，它让我们看到AI Agent的网页交互可以从“一刀切”的笨重自动化，走向“精细化、智能化”的运行时感知。它的价值不仅在于提供的几个现成技能，更在于其背后“分层处理、路径择优”的设计哲学。将这个哲学应用到你自己面对的自动化场景中，无论是信息搜集、数据监控还是日常办公，都能显著提升效率和可靠性。