常见问题

为 Agent 和开发者整理的高频问答。每个回答都做成独立的一段话，方便 AI 助手直接引用。

Uni-CLI 是什么？

Uni-CLI 是 AI Agent 控制 computer 的通用平台。它把网站、登录态浏览器、桌面应用、本地工具、文件、操作系统能力、MCP 服务、截图、无障碍树和 App wrapper 收进可治理的操作层；一条路径接受意图、选择行动 substrate、按策略执行、返回证据、诊断失败，并修复或换路。当前覆盖 317 个站点、1772 条命令。

和浏览器自动化库有什么区别？

浏览器自动化只是一个行动 substrate。Uni-CLI 位于它之上，提供 operation contract、权限策略、证据回执、delivery assessment 和 repair/reroute 路径。无论是浏览器命令、桌面动作、subprocess bridge、MCP route 还是 App wrapper，都应该返回同一种 AgentEnvelope，并遵守同一条控制闭环。

和 computer-use sandbox 有什么区别？

computer-use sandbox 给 Agent 一个带屏幕、鼠标、键盘和 benchmark hook 的环境。Uni-CLI 可以使用这类边界，但它的类目更大：通过最小可用 substrate 控制用户真实软件环境，从 typed API、browser CDP，到桌面无障碍、subprocess、文件、协议和 visual fallback。

为什么是 CLI 而不是 MCP 服务？

docs/BENCHMARK.md 实测一次 --limit 5 列表型 Uni-CLI 调用的总预算落在 364-423 token (中位 412)；相同动作走 MCP 服务，工具清单常驻在 Agent 上下文里——每个服务通常 1500-3000 token，调用与否都占着。Uni-CLI 两条路径都提供，CLI 是便宜且确定性的主入口，MCP 包同一份目录给纯 MCP 运行时。

自修复 (self-repair) 是怎么跑的？

操作失败时 Uni-CLI 会吐出结构化的错误 JSON，里面有 source path、失败 step 或边界、动作描述、是否可重试、替代路径和一句话建议。Agent 可以读那个路径下的 YAML 或代码，改选择器、认证头或边界逻辑，然后跑 unicli repair <site> <command> 或有界 delivery verification。用户本地修复会保存在 ~/.unicli/adapters/，npm update 不会冲掉。

支持哪些 AI Agent 运行时？

任何能 spawn 子进程的运行时都能直接使用 Uni-CLI。Uni-CLI 同时也跑 MCP 服务、ACP 网关，并通过 AGENTS.md 让 Agent 自动发现能力，不用手动配置。

一共有多少站点和命令？

v0.225.2 生成操作目录包含 317 个站点、1772 条命令、1222 个适配器、103 个 pipeline step、9183 个测试。真正重要的不是数字，而是一套共享控制合同：意图、策略、行动 substrate、证据、交付、修复，以及跨 web、browser、desktop、本地工具、文件和协议的同一种 AgentEnvelope。

能下载论文并读取本地 PDF 吗？

能。unicli arxiv download <id> --output ./papers -f json 下载论文 PDF，unicli pdf read ./papers/<id>.pdf --first_page 1 --last_page 3 -f json 把本地 PDF 文本抽成同一种结构化 envelope。Agent 可以先搜 arXiv，再下载 PDF、读取指定页、整理摘要，全程不离开 CLI 契约。

ACG、动画、漫画、booru 内容应该怎么搜？

先按意图搜索，再落到领域命令：unicli search "花火 星穹铁道 character"、unicli anilist characters "Sparkle" -f json、unicli moegirl search "花火 星穹铁道" -f json、unicli danbooru tags sparkle -f json。booru adapter 走明确 tag 工作流；动画、游戏、wiki adapter 按来源能力提供实体搜索、媒体目录、年份筛选、热度/排名/趋势排序。

不写 TypeScript 能加新站点吗？

能。推荐的贡献格式是短 YAML 适配器，写清楚 site、command、strategy 和 pipeline。YAML 是 operation contract 下面的作者格式，不是产品身份。unicli init <site> <command> 帮你生成骨架，unicli dev <path> 边写边热重载。大多数适配器一行 TypeScript 都不用写。

需要登录的网站能跑吗？

能。strategy 会按 public → cookie → header (cookie + CSRF) → intercept (浏览器 XHR 抓取) → ui (交互) 级联探测。Cookie 文件存在 ~/.unicli/cookies/，Uni-CLI 自动选最便宜的能拿到合法数据的策略。

token 成本上比 MCP 好多少？

docs/BENCHMARK.md 实测列表型 Uni-CLI 调用预算 364-423 token (中位 412)。MCP 服务必须把工具清单驻在上下文里，通常每个服务 1500-3000 token，工具调与不调都占着。Uni-CLI 用结构化错误回执让 Agent 避开把上下文越撑越大的重试 loop。

是免费开源的吗？

是。Uni-CLI 走 Apache-2.0，仓库在 olo-dot-io/Uni-CLI，npm 包是 @zenalexa/unicli。没有付费功能、没有锁住的命令、没有遥测。所有 YAML 适配器和 pipeline step 都让 Agent 直接读、直接改。

完整命令清单在哪？

完整操作目录在 /reference/sites。Agent 可读索引: /llms.txt 是策划过的目录，/llms-full.txt 是文档全文拼接。

适配器坏了怎么报？

去 github.com/olo-dot-io/Uni-CLI/issues 开 issue，把那段结构化错误 JSON 贴上来。错误回执里已经包含 adapter 路径和失败 step，通常改一行 YAML 就能修。