opencli-operate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenCLI — Make Websites Accessible for AI Agents

OpenCLI — 让网站可被AI Agent访问

Control Chrome step-by-step via CLI. Reuses existing login sessions — no passwords needed.

通过CLI逐步控制Chrome。复用现有登录会话，无需输入密码。

Prerequisites

前置条件

bash

opencli doctor    # Verify extension + daemon connectivity

Requires: Chrome running + OpenCLI Browser Bridge extension installed.

bash

opencli doctor    # Verify extension + daemon connectivity

要求：Chrome正在运行，且已安装OpenCLI Browser Bridge扩展。

Quickstart for AI Agents (1 step)

AI Agent快速上手（1步）

Point your AI agent to this file. It contains everything needed to operate browsers.

将你的AI Agent指向此文件，它包含操作浏览器所需的所有内容。

Quickstart for Humans (3 steps)

普通用户快速上手（3步）

bash

npm install -g @jackwener/opencli          # 1. Install

bash

npm install -g @jackwener/opencli          # 1. Install

Install extension from chrome://extensions # 2. Load extension

opencli operate open https://example.com # 3. Go!

undefined

opencli operate open https://example.com # 3. Go!

undefined

Core Workflow

核心工作流

Navigate:
```
opencli operate open <url>
```
Inspect:
```
opencli operate state
```
→ see elements with
```
[N]
```
indices
Interact: use indices —
```
click
```
,
```
type
```
,
```
select
```
,
```
keys
```

Wait:

opencli operate wait selector ".loaded"

wait text "Success"

Verify:

opencli operate get title

opencli operate screenshot

Repeat: browser stays open between commands
Save: write a TS adapter to
```
~/.opencli/clis/<site>/<command>.ts
```

导航：
```
opencli operate open <url>
```
检查：
```
opencli operate state
```
→ 查看带有
```
[N]
```
索引的元素
交互：使用索引执行
```
click
```
、
```
type
```
、
```
select
```
、
```
keys
```
操作

等待：

opencli operate wait selector ".loaded"

或

wait text "Success"

验证：

opencli operate get title

或

opencli operate screenshot

重复：浏览器在命令执行间隙保持打开状态
保存：编写TS适配器保存到
```
~/.opencli/clis/<site>/<command>.ts
```

Commands

命令

Navigation

Inspect

检查

bash

opencli operate state                   # Elements with [N] indices
opencli operate screenshot [path.png]   # Screenshot

bash

opencli operate state                   # Elements with [N] indices
opencli operate screenshot [path.png]   # Screenshot

Get (structured data)

获取（结构化数据）

bash

opencli operate get title               # Page title
opencli operate get url                 # Current URL
opencli operate get text <index>        # Element text content
opencli operate get value <index>       # Input/textarea value
opencli operate get html                # Full page HTML
opencli operate get html --selector "h1" # Scoped HTML
opencli operate get attributes <index>  # Element attributes

bash

opencli operate get title               # Page title
opencli operate get url                 # Current URL
opencli operate get text <index>        # Element text content
opencli operate get value <index>       # Input/textarea value
opencli operate get html                # Full page HTML
opencli operate get html --selector "h1" # Scoped HTML
opencli operate get attributes <index>  # Element attributes

Interact

交互

bash

opencli operate click <index>           # Click element [N]
opencli operate type <index> "text"     # Type into element [N]
opencli operate select <index> "option" # Select dropdown
opencli operate keys "Enter"            # Press key (Enter, Escape, Tab, Control+a)

bash

opencli operate click <index>           # Click element [N]
opencli operate type <index> "text"     # Type into element [N]
opencli operate select <index> "option" # Select dropdown
opencli operate keys "Enter"            # Press key (Enter, Escape, Tab, Control+a)

Wait

等待

bash

opencli operate wait selector ".loaded"           # Wait for element
opencli operate wait selector ".spinner" --timeout 5000  # With timeout
opencli operate wait text "Success"               # Wait for text
opencli operate wait time 3                       # Wait N seconds

bash

opencli operate wait selector ".loaded"           # Wait for element
opencli operate wait selector ".spinner" --timeout 5000  # With timeout
opencli operate wait text "Success"               # Wait for text
opencli operate wait time 3                       # Wait N seconds

Extract

提取

bash

opencli operate eval "document.title"
opencli operate eval "JSON.stringify([...document.querySelectorAll('h2')].map(e => e.textContent))"

bash

opencli operate eval "document.title"
opencli operate eval "JSON.stringify([...document.querySelectorAll('h2')].map(e => e.textContent))"

Network (API Discovery)

网络（API发现）

bash

opencli operate network                  # Show captured API requests (auto-captured since open)
opencli operate network --detail 3       # Show full response body of request #3
opencli operate network --all            # Include static resources

bash

opencli operate network                  # Show captured API requests (auto-captured since open)
opencli operate network --detail 3       # Show full response body of request #3
opencli operate network --all            # Include static resources

Sedimentation (Save as CLI)

沉淀（保存为CLI命令）

bash

opencli operate init hn/top              # Generate adapter scaffold
opencli operate verify hn/top            # Test the adapter

bash

opencli operate init hn/top              # Generate adapter scaffold
opencli operate verify hn/top            # Test the adapter

Session

会话

bash

opencli operate close                   # Close automation window

bash

opencli operate close                   # Close automation window

Example: Extract HN Stories

示例：提取Hacker News文章

bash

opencli operate open https://news.ycombinator.com
opencli operate state                   # See [1] a "Story 1", [2] a "Story 2"...
opencli operate eval "JSON.stringify([...document.querySelectorAll('.titleline a')].slice(0,5).map(a => ({title: a.textContent, url: a.href})))"
opencli operate close

bash

opencli operate open https://news.ycombinator.com
opencli operate state                   # See [1] a "Story 1", [2] a "Story 2"...
opencli operate eval "JSON.stringify([...document.querySelectorAll('.titleline a')].slice(0,5).map(a => ({title: a.textContent, url: a.href})))"
opencli operate close

Example: Fill a Form

示例：填写表单

bash

opencli operate open https://httpbin.org/forms/post
opencli operate state                   # See [3] input "Customer Name", [4] input "Telephone"
opencli operate type 3 "OpenCLI"
opencli operate type 4 "555-0100"
opencli operate get value 3             # Verify: "OpenCLI"
opencli operate close

bash

opencli operate open https://httpbin.org/forms/post
opencli operate state                   # See [3] input "Customer Name", [4] input "Telephone"
opencli operate type 3 "OpenCLI"
opencli operate type 4 "555-0100"
opencli operate get value 3             # Verify: "OpenCLI"
opencli operate close

Saving as Reusable CLI — Complete Workflow

保存为可复用CLI——完整工作流

Step-by-step sedimentation flow:

分步沉淀流程：

bash

undefined

bash

undefined

1. Explore the website

1. 探索网站

opencli operate open https://news.ycombinator.com opencli operate state # Understand DOM structure

opencli operate open https://news.ycombinator.com opencli operate state # 了解DOM结构

2. Discover APIs (crucial for high-quality adapters)

2. 发现API（高质量适配器的关键）

opencli operate eval "fetch('/api/...').then(r=>r.json())" # Trigger API calls opencli operate network # See captured API requests opencli operate network --detail 0 # Inspect response body

opencli operate eval "fetch('/api/...').then(r=>r.json())" # 触发API调用 opencli operate network # 查看捕获的API请求 opencli operate network --detail 0 # 查看响应体内容

3. Generate scaffold

3. 生成脚手架

opencli operate init hn/top # Creates ~/.opencli/clis/hn/top.ts

opencli operate init hn/top # 创建 ~/.opencli/clis/hn/top.ts

4. Edit the adapter (fill in func logic)

4. 编辑适配器（补充函数逻辑）

- If API found: use fetch() directly (Strategy.PUBLIC or COOKIE)

- 如果找到API：直接使用fetch()（Strategy.PUBLIC或COOKIE）

- If no API: use page.evaluate() for DOM extraction (Strategy.UI)

- 如果没有API：使用page.evaluate()做DOM提取（Strategy.UI）

5. Verify

5. 验证

opencli operate verify hn/top # Runs the adapter and shows output

opencli operate verify hn/top # 运行适配器并展示输出

6. If verify fails, edit and retry

6. 如果验证失败，编辑后重试

7. Close when done

7. 完成后关闭

opencli operate close

undefined

opencli operate close

undefined

Example adapter:

适配器示例：

typescript

// ~/.opencli/clis/hn/top.ts
import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'hn',
  name: 'top',
  description: 'Top Hacker News stories',
  domain: 'news.ycombinator.com',
  strategy: Strategy.PUBLIC,
  browser: false,
  args: [{ name: 'limit', type: 'int', default: 5 }],
  columns: ['rank', 'title', 'score', 'url'],
  func: async (_page, kwargs) => {
    const limit = Math.min(Math.max(1, kwargs.limit ?? 5), 50);
    const resp = await fetch('https://hacker-news.firebaseio.com/v0/topstories.json');
    const ids = await resp.json();
    return Promise.all(
      ids.slice(0, limit).map(async (id: number, i: number) => {
        const item = await (await fetch(`https://hacker-news.firebaseio.com/v0/item/${id}.json`)).json();
        return { rank: i + 1, title: item.title, score: item.score, url: item.url ?? '' };
      })
    );
  },
});

Save to

~/.opencli/clis/<site>/<command>.ts

→ immediately available as

opencli <site> <command>

typescript

// ~/.opencli/clis/hn/top.ts
import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'hn',
  name: 'top',
  description: 'Top Hacker News stories',
  domain: 'news.ycombinator.com',
  strategy: Strategy.PUBLIC,
  browser: false,
  args: [{ name: 'limit', type: 'int', default: 5 }],
  columns: ['rank', 'title', 'score', 'url'],
  func: async (_page, kwargs) => {
    const limit = Math.min(Math.max(1, kwargs.limit ?? 5), 50);
    const resp = await fetch('https://hacker-news.firebaseio.com/v0/topstories.json');
    const ids = await resp.json();
    return Promise.all(
      ids.slice(0, limit).map(async (id: number, i: number) => {
        const item = await (await fetch(`https://hacker-news.firebaseio.com/v0/item/${id}.json`)).json();
        return { rank: i + 1, title: item.title, score: item.score, url: item.url ?? '' };
      })
    );
  },
});

保存到

~/.opencli/clis/<site>/<command>.ts

→ 即可立即作为

opencli <site> <command>

命令使用。

Strategy Guide

策略指南

Strategy	When	browser:
`Strategy.PUBLIC`	Public API, no auth	`false`
`Strategy.COOKIE`	Needs login cookies	`true`
`Strategy.UI`	Direct DOM interaction	`true`

Always prefer API over UI — if you discovered an API during browsing, use

fetch()

directly.

策略	适用场景	browser取值
`Strategy.PUBLIC`	公开API，无需鉴权	`false`
`Strategy.COOKIE`	需要登录cookie	`true`
`Strategy.UI`	直接DOM交互	`true`

始终优先使用API而非UI——如果你在浏览过程中发现了API，直接使用

fetch()

调用即可。

Troubleshooting

故障排查

Error	Fix
"Browser not connected"	Run `opencli doctor`
"attach failed: chrome-extension://"	Disable 1Password temporarily
Element not found	`opencli operate scroll down` then `opencli operate state`

错误	修复方案
"Browser not connected"	运行 `opencli doctor`
"attach failed: chrome-extension://"	临时禁用1Password
元素未找到	执行 `opencli operate scroll down` 后再运行 `opencli operate state`

opencli-operate

Original

Translation

OpenCLI — Make Websites Accessible for AI Agents

OpenCLI — 让网站可被AI Agent访问

Prerequisites

前置条件

Quickstart for AI Agents (1 step)

AI Agent快速上手（1步）

Quickstart for Humans (3 steps)

普通用户快速上手（3步）

Install extension from chrome://extensions # 2. Load extension

Install extension from chrome://extensions # 2. Load extension

Core Workflow

核心工作流

Commands

命令

Navigation

导航

Inspect

检查

Get (structured data)

获取（结构化数据）

Interact

交互

Wait

等待

Extract

提取

Network (API Discovery)

网络（API发现）

Sedimentation (Save as CLI)

沉淀（保存为CLI命令）

Session

会话

Example: Extract HN Stories

示例：提取Hacker News文章

Example: Fill a Form

示例：填写表单

Saving as Reusable CLI — Complete Workflow

保存为可复用CLI——完整工作流

Step-by-step sedimentation flow:

分步沉淀流程：

1. Explore the website

1. 探索网站

2. Discover APIs (crucial for high-quality adapters)

2. 发现API（高质量适配器的关键）

3. Generate scaffold

3. 生成脚手架

4. Edit the adapter (fill in func logic)

4. 编辑适配器（补充函数逻辑）

- If API found: use fetch() directly (Strategy.PUBLIC or COOKIE)

- 如果找到API：直接使用fetch()（Strategy.PUBLIC或COOKIE）

- If no API: use page.evaluate() for DOM extraction (Strategy.UI)

- 如果没有API：使用page.evaluate()做DOM提取（Strategy.UI）

5. Verify

5. 验证

6. If verify fails, edit and retry

6. 如果验证失败，编辑后重试

7. Close when done

7. 完成后关闭

Example adapter:

适配器示例：

Strategy Guide

策略指南

Troubleshooting

故障排查