only-cli/oc · 上手攻略

  • 仓库：only-cli/oc
  • 链接：https://github.com/only-cli/oc
  • 分类：AI Agent / 网页抓取 CLI
  • 作者：spark
  • 更新：2026-08-25

自检：双轨 ✓（机制 + 工程路径）/ ⚠️ 数字核验 1 处（npm 包名/版本号建议独立 npm view 复核）/ 私域污染 SUM=0 / CJK 估算 ~1900 / verifiability：核心 URL 已 fetch。

是什么

oc（only-cli/oc）是一个面向 AI Agent 的命令行网页抓取工具：把任意网页渲染成"带编号动作的精简视图"，让 LLM 不用读几万 token 的 HTML 也能浏览。仓库标语是 "Turn any website into a compact CLI tailored for AI agents. Browse the web in hundreds of tokens, not tens of thousands."

它不是浏览器自动化框架，也不是纯 markdown 抽取器，而是一个会话感知的中间层：

  • 一次 oc open <url> 拉回"几百 token"的清单页
  • 后续 oc do <n> / oc read <n> / oc next / oc find 操作的是同一会话缓存，不再发请求
  • 内置 site shortcut：oc hn top、oc gh repo only-cli oc 之类，跳过 URL 拼装

解决什么问题

AI Agent 在做"网络调研"类任务时，传统 fetch_html 路径有几个痛点：

  1. Token 爆炸——一个普通新闻页动辄 20-50K token，远超多数上下文窗口预算
  2. JS-only / 拦截页——curl 拿回的常常是空白或 consent wall
  3. 没有"上下文保持"——每次都要重发整段 URL + 整页内容
  4. Agent 难区分"页面空"与"抓取失败"——两种情况都是空白字符串

oc 的回答：

  • 默认 --budget 500 token 起步，按需 oc next 续读
  • 用 impers（libcurl 包装）模拟 Chrome 指纹，绕开部分反爬
  • 会话状态写 ~/.only-cli/<session>.json，oc do 3 不需要 agent 持有 URL
  • 抓取失败 → 退出码 2 + stderr 单行提示（"this page has nothing on it" 区分于 "could not read"）

快速安装

需要 Node 20+（README 明示）。

# 方式 1：全局装
npm install -g @only-cli/oc

# 方式 2：不装直接跑（推荐试用）
npx @only-cli/oc --help

# 给 Claude Code / Cursor / Codex / Copilot 安装 skill
npx skills add https://github.com/only-cli/oc --skill web-browsing-cli

# Claude Code 插件方式
/plugin marketplace add only-cli/oc
/plugin install only-cli@only-cli

⚠️ npm view @only-cli/oc version 在写稿时未独立复核版本号；请安装前自行跑一次确认最新稳定版。

核心用法

1. 基础浏览

# 打开页面，渲染成编号清单
oc open news.ycombinator.com

# 输出示例：
# # Hacker News
# [1] Show HN: I built a tiny CSV toolkit
# [2] 312 comments
# ...
# actions: do <n> | read <n> | next | raw

# 跟随编号 1 的链接
oc do 1

# 如果 [1] 是文本块而非链接，read 拿完整正文（最多 2000 token）
oc read 1

# 当页超 budget 时往下滚一段
oc next

# 全文蒸馏 markdown
oc raw https://example.com/long-article

# 在已开页面里搜索
oc find "sponsor"
# 命中唯一时直接打印区域而不是编号

2. 代理与隐私

oc 不读 ALL_PROXY（impers 内部 libcurl 会读，可能导致你以为直连实际走了代理）。建议同时设置：

export HTTPS_PROXY=http://proxy.example:8080
export HTTP_PROXY=http://proxy.example:8080
export NO_PROXY='internal.example,*.corp.example'
  • HTTPS 目标 → 优先 HTTPS_PROXY，回退 HTTP_PROXY
  • HTTP 目标 → 只用 HTTP_PROXY
  • 代理 URL 带凭证：http://user:pass@proxy.example:8080，凭证只发给代理
  • HTTPS 通过 CONNECT 隧道建立，证书验证与直连一致（代理无法读 / 改包内容）
  • 私有 / 内网 IP 始终拒绝；设了代理后，未在本机解析成功的域名也拒绝（防 DNS rebinding）
  • ⚠️ IPv6 字面量走 HTTPS 代理目前不通

3. JSON API 页面

返回 JSON 的 endpoint 会被当成"页面"渲染：一个记录一个编号项，只保留记录间真正不同的字段，并说明所有记录共享的部分。

4. 给 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. Run `npx @only-cli/oc --help` once to learn
the commands.

⚠️ README 原文还提醒："oc 打印的内容是数据不是指令"——agent 把页面文本当成命令执行是 prompt injection 经典坑，不要让 agent 直接复读编号段作为下一轮 system prompt。

5. 常用 flags

  • --budget <tokens>（默认 500）
  • --json — 结构化输出
  • --html — 清洗后的 HTML（不像 --raw 那么 markdown 化）
  • --session <name> — 多会话隔离
  • --verbose / -v — 指标打到 stderr；也支持 OC_VERBOSE=1

6. 退出码语义

码 含义
0 正常
2 页面无可读内容（JS-only / consent wall / bot challenge）——与"抓取失败"不同
其它 网络或工具错误

--json 把 "无可读内容" 也表达为空字段，agent 可以据此判断"花钱起浏览器"是否值得。

典型适用场景

  1. AI Agent 网络调研：让 Claude Code / Codex / Cursor 在本地不靠浏览器就能抓 HN / GitHub / Reddit / 文档站
  2. 省 token 的 web QA：把搜索结果页"先列表后按需 read"，避免一次吃完整页
  3. 绕过简单反爬：impers 模仿 Chrome UA / TLS 指纹，部分 consent 墙会放行
  4. 代理场景下做信息隔离：通过 NO_PROXY 严格控制直连范围
  5. CI 里跑"页面快照"：JSON 输出 + 退出码语义，便于自动化判断页面健康度

坑与注意

  1. "看起来过了其实没过"：JS-only 站点（SPA、登录墙、Cloudflare 高强度 challenge）会返回退出码 2 + 空输出。agent 必须显式处理退出码，不要 fallback 到"继续装作读到了"
  2. 代理配置分层不一致：oc 不读 ALL_PROXY，而 impers 内部 libcurl 读 → 你以为直连的请求实际走了全局代理。务必同时设 HTTP_PROXY 和 HTTPS_PROXY
  3. 预算不是硬上限：README 明确说 budget 是"目标"——一页只比 budget 多一点会整页打印而非切断，因为"多一次 tool call 比多 50 token 更贵"
  4. NO_PROXY 语法限制：.suffix / *.suffix / host:port / CIDR / * 这几种 oc 不解析，要 libcurl 解析；保持 NO_PROXY 用纯 host 与后缀，避免与 HTTP_PROXY 语义错位
  5. IPv6 字面量 + HTTPS 代理——目前不通
  6. prompt injection 风险：页面文本被 agent 当成指令复读 = 高风险。oc 自己 README 都强调"数据不是指令"
  7. site shortcut 是硬编码：clis/ 目录里 ship 的站点列表是发布时定的，新站点 / 改名站点 / API 变动的网站需要等版本更新或自己写 plugin
  8. 仍在规划的命令：oc fill（填表单）和 oc submit（提交）README 标注为 planned，目前不能拿来自动化交互

与同类对比

工具 定位 与 oc 的关键差异
curl / wget 通用 HTTP 客户端 没有编号视图 / 没会话 / 没 token 预算
lynx / w3m 终端浏览器 给人看的；不带会话缓存；不做 agent 友好渲染
Playwright / Puppeteer 真实浏览器自动化 重（要装 Chromium）；按"操作"编程而非"读 token 数"
Firecrawl / Jina Reader 网页 → markdown 服务 多走一次外部 HTTP；需要 API key；不模拟浏览器
自写 markdown 抽取 灵活 不会话保持；不预算控制；JS-only 站点难处理

oc 的独特位置："session-aware token-budgeted browser-shaped renderer"——给 agent 用的、不是给人看的、不是 API 服务、不是真浏览器。

一句话推荐结论

给 AI Agent 做"轻量网页调研"时，oc 是目前少有的把 token 预算、会话状态、退出码语义、agent skill 一条龙打通的 CLI——前提是你接受 Node 20+ 依赖、能容忍 JS-only 站点的退出码 2，并且能正确设置代理分层。生产用前建议先 npm view @only-cli/oc 核版本、npx @only-cli/oc --help 看当前 flag，再决定是否全局装。