awlevin/typesafe-computer-use
一、一句话定位
一个用 TypeSafe 小模型做低成本 Mac 电脑操作代理的项目：输入自然语言目标，它自动截屏、OCR、用分类器决策下一步，每步约 0.02 美分，且不把截图发给大模型。
二、核心技术/架构亮点
- 确定性感知 + 小模型决策：本地截图 OCR、辅助功能 API、AppleScript 提取屏幕状态，只把结构化文本发给 TypeSafe 做 Choice 分类，避免大模型“看图规划”的高成本。
- 三问题拆分：每个步骤同时问三个问题——动作类型（kind）、点击哪个 OCR 块（item）、打开哪个站点（site）。动作集互斥，减少语义重叠带来的置信度下降。
- 写作模型按需调用：只在 `type_text` 和 `open_site` 时调用，返回结构化 JSON 并做 URL/字段校验；密码字段拒绝输入，依赖系统密码管理器。
- 可回放调试：每次运行生成 `runs/<timestamp>/`，保存原始截图、标注图、TypeSafe payload、概率答案；可用 `--image` 离线重放某一步，方便复现和修复卡死。
- 平台适配隔离：`macos.py` 是唯一接触 Quartz/AX/AppleScript 的模块，Linux 可替换为 xdotool + AT-SPI + PaddleOCR。
三、适用场景与目标用户
适合需要自动操作 Mac GUI 的开发者、RPA/Agent 研究者、追求低成本和可观测性的 AI 自动化团队。不适合图标为主、无文字或强视觉推理的界面（OCR 只能看到文本）。
四、可动手动作
1. Clone 并安装：`git clone ... && cd typesafe-computer-use && uv sync`，复制 `.env.example` 填入 `TYPESAFE_API_KEY`。
2. 授予终端“屏幕录制”和“辅助功能”权限，否则截屏无效、点击被系统丢弃。
3. 先 dry run 验证：`uv run clicker "open the Playground"`，再用 `--act` 真实执行。
4. 用 `uv run clicker-inspect "任何目标"` 查看 OCR 块、focus 字段、payload，理解决策输入。
5. 借鉴思路：本地 OCR + 系统辅助功能 + 小模型互斥动作集；用确定性日期解析补充模型短板；保存每步 payload 用于离线回归。
五、学习优先级
- P0（本周动手）：跑通 demo，精读 `runner.py`、`decide.py`、`actions.py`，掌握“感知-决策-执行”循环。
- P1（排期）：把动作集换成自己的场景，或用本地分类模型/OpenAI 兼容接口替换 TypeSafe，借鉴其回放机制。
- P2（观念了解）：TypeSafe 决策模型、Noul 校验、成本/延迟对比方法——理解“大多数步骤只需低成本选择”的架构哲学。
- P3（略读）：`dates.py` 日期解析和 OCR 行合并细节，遇到相关卡点时再深入。⌂