@zenalexa/unicli

v0.225.2

Published

2 days ago

Universal computer-control platform for agents: intent, policy, action substrates, evidence, delivery, and repair.

0High
0Medium
0Low

zenalexa

cli ai-agent browser-automation desktop-automation mcp cli-hub agent-tools claude-code codex cursor

30 秒安装并运行

npm install -g @zenalexa/unicli
unicli do "找 Hacker News 首页"
unicli extract https://example.com --max-chars 1200
unicli compute snapshot --app Calculator --format compact
npx @zenalexa/unicli mcp serve

| Agent 遇到的问题 | Uni-CLI 给的答案 | | --------------------------- | -------------------------------------------------------------------------------- | | "什么能控制这个？" | unicli search 和 unicli do 把意图转成排序后的操作计划 | | "应该走哪个软件边界？" | Web、browser、desktop、subprocess、protocol、visual substrate 共享同一个 runtime | | "能不能安全地跑？" | permission profile 暴露 open、confirm、locked 三种执行模式 | | "刚才发生了什么？" | 每次运行都返回带 data、context、retryability 和证据钩子的 AgentEnvelope | | "这条路径失败了。" | unicli delivery 把运行证据转成诊断、下一次实验、执行和修复边界 | | "把它接给我的 Agent host。" | unicli mcp serve、ACP、native CLI、JSON stream 暴露同一份操作合同 |

为什么需要它

下一代软件用户不只是拿鼠标的人，也会是带着任务、上下文窗口、权限预算和证据需求的 Agent。车载助手能成立，是因为导航、媒体、空调、辅助驾驶都在一个有边界的控制层下面。通用 computer 也有同样结构，只是规模更大：浏览器状态、桌面 App、本地工具、文件、OS 服务、无障碍树、截图、协议服务、站点路径，都需要被编译成一个可控环境。

Uni-CLI 就是这个控制面。它不是浏览器库、computer-use VM、自然语言 shell、MCP 服务，也不是一堆站点 wrapper；这些都是有价值的 substrate。Uni-CLI 位于它们之上，把 Agent 的意图变成可治理的软件动作，返回证据回执，并保留可修复、可换路的路径。

因此项目里这些能力不是并列身份，而是同一个平台的下层：

operation contract：覆盖网站、App、OS 状态、本地工具、文件和协议的可复用动作；
substrate adapter：HTTP、browser CDP、desktop accessibility、subprocess、visual fallback、MCP、ACP、external CLI；
invocation kernel：校验参数、执行策略、选择 substrate、统一 envelope；
evidence / delivery loop：诊断失败、记录下一条假设、修复或换路，并判断目标是否已经交付。

Computer-Control 闭环

严肃的 Agent 操作基本都走同一条链路。

| 步骤 | Uni-CLI 给 Agent 的东西 | | ---- | -------------------------------------------------------------------------------------------- | | 意图 | unicli search 和 unicli do 把任务映射成候选操作、参数、认证方式、样例和风险信号 | | 选择 | operation contract 选择能行动的最小边界：API、browser、desktop、subprocess、protocol、visual | | 治理 | open、confirm、locked profile 在请求、写入、启动进程前拦住高风险动作 | | 行动 | 共享 kernel 调用选中的 substrate，不让 wrapper 各自定义行为 | | 观察 | AgentEnvelope v2 返回 data、context、retryability、耗时和证据 hook | | 诊断 | unicli delivery assess 把失败归为产品漂移、缺少上下文、策略阻断或上游/环境问题 | | 修复 | unicli delivery trajectory 和 repair-candidate 让下一次实验继续受证据约束 | | 交付 | evidence gate 判断目标已交付、仍在进行、被阻断，还是已经耗尽 | | 暴露 | 同一条操作可以给人、Agent、MCP client、ACP client、CI 和脚本调用 |

和常见路径的区别

| 如果从...开始 | 通常会得到... | Uni-CLI 把它放到哪个上位模型下面 | | ----------------------- | --------------------------------- | -------------------------------------------------------------------- | | 浏览器自动化 | 强大的网页控制 | operation contract、登录态姿态、证据、交付和修复 | | computer-use sandbox | 屏幕、鼠标、键盘和 benchmark 环境 | 和本地 App、浏览器、CLI、协议共用的 Agent-to-computer 闭环 | | 自然语言本地执行 | 灵活的 shell 和代码能力 | typed 操作边界、策略、回执和可复用合同 | | MCP server 集合 | 接 Agent 很方便，但常驻上下文很重 | search-first 的低 token 主路径，以及 host 需要时才启用的 MCP profile | | 单 App / 单站点 wrapper | 对一个 surface 的深访问 | 横跨 web、desktop、本地工具、文件和 Agent 协议的一套可治理 runtime |

它控制什么

Uni-CLI 把 computer 当作环境，把每一个可控边界当作 substrate。substrate 可以是高层 typed API，也可以是低层 visual；回执保持同一种。

| 层级 | 能力 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Operation contract | 可复用动作，带 args、输出形状、认证姿态、安全元数据、source path、repair path | | Web 和 API | public、cookie、header、browser-intercept、download、upload、publish、extract、search 工作流 | | Browser session | CDP navigate/click/type/fill/select/wait/network/screenshot/snapshot/evidence | | Desktop 和 OS | macOS App、Accessibility ref、截图、剪贴板、日历、亮度、App action、本地系统状态 | | 本地工具和文件 | subprocess bridge、外部二进制、PDF/论文工作流、文件转换、媒体工具、开发者 CLI | | Agent 协议 | native CLI、JSON stream、MCP、ACP、Streamable HTTP、OpenAI-compatible route、生成配置、skill | | 策略和证据 | permission profile、deny rule、approval、run recording、replay、probe、compare、browser session lease、render-aware evidence、movement check、stale-ref 细节 | | 交付和修复 | unicli delivery assess、run、trajectory、repair-candidate，覆盖 evidence gate、diagnosis、hypothesis、已执行尝试、换路和有边界修复 |

为 Agent Runtime 设计

Uni-CLI 在边界上刻意保持朴素：进程、文件、JSON、Markdown 和标准协议。Agent 运行时、shell 脚本、CI，以及任何能启动 subprocess 或接 MCP server 的 host 都能用。

长期任务里，这些细节比 demo 更重要：

按意图发现命令，不要求 Agent 背站点名和参数名；
输出足够稳定，可以 pipe 给 jq、存为证据，或者继续喂给下一步工具；
auth failure、empty result、timeout、blocked action 是不同 exit state；
repair instruction 指向我们拥有的文件，而不是让 Agent 猜 upstream 哪儿变了；
生成文档、llms.txt、AGENTS.md、MCP profile 和 skills 描述的是同一份操作合同。

能力地图

| 层级 | 例子 | | --------------------- | ---------------------------------------------------------------------------------------- | | 意图和发现 | search、do、生成操作目录、docs index、compact catalog、AGENTS surface | | Operation contract | args、output、auth posture、effect、safety、capability、source path、repair path | | 行动 substrate | HTTP、RSS、CDP、AX/UIA/AT-SPI、subprocess、visual、protocol、App-specific adapter | | 本地 computer control | compute apps、snapshot、find、click、type、press、scroll、doctor compute | | 策略和证据 | permission profile、deny rule、approval、run recording、replay、probe、compare | | 交付和修复 | objective spec、trajectory、repair candidate、reroute、evidence gate | | Runtime 暴露 | native CLI、MCP stdio、MCP Streamable HTTP、ACP、package export、agent skills |

给 Agent 的入口

先搜索，再执行最小可用命令。

unicli search "推特热门" --limit 5
unicli twitter search "coding agents" -f json
unicli anilist characters "Sparkle" --limit 5 -f json
unicli danbooru tags sparkle --limit 5 -f json
unicli arxiv download 1706.03762 --output ./papers -f json
unicli pdf read ./papers/1706.03762.pdf --first_page 1 --last_page 3 -f json
unicli macos app-actions --app WhatsApp -f json
unicli macos automation-smoke -f json
unicli repair twitter search

非 TTY 和 Agent 环境默认输出结构化 Markdown。需要机器格式时显式指定：

UNICLI_OUTPUT=json unicli reddit hot --limit 10
unicli hackernews top --limit 5 -f yaml
unicli --record --permission-profile confirm twitter search "coding agents" -f json
unicli runs list -f json
unicli runs show <run_id> -f json
unicli runs probe <run_id> -f json
unicli runs replay <run_id> --permission-profile confirm --yes --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
unicli runs compare <run_id> <replay_run_id> -f json
unicli runs compare <run_id> <replay_run_id> --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
unicli --permission-profile locked --yes --remember-approval word set-font "Inter"
unicli approvals list -f json
unicli approvals revoke <approval_key> -f json
unicli browser evidence --render-aware --expect-domain example.com -f json

协议入口：

npx @zenalexa/unicli mcp serve
npx @zenalexa/unicli mcp serve --transport streamable --port 19826
unicli acp
unicli agents recommend codex
unicli agents matrix

ACP 作为编辑器和桥接兼容层保留。真正跑任务时，优先 native CLI、JSON stream 或 MCP。

覆盖范围

每条命令都能搜索、可声明、可验证、可修。近期覆盖已经扩展到论文下载和本地 PDF 读取、ACG/动画/漫画/wiki 发现、booru tag 搜索、美少女游戏目录，以及日文和罗马音实体检索。

下面的网格由 active manifest 中带真实 logo 的站点生成，徽章命令数不包含 quarantined 命令。完整目录始终以 unicli list 和文档站为准。

看实时目录：

unicli list
unicli list --site macos
unicli ext list
unicli ext list --tag agent

同一份生成目录也发布在文档站： https://olo-dot-io.github.io/Uni-CLI/reference/sites

输出契约

普通命令都返回 v2 envelope。mcp serve 和 acp 是协议服务器，保留各自原始 stdio 协议。

ok: true
schema_version: "2"
command: "twitter.search"
meta:
  duration_ms: 412
  count: 20
  surface: web
data:
  - { id: "...", text: "...", author: "..." }
error: null

错误也要可执行：

ok: false
schema_version: "2"
command: "twitter.search"
meta:
  duration_ms: 91
data: null
error:
  code: auth_required
  message: "401 Unauthorized"
  adapter_path: "src/adapters/twitter/search.yaml"
  step: 1
  suggestion: "Run: unicli auth setup twitter"
  retryable: false
  alternatives: ["twitter.timeline", "twitter.profile"]

退出码：0 成功，66 空结果，69 服务不可用，75 临时失败，77 需要认证，78 配置错误。

自修复

adapter 默认是很小的 YAML。命令失败时，Agent 不需要猜，可以直接按错误定位到文件和步骤。

1. 执行命令。
2. 读取错误 envelope。
3. 打开 error.adapter_path。
4. 修改失败 step。
5. 保存到 ~/.unicli/adapters/<site>/<command>.yaml。
6. 用 unicli repair <site> <command> 验证。

本地修复会在 npm 更新后继续保留。

写一个 adapter

site: example
name: search
description: "Search example.com"
transport: http
strategy: public
capabilities: [fetch, select, map, limit]
minimum_capability: http.fetch
trust: public
confidentiality: public
quarantine: false
pipeline:
  - fetch:
      url: "https://api.example.com/search?q=${{ args.query }}"
  - select: data.results
  - map:
      title: "${{ item.title }}"
      url: "${{ item.url }}"
  - limit: "${{ args.limit }}"
args:
  - { name: query, type: string, required: true, positional: true }
  - { name: limit, type: int, default: 20 }
columns: [title, url]

文档入口：

边界和诚实说明

需要登录的网站使用本地 cookie 文件：~/.unicli/cookies/<site>.json。
Browser adapter 需要可连接的 Chrome/CDP。
Permission profile 是用户选择的运行时策略。默认是 open；更严格的 confirm 和 locked profile 会要求 --yes 或 UNICLI_APPROVE=1。 --yes 加 --remember-approval 会把同一条命令的 capability 和资源 scope 记到 ~/.unicli/approvals.jsonl。资源 scope 来自稳定 metadata，比如域名、账号面、应用、进程族和路径参数槽。用 unicli approvals list、revoke、 clear 查看或移除已记住的 scope。文件只存 scope metadata，原始运行参数留在审批记忆之外。
本地 deny 规则放在 ~/.unicli/permission-rules.json，也可以用 UNICLI_PERMISSION_RULES_PATH 指定。规则按站点、命令、effect、capability 维度和资源 metadata 匹配，优先级高于 --yes 和已记住的审批。运行时还会检查 fetch 域名、浏览器跳转目标、下载和输出路径、子进程可执行文件，命中后在请求、写入或启动进程之前停下。
Run recording 是显式启用能力。需要可审查证据时使用 --record 或 UNICLI_RECORD_RUN=1，追加写入 ~/.unicli/runs。
Visual 路由必须配置真实 backend。声明了但不可用的 provider 会失败关闭，并返回结构化错误。
用户 adapter 和修复放在 ~/.unicli/adapters/；包内 adapter 是基线。
如果网站阻止自动化或私有 API 变了，Uni-CLI 会返回清楚的失败 envelope。

开发

npm install
npm run typecheck
npm run lint
npm run verify

License

Apache-2.0