universal-computer

UniversalComputer｜Windows 电脑自动化与 AI Agent Computer Use

跨宿主的电脑操作工具：Python + CLI + JSON，让 AI Agent 在 Windows 上操作浏览器、桌面控件和命令行。 支持 WorkBuddy、Codex、Qoder CN 等能够启动进程并读取 JSON 的调用方；不需要安装专属 Agent 服务。

English README · 快速安装 · 功能范围 · CLI 调用示例 · Agent Skill · 12 项验收记录 · 安全模型

与任何 Agent 宿主解耦的通用电脑操作核心：把「操作浏览器、Windows 桌面软件、 窗口控件、命令行」的能力收敛为一套宿主中立的 CLI + JSON 协议。 任何能「启动进程 + 解析 JSON」的 Agent（WorkBuddy / Codex / 自研脚本均可） 都可以调用它，无需绑定特定宿主。

• 许可证：MIT（自研代码，见 LICENSE）；第三方依赖出处见 THIRD_PARTY_NOTICES.md
• 平台：Windows 10/11，Python 3.11+（3.13 验证）
• 形态：纯 Python 代码库 + 可选的 Agent Skill 包（skill/），无服务、无后台驻留

自主开发声明： Universal Computer 的公开核心程序、统一任务路由、执行适配层、CLI、Skill 和相关项目文档由本项目开发者自主编写、整合并维护。系统使用公开的第三方软件 API 与开源依赖，不宣称对 Playwright、Windows UIA、Win32、COM 等基础技术及其上游项目拥有原创权。详见 《自主开发与第三方依赖声明》及 第三方项目出处。

能力范围

工程能力：能力探测（detect）、Domain-aware 路由、声明式多步任务（uc.py run）、 失败恢复（重获取→重定位，硬上限 2 次）、任务状态机与断点续跑判定、逐动作 JSONL 审计、三级风险声明（READ / WRITE / DESTRUCTIVE）。

一眼看懂执行链路

flowchart LR
    A["Agent / 自定义脚本"] --> B["uc.py CLI + JSON"]
    B --> C["能力探测与安全路由"]
    C --> D["Playwright 浏览器"]
    C --> E["Windows UIA / Win32"]
    C --> F["COM 接口"]
    C -. "预留接口，非完整实现" .-> G["Visual / MCP"]

实线为已提供的调用接口；虚线为尚未交付完整运行实现的可选接口。能力是否可用以本机 doctor 结果为准。

三分钟上手：先在隔离环境验证

以下命令适用于 Windows PowerShell，需要 Git、Python 3.11+ 和本机 Chrome；不需要接入任何私人网站或 Agent 账号。请勿在现有生产 Python 环境内直接安装依赖。

git clone https://github.com/asd454314633-byte/universal-computer.git
cd universal-computer
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock.txt
.\.venv\Scripts\python.exe uc.py doctor
.\.venv\Scripts\python.exe uc.py capabilities

• 看能力： doctor 和 capabilities 会报告可用的浏览器、Windows UIA/Win32 等 Provider；可选 Visual、MCP 等占位模块返回不可用是正常的。
• 试真实动作： 先阅读 安装/卸载说明 和 CLI 示例，再对你自行控制的浏览器页面或测试窗口操作。
• 看验证证据： 12/12 Phase 1 验收报告 使用了自有浏览器页面和 Windows 测试窗口；它不代表任意真实网站或软件都能无障碍自动化。
• 安全边界： 本项目仅报告 READ / WRITE / DESTRUCTIVE 风险等级；操作授权由调用方处理。参阅 风险模型 和 当前限制。

安装

完整环境要求、隔离安装、健康检查与卸载方式见 INSTALL.md。上方命令可直接复制，无需手动替换 <venv-dir> 占位符。

doctor 为环境探测：浏览器可用时应有 capabilities.playwright: true 和 browser_live_launch: true；Windows 控件操作检查 capabilities.uia: true。 部分可选/占位 Provider 默认不可用是正常情况，不要求全部 available: true。 详见 INSTALL.md。

调用

统一入口 uc.py，stdout 恒为单个 JSON 文档：

python uc.py doctor                          # 健康检查
python uc.py capabilities                    # 各 Provider 可用性
python uc.py run task.json                   # 声明式多步任务
python uc.py browser open --url https://example.com
python uc.py browser fill --selector "#q" --value "hello"
python uc.py windows list
python uc.py windows read_tree --window-name "记事本" --depth 4
python uc.py inspect window --name "记事本"  # 只读侦察

全局参数：--headed（前台浏览器）、--profile <dir>（持久登录态）、 --cdp <endpoint>（attach 已运行浏览器）、--webmcp（实验性探测，默认关）、 --visual（允许视觉兜底，默认关）。完整动作清单与返回契约见 skill/references/PROVIDERS.md。

声明式任务

{
  "task_id": "example-task",
  "domain": "browser",
  "steps": [
    {"step_id": "s1", "action": "open", "params": {"url": "https://example.com"}},
    {"step_id": "s2", "action": "read_text", "params": {"selector": "h1"}}
  ]
}

作为 Agent Skill 使用

skill/ 是宿主中立的 Agent Skill 包（SKILL.md + references + scripts）。 定位 Core 的顺序：环境变量 UNIVERSAL_COMPUTER_HOME → Skill 目录下 scripts/core_path.txt（由 adapters/sync_skill.py 同步时生成）→ 手动指定。 可用 python adapters/sync_skill.py --check 校验宿主副本一致性。

作为库使用

from factory import build_router, build_runner   # 唯一组合根
router, providers = build_router()
runner = build_runner(router)

路由策略（摘要）

先探测、后路由；不存在全局固定 Provider 顺序——先分类任务域，再在域内按 可靠性/成本选 1 个 primary + 至多 1 个正常 fallback（特殊至多 3 候选）：

browser: (webmcp, opt-in) → playwright → visual(仅 --visual)
windows: com(任务声明 use_com 时) → uia → win32 → visual(仅 --visual)

重试与切换是独立计数器（同 Provider 内重试 ≤ 2；整条任务最多换 2 次 Provider）， 禁止链式膨胀。完整策略见 skill/references/ROUTING_POLICY.md 及其机器可读投影 skill/references/provider_registry.json。

测试

python tests/run_acceptance.py    # 最小真实验收：浏览器/路由/恢复/Windows UIA（自有 fixture）
python tests/validate_routing.py  # 路由收敛离线断言（无网络、无副作用）

测试使用自有的本地 fixture 站点与自建 Win32 窗口，不触碰用户真实应用会话。 升级任何依赖前必须重跑验收并全部 PASS。

目录结构

uc.py                  # 启动器
factory.py             # 组合根：provider 装配 + router + runner
cli/                   # CLI 入口（所有子命令输出单个 JSON）
core/                  # router / runner / protocol / security / recovery / state / audit
providers/             # browser(playwright, webmcp) / windows(uia, win32, com) / visual / mcp
skill/                 # 宿主中立 Agent Skill 包（SKILL.md + references + scripts）
adapters/              # 宿主 Skill 同步器（sync_skill.py）
tests/                 # 验收测试 + 隔离 fixture
docs/                  # 架构 / Provider 契约 / 安全模型 / 验收报告等设计文档
requirements.lock.txt  # 依赖锁定

已知限制

1. 仅支持 Windows（UIA / Win32 / COM 依赖 Windows API）；浏览器部分跨平台可跑， 但整体面向 Windows 场景设计与验证。
2. Visual Provider 仅为接口 + Mock：未内置任何视觉模型，--visual 开启后 也只有契约与模拟实现，不会真正操作屏幕。接入真实模型需自行实现 VisualProvider 子类。
3. MCP Provider 仅为探测槽位：Phase 1 不含 MCP 传输实现。
4. WebMCP 为实验性探测：默认关闭，探测结果仅供参考，永不阻断任务。
5. COM Provider 为接口 + 注册表探测：具体应用的 COM 操作需按应用编写 adapter（Office 等），核心不内置逐应用 COM 语义。
6. 风险确认不在 Core 内：Core 只声明风险等级（DESTRUCTIVE 默认返回 PERMISSION_DENIED），是否确认由调用宿主决定。
7. 依赖版本已锁定：升级依赖前必须重跑 tests/run_acceptance.py 全部 PASS。
8. 运行时会生成 logs/（任务状态）与 evidence/（审计日志），已在 .gitignore 中排除；请按需自行清理。

许可证

• 自研代码：MIT（LICENSE）
• 第三方依赖：均通过 pip 安装，未修改、未内联；出处与许可见 THIRD_PARTY_NOTICES.md