<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>OpenCLI 项目技术分析报告</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;700&family=Noto+Serif+SC:wght@400;700&family=Source+Code+Pro:wght@400;700&display=swap" rel="stylesheet">
<style>
<span class="mention-invalid">@import</span> url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;700&family=Noto+Serif+SC:wght@400;700&family=Source+Code+Pro:wght@400;700&display=swap');
:root {
--bg-color: #FFFFFF;
--content-bg-color: #FFFFFF;
--text-color: #212529;
--accent-color: #0D6EFD;
--border-color: #dee2e6;
--code-bg-color: #f8f9fa;
--hover-bg-color: #f1f3f5;
}
body {
font-family: "Noto Serif SC", serif;
font-size: 16px;
line-height: 1.8;
color: var(--text-color);
background-color: var(--bg-color);
margin: 0;
padding: 0;
}
.container {
max-width: 800px;
margin: 2em auto;
padding: 2em 3em;
background-color: var(--content-bg-color);
box-shadow: 0 4px 12px rgba(0,0,0,0.05);
border-radius: 4px;
}
h1, h2, h3, h4, h5, h6 {
font-family: "Noto Sans SC", "Noto Serif SC", sans-serif;
font-weight: 700;
line-height: 1.4;
color: var(--text-color);
}
h1 {
font-size: 28px;
text-align: center;
margin-top: 24px;
margin-bottom: 20px;
color: var(--text-color);
}
h2 {
font-size: 22px;
margin-top: 2.5em;
margin-bottom: 1.2em;
padding-bottom: 0.4em;
border-bottom: 1px solid var(--border-color);
position: relative;
}
h2::before {
content: '';
display: inline-block;
width: 14px;
height: 14px;
background-color: var(--accent-color);
border-radius: 50%;
margin-right: 0.5em;
vertical-align: middle;
}
h3 {
font-size: 20px;
margin-top: 2em;
margin-bottom: 1em;
}
h4 {
font-size: 18px;
margin-top: 1.5em;
margin-bottom: 0.8em;
}
p {
margin-bottom: 1.2em;
}
a {
color: var(--accent-color);
text-decoration: none;
transition: color 0.2s, text-decoration 0.2s;
}
a:hover {
color: #0a58ca;
text-decoration: underline;
}
strong {
font-weight: 700;
color: var(--text-color);
}
ul, ol {
padding-left: 2em;
margin-bottom: 1.2em;
}
li {
margin-bottom: 0.5em;
}
blockquote {
margin: 1.5em 0;
padding: 0.8em 1.5em;
border-left: 5px solid var(--accent-color);
background-color: var(--code-bg-color);
color: #495057;
}
blockquote p {
margin-bottom: 0;
}
code {
font-family: "Source Code Pro", monospace;
background-color: #e9ecef;
padding: 0.2em 0.4em;
border-radius: 3px;
font-size: 0.9em;
}
pre {
background-color: var(--code-bg-color);
padding: 1em;
border-radius: 4px;
overflow-x: auto;
border: 1px solid var(--border-color);
margin: 1.5em 0;
}
pre code {
background-color: transparent;
padding: 0;
border-radius: 0;
font-size: 0.9em;
line-height: 1.5;
}
table {
width: 100%;
border-collapse: collapse;
margin: 1.5em 0;
font-size: 0.95em;
}
th, td {
padding: 0.8em 1em;
text-align: left;
border: none;
}
thead {
border-bottom: 2px solid var(--accent-color);
}
thead th {
font-weight: 700;
font-family: "Noto Sans SC", sans-serif;
}
tbody tr:hover {
background-color: var(--hover-bg-color);
}
hr {
border: 0;
height: 2px;
background-color: var(--accent-color);
margin: 3em 0;
}
.toc {
background-color: var(--code-bg-color);
border: 1px solid #e9ecef;
padding: 1.5em 2em;
margin-bottom: 2em;
border-radius: 4px;
}
.toc-title {
font-family: "Noto Sans SC", sans-serif;
font-weight: 700;
font-size: 1.2em;
margin-top: 0;
margin-bottom: 1em;
color: var(--text-color);
}
.toc ul {
padding-left: 0;
list-style: none;
}
.toc .toc-level-2 > li {
margin-bottom: 0.8em;
}
.toc .toc-level-3 {
padding-left: 2em;
margin-top: 0.5em;
}
.toc a {
color: var(--accent-color);
font-weight: normal;
}
.toc a:hover {
text-decoration: underline;
}
.toc-counter {
margin-right: 0.5em;
font-weight: bold;
}
.component-group {
border: 1px solid #e9ecef;
border-radius: 4px;
padding: 1.5em;
margin: 1.5em 0;
background-color: #fdfdfe;
}
.component-group-title {
font-weight: bold;
margin-bottom: 1em;
color: var(--accent-color);
display: block;
}
.chart-placeholder {
margin: 2em 0;
border: 1px dashed #ced4da;
padding: 1.5em;
text-align: center;
background-color: #f8f9fa;
border-radius: 4px;
}
.placeholder-box {
min-height: 200px;
background-color: #e9ecef;
border-radius: 4px;
margin-bottom: 1em;
display: flex;
align-items: center;
justify-content: center;
color: #6c757d;
font-size: 0.9em;
}
.placeholder-box::before {
content: "图表区域 (Chart Area)";
}
.chart-placeholder figcaption {
font-size: 0.9em;
color: #495057;
line-height: 1.4;
}
.chart-placeholder figcaption strong {
color: #212529;
}
.generated-chart {
margin: 2em 0;
}
</style>
</head>
<body>
<div class="container">
<h1>OpenCLI 项目技术分析报告</h1>
<nav class="toc">
<p class="toc-title">目录</p>
<ul class="toc-level-2">
<li><span class="toc-counter">一、</span><a href="#执行摘要">执行摘要</a></li>
<li><span class="toc-counter">二、</span><a href="#技术架构分析">技术架构分析</a>
<ul class="toc-level-3">
<li><a href="#核心架构概览">核心架构概览</a></li>
<li><a href="#代码组织与模块划分">代码组织与模块划分</a></li>
<li><a href="#启动流程与运行机制">启动流程与运行机制</a></li>
<li><a href="#适配器与命令注册">适配器与命令注册</a></li>
<li><a href="#浏览器桥接与自动化">浏览器桥接与自动化</a></li>
<li><a href="#桌面应用控制cdp集成">桌面应用控制（CDP集成）</a></li>
<li><a href="#ai-agent-集成设计">AI Agent 集成设计</a></li>
</ul>
</li>
<li><span class="toc-counter">三、</span><a href="#功能特性分析">功能特性分析</a>
<ul class="toc-level-3">
<li><a href="#丰富的网站与工具适配">丰富的网站与工具适配</a></li>
<li><a href="#统一的命令行接口">统一的命令行接口</a></li>
<li><a href="#账号安全与零凭证存储">账号安全与零凭证存储</a></li>
<li><a href="#零llm运行成本">零LLM运行成本</a></li>
<li><a href="#可扩展性与插件生态">可扩展性与插件生态</a></li>
</ul>
</li>
<li><span class="toc-counter">四、</span><a href="#ai-集成能力分析">AI 集成能力分析</a>
<ul class="toc-level-3">
<li><a href="#ai-agent-友好设计">AI Agent 友好设计</a></li>
<li><a href="#技能skills机制">技能（Skills）机制</a></li>
<li><a href="#自适应适配器修复">自适应适配器修复</a></li>
<li><a href="#智能搜索与发现">智能搜索与发现</a></li>
</ul>
</li>
<li><span class="toc-counter">五、</span><a href="#安装指南">安装指南</a>
<ul class="toc-level-3">
<li><a href="#安装-opencli-主程序">安装 OpenCLI 主程序</a></li>
<li><a href="#安装浏览器桥接扩展">安装浏览器桥接扩展</a></li>
<li><a href="#验证安装">验证安装</a></li>
</ul>
</li>
<li><span class="toc-counter">六、</span><a href="#使用指南">使用指南</a>
<ul class="toc-level-3">
<li><a href="#人类用户使用">人类用户使用</a></li>
<li><a href="#ai-agent-使用">AI Agent 使用</a></li>
<li><a href="#常用命令示例">常用命令示例</a></li>
<li><a href="#输出格式与管道">输出格式与管道</a></li>
</ul>
</li>
<li><span class="toc-counter">七、</span><a href="#总结">总结</a></li>
</ul>
</nav>
<h2 id="执行摘要">执行摘要</h2>
<p>OpenCLI 是一个开源的通用 CLI 聚合框架，旨在将任何网站、浏览器会话、Electron 桌面应用或本地工具转化为统一的命令行接口【17†source】。其核心价值在于为人类用户和 AI 代理提供<strong>确定性</strong>、<strong>零LLM成本</strong>且<strong>账号安全</strong>的自动化操作能力【17†source】。通过内置 90+ 适配器和浏览器桥接技术，OpenCLI 实现了从热门社交媒体（如 Bilibili、Zhihu、Xiaohongshu）到开发工具（如 GitHub CLI、Docker）的广泛覆盖【17†source】。同时，它创新性地引入<strong>技能（Skills）</strong>机制，使 Claude Code、Cursor 等 AI 代理能够直接驱动浏览器执行任务，而无需人工干预【17†source】。本报告将深入分析 OpenCLI 的技术架构、功能特性、AI 集成能力，并提供详尽的安装与使用指南，以帮助开发者全面了解该项目的技术细节和实用价值。</p>
<h2 id="技术架构分析">技术架构分析</h2>
<h3 id="核心架构概览">核心架构概览</h3>
<p>OpenCLI 采用 Node.js 编写，基于 Commander.js 框架构建 CLI 入口，整体架构围绕<strong>命令发现与注册</strong>、<strong>适配器执行引擎</strong>和<strong>浏览器自动化桥接</strong>三大核心模块展开【33†source】。项目源码结构清晰，主要包含以下模块：</p>
<ul>
<li><strong>命令注册与调度</strong>：通过 <code>registry.ts</code> 实现命令的注册表和生命周期管理，<code>commanderAdapter.ts</code> 负责将注册的命令对接到 Commander 框架【33†source】。启动时，主入口 <code>main.ts</code> 会动态导入 <code>cli.ts</code> 和 <code>discovery.ts</code> 等模块，完成命令的发现与注册【33†source】。</li>
<li><strong>适配器发现与加载</strong>：<code>discovery.ts</code> 提供两种发现模式：快速路径（manifest）和传统文件扫描【35†source】。在生产环境，预先编译的 <code>cli-manifest.json</code> 可让命令注册几乎瞬时完成，模块按需懒加载；在开发环境下，则扫描 <code>clis/</code> 目录下的 JS 文件动态注册【35†source】。此外，<code>ensureUserCliCompatShims</code> 和 <code>ensureUserAdapters</code> 等函数确保用户目录 <code>~/.opencli/</code> 下也具备运行适配器的环境（如创建必要的符号链接和目录结构）【35†source】。</li>
<li><strong>浏览器自动化桥接</strong>：这是 OpenCLI 与网站交互的关键模块。它通过一个轻量级的 Chrome 扩展（Browser Bridge）与本地微守护进程（daemon）协同工作【40†source】。daemon 自动启动并监听在 <code>localhost:19825</code>，作为 CLI 与 Chrome 扩展之间的 WebSocket 中继【40†source】。当执行浏览器相关命令时，CLI 通过 daemon 将指令发送给 Chrome 扩展，扩展在已登录的浏览器环境中执行 JavaScript，从而操作网页【40†source】。这种架构确保<strong>复用用户已登录的会话</strong>，无需重复登录，实现“账号安全”和“零风控”【17†source】。</li>
<li><strong>命令执行引擎</strong>：<code>cli.ts</code> 中定义了实际的命令处理逻辑，包括内置命令和动态适配器命令的执行【37†source】。内置命令如 <code>list</code>、<code>doctor</code>、<code>daemon</code> 等直接在此实现；对于动态适配器命令，则通过 <code>commanderAdapter</code> 注册后，由 <code>runCli</code> 框架调度执行【33†source】。执行引擎负责解析命令参数、调用适配器逻辑，并将结果通过 <code>output.ts</code> 渲染成表格、JSON、YAML 等多种格式【33†source】。</li>
<li><strong>扩展与插件体系</strong>：OpenCLI 设计了完善的插件机制，允许社区贡献新的适配器【17†source】。<code>plugin.ts</code> 和 <code>plugin-scaffold.ts</code> 等模块负责插件的安装、列表、更新和卸载等管理功能【33†source】。插件本质上是符合规范的适配器包，可从 GitHub 仓库安装，扩展 OpenCLI 的命令集【17†source】。</li>
</ul>
<p>整体而言，OpenCLI 的架构在保证<strong>高性能启动</strong>（通过 manifest 缓存和并行发现）的同时，实现了<strong>高度解耦</strong>和<strong>可扩展性</strong>。各模块职责分明：注册表管理命令元数据，适配器负责具体逻辑，浏览器桥接提供统一的自动化能力，而插件体系则为生态扩展预留了空间。</p>
<h3 id="代码组织与模块划分">代码组织与模块划分</h3>
<p>OpenCLI 的源码按照功能模块进行组织，主要目录结构如下：</p>
<ul>
<li><strong>src/</strong>：核心代码目录，采用 TypeScript 编写，编译后输出到 <code>dist/src/</code>。主要模块包括：
<ul>
<li><code>main.ts</code>：程序入口，负责初始化环境、动态导入核心模块并启动 CLI【33†source】。</li>
<li><code>cli.ts</code>：定义内置命令和执行逻辑，如 <code>list</code>、<code>validate</code>、<code>explore</code> 等，以及适配器命令的执行流程【37†source】。</li>
<li><code>registry.ts</code>：命令注册表，管理所有已知命令的元数据（站点、名称、策略、参数、列定义等）【37†source】。</li>
<li><code>discovery.ts</code>：命令发现机制，实现 manifest 快速加载和文件系统扫描两种模式【35†source】。</li>
<li><code>browser/</code>：浏览器自动化相关模块，包括与 daemon 通信的客户端、目标解析、网络请求拦截、页面分析等【37†source】。</li>
<li><code>commands/</code>：一些独立的命令模块，如 <code>daemon.ts</code> 提供 daemon 管理，<code>doctor.ts</code> 提供诊断等【37†source】。</li>
<li><code>output.ts</code>、<code>serialization.ts</code>：输出格式化和序列化，将命令结果转换为表格、JSON、YAML、Markdown、CSV 等格式【33†source】。</li>
<li><code>plugin.ts</code>、<code>plugin-scaffold.ts</code>：插件管理，包括安装、列表、卸载等【33†source】。</li>
<li><code>launcher.ts</code>、<code>runtime.ts</code>、<code>diagnostic.ts</code>：辅助模块，如进程启动、运行时检测、诊断信息收集等【33†source】。</li>
</ul>
</li>
<li><strong>clis/</strong>：适配器脚本目录，按站点分组织。每个站点一个子目录，其中包含该站点下所有命令的 JS 文件。例如 <code>clis/hackernews/top.js</code> 定义了 HackerNews 的“top”命令【44†source】。这些适配器文件使用 OpenCLI 提供的注册 API（如 <code>cli()</code>）声明命令元数据和执行逻辑【44†source】。</li>
<li><strong>extension/</strong>：Chrome 扩展源码目录，包含 Browser Bridge 扩展的实现。该扩展负责在浏览器中执行由 CLI 发来的自动化指令，并与本地 daemon 通信【40†source】。</li>
<li><strong>docs/</strong>：文档目录，包含用户指南和开发文档。使用 VitePress 构建，提供详细的安装、使用和开发指南【32†source】。</li>
<li><strong>skills/</strong>：AI 代理技能目录，包含预定义的技能模块，如 <code>opencli-adapter-author</code>、<code>opencli-browser</code> 等【42†source】。这些技能可通过 <code>npx skills add</code> 安装到 Claude Code 等代理中，赋予其使用 OpenCLI 的能力【17†source】。</li>
</ul>
<p>这种组织方式使项目结构清晰，核心运行时与适配器逻辑分离，便于维护和扩展。适配器作为独立模块存在，可由社区贡献或用户自定义，而核心框架负责统一调度和提供基础能力。</p>
<h3 id="启动流程与运行机制">启动流程与运行机制</h3>
<p>OpenCLI 的启动流程经过精心优化，以实现<strong>快速响应</strong>和<strong>按需加载</strong>：</p>
<ol>
<li><strong>环境准备</strong>：在 <code>main.ts</code> 中，首先确保非 Windows 平台下系统路径（如 <code>/usr/local/bin</code> 等）可用，以避免某些环境下外部命令找不到的问题【33†source】。然后，它检查命令行参数中是否包含 <code>--live</code> 或 <code>--focus</code> 等会话生命周期标志，并将其从 <code>argv</code> 中移除，转换为环境变量供后续使用【33†source】。</li>
<li><strong>快速路径判断</strong>：接下来，程序进入“超快路径”判断，针对一些高频或轻量命令直接处理，无需完整启动框架【33†source】。例如：
<ul>
<li>若命令为 <code>--version</code>，则直接输出版本号并退出【33†source】。</li>
<li>若命令为 <code>completion</code>，则尝试直接生成对应 shell 的补全脚本并退出【33†source】。</li>
<li>若命令包含 <code>--get-completions</code>，则尝试从预生成的 manifest 中获取补全候选并退出【33†source】。如果 manifest 不存在，则继续下一步。</li>
</ul>
</li>
<li><strong>核心模块动态加载</strong>：对于非快速路径的命令，程序开始加载核心模块。为了减少启动开销，这些模块采用动态 <code>import()</code> 导入，仅在需要时加载【33†source】。加载的模块包括：
<ul>
<li><code>discovery.js</code>：命令发现模块，用于注册命令。</li>
<li><code>completion.js</code>：补全逻辑模块。</li>
<li><code>cli.js</code>：CLI 执行引擎。</li>
<li><code>hooks.js</code>：生命周期钩子模块。</li>
<li><code>node-network.js</code>：网络拦截模块（用于浏览器自动化）。</li>
<li><code>update-check.js</code>：后台更新检查模块。</li>
</ul>
</li>
<li><strong>并行命令发现</strong>：加载完模块后，程序并行执行<strong>内置适配器</strong>和<strong>用户适配器</strong>的发现过程【33†source】。内置适配器位于安装包的 <code>clis/</code> 目录，用户适配器位于 <code>~/.opencli/clis/</code>。发现过程通过 <code>discoverClis</code> 函数完成，该函数优先尝试从 manifest 加载命令，若 manifest 不存在则回退到文件系统扫描【35†source】。由于内置和用户适配器相互独立，可以同时发现，从而加速启动。</li>
<li><strong>插件发现</strong>：在用户适配器发现完成后，程序继续调用 <code>discoverPlugins</code>，扫描 <code>~/.opencli/plugins/</code> 目录下的插件【35†source】。插件发现最后执行，以确保插件的命令可以覆盖同名内置或用户命令（用户命令优先级最高，插件次之，内置最低）。</li>
<li><strong>注册退出钩子与后台更新</strong>：在所有命令注册完成后，程序注册一个退出钩子，在命令执行完毕后检查并显示更新提示【33†source】。同时，它会异步触发后台更新检查，为下次运行准备更新信息【33†source】。</li>
<li><strong>补全回退处理</strong>：如果之前因 manifest 不存在而跳过了补全快速路径，此时会使用完整注册表来计算补全候选并退出【33†source】。</li>
<li><strong>生命周期钩子</strong>：最后，程序触发 <code>onStartup</code> 生命周期钩子，通知所有注册的插件或模块启动完成【33†source】。</li>
<li><strong>进入命令执行</strong>：启动流程结束后，调用 <code>runCli</code> 进入 Commander 框架的命令解析与执行循环，处理用户输入的命令【33†source】。</li>
</ol>
<p>通过上述流程，OpenCLI 实现了<strong>零启动延迟</strong>的体验：对于简单命令（如查看版本、补全），几乎无需加载任何模块即可响应；对于复杂命令，也通过并行发现和懒加载模块将启动开销降至最低。这种设计保证了 OpenCLI 在实际使用中的响应速度和资源效率。</p>
<h3 id="适配器与命令注册">适配器与命令注册</h3>
<p>OpenCLI 的核心概念之一是<strong>适配器（Adapter）</strong>，它封装了对特定网站或工具的访问逻辑。每个适配器对应一个站点或工具，可以包含多个命令。适配器通过统一的 API 与 OpenCLI 框架交互，主要包括：</p>
<ul>
<li><strong>命令注册 API</strong>：适配器使用 <code>cli()</code> 函数（从 <code>@jackwener/opencli/registry</code> 导入）来声明命令【44†source】。该函数接收一个配置对象，定义命令的元数据和执行逻辑。例如：
<pre><code class="language-javascript">import { cli, Strategy } from '<span class="mention-invalid">@jackwener</span>/opencli/registry';
cli({
site: 'hackernews',
name: 'top',
description: 'Hacker News top stories',
domain: 'news.ycombinator.com',
strategy: Strategy.PUBLIC,
browser: false,
args: [ { name: 'limit', type: 'int', default: 20, help: 'Number of stories' } ],
columns: ['rank', 'title', 'score', 'author', 'comments'],
pipeline: [ ... ],
});</code></pre>
上述代码注册了 HackerNews 站点的“top”命令，声明了其名称、描述、域名、策略（无需登录）、参数、输出列以及执行管道【44†source】。
</li>
<li><strong>策略（Strategy）</strong>：策略定义了访问站点所需的认证方式，包括 <code>PUBLIC</code>、<code>COOKIE</code>、<code>HEADER</code> 和 <code>INTERCEPT</code> 等【37†source】。例如，<code>PUBLIC</code> 表示无需认证，<code>COOKIE</code> 表示需要浏览器的 Cookie，<code>HEADER</code> 表示需要特定的请求头，<code>INTERCEPT</code> 则表示需要拦截网络请求获取令牌【37†source】。策略由适配器在注册时指定，运行时由注册表和执行引擎根据策略类型决定如何获取数据。</li>
<li><strong>执行管道（Pipeline）</strong>：适配器的核心是<strong>执行管道</strong>，它定义了命令执行的步骤序列【44†source】。管道由一系列操作组成，如网络请求、数据过滤、映射转换、结果限制等【44†source】。例如，HackerNews 的“top”命令管道首先抓取 HN 的 Top Stories JSON，然后限制条目数量，再逐个获取每条新闻的详情，最后映射输出列并限制结果数量【44†source】。管道通过声明式的方式组合这些操作，使适配器逻辑清晰且易于维护。</li>
<li><strong>内置命令与生命周期</strong>：除了动态适配器命令，OpenCLI 还内置了一些基础命令，如 <code>list</code>（列出所有命令）、<code>doctor</code>（诊断浏览器连接）、<code>validate</code>（验证适配器）等【37†source】。这些命令直接在 <code>cli.ts</code> 中实现，不通过适配器注册。此外，适配器还可以注册生命周期钩子（如 <code>onStartup</code>、<code>onBeforeExecute</code>、<code>onAfterExecute</code>），在特定事件触发时执行自定义逻辑【35†source】。</li>
</ul>
<p>通过这种<strong>声明式注册+管道执行</strong>的模型，OpenCLI 实现了高度模块化和可组合的命令体系。开发者只需关注如何获取和转换数据，而框架负责调度、认证和输出格式化，大大降低了开发适配器的门槛。</p>
<h3 id="浏览器桥接与自动化">浏览器桥接与自动化</h3>
<p>OpenCLI 的一大技术亮点是其<strong>浏览器自动化桥接</strong>能力。通过这一机制，OpenCLI 可以操作用户已登录的浏览器，执行如导航、点击、提取等操作，从而访问需要登录的网站或复杂的动态网页。其架构和工作流程如下：</p>
<ol>
<li><strong>架构组成</strong>：浏览器桥接由两部分组成：
<ul>
<li><strong>Chrome 扩展（Browser Bridge）</strong>：一个轻量级的 Chrome 扩展，安装在用户浏览器中【40†source】。该扩展负责在浏览器上下文中执行 JavaScript，与网页交互，并将结果返回给守护进程。</li>
<li><strong>本地守护进程（Daemon）</strong>：一个随 OpenCLI 安装的后台进程，默认监听在 <code>localhost:19825</code>【40†source】。CLI 通过 WebSocket 与 daemon 通信，daemon 再通过 Chrome DevTools Protocol (CDP) 与扩展通信【40†source】。</li>
</ul>
</li>
<li><strong>通信流程</strong>：当执行一个需要浏览器的命令时，流程如下：
<ul>
<li>CLI 将命令请求发送给本地 daemon（通过 HTTP 或 WebSocket）【40†source】。</li>
<li>daemon 将请求转发给 Chrome 扩展（通过 CDP）【40†source】。</li>
<li>扩展在浏览器中执行相应的操作（如导航到 URL、执行 JavaScript 等）【40†source】。</li>
<li>执行结果（如页面内容、网络请求、元素状态等）由扩展返回给 daemon，再由 daemon 返回给 CLI【40†source】。</li>
</ul>
</li>
<li><strong>会话复用</strong>：由于扩展运行在用户已登录的浏览器环境中，因此可以直接访问受保护的页面，而无需重新登录【40†source】。这保证了<strong>账号安全</strong>（凭证不离开浏览器）和<strong>零风控</strong>（使用真实浏览器会话，不易触发反爬）【17†source】。</li>
<li><strong>守护进程生命周期</strong>：daemon 在首次需要时自动启动，并持续运行【40†source】。用户可以通过 <code>opencli daemon stop</code> 命令优雅地停止守护进程【40†source】。守护进程会保持活跃，直到用户显式停止或卸载 OpenCLI【40†source】。</li>
<li><strong>命令示例</strong>：用户可以使用 <code>opencli browser</code> 系列命令直接与浏览器交互，例如：
<ul>
<li><code>opencli browser open <url></code>：在默认标签页中打开指定 URL【40†source】。</li>
<li><code>opencli browser tab list</code>：列出当前打开的标签页及其 targetId【40†source】。</li>
<li><code>opencli browser tab new <url></code>：在新标签页中打开 URL，并返回 targetId【40†source】。</li>
<li><code>opencli browser click <selector></code>：点击页面上的元素。</li>
<li><code>opencli browser type <selector> <text></code>：在输入框中输入文本。</li>
<li><code>opencli browser extract <selector></code>：提取页面元素的内容。</li>
<li><code>opencli browser network</code>：捕获页面的网络请求【37†source】。</li>
</ul>
</li>
</ol>
<p>通过浏览器桥接，OpenCLI 能够处理那些没有公开 API 或需要复杂交互的网站。例如，小红书（Xiaohongshu）、知乎（Zhihu）等网站的很多操作需要登录和模拟交互，OpenCLI 可以通过浏览器直接完成，而无需逆向工程其 API。这使得 OpenCLI 在<strong>网站自动化</strong>方面具备强大的能力。</p>
<h3 id="桌面应用控制cdp集成">桌面应用控制（CDP集成）</h3>
<p>除了网站，OpenCLI 还支持将<strong>Electron 桌面应用</strong>转化为 CLI 命令，通过 Chrome DevTools Protocol (CDP) 与应用交互【48†source】。其架构与浏览器桥接类似，但目标对象是本地 Electron 应用。主要流程和特点如下：</p>
<ol>
<li><strong>前提条件</strong>：目标 Electron 应用必须支持远程调试端口（通常通过 <code>--remote-debugging-port=<port></code> 启动参数开启）【48†source】。例如，Cursor IDE 可以通过 <code>/Applications/Cursor.app/Contents/MacOS/Cursor --remote-debugging-port=9226</code> 启动【48†source】。</li>
<li><strong>环境配置</strong>：在运行 OpenCLI 前，需要设置环境变量 <code>OPENCLI_CDP_ENDPOINT</code> 指向该调试端口，例如 <code>export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9226"</code>【48†source】。这样 OpenCLI 就知道通过 CDP 与哪个应用通信。</li>
<li><strong>适配器模式</strong>：对于 Electron 应用，OpenCLI 提供了一种<strong>5命令模式</strong>作为开发适配器的起点【48†source】。建议的实现顺序是：
<ul>
<li><code>status.js</code>：验证 CDP 连接是否可达，获取应用的基本信息（如 URL、标题等）【48†source】。</li>
<li><code>dump.js</code>：导出应用的 DOM 结构和 Accessibility 快照，用于分析页面结构【48†source】。</li>
<li><code>read.js</code>：提取应用当前可见的关键内容（如聊天记录、文档内容等）【48†source】。</li>
<li><code>send.js</code>：向应用发送输入（如在编辑器中输入文本并发送）【48†source】。</li>
<li><code>new.js</code>：创建新的会话/标签页（如新建聊天、新建文档）【48†source】。</li>
</ul>
这5个命令覆盖了连接检查、逆向工程、读取、写入和会话重置，是开发 Electron 适配器的基础【48†source】。
</li>
<li><strong>实现要点</strong>：在实现 Electron 适配器时，需要注意以下几点：
<ul>
<li><strong>获取正确的窗口/标签</strong>：由于 Electron 应用可能有多个窗口或标签，需要确保操作的是目标窗口【48†source】。</li>
<li><strong>等待渲染完成</strong>：应用界面可能动态加载，需要等待关键元素加载完毕再提取数据【48†source】。</li>
<li><strong>避免猜测选择器</strong>：不要凭肉眼猜测元素选择器，而应通过 dump 分析真实的 DOM 结构和属性（如 <code>data-testid</code>、<code>role</code> 等）【48†source】。</li>
<li><strong>处理受控编辑器</strong>：许多 Electron 应用使用 React 等框架的受控组件，直接设置 <code>.value</code> 可能无效。应优先使用模拟用户输入的方式（如聚焦后调用 <code>document.execCommand('insertText')</code> 或模拟键盘事件）【48†source】。</li>
</ul>
</li>
<li><strong>示例：Cursor IDE</strong>：OpenCLI 已经为 Cursor IDE 提供了适配器。通过 <code>opencli cursor</code> 系列命令，可以控制 Cursor 的 Composer、聊天等核心功能【48†source】。例如：
<ul>
<li><code>opencli cursor status</code>：检查 Cursor 的 CDP 连接状态【48†source】。</li>
<li><code>opencli cursor dump</code>：导出 Cursor 的 DOM 和 Accessibility 快照到本地文件【48†source】。</li>
<li><code>opencli cursor screenshot</code>：截取 Cursor 当前窗口的屏幕快照【48†source】。</li>
<li><code>opencli cursor new</code>：模拟按下 <code>Cmd+N</code> 新建文件/标签【48†source】。</li>
<li><code>opencli cursor send "message"</code>：在 Composer 中输入文本并提交【48†source】。</li>
<li><code>opencli cursor ask "message"</code>：发送消息并等待回复，再读取回复【48†source】。</li>
<li><code>opencli cursor read</code>：读取当前聊天面板的完整对话历史【48†source】。</li>
<li><code>opencli cursor composer "prompt"</code>：打开 Composer 并发送提示【48†source】。</li>
<li><code>opencli cursor model</code>：获取当前使用的 AI 模型名称【48†source】。</li>
<li><code>opencli cursor extract-code</code>：从当前对话中提取所有代码块【48†source】。</li>
<li><code>opencli cursor history</code>：列出最近的聊天/Composer 会话【48†source】。</li>
<li><code>opencli cursor export</code>：将当前对话导出为 Markdown【48†source】。</li>
</ul>
</li>
</ol>
<p>通过 CDP 集成，OpenCLI 将<strong>桌面应用自动化</strong>纳入了其能力版图。这使其不仅局限于 Web，还可以控制本地安装的 Electron 应用，极大地扩展了适用范围。开发者可以按照文档指引，为其他 Electron 应用编写适配器，将它们也变成 OpenCLI 可驱动的命令。</p>
<h3 id="ai-agent-集成设计">AI Agent 集成设计</h3>
<p>OpenCLI 的设计初衷之一是服务 AI 代理，使其能够像人类一样使用各种工具。为此，项目在架构上做了专门的设计，包括<strong>技能（Skills）机制</strong>、<strong>自适应修复</strong>和<strong>智能搜索</strong>等模块，以降低 AI 代理使用 OpenCLI 的门槛。</p>
<ol>
<li><strong>技能（Skills）机制</strong>：OpenCLI 引入了“技能”概念，本质上是预定义的提示或脚本，用于指导 AI 代理如何使用 OpenCLI 的能力【17†source】。每个技能对应一类任务，例如：
<ul>
<li><code>opencli-adapter-author</code>：用于实时操作网站或编写新适配器的技能【42†source】。当 AI 代理需要访问一个新网站时，该技能会引导它完成从侦察站点、发现 API、解码字段、编写适配器到验证的整个流程【42†source】。</li>
<li><code>opencli-autofix</code>：用于修复损坏适配器的技能【42†source】。当内置命令返回空数据或出错时，AI 代理可以调用此技能，自动诊断并尝试修复适配器。</li>
<li><code>opencli-browser</code>：浏览器自动化参考技能【42†source】。提供 OpenCLI 浏览器命令的详细用法，供 AI 代理查询。</li>
<li><code>opencli-usage</code>：命令和站点参考技能【42†source】。提供 OpenCLI 所有命令和站点的索引，方便 AI 代理查询可用功能。</li>
<li><code>smart-search</code>：智能搜索技能【42†source】。AI 代理可以通过自然语言查询，在现有适配器和命令中搜索所需功能。</li>
</ul>
技能通过 <code>npx skills add</code> 安装到代理的上下文中【17†source】。安装后，AI 代理在对话中可以引用这些技能，将其作为“工具”来调用。例如，Claude Code 可以在对话中调用 <code>opencli-adapter-author</code> 技能来帮助用户检查小红书通知【17†source】。技能机制使 AI 代理<strong>无需理解 OpenCLI 的底层实现</strong>，只需按照技能指引操作即可，大大降低了集成难度。
</li>
<li><strong>自适应修复（Autofix）</strong>：当适配器因为网站改版等原因失效时，OpenCLI 提供了自动修复能力。<code>opencli-autofix</code> 技能会尝试重新侦察站点、发现新的接口或选择器，并更新适配器代码【42†source】。这一过程对 AI 代理是透明的，它只需在适配器失败时调用 autofix 技能即可。这种设计保证了 OpenCLI 的<strong>持续可用性</strong>，即使目标站点变化，也能通过 AI 自主修复，无需人工介入。</li>
<li><strong>智能搜索与发现</strong>：OpenCLI 内置了丰富的命令和适配器，对于 AI 代理来说，如何快速找到所需的命令是关键。<code>smart-search</code> 技能提供了自然语言搜索能力，AI 代理可以用自然语言描述需求，技能会在命令注册表中搜索匹配的适配器【42†source】。例如，AI 代理可以询问“如何获取抖音热门视频”，smart-search 会返回相关适配器信息。此外，<code>opencli-usage</code> 技能提供了命令和站点的索引查询，AI 代理可以列出所有支持的网站或命令，以发现可用功能【42†source】。</li>
<li><strong>统一的 AGENT.md 集成</strong>：OpenCLI 的 README 中提到，它通过“统一的 AGENT.md 集成”让 AI 代理发现、学习和执行工具【17†source】。这意味着 OpenCLI 为 AI 代理提供了一个统一的接口或文档，使其能够自动获取 OpenCLI 的能力和用法，而无需人工编写集成代码。这体现了 OpenCLI 在设计上对 AI 代理的友好性：AI 可以像人类一样“阅读”OpenCLI 的文档并使用其命令，而无需特殊适配。</li>
</ol>
<p>综上，OpenCLI 在架构上充分考虑了 AI 代理的使用场景。通过技能、自动修复和智能搜索等机制，它降低了 AI 集成的复杂度，使 AI 代理能够<strong>自主地发现和使用工具</strong>。这与 OpenCLI “AI-native runtime”的定位相符，使其成为 AI 代理的强大工具库。</p>
<h2 id="功能特性分析">功能特性分析</h2>
<p>OpenCLI 提供了丰富的功能特性，既面向人类用户，也面向 AI 代理。下面将从<strong>网站与工具支持</strong>、<strong>命令行接口</strong>、<strong>账号安全与性能</strong>、<strong>扩展性</strong>等方面进行分析。</p>
<h3 id="丰富的网站与工具适配">丰富的网站与工具适配</h3>
<p>OpenCLI 内置了大量适配器，覆盖了国内外主流网站和开发工具，包括但不限于：</p>
<div class="component-group">
<span class="component-group-title">内置适配器示例</span>
<ul>
<li><strong>社交媒体与内容平台</strong>：Bilibili（B站）、Zhihu（知乎）、Xiaohongshu（小红书）、Reddit、Twitter/X、HackerNews、Douban（豆瓣）等【17†source】。例如，<code>opencli bilibili hot</code> 可获取B站热门视频，<code>opencli zhihu hot</code> 可获取知乎热门问题，<code>opencli xiaohongshu search note</code> 可搜索小红书笔记等【17†source】。</li>
<li><strong>开发者工具</strong>：GitHub CLI (<code>gh</code>)、Docker、Obsidian 笔记、Lark/飞书 CLI、DingTalk CLI、WeCom CLI、Vercel CLI 等【17†source】。OpenCLI 将这些工具作为<strong>CLI Hub</strong>集成，用户可以通过 <code>opencli gh pr list</code> 或 <code>opencli docker ps</code> 等命令直接调用，而无需记忆不同工具的命令【17†source】。如果目标工具未安装，OpenCLI 甚至会尝试自动安装（如通过 Homebrew）再执行【17†source】。</li>
<li><strong>桌面应用</strong>：Cursor IDE、ChatGPT App、ChatWise、Notion、Discord、Doubao 等 Electron 应用【17†source】。通过 CDP 集成，OpenCLI 可以控制这些应用的核心功能，如 Cursor 的 Composer 和聊天、Notion 的页面读写等【48†source】。</li>
<li><strong>其他</strong>：还包括 Amazon（商品搜索）、1688（商品与店铺）、Gitee（开源项目）、Google/Baidu 学术搜索、Spotify（音乐控制）、Xianyu（闲鱼二手交易）、Xiaoe（小鹅通课程）、Quark（网盘）等【17†source】。几乎涵盖了社交媒体、电商、开发、办公等常见领域。</li>
</ul>
</div>
<p>这些适配器使用统一的命令格式，例如 <code>opencli <site> <command> [options]</code>，让用户和 AI 代理可以用<strong>一致的方式</strong>访问不同网站和工具。OpenCLI 还支持<strong>自定义注册</strong>本地命令，通过 <code>opencli register mycli</code> 可以将任意本地可执行命令暴露到 OpenCLI 的发现表面，供 AI 代理发现和调用【17†source】。这进一步扩展了 OpenCLI 的适用范围。</p>
<h3 id="统一的命令行接口">统一的命令行接口</h3>
<p>OpenCLI 为所有适配器提供了<strong>统一的命令行接口</strong>和输出格式，这带来了几个显著优势：</p>
<ul>
<li><strong>一致的用法</strong>：用户无需记忆不同网站或工具的复杂用法，只需遵循 OpenCLI 的通用格式。例如，要获取某站点的热门内容，通常命令格式为 <code>opencli <site> hot</code>；要搜索内容，通常为 <code>opencli <site> search <query></code>。这种一致性降低了学习成本。</li>
<li><strong>多格式输出</strong>：所有命令均支持 <code>--format/-f</code> 选项，可输出为表格（默认）、JSON、YAML、Markdown、CSV 等格式【17†source】。例如，<code>opencli bilibili hot -f json</code> 会以 JSON 格式输出结果，方便程序处理；<code>-f csv</code> 则便于导入电子表格【17†source】。这保证了 OpenCLI 的输出既<strong>人类可读</strong>，又<strong>机器友好</strong>。</li>
<li><strong>可管道与脚本化</strong>：由于输出格式统一且命令遵循 Unix 哲学（如退出码规范），OpenCLI 的命令可以方便地串联到 shell 管道或脚本中【17†source】。例如，可以将 <code>opencli hackernews top -f json</code> 的结果通过管道传给 <code>jq</code> 进行进一步筛选，或者将多个 OpenCLI 命令写入脚本自动化执行。</li>
<li><strong>CI 友好</strong>：OpenCLI 的命令输出和退出码设计使其非常适合在 CI/CD 环境中使用【17†source】。命令执行成功返回 0，不同错误情况返回不同的非0退出码（如通用错误1、用法错误2、空结果66、服务不可用69、临时失败75、需认证77、配置错误78等）【17†source】。这种设计让 CI 脚本可以可靠地判断命令执行结果并采取相应措施。</li>
</ul>
<p>通过这些设计，OpenCLI 实现了<strong>“一个表面，多种用途”</strong>：既可以直接作为人类命令行工具使用，又可以作为 AI 代理的底层执行引擎，还能无缝融入自动化脚本和持续集成系统。</p>
<h3 id="账号安全与零凭证存储">账号安全与零凭证存储</h3>
<p>在需要登录的网站操作时，OpenCLI 采用了<strong>账号安全</strong>的设计：它<strong>复用用户已登录的浏览器会话</strong>，而不需要用户在命令行中输入密码或存储凭证【17†source】。具体而言，当执行需要登录的命令时，OpenCLI 会通过浏览器桥接访问用户浏览器中已打开的标签页，利用浏览器的 Cookie 和会话信息来完成请求【40†source】。这意味着：</p>
<ul>
<li><strong>零风控</strong>：由于使用真实浏览器会话，网站的反爬虫机制几乎无法检测，因为请求来自用户自身的浏览器环境【17†source】。</li>
<li><strong>零凭证存储</strong>：OpenCLI 不存储用户的密码或 Token，所有认证信息都留在浏览器中【17†source】。这避免了在命令行工具中保存敏感信息的安全风险。</li>
<li><strong>无需重新登录</strong>：只要用户在浏览器中保持登录状态，OpenCLI 就能直接使用，省去了在命令行工具中重新登录的麻烦【40†source】。</li>
</ul>
<p>这种设计在保证安全的同时，也极大方便了用户。用户只需确保在 Chrome/Chromium 中登录目标网站，然后使用 OpenCLI 命令即可，无需在命令行中传递任何敏感信息。对于 AI 代理来说，这同样重要——代理可以代表用户执行操作，但不需要获取用户的密码，从而降低了安全风险。</p>
<h3 id="零llm运行成本">零LLM运行成本</h3>
<p>OpenCLI 的另一个显著特点是<strong>零 LLM 运行成本</strong>【17†source】。这意味着使用 OpenCLI 执行命令时，不会消耗任何大模型（LLM）的 Token 或调用次数。原因在于 OpenCLI 的所有操作都是基于预先编写好的适配器逻辑和浏览器自动化，而不需要实时调用 LLM 来生成行为。例如，获取知乎热门问题，OpenCLI 是通过浏览器或接口直接抓取，而不是让 LLM 去理解页面或编写脚本。这种设计带来几个优势：</p>
<ul>
<li><strong>成本固定</strong>：无论执行多少次命令，OpenCLI 本身不产生额外的 AI 调用费用【17†source】。这对于需要频繁调用 CLI 的场景（如批量数据处理、持续监控）非常重要，避免了高昂的 LLM 使用成本。</li>
<li><strong>性能稳定</strong>：由于不依赖 LLM 的响应速度，OpenCLI 的执行延迟主要取决于目标网站或工具的响应，而不会因为 LLM 调用而变慢。这使得 OpenCLI 的性能更加可预测和稳定。</li>
<li><strong>确定性</strong>：相同命令始终产生相同输出结构【17†source】。因为行为是预定义的，不会因为 LLM 的不确定性而变化。这对于需要可靠输出的场景（如数据管道、自动化测试）至关重要。</li>
</ul>
<p>当然，这并不意味着 OpenCLI 不能与 LLM 结合。实际上，OpenCLI 正是为 LLM 提供了一个强大的工具层，让 LLM 可以通过调用 OpenCLI 的命令来与外部世界交互，而 LLM 自身不需要直接处理网络请求或页面解析。这种<strong>解耦</strong>既降低了 LLM 的负担，也保证了工具层的稳定和高效。</p>
<h3 id="可扩展性与插件生态">可扩展性与插件生态</h3>
<p>OpenCLI 设计了完善的扩展机制，鼓励社区和用户扩展其功能：</p>
<ul>
<li><strong>适配器扩展</strong>：任何人都可以编写新的适配器来支持新的网站或工具。适配器可以放在 <code>~/.opencli/clis/<site>/</code> 目录下，OpenCLI 会自动发现并注册【35†source】。开发者只需遵循适配器 API 规范，使用 <code>cli()</code> 注册命令，定义策略和管道即可【44†source】。OpenCLI 还提供了 <code>opencli browser init</code> 和 <code>opencli browser verify</code> 等命令，帮助开发者初始化适配器骨架和验证适配器输出【42†source】。</li>
<li><strong>插件体系</strong>：对于更复杂的功能，OpenCLI 引入了插件机制【17†source】。插件可以是新的命令集，也可以是增强现有功能（如提供新的输出格式、集成第三方服务等）。用户可以通过 <code>opencli plugin install <plugin></code> 安装插件【17†source】。OpenCLI 已经有一些社区插件，如 GitHub Trending、多平台热门聚合、掘金热门等【17†source】。插件机制遵循 OpenCLI 的统一接口，安装后即可像内置命令一样使用。</li>
<li><strong>技能扩展</strong>：技能本质上是面向 AI 代理的插件。开发者可以为特定任务编写技能脚本，让 AI 代理更高效地使用 OpenCLI。例如，可以编写一个技能专门处理电商数据抓取，或编写一个技能将 OpenCLI 输出直接导入某数据库。技能通过 <code>npx skills add</code> 安装，方便 AI 代理获取【17†source】。</li>
<li><strong>开放源码与贡献</strong>：OpenCLI 是开源项目，遵循 Apache-2.0 许可【17†source】。项目欢迎社区贡献适配器、修复和文档。贡献指南（CONTRIBUTING.md）详细说明了如何参与开发，包括代码风格、测试和提交流程等【17†source】。这种开放模式保证了 OpenCLI 的持续演进和生态繁荣。</li>
</ul>
<p>通过适配器、插件和技能三层扩展体系，OpenCLI 构建了一个<strong>可生长的工具生态</strong>。用户和开发者可以根据自己的需求，灵活地扩展 OpenCLI 的功能，使其成为一个真正<strong>通用且可定制</strong>的 CLI 运行时。</p>
<h2 id="ai-集成能力分析">AI 集成能力分析</h2>
<p>OpenCLI 在 AI 代理集成方面表现出色，其设计充分考虑了 AI 代理的使用场景和需求。下面从<strong>AI 代理友好性</strong>、<strong>技能系统</strong>、<strong>自动修复</strong>和<strong>智能搜索</strong>等方面进行分析。</p>
<h3 id="ai-agent-友好设计">AI Agent 友好设计</h3>
<p>OpenCLI 的很多特性都直接服务于 AI 代理：</p>
<ul>
<li><strong>统一接口</strong>：AI 代理不需要学习不同网站或工具的专用 API，只需掌握 OpenCLI 的命令格式和用法。这大大降低了 AI 集成的复杂度，使其可以<strong>一通百通</strong>地访问各种服务。</li>
<li><strong>确定性输出</strong>：AI 代理依赖稳定的输出格式来解析结果。OpenCLI 保证相同命令始终返回相同结构的输出【17†source】，并支持多种格式，方便代理根据需要选择。例如，代理可以要求 JSON 格式输出，然后用代码直接解析，而无需处理 HTML 或自然语言的歧义。</li>
<li><strong>账号安全</strong>：AI 代理在代表用户操作时，无需获取用户的密码等敏感信息【17†source】。这通过复用浏览器会话实现，既方便又安全，符合 AI 代理作为“助手”的定位。</li>
<li><strong>零 LLM 成本</strong>：AI 代理调用 OpenCLI 命令不会消耗自身的 Token 或调用次数【17†source】。这使得代理可以频繁调用 CLI 而无需担心成本，非常适合需要大量工具调用的场景（如信息检索、数据抓取）。</li>
<li><strong>丰富的功能集</strong>：OpenCLI 提供了从社交媒体到开发工具的广泛命令集，AI 代理可以用它来完成从内容获取、数据分析到自动化运维等各种任务，而无需额外集成其他工具。</li>
</ul>
<p>这些特性使 OpenCLI 成为一个<strong>AI 代理的理想工具库</strong>。代理可以像人类一样使用命令行工具，但借助 OpenCLI，它有了统一、安全且强大的工具接口。这降低了 AI 代理与外部世界交互的门槛，使其能更专注于高层决策而非底层实现。</p>
<h3 id="技能skills机制">技能（Skills）机制</h3>
<p>OpenCLI 的技能系统是其 AI 集成的核心创新之一。每个技能相当于一个<strong>AI 代理的“工具包”</strong>，封装了一类任务的执行流程和知识。技能机制带来的价值包括：</p>
<ul>
<li><strong>任务引导</strong>：技能为 AI 代理提供了明确的指引。例如，<code>opencli-adapter-author</code> 技能会引导代理一步步完成从访问网站、发现接口到编写适配器的全过程【42†source】。代理只需按照技能提示执行，无需自己摸索。</li>
<li><strong>知识沉淀</strong>：技能包含了领域知识，如如何解析特定网站的结构、如何处理分页、如何解码字段等。这些知识通过技能传递给 AI 代理，使其能处理复杂任务，而不需要人类反复提示。</li>
<li><strong>可组合性</strong>：AI 代理可以组合使用多个技能。例如，先用 <code>opencli-adapter-author</code> 技能发现一个网站的接口，再用 <code>opencli-browser</code> 技能执行浏览器操作，最后用 <code>opencli-usage</code> 技能查询其他命令。这种组合使代理能完成端到端的复杂工作流。</li>
<li><strong>可扩展性</strong>：开发者可以创建新的技能来扩展 AI 代理的能力。例如，可以编写一个技能专门处理某类数据可视化，或将 OpenCLI 输出转化为特定格式。技能通过 <code>npx skills add</code> 安装，AI 代理即可获取新能力【17†source】。</li>
</ul>
<p>技能机制本质上解决了<strong>AI 代理如何使用工具</strong>的问题。通过将工具的使用方法编码为技能，OpenCLI 让 AI 代理<strong>无需理解工具底层实现</strong>就能高效使用，这大大降低了 AI 集成的门槛。同时，技能也为人类开发者提供了一种封装复杂流程的方式，使得 OpenCLI 的能力可以被<strong>模块化地扩展和复用</strong>。</p>
<h3 id="自适应适配器修复">自适应适配器修复</h3>
<p>网站和应用的改版常常导致适配器失效，这是自动化工具的一大痛点。OpenCLI 通过 <code>opencli-autofix</code> 技能引入了<strong>自适应修复</strong>能力，使 AI 代理能够自动应对适配器失败的情况：</p>
<ul>
<li><strong>自动诊断</strong>：当内置命令返回空数据或错误时，AI 代理可以调用 <code>opencli-autofix</code> 技能。该技能会自动诊断问题，例如检查是否需要登录、接口是否变化、选择器是否失效等【42†source】。</li>
<li><strong>自动修复</strong>：在诊断后，autofix 会尝试修复适配器。这可能包括重新运行站点侦察（site-recon）以发现新的接口，更新字段映射，调整选择器，甚至重写部分适配器逻辑【42†source】。修复完成后，会重新验证适配器输出是否正常。</li>
<li><strong>闭环流程</strong>：Autofix 技能确保了适配器的维护形成一个闭环：当适配器失效时，AI 代理可以自主修复，而无需人工介入。这极大地提高了 OpenCLI 的<strong>健壮性</strong>和<strong>持续可用性</strong>。</li>
</ul>
<p>这种自适应修复能力是 OpenCLI 区别于传统 CLI 工具的重要特征。它意味着 OpenCLI 不会因为目标站点的一点变化就完全失效，而是可以通过 AI 自主调整，继续提供服务。对于 AI 代理来说，这提供了更高的可靠性；对于人类用户，这也降低了维护成本，因为很多问题可以被自动解决。</p>
<h3 id="智能搜索与发现">智能搜索与发现</h3>
<p>OpenCLI 提供了<strong>智能搜索</strong>功能，帮助 AI 代理快速找到所需的命令或适配器：</p>
<ul>
<li><strong>自然语言搜索</strong>：AI 代理可以通过 <code>smart-search</code> 技能用自然语言查询所需功能【42†source】。例如，代理可以问“如何获取抖音热门视频”，smart-search 会在命令注册表中搜索相关关键词，返回匹配的适配器和命令。这解决了 AI 代理在面对庞大命令集时不知道从何下手的问题。</li>
<li><strong>命令索引</strong>：<code>opencli-usage</code> 技能提供了对所有命令和站点的索引【42†source】。AI 代理可以列出所有支持的网站，或查询某站点下有哪些命令。这类似于一个命令字典，供代理参考。</li>
<li><strong>上下文感知</strong>：OpenCLI 的技能和搜索机制还考虑了上下文。例如，当 AI 代理在执行某网站相关任务时，可以调用 <code>opencli-browser</code> 技能获取该网站的浏览器自动化参考，从而知道如何操作该网站【42†source】。这种上下文相关的帮助使代理能更精确地获取所需信息。</li>
</ul>
<p>通过智能搜索和发现，AI 代理可以<strong>自主地探索 OpenCLI 的功能</strong>，而无需人类逐一指导。这赋予了代理更强的自主性和灵活性，使其能够在面对新任务时，自行找到合适的工具和方法。对于人类用户，这些功能也提供了便利，比如可以用自然语言查询 OpenCLI 能做什么，而不必阅读完整文档。</p>
<h2 id="安装指南">安装指南</h2>
<p>要开始使用 OpenCLI，需要完成以下安装步骤：</p>
<h3 id="安装-opencli-主程序">安装 OpenCLI 主程序</h3>
<p>OpenCLI 通过 npm 发布为全局包，可以使用 npm 或 yarn 安装：</p>
<pre><code class="language-bash">npm install -g <span class="mention-invalid">@jackwener</span>/opencli</code></pre>
<p>或者使用 yarn：</p>
<pre><code class="language-bash">yarn global add <span class="mention-invalid">@jackwener</span>/opencli</code></pre>
<p>安装完成后，即可在命令行使用 <code>opencli</code> 命令。请确保 Node.js 版本在 21.0.0 以上（或使用 Bun 1.0 以上）【17†source】。</p>
<h3 id="安装浏览器桥接扩展">安装浏览器桥接扩展</h3>
<p>为了使 OpenCLI 能够访问需要登录的网站，需要安装浏览器桥接扩展。该扩展连接用户浏览器与 OpenCLI 的本地守护进程，实现会话复用。安装方法有两种：</p>
<div class="component-group">
<span class="component-group-title">浏览器桥接扩展安装方式</span>
<ul>
<li><strong>方法一（推荐）：从 Chrome 网上应用店安装</strong>。在 Chrome 浏览器中访问 OpenCLI 的扩展页面，点击“添加至 Chrome”即可完成安装【17†source】。这是最简单的方式，扩展会自动更新。</li>
<li><strong>方法二：手动加载扩展</strong>。从 OpenCLI 的 GitHub Releases 页面下载最新版本的扩展压缩包（如 <code>opencli-extension-v{version}.zip</code>），解压后在 Chrome 浏览器中打开 <code>chrome://extensions</code>，启用“开发者模式”，然后点击“加载已解压的扩展程序”，选择解压后的目录【17†source】。这种方式适合开发或离线环境。</li>
</ul>
</div>
<p>安装扩展后，需要确保 Chrome 浏览器正在运行且已登录目标网站。OpenCLI 的守护进程会自动启动并与扩展通信，无需手动配置【40†source】。</p>
<h3 id="验证安装">验证安装</h3>
<p>安装完成后，可以使用 <code>opencli doctor</code> 命令检查环境是否正常：</p>
<pre><code class="language-bash">opencli doctor</code></pre>
<p>该命令会验证 Node.js 版本、守护进程连接、浏览器扩展状态等，并给出提示【17†source】。如果一切正常，会显示类似“Everything looks good”的信息。如果浏览器未连接，会提示“Browser Bridge not connected”【17†source】，此时需要确保 Chrome 扩展已安装且 Chrome 浏览器已打开。</p>
<p>安装和验证完成后，即可开始使用 OpenCLI 的各种命令。例如，可以运行 <code>opencli list</code> 查看所有可用命令，或尝试 <code>opencli hackernews top --limit 5</code> 获取 Hacker News 的前5条新闻【17†source】。</p>
<h2 id="使用指南">使用指南</h2>
<p>OpenCLI 的使用分为<strong>人类用户</strong>和<strong>AI 代理</strong>两种视角。下面分别介绍，以及提供一些常用命令示例。</p>
<h3 id="人类用户使用">人类用户使用</h3>
<p>对于人类用户，OpenCLI 提供了直接且强大的命令行工具体验：</p>
<ul>
<li><strong>查看可用命令</strong>：使用 <code>opencli list</code> 可以列出所有已注册的命令，包括内置适配器和自定义注册的命令【17†source】。这有助于发现 OpenCLI 能做什么。</li>
<li><strong>执行适配器命令</strong>：使用 <code>opencli <site> <command> [options]</code> 的格式执行具体命令。例如：
<ul>
<li><code>opencli bilibili hot</code>：获取B站热门视频【17†source】。</li>
<li><code>opencli zhihu hot --limit 10</code>：获取知乎前10个热门问题。</li>
<li><code>opencli xiaohongshu search note "关键词"</code>：在小红书搜索笔记。</li>
<li><code>opencli hackernews top --limit 5</code>：获取 Hacker News 前5条新闻【17†source】。</li>
<li><code>opencli gh pr list --limit 5</code>：使用 GitHub CLI 列出当前仓库前5个 Pull Request【17†source】。</li>
</ul>
</li>
<li><strong>诊断与调试</strong>：如果遇到问题，可以使用 <code>opencli doctor</code> 检查环境【17†source】；使用 <code>opencli <site> <command> --verbose</code> 或设置环境变量 <code>OPENCLI_VERBOSE=1</code> 获取详细日志，帮助定位问题。</li>
<li><strong>输出格式</strong>：通过 <code>--format/-f</code> 选项选择输出格式。例如 <code>-f json</code> 输出 JSON，<code>-f csv</code> 输出 CSV【17†source】。默认输出表格，人类可读性好。</li>
<li><strong>自定义命令</strong>：使用 <code>opencli register <name></code> 可以将本地命令注册到 OpenCLI，使其出现在 <code>opencli list</code> 中【17†source】。例如，<code>opencli register mycli</code> 会注册一个名为 <code>mycli</code> 的命令，之后就可以用 <code>opencli mycli</code> 调用。</li>
</ul>
<p>人类用户可以像使用其他 CLI 工具一样使用 OpenCLI，但享受到了<strong>统一的接口</strong>和<strong>丰富的功能</strong>。OpenCLI 的命令设计遵循 Unix 哲学，输出友好且可管道，非常适合脚本和日常命令行操作。</p>
<h3 id="ai-agent-使用">AI Agent 使用</h3>
<p>对于 AI 代理，OpenCLI 提供了更高级的使用方式，通常不需要代理直接运行 <code>opencli</code> 命令，而是通过<strong>技能</strong>来调用：</p>
<ul>
<li><strong>安装技能</strong>：AI 代理首先需要安装 OpenCLI 的技能。可以使用 <code>npx skills add jackwener/opencli</code> 一键安装所有技能，或按需安装单个技能【17†source】。例如：
<pre><code class="language-bash">npx skills add jackwener/opencli --skill opencli-adapter-author
npx skills add jackwener/opencli --skill opencli-autofix
npx skills add jackwener/opencli --skill opencli-browser
npx skills add jackwener/opencli --skill opencli-usage
npx skills add jackwener/opencli --skill smart-search</code></pre>
</li>
<li><strong>使用技能</strong>：安装后，AI 代理可以在对话中引用这些技能，将其作为工具来调用。例如，Claude Code 可以在对话中调用 <code>opencli-adapter-author</code> 技能来帮助用户检查小红书通知【17†source】。技能会内部调用相应的 OpenCLI 命令，代理无需关心底层细节。</li>
<li><strong>典型工作流</strong>：
<ul>
<li>当用户请求访问一个新网站时，AI 代理可以调用 <code>opencli-adapter-author</code> 技能。该技能会引导代理完成从打开浏览器、侦察网站、发现接口、解码字段、编写适配器到验证的整个流程【42†source】。最终，代理可以为用户生成一个可复用的 OpenCLI 命令。</li>
<li>当代理发现某个内置命令返回空结果或错误时，可以调用 <code>opencli-autofix</code> 技能尝试自动修复【42†source】。</li>
<li>当代理需要查询 OpenCLI 的功能时，可以调用 <code>opencli-usage</code> 技能获取命令和站点列表【42†source】。</li>
<li>当代理需要执行浏览器操作时，可以调用 <code>opencli-browser</code> 技能获取浏览器命令参考【42†source】。</li>
<li>当代理不确定某个功能是否存在时，可以调用 <code>smart-search</code> 技能进行自然语言搜索【42†source】。</li>
</ul>
</li>
<li><strong>会话管理</strong>：AI 代理在使用浏览器功能时，可以利用 OpenCLI 的 <code>--live</code> 和 <code>--focus</code> 标志来控制会话生命周期【33†source】。例如，在调试适配器时，使用 <code>--live --focus</code> 可以保持浏览器窗口打开并聚焦，方便代理观察最终页面状态【42†source】。</li>
</ul>
<p>通过技能，AI 代理可以<strong>像人类一样使用 OpenCLI</strong>，而无需理解其底层实现。这大大降低了 AI 集成的门槛，使代理能够专注于与用户的交互和高层决策，而不必关心如何与各种网站交互的技术细节。</p>
<h3 id="常用命令示例">常用命令示例</h3>
<p>下面列出一些 OpenCLI 的常用命令示例，涵盖不同站点和功能：</p>
<div class="component-group">
<span class="component-group-title">常用命令示例</span>
<ul>
<li><strong>社交媒体</strong>：
<ul>
<li><code>opencli bilibili hot --limit 10</code>：获取B站前10个热门视频。</li>
<li><code>opencli zhihu hot --limit 10</code>：获取知乎前10个热门问题。</li>
<li><code>opencli xiaohongshu search note "旅行"</code>：在小红书搜索包含“旅行”的笔记。</li>
<li><code>opencli reddit hot</code>：获取 Reddit 热门帖子。</li>
<li><code>opencli twitter trending</code>：获取 Twitter/X 的趋势话题。</li>
</ul>
</li>
<li><strong>开发工具</strong>：
<ul>
<li><code>opencli gh pr list --limit 5</code>：使用 GitHub CLI 列出当前仓库前5个 PR【17†source】。</li>
<li><code>opencli docker ps</code>：列出运行中的 Docker 容器【17†source】。</li>
<li><code>opencli obsidian search "AI"</code>：在 Obsidian 中搜索包含“AI”的笔记【17†source】。</li>
</ul>
</li>
<li><strong>桌面应用</strong>：
<ul>
<li><code>opencli cursor status</code>：检查 Cursor IDE 的 CDP 连接状态【48†source】。</li>
<li><code>opencli cursor read</code>：读取 Cursor 当前聊天面板的对话历史【48†source】。</li>
<li><code>opencli notion search "项目计划"</code>：在 Notion 中搜索包含“项目计划”的页面。</li>
</ul>
</li>
<li><strong>通用功能</strong>：
<ul>
<li><code>opencli list</code>：列出所有可用命令【17†source】。</li>
<li><code>opencli doctor</code>：检查 OpenCLI 环境是否正常【17†source】。</li>
<li><code>opencli browser open https://www.baidu.com</code>：在默认浏览器标签页中打开百度【40†source】。</li>
<li><code>opencli browser tab list</code>：列出当前打开的浏览器标签页【40†source】。</li>
</ul>
</li>
</ul>
</div>
<p>这些示例展示了 OpenCLI 的广泛适用性。无论是获取信息、自动化操作还是开发调试，OpenCLI 都提供了相应的命令。用户和 AI 代理可以根据需求组合使用这些命令，完成复杂的任务。</p>
<h3 id="输出格式与管道">输出格式与管道</h3>
<p>OpenCLI 的命令输出支持多种格式，方便不同场景使用：</p>
<ul>
<li><strong>表格（默认）</strong>：以表格形式输出，适合人类阅读。例如 <code>opencli bilibili hot</code> 默认输出表格，包含视频标题、作者、播放量等列。</li>
<li><strong>JSON</strong>：使用 <code>-f json</code> 输出 JSON 格式。例如 <code>opencli bilibili hot -f json</code> 会输出 JSON 数组，每个元素包含完整的数据对象。这便于程序解析或存入数据库。</li>
<li><strong>YAML</strong>：使用 <code>-f yaml</code> 输出 YAML 格式。YAML 格式可读性好，也常用于配置文件。</li>
<li><strong>Markdown</strong>：使用 <code>-f md</code> 输出 Markdown 表格。可以直接嵌入 Markdown 文档。</li>
<li><strong>CSV</strong>：使用 <code>-f csv</code> 输出 CSV 格式。适合导入电子表格或数据清洗工具。</li>
</ul>
<p>此外，OpenCLI 的命令遵循标准的退出码规范【17†source】。例如，成功返回0，参数错误返回2，未登录返回77等【17†source】。这使得 OpenCLI 的命令可以方便地与 shell 脚本、CI 系统集成，通过退出码判断执行结果。</p>
<p>通过丰富的输出格式和规范的退出码，OpenCLI 实现了<strong>人机两宜</strong>：既可以直接为人所用，又可以被程序和 AI 代理可靠地调用和解析。</p>
<h2 id="总结">总结</h2>
<p>OpenCLI 是一个雄心勃勃且功能强大的项目，它将<strong>网站、浏览器、桌面应用和本地工具</strong>统一到了一个命令行接口下，为人类用户和 AI 代理提供了前所未有的自动化能力。通过其精巧的架构设计——包括模块化的适配器系统、浏览器桥接、CDP 集成、技能机制等——OpenCLI 实现了<strong>高性能、高扩展性和高安全性</strong>的统一。它内置的丰富适配器覆盖了日常所需，而其开放的插件和技能体系又保证了生态的持续繁荣。对于开发者而言，OpenCLI 提供了一套完善的 API 和工具，使其可以轻松扩展新功能；对于 AI 代理而言，OpenCLI 是一个强大的工具库，让其能够像人类一样使用各种工具，而无需关心底层实现细节。总而言之，OpenCLI 代表了 CLI 工具和 AI 集成的新范式，其<strong>“Make Any Website & Tool Your CLI”</strong>的愿景正在成为现实，为未来的自动化和智能化提供了坚实的基础。【17†source】</p>
</div>
</body>
</html>
