数据截至 2025-09-19(上游 commit fac568eea7da)

Self-Operating Computer Framework — 架构与原理

30 秒导读: Self-Operating Computer(简称 SOC)是 2023 年 11 月最早的"全电脑操作"demo 之一。它让一个多模态大模型像人一样用电脑:截一张全屏截图发给模型,模型看图 + 目标,回一串动作(点这里、写这段字、按这个键、完成了),框架再用 pyautogui 真的去移动鼠标、敲键盘。整个核心不到 300 行,是理解 computer-use agent 最干净的起点。

1. 这是什么(零基础也能懂)

一句话定义: SOC 是一个computer-use agent(电脑操作智能体)框架——你给它一句话目标("帮我在谷歌上搜一下今天的天气"),它就自主地截屏、思考、然后真的去点鼠标敲键盘,把这件事做完。

它的历史地位: README 明说它是 2023 年 11 月发布、最早的全 computer-use 例子之一。它不追求 SOTA 准确率,而是把"多模态模型操作电脑"这件事拆到最简、最好读。

解决什么问题 / 给谁用

设想你想让 AI 帮你干这种活:

打开浏览器,搜一个东西
在某个网页表单里填几个字
在 Google Docs 里新建一个文档

这些活的共同点:没有 API,只能靠"看屏幕 + 动鼠标键盘"。SOC 就是把这类"只能用眼睛和手完成"的任务交给模型来做。给谁用:想研究 / 上手 computer-use 的开发者与研究者。

它能做什么

支持一堆多模态模型:GPT-4o、GPT-4.1、o1、Gemini Pro Vision、Claude 3、Qwen-VL、LLaVA(通过 -m 切换)。
三种"把描述落到坐标"的定位法:OCR、Set-of-Mark(YOLO 框标注)、直接百分比。
语音输入目标(--voice,基于 whisper)。
跨平台:Mac / Windows / Linux。

用起来什么样

最小使用就是命令行一句:

pip install self-operating-computer
operate

启动后它先问你"要做什么",你打一句目标,它就开始一轮轮截屏 + 操作。也可以直接把目标塞进命令行:

operate -m claude-3 --prompt "打开 Google 搜索今天的天气"

入口在 operate/main.py:9(main_entry),它把 -m/--model、--prompt、--voice、--verbose 解析后转交给真正的主循环 operate/operate.py:33(main)。

一句话直觉 / 类比

把它想成一个"盲操作代打": 你雇了个只能通过"每隔一秒给你看一张屏幕照片"来了解情况的助手。它每看一张照片,就告诉你"帮我点左上角那个蓝按钮",而你(框架)负责把这句话翻成"鼠标移到 (312, 88) 并单击"。模型是眼睛和大脑,框架是手,而两者之间的翻译层——把"那个蓝按钮"变成 (312, 88)——才是全篇最难的工程。

本节不碰底层。记住一件事:SOC = 一个不断"截屏→问模型→执行动作"的循环。

2. 顶层全景(它大概怎么转)

一张顶层图

这张图从上到下就是一次循环。看图要点:左边是"一步的生命周期",箭头回到顶部表示循环;右边灰字是负责的文件。

   用户目标 objective("搜今天天气")
            │
            ▼
  ┌───────────────────────────┐
  │  攒消息 messages           │   operate.py:99-101
  │  [系统prompt] + 历次动作    │
  └───────────────────────────┘
            │
            ▼  ┌─────────── 每一轮循环从这里开始 (operate.py:107 while True) ───────────┐
            │  │
            ▼  │
  ┌───────────────────────────┐
  │ ① 截全屏(带鼠标)          │   screenshot.py:capture_screen_with_cursor
  └───────────────────────────┘
            │
            ▼
  ┌───────────────────────────┐
  │ ② 发给模型,要 JSON 动作    │   apis.py:get_next_action → call_*
  │    图片 + "下一步该干嘛?"   │
  └───────────────────────────┘
            │
            ▼
  ┌───────────────────────────┐
  │ ③ 定位:把"点登录"→(x,y)   │   ocr.py / label.py(仅 click 需要)
  └───────────────────────────┘
            │
            ▼
  ┌───────────────────────────┐
  │ ④ 执行:pyautogui 真操作    │   operating_system.py:OperatingSystem
  │    click / write / press    │   operate.py:134 operate()
  └───────────────────────────┘
            │
            ▼
      done? ──否──┐
        │是       └──────────► 回到 ①(loop_count+1,>10 强制停)
        ▼
      结束,打印总结

部件一句话职责

部件	干什么	在哪个文件
入口 `main_entry`	解析命令行参数,转交主循环	`operate/main.py:9`
主循环 `main`	攒目标、跑 while 循环、控制停机	`operate/operate.py:33`
执行器 `operate`	把一串动作逐个用 pyautogui 落地	`operate/operate.py:134`
模型分发 `get_next_action`	按 `-m` 选的模型分发到具体调用	`operate/models/apis.py:34`
系统 prompt	把"操作电脑"约束成 4 个 JSON 动作	`operate/models/prompts.py`
定位(OCR)	把"点某文字"→屏幕百分比坐标	`operate/utils/ocr.py`
定位(SoM)	YOLO 检测按钮 + 画框标号 → 坐标	`operate/utils/label.py`
OS 执行层	真正 click/write/press	`operate/utils/operating_system.py`
截屏	跨平台抓全屏(带光标)	`operate/utils/screenshot.py`
配置	单例,管各家 API key 和客户端	`operate/config.py`

主线走一遍(高层,不进代码)

拿目标。 用户打一句 objective,框架把它塞进系统 prompt,组成 messages = [系统消息](operate.py:99-101)。
进循环。 每一轮:截全屏 → 连同"请给下一步动作"的提示发给模型 → 模型回一段 JSON 动作数组。
必要时定位。 如果动作是 click,模型给的往往是"点某个文字/某个标号",框架用 OCR / YOLO 把它翻成屏幕坐标。
执行。 operate() 逐个动作调 pyautogui:移动鼠标画个小圈再点、逐字敲键、按热键。
停机。 模型回 done 就结束;否则回到第 2 步。硬上限:超过 10 轮强制停(operate.py:120),防止无限烧钱。

3. 核心机制概览(各章展开)

这份文档拆成三章,由浅入深:

章	讲什么	一句话精华
`01-control-loop.md`	主循环的完整生命周期	极简 while 循环 + 消息历史累加 + 10 轮熔断;动作用 `pyautogui` 落地,click 还会画个催眠小圆圈
`02-models-and-prompts.md`	多模型分发 + prompt 设计 + 回退	一个 `get_next_action` if-else 分发十来个模型;prompt 把动作压成 4 种 JSON;任何模型挂了都逐级 fallback 到 gpt-4o
`03-grounding.md`	三种视觉定位法	模型只会说"点登录",OCR / YOLO 标号 / 直接百分比三条路把它变成 (x,y)

4. 边界与局限(先给个诚实的总印象)

它是 demo,不是产品。 README 自己说 LLaVA 模式"错误率非常高";整体准确率不是卖点。
无规划、无记忆、无反思模块。 对比兄弟项目(见各章横向对比),SOC 没有分层规划、没有反思 agent,就是最朴素的"看一步走一步"。
10 轮硬熔断。 复杂任务经常还没做完就被 loop_count > 10 掐掉(operate.py:120)。
坐标定位脆弱。 OCR 找不到文字、YOLO 漏检按钮,都会让 click 落空;详见 03-grounding.md。

更完整的边界讨论散在各章末尾。

5. 代码地图(导航索引)

主题	文件	关键符号
命令行入口	`operate/main.py`	`main_entry`
主循环 / 停机	`operate/operate.py`	`main`、`operate`
模型分发	`operate/models/apis.py`	`get_next_action`
各模型调用	`operate/models/apis.py`	`call_gpt_4o`、`call_claude_3_with_ocr`、`call_gpt_4o_labeled`
回退 / 清洗	`operate/models/apis.py`	`gpt_4_fallback`、`clean_json`、`confirm_system_prompt`
系统 prompt	`operate/models/prompts.py`	`SYSTEM_PROMPT_OCR`、`SYSTEM_PROMPT_LABELED`、`SYSTEM_PROMPT_STANDARD`、`get_system_prompt`
OCR 定位	`operate/utils/ocr.py`	`get_text_element`、`get_text_coordinates`
SoM / YOLO 定位	`operate/utils/label.py`	`add_labels`、`get_label_coordinates`、`get_click_position_in_percent`
OS 执行	`operate/utils/operating_system.py`	`OperatingSystem`、`click_at_percentage`
截屏	`operate/utils/screenshot.py`	`capture_screen_with_cursor`、`compress_screenshot`
配置单例	`operate/config.py`	`Config`、`initialize_openai`、`validation`

6. 横向对比(同 shelf 的 computer-use 兄弟)

SOC 是这一类里最早、最简的那个。同 shelf 里更"现代"的 computer-use agent 各自补了 SOC 缺的东西:

项目	相对 SOC 多了什么
`agent-s`(`docs/agent-s/index.md`)	两段式(大脑模型 + 独立视觉定位模型)、反思 agent、Behavior Best-of-N 投票
`cua`(`docs/cua/index.md`)	可插拔 agent loop 注册表、组合式定位、回调钩子、沙箱 runtime
`ui-tars-desktop`(`docs/ui-tars-desktop/index.md`)	端到端原生 GUI 模型 UI-TARS,定位内建进模型而非靠 OCR
`openmanus`(`docs/openmanus/index.md`)	ReAct 工具调用、规划 flow、MCP 工具接入

共同暗线: 它们都要解决 SOC 的核心难题——把模型说的"点那个按钮"落到真实屏幕坐标——只是手段更高级(专用定位模型 vs SOC 的 OCR/YOLO)。要理解这条主线最省力的入口,就是先读懂 SOC,再看别人怎么加码。

1. 这是什么(零基础也能懂)​

解决什么问题 / 给谁用​

它能做什么​

用起来什么样​

一句话直觉 / 类比​

2. 顶层全景(它大概怎么转)​

一张顶层图​

部件一句话职责​

主线走一遍(高层,不进代码)​

3. 核心机制概览(各章展开)​

4. 边界与局限(先给个诚实的总印象)​

5. 代码地图(导航索引)​

6. 横向对比(同 shelf 的 computer-use 兄弟)​