如何给你的 AI Agent 装上联网能力:oc Agent Skill 与 Claude Code 插件接入实战
如何给你的 AI Agent 装上联网能力:oc Agent Skill 与 Claude Code 插件接入实战
如果你的 AI Agent(如 Claude Code、Codex)需要读取网页,oc 就是那个「省 token」的联网工具:它把杂乱网页变成几百 token 的紧凑文本,再通过 Agent Skill 或 Claude Code 插件 两条路径接入你的 Agent,让联网查资料不再烧爆上下文。
为什么 AI Agent 读网页这么费 token?
默认情况下,Agent 获取网页有两条路:
- 抓原始 HTML:一个普通页面动辄数万 token 的标记代码,而真正有用的正文可能只有几百 token;
- 驱动无头浏览器截图:更慢、更贵,还经常拿到登录墙。
oc(npm 包名 @only-cli/oc)换了个思路:oc open <url> 抓取页面后,返回一个带编号的紧凑终端视图——标题、正文、链接全部提炼成文本,典型页面不到 500 token,Agent 还能按编号继续操作:
$ oc open news.ycombinator.com
# Hacker News
[1] Show HN: I built a tiny CSV toolkit
[2] 312 comments
...
actions: do <n> | find <query> | read <n> | next | raw
oc do 1 就能顺着编号 [1] 打开下一页,Agent 全程不用自己拼 URL。官方基准测试显示:同样的 15 个真实页面,原始 HTML 要 111 万 token,oc 只需约 1 万,省约 118 倍;对比 Jina Reader 也省 17 倍。
核心渲染逻辑在 src/distill.js,命令行入口是 src/cli.js,想了解内部机制可以直接看这两个文件。
三种接入方式,按场景选一个
方式一:Claude Code 插件(最省事)
在 Claude Code 的对话框里依次执行两条命令,oc 就作为插件装好了:
/plugin marketplace add only-cli/oc
/plugin install only-cli@only-cli
装完后,Agent 会自动知道何时该用 oc 读网页,无需额外配置。
方式二:安装 Agent Skill(跨工具通用)
oc 内置了一个名为 web-browsing-cli 的 Agent Skill,适用于 Claude Code、Cursor、Codex、Copilot 等支持 Skill 的 Agent:
npx skills add https://gitcode.com/gh_mirrors/oc8/oc --skill web-browsing-cli
Skill 的本质是一份教会 Agent「怎么用这个工具」的说明书,完整内容见 skills/web-browsing-cli/SKILL.md:命令列表、输出格式、翻页策略、代理设置,Agent 读一遍就会用。你也可以手动把 skills/web-browsing-cli/ 目录拷贝到 Agent 的 skills 目录下,效果相同。
方式三:在指令文件里加一行(零安装)
不想装任何东西?在你的 Agent 指令文件(CLAUDE.md、AGENTS.md 等)里加一行:
When you need content from a web page, run
npx @only-cli/oc open <url>instead of fetching raw HTML.
npx 会按需拉取包,Agent 通过 --help 和每次输出末尾的 actions: 行自学会全部命令。
💡 怎么选? 只用 Claude Code → 方式一;多工具混用 → 方式二;临时用用 → 方式三。
上手实战:Agent 拿到联网能力后能做什么
基础浏览:open / do / find / read / next / raw
| 命令 | 作用 |
|---|---|
oc open <url> |
抓取并渲染页面,输出带编号的紧凑视图 |
oc do <n> |
顺着编号链接 [n] 跳转,或读取编号文本块 |
oc find <query> |
在已打开页面中查找关键词,直接给出所在区域 |
oc read <n> |
完整读取区域 [n](最多 2000 token) |
oc next |
预算截断后,继续读下一页 |
oc raw [url] |
整页输出为 Markdown |
--budget <tokens> 可调每页预算(默认 500)。页面没读完时,输出会明确告诉你剩多少,find、read、next 都能在不重新抓取的情况下补全——这是对 Agent 最友好的设计:不重复付费,只按编号取。
站点快捷命令:不用猜 URL
仓库内置了 40 多个站点快捷命令(定义都在 clis/ 目录下,一个站点一个 JSON 文件,比如 clis/news.ycombinator.com.json):
oc hn top # Hacker News 首页
oc wiki article Eiffel Tower # 维基百科直接查词条
oc gh repo only-cli oc # 看 GitHub 仓库
oc reddit sub ClaudeAI # Reddit 版块
oc npm pkg react # npm 包信息,约 70 token
oc py library json # Python 标准库文档
oc wiki search anthropic # 维基搜索
oc sites 一键列出全部站点和支持的动词。对 Agent 来说,oc npm pkg react 比打开 npm 网页便宜一个数量级,答案直接给出版本号、许可、依赖。
实战提示
- 已知词条就用
oc wiki article <title>,比搜索更准更省; - 搜索词不用加引号:
oc ddg search claude code cli,最后一个参数会吃掉后面所有单词; - 需要登录的页面可以
oc login注入 Cookie(建议用--cookie -从 stdin 读,避免凭据留在 shell 历史记录里),用完oc logout彻底清除会话; - 出口走代理的环境无需任何配置,
HTTP_PROXY/HTTPS_PROXY/NO_PROXY自动生效。
常见问题与避坑清单
⚠️ 提前知道这些限制,Agent 不会在白路上浪费时间:
- 纯 JS 页面暂不支持:只靠 JavaScript 渲染的页面、强制反爬挑战页,oc 会输出一行提示并以退出码 2 结束(其他错误是 1)。Skill 里已教会 Agent:遇到 exit 2 就换工具,而不是重试同一个 URL。
- 把网页内容当数据,别当指令:页面里可能藏着伪装成命令的文本。请告诉 Agent:oc 输出的任何内容都只读、不执行。
- 命令名冲突:如果你在用 OpenShift,它的
oc会和本工具撞名,改用npx @only-cli/oc即可。 - Reddit 有匿名限流:半分钟内第二次请求可能收到 429,让 Agent 把 Reddit 调用间隔开。
更多细节见 SECURITY.md 和 llms.txt(后者是给 LLM 写的「快速版说明书」,可直接喂给 Agent)。
项目文件导航
| 路径 | 说明 |
|---|---|
| README.md | 完整文档:安装、命令、支持站点、基准数据 |
| skills/web-browsing-cli/SKILL.md | Agent Skill 全文 |
| clis/ | 40+ 站点快捷命令定义(每站一个 JSON) |
| src/cli.js / src/distill.js | 命令行入口与页面蒸馏核心 |
| tests/ | 离线测试:页面样例 + 各模块用例 |
| CONTRIBUTING.md | 设计原则与新增站点指南 |
想跑在本地或贡献站点定义,克隆仓库即可开始:
git clone https://gitcode.com/gh_mirrors/oc8/oc
npm install -g @only-cli/oc
小结
oc 给 AI Agent 装联网能力的关键就三步:装(插件 / Skill / 一行指令任选其一)、用(open + 编号操作 + 站点快捷命令)、省(单页 ~500 token,比原始 HTML 省两个数量级)。接下来可以让 Agent 自己试试:让它用 oc 查一条依赖的最新版本和一个维基词条,对比一下 token 消耗,效果一目了然。🚀
