# Visual Agent Phase 0 PoC

验证 "截屏 → 火山 VLM → 解析 → nut.js 点击/粘贴 → 发送" 端到端链路在微信 4.x 文件传输助手能不能跑通。

## 用什么模型

读取 `netaclaw_model_channel` id=2 的火山引擎配置(`doubao-seed-2-0-pro-260215`,2026-02 多模态)。

> 当前火山 channel **未配置 doubao-1.5-ui-tars-250428**。如果 Seed 2.0 Pro 成功率 ≥ 80%,直接进 Phase A;若 < 80%,先去火山控制台开 UI-TARS 模型,再用 `MODEL_NAME=doubao-1.5-ui-tars-250428` 环境变量重跑。

## 准备

1. **打开 PC 微信** 4.x 并登录
2. 在微信里**打开"文件传输助手"对话**(主窗口可见,不要最小化到托盘)
3. 让微信窗口在屏幕上**清晰可见**,最好最大化或大窗口
4. **关闭其他可能弹窗的程序**(防止抢前台)
5. 确保**仓库已 `pnpm install`** 过(backend 依赖已就绪,需要 `node-screenshots` / `@nut-tree-fork/nut-js` / `clipboardy` / `koffi` / `openai`)

## 安装 PoC 需要的额外依赖

PoC 用的几个原生模块当前不在 backend deps 里,先装上:

```bash
cd packages/backend
pnpm add node-screenshots @nut-tree-fork/nut-js clipboardy koffi
```

(这一步等于 plan v2 的 Task 1 — 提前做也无所谓,反正后续要装。)

## 跑 PoC

```bash
# 在仓库根目录
pnpm --filter @neta/backend exec tsx ../../tools/visual_agent_probe/run-once.ts 3
```

- 参数 `3` = 跑 3 次(快速验证用)
- 完整门禁验证应跑 `20`

启动后:
- 控制台打印环境信息和窗口句柄
- **倒计时 3 秒,期间不要碰键盘鼠标**
- 之后每次自动:Ctrl+1(聊天 tab)→ Ctrl+F(搜索)→ 输入"文件传输助手"→ 回车 → 截图 + VLM 验证已进群 → 粘贴 `[probe-i-ts]` → 回车 → 截图 + VLM 验证消息已发送
- 两次 VLM 调用 / 条
- 每条间 cooldown 3 秒

## 看什么

控制台最后会输出 Summary:

```
Summary
  total runs:        3
  successes:         3
  success rate:      100.0%
  ...
```

**门禁标准**:
- ✅ `success rate >= 80%` → 可进 Phase A,把脚本里录到的 VLM raw 输出转成 Task 3 的测试 fixtures
- ❌ `success rate < 80%` → STOP,讨论:
  - 换 `doubao-1.5-ui-tars-250428` 试一次(在火山控制台先开通)
  - 或换 Claude Sonnet 4.6 vision
  - 或调整 prompt
  - 或放弃视觉路线

## 原始报告

完整 raw results(含每次的动作 trace 和 VLM 原始输出)落盘到:
`docs/superpowers/followups/2026-05-14-visual-agent-poc-raw.json`

这份文件后续用来:
- 生成 Phase A Task 3 的 50+ fixture 测试用例
- 校验 spec §7.3 的成本估算表
- 失败模式分析

## 失败排查

| 失败状态 | 含义 | 怎么办 |
|---|---|---|
| `window-missing` | 没找到微信进程 | 确保微信已打开,窗口未最小化到托盘 |
| `verify-failed` (step 4) | Ctrl+F 搜索没生效 / 未进入文件传输助手 | 手动验一遍快捷键是否被微信支持;不行则改路线(直接点击) |
| `verify-failed` (step 7) | 消息确实没发出去 / VLM 没看到 | 看 trace 里 vlm-2 的 raw 输出,可能是 prompt 太严 |
| `model-failed` | VLM API 调用失败 | 检查 apiKey + baseUrl 是否对,网络是否能通火山 |
| `exception` | 截屏/键鼠/koffi 异常 | 看 error 字段 |
| `action-failed` | 模型输出无法解析 | 看 raw 输出,可能不是合法 JSON |