企业官网建设流程全解析

typesafe-computer-use（项目内简称 jev）是一个超低成本的 computer use 项目：用 OCR 读屏、用 TypeSafe 分类器决定下一步动作、然后点击，单步成本约 $0.0002。如果你想参与贡献，本文是一份完整指南，重点讲两件事：如何为 typesafe-computer-use 写场景化测试（scenario tests），以及如何提交一个能通过 CI 的 PR。

1. 动手前：环境准备与项目结构

快速搭建开发环境 🛠️

项目要求 Python 3.12+，依赖管理使用 uv 中的 dev 组：pytest与ruff）：

git clone https://gitcode.com/gh_mirrors/ty/typesafe-computer-use cd typesafe-computer-use uv sync # 安装依赖（含 pytest、ruff） uv run pytest -q # 全量测试是纯逻辑测试，任何 OS 都能跑

一分钟看懂目录结构

每个模块的职责在 docs/layout.md 中有完整说明，核心部分如下：

2. 场景化测试的核心思想：用假电脑驱动真循环

typesafe-computer-use 的主循环由四个接缝（seam）组成：截屏、感知条目、询问分类器、在机器上执行动作。普通的单元测试只覆盖单个接缝，而场景化测试通过 tests/world.py 里的模拟电脑把整条循环跑起来：

1. 页面图（page graph）：用Page描述每一屏有什么条目、点击后跳到哪一页；
2. 策略（policy）：一个函数顶替分类器，每步返回一个动作（如("click_item", "Tickets")或("done", None)）；
3. 三重断言：断言运行结局（state.outcome）、世界最终停在的页面（world.page.name）、世界实际收到的动作日志（world.log）。

关键点在于：场景测试运行的是真实的runner.run循环（tests/test_scenarios.py 的文件头注释写明了这一点）。所以如果某个场景失败，说明的是架构做不了这个任务，而不是测试框架的问题——这正是这个项目所有停止规则被发现和被修复的方式。

💡 上图是tests/fixtures/中的真实屏幕 fixture：像 OSWorld 感知类测试会使用这类屏幕截图来验证感知逻辑。而场景化测试连截图都不需要——屏幕就是几行Page定义。另外注意 tests/conftest.py 里有一个autouse守卫：任何试图移动鼠标、按键、截屏的调用在测试中都会直接报错，测试永远碰不到你的真机，请勿削弱这个守卫（见 AGENTS.md）。

3. 三步写出你的第一个场景 ✍️

下面是一个最小场景的完整形态（对应 tests/test_scenarios.py 的 L2 级别）：

第 1 步：画出页面图。on字典声明"动作 → 下一页"的映射，没有声明的动作就是"什么都没发生"：

world = World( [ Page(name="home", items=["Home", "Tickets", "About"], url="https://example.com/", on={"click:Tickets": "tickets"}), Page(name="tickets", items=["Buy", "Terms"], url="https://example.com/tickets"), ] )

第 2 步：写策略。用现成的scripted工具按脚本喂动作，或写一个函数根据屏幕状态决策：

policy = scripted(("click_item", "Tickets"), ("done", None)) state = drive(world, policy, goal=GOAL, monkeypatch=monkeypatch, tmp_path=tmp_path)

第 3 步：断言结局、终点页、动作日志。

assert state.outcome == "done" assert world.page.name == "tickets" assert world.log == ["click:Tickets"]

场景文件从 L1 到 L34+ 难度递增（目标已达成 → 单击到达 → 慢页面等待 → 死胡同回退 → 卡顿检测 → 重复动作规则……），新场景请继续这个编号约定，并参考同级场景的写法。需要慢加载页面就用loads_in=N，需要重复标签消歧就用行内列表（如["Coldplay", "Oct 2", "Buy"]）。

4. 循环做不到的任务怎么办：xfail，而不是绕开

这是 CONTRIBUTING.md 中最重要的一条约定：

• 写一个场景，让它保持失败，打上xfail并写清原因；
• 等主循环（而不是场景本身）被修复后，xfail转为通过，再移除标记；
• 修循环，而不是改场景——"每一个停止规则都是这样被发现或修复的"。

5. 提交前必读：Ground Rules 清单

CONTRIBUTING.md 的几条铁律，改代码前先对照一遍：

6. 提交一个 PR 的完整流程 🚀

第 1 步：本地门禁，两条命令必须全绿。

uv run ruff check . && uv run ruff format . uv run pytest -q

第 2 步：了解 CI 会做什么。CI 在 macOS 上跑同样的 ruff + pytest，在 Linux 上再跑一次测试——测试是纯逻辑的，tests/conftest.py 会在装不了的平台模块处注入替身。另有第三个任务检查 infra/gcp 的格式、校验与terraform test（mock provider，无需云凭据）。

第 3 步：PR 描述附上 replay 说明。如果你的改动改变了模型看到的东西（payload 结构、状态字段、动作集等），PR 中必须写清：哪个 run folder、哪一步、改动前后的决策分别是什么。每次运行都会写 runs/* 保存完整 payload 与每个概率值，可离线回放：

uv run clicker "same goal" --image runs/<ts>/step-003-raw.png --app "Google Chrome"

第 4 步：报 Bug 时带上 run folder。项目维护者原话：附带 run folder 的 bug 报告是有用的东西。runs/<timestamp>/里有截图、精确 payload 和所有概率值，卡顿可以离线重放定位。

7. 小结

给 typesafe-computer-use 做贡献的路径其实很短：

1. uv sync后本地ruff+pytest全绿；
2. 新功能/新能力 → 在 tests/test_scenarios.py 按 L 级编号补场景，做不到的先xfail挂着；
3. 改到"模型看到的东西" → PR 里附 run folder 回放说明；
4. 对照 CONTRIBUTING.md 的 ground rules 自查，提交 PR。

更多背景可延伸阅读：docs/how-a-step-works.md（一步的完整流程）、docs/layout.md（每个模块的职责）、docs/run-folder.md（运行产物与离线回放）。