Appearance
Computer Use Harness 工程与产品策略
方向定位：聚焦 Computer Use（CU）/ Browser Use Agent 的 Harness 工程特有问题——分辨率与坐标系管理、模型选型矩阵、Thinking effort 调优、Teach Mode 示教回放、Batch 工具、上下文管理三层架构、安全防御、调试工具链。CU Agent 的 Harness 与通用 Coding Agent Harness 的核心差异在于：输入是截图流（图片模态）、输出是坐标+动作（物理操作）、上下文膨胀速度远超文本对话。 当前版本：v0.1 首次构建：2026-05-20 最近更新：2026-05-20 来源数：1 篇（Anthropic "Best practices for computer and browser use with Claude" 2026-05-13）
方向定位
本方向研究的核心问题是："Computer Use Agent 的 Harness 层有哪些特有的工程挑战和产品设计决策？"
与本目录其他文件的边界：
- 不重复 Harness 通用概念（→ Harness概念架构与Coding工程实践）
- 不重复通用失效模式理论（→ Harness失效模式与演化方向）
- 不重复 Token 降本通用策略（→ Token计费与降本工程）
- 聚焦 CU/Browser Use 场景特有的 Harness 工程问题
CU Harness 与通用 Agent Harness 的三大差异：
| 维度 | 通用 Agent Harness | CU Agent Harness |
|---|---|---|
| 输入模态 | 文本为主（代码、文档、API 返回） | 截图流为主（每步一张图 ≈ 1,000-1,800 token） |
| 输出形态 | 文本/代码/API 调用 | 坐标 + 物理动作（click/type/scroll） |
| 上下文膨胀速度 | 线性累积，可控 | 指数级——100 步即可填满 200K window |
核心概念
1. 分辨率与坐标系管理
CU Agent 的"点击准确性"是一切下游工作流的基础——点不准，表单填不了、按钮按不到、流程走不通。
API 内部分辨率限制：
| 模型家族 | 最大长边 | 最大总像素 | 超限处理 |
|---|---|---|---|
| Claude 4.6 family | 1568 px | 1.15 MP | 静默降采样 |
| Opus 4.7 | 2576 px | 3.75 MP | 静默降采样 |
静默降采样是 CU 点击不准的首要原因：当截图超过 API 限制时，API 内部会降采样后再给模型看，但返回的坐标仍在 display_width_px / display_height_px 指定的坐标空间中——模型基于降质图片做判断，坐标却对应原始分辨率，导致系统性偏移。
推荐分辨率：
- 4.6 family 默认起步：1280×720（用 80% 像素预算，训练时常见分辨率）
- Opus 4.7 默认起步：1080p（在 3.75MP 预算内，质量显著优于 720p）
- 进阶：
compute_max_api_fit()按源图宽高比计算最大 API 适配分辨率
坐标缩放公式（截图缩放后必须反向映射）：
screen_x = api_returned_x × (screen_w / display_w)
screen_y = api_returned_y × (screen_h / display_h)macOS 陷阱：macOS 截图默认 device pixel ratio = 2，实际截图分辨率是屏幕坐标的 2 倍——不处理会导致所有点击偏移一半。
2. 内容排序规则
消息数组中 text 在前、image 在后 可提升点击准确率——让模型在处理截图前就知道要找什么。
3. 模型选型矩阵（CU 场景）
| 模型 | 优势 | 推荐场景 |
|---|---|---|
| Sonnet 4.6 | 机械点击精度最高、对重度降采样最鲁棒、成本最低 | 默认起步、简单工作流、高吞吐 |
| Opus 4.7 | 推理更强、分辨率预算更大（3.75MP）、low effort 即强 | 高难度/高分辨率/复杂决策 |
| Haiku 4.5 | 延迟最低 | 延迟优先场景 |
进阶模式：Orchestrator + Sub-agent——推理模型做规划和决策，Sonnet/Haiku 做机械点击执行。这与 Advisor Tool 的服务端实现是同源思想。
4. Thinking Effort 调优
CU 任务主要是感知和机械操作而非深度逻辑推理，thinking effort 对成本/质量的影响曲线与常规任务不同。
Opus 4.7 推荐：默认 high（接近 max 成功率，token 仅为 max 的约一半） 4.6 family 推荐：默认 medium（与 high 在重试后收敛到相同成功率，token 仅为一半）
关键数据：Opus 4.7 low effort 在 OSWorld 基准上得分 ≈ Sonnet 4.6 max effort，但 token 消耗仅为后者的 ~1/10。
5. Teach Mode（示教回放）
核心思想：用工作流录制代替文字指令——人类做一遍 → 系统录制每步截图+动作+选择器+坐标+视口尺寸 → Agent 回放。
WorkflowStep 数据模型：action / selector / coordinates / screenshot / viewport_dimensions / description
三种回放模式：Strict（严格复现）/ Adaptive（允许路径偏差）/ Goal-oriented（仅参考目标，自主规划）
6. Batch 工具
computer_batch / browser_batch 允许在单次 API 往返中执行多个动作——减少网络延迟，适合确定性操作序列（如表单填写）。
7. 上下文管理三层架构
| 层 | 策略 | 触发条件 |
|---|---|---|
| L1 | Cache breakpoints + 预降采样 | 每轮 |
| L2 | Rolling buffer（keep_n=3, interval=25） | 截图累积 |
| L3 | LLM-based Compaction（8 段结构化 prompt） | input token ≈ 150K |
服务端 Compaction beta：compact-2026-01-12——服务端自动执行摘要，客户端无需自行实现。
8. Zoom 能力
enable_zoom: True 让模型在点击前先放大特定区域检查——解决小目标（checkbox、toggle、系统托盘图标）点击不准的问题。
方法论与框架
框架一：CU 点击不准诊断表
| 症状 | 可能原因 | 解法 |
|---|---|---|
| 点击系统性偏移 | display 尺寸与实际发送图片不匹配 / 超限被静默降采样 / 内容排序错误 | 确保 display 尺寸精确匹配缩放后截图 / 预降采样 / text 在 image 前 |
| 点击大致正确但偏差 | 目标太小 / 4K+ 源图降采样丢细节 / 宽高比失真 | 启用 zoom / 降低源 DPI / 保持原始宽高比 |
| 点错元素 | 指令歧义 / 相似元素干扰 / UI 过于复杂 | 更具体的 prompt（含位置描述）/ 拆分步骤 / 提供页面布局上下文 |
| 全面不准 | 截图超 API 限制 / 4K+ 极端压缩 / 分辨率过低 | 预降采样至限制内 / 用 1280×720 作基线 / 4.6 family 用 Sonnet（对降采样更鲁棒） |
框架二：CU 产品安全部署 4 条底线
- Human-in-the-loop 常驻（不可逆操作永远不允许自动批准）
- 权限范围最小化（限制可访问应用/网站/目录）
- 操作日志全程记录（截图+动作+时间戳，不可篡改）
- 网页内容视为不可信（所有浏览器获取内容统一视为外部不可信输入）
框架三：CU 成本优化决策树
任务是否需要深度推理？
├─ 否 → Sonnet 4.6 + medium effort（成本最低）
├─ 是 → Opus 4.7 + high effort（推理+精度平衡）
└─ 不确定 → Sonnet 执行 + Opus advisor（Advisor Tool 模式）
任务是否支持重试？
├─ 是 → 4.6 family medium effort（重试后收敛到 high 同等成功率）
└─ 否 → 4.6 family high / Opus 4.7 high（必须首次成功）关键洞察
预降采样是 CU 最高 ROI 的单一优化：所有其他优化（prompt 改进、zoom、batch）的前提是点击准确——而点击准确的首要保障是截图不被 API 静默降采样。一行代码的改动（预缩放到 1280×720）比任何 prompt 优化都有效。
CU 的上下文膨胀速度使其成为 Harness 工程的"极端工况"：每步一张截图 ≈ 1,000-1,800 token，100 步填满 200K window。通用 Agent 的上下文管理策略（如"超过 60% 触发压缩"）在 CU 场景下需要更激进的参数——CU 是 Harness 上下文管理能力的压力测试。
Teach Mode 是"上下文工程"的极致形态：用截图序列+结构化标注取代自然语言指令，消除指令歧义。这证明"给 Agent 看什么"比"给 Agent 说什么"更重要——与 Harness 概念体系中"Context Engineering > Prompt Engineering"的范式跃迁一致。
CU 安全风险从"数据层"升级到"操作层"：传统 Agent 安全关注数据泄漏/越权访问，CU Agent 的风险是物理操作不可逆（删文件、发邮件、提交表单）。安全防线必须从"拦截 API 调用"升级到"拦截屏幕操作"。
Advisor Tool 是 CU 场景的最优成本效益模型组合：Sonnet 4.6 负责机械点击（精度高、成本低），Opus 4.7 负责决策判断（推理强、按需介入）——单次 API 请求内完成，零额外网络往返。
待探索问题
- CU Agent 在移动端（iOS/Android）的适配——屏幕尺寸、触摸 vs 点击、手势操作的坐标映射差异？
- Teach Mode 的示教录制在 UI 频繁变更的产品中如何保持有效性？Adaptive 模式的"自适应"边界在哪？
- CU Agent 的操作日志如何与企业 SIEM/SOAR 系统集成？是否需要专门的"CU 操作审计"产品品类？
- 多 CU Agent 并行操作同一桌面/浏览器时的冲突解决机制？
- 服务端 Compaction beta GA 后，是否会出现"CU 专用上下文管理 API"？
来源索引
| # | 标题 | 来源 | 收录日期 | 贡献章节 |
|---|---|---|---|---|
| 1 | Best practices for computer and browser use with Claude | Anthropic 官方博客 | 2026-05-13 | 全文 |
关联方向
- Harness概念架构与Coding工程实践：CU Harness 是通用 Harness 六层架构在"截图流+物理操作"场景的特化
- Harness失效模式与演化方向：CU 的 Context Anxiety 是该方向 §1.2.1 的极端工况实证；CU Compaction 是 §2.4 的场景特化
- Token计费与降本工程：CU 截图 token 消耗数据在 §1.2；CU 三层降本策略在 §5.1；Thinking effort 在 §5.9
- Agent安全工程：CU 安全部署 4 条最佳实践在框架十；CU Prompt Injection 三层防御在案例 G
- Agent架构与协作模式：Advisor Tool 作为 Orchestrator-Worker 服务端变体在概念 4
- Agent设计哲学与决策框架：Teach Mode 设计哲学在 §1.13；Advisor Tool API 细节在 §2.11
演进记录
| 日期 | 版本 | 变更摘要 |
|---|---|---|
| 2026-05-20 | v0.1 | 首次构建，由 /route-knowledge-pm 路由触发。来源：Anthropic "Best practices for computer and browser use with Claude"（2026-05-13）。覆盖分辨率/坐标系管理、模型选型矩阵、Thinking effort 调优、Teach Mode 示教回放、Batch 工具、上下文管理三层架构、安全防御、点击诊断表、成本优化决策树。定位为 CU/Browser Use 场景特有的 Harness 工程问题集中沉淀。 |