# SOP：WorkBuddy AI 运行时调试与对话区参照采集

> 历史 SOP。YCode 自 2026-10-15 接手起，查看 WorkBuddy 实现统一经 REA；以下直接 CDP、evaluate 和采集脚本不再作为执行入口。当前 REA 已提供 `list_electron_targets` / `inspect_electron_page`，支持原版 file 页面。原始测量只作待复核参照。

验证日期：2026-10-08。已验证环境：Windows、WorkBuddy AI 5.7.6、Node 24.21.0。
项目脚本要求 Node 22+，使用内置 `fetch` 和 `WebSocket`，无需额外 npm 依赖。

目标：通过 WorkBuddy 内置 Chromium DevTools Protocol（CDP）读取实际对话页面的
DOM、computed style 和截图，为 Ygent 对标提供可重复采集的依据。
这套流程不依赖 computer-use 或内存 hook，也不修改 WorkBuddy 安装包。

## 1. 调试入口与适用范围

安装包 `main/index.js` 的 `applyCliCommandLineSwitches` 读取
`WORKBUDDY_REMOTE_DEBUGGING_PORT`，并调用 Chromium 的 `remote-debugging-port` 开关。
此开关仅在启动时生效；WorkBuddy 有单实例锁，启动第二个实例不会给旧实例开启调试。

本次端口为 `9223`，已验证监听地址是 `127.0.0.1`。
端口提供页面调试能力，保持本机使用，不做公网转发。
捕获脚本只读取页面，不发送对话、不执行工具、不读取 cookies 或 localStorage。

## 2. 准备环境

以下命令在 PowerShell 中执行。切换到项目目录，检查 Node 与安装路径：

```powershell
Set-Location 'C:\Users\Administrator\code\ygent'
node --version
Test-Path "$env:LOCALAPPDATA\Programs\WorkBuddyAI\WorkBuddyAI.exe"
```

Node 应为 22+，安装路径应返回 `True`。如果 WorkBuddy 安装在其他位置，替换后续启动路径。
完成正在运行的任务，保存输入框草稿，然后通过应用的“退出”菜单或托盘退出应用。
只关闭窗口可能留在托盘，不能视为进程已退出。

```powershell
Get-Process -Name WorkBuddyAI -ErrorAction SilentlyContinue |
  Select-Object Id, MainWindowTitle
Get-NetTCPConnection -LocalPort 9223 -State Listen -ErrorAction SilentlyContinue |
  Select-Object LocalAddress, LocalPort, OwningProcess
```

确认主应用已退出且端口可用。若端口已被当前 WorkBuddy 的 CDP 占用，可直接进入第 4 步；
若被其他程序占用，选择其他空闲端口，并同步修改启动环境变量和采集命令。

## 3. 开启调试并启动

环境变量只用于此次启动，不通过 `setx` 永久写入。启动后恢复当前终端原有值：

```powershell
$wbSopPreviousPort = $env:WORKBUDDY_REMOTE_DEBUGGING_PORT
try {
  $env:WORKBUDDY_REMOTE_DEBUGGING_PORT = '9223'
  Start-Process "$env:LOCALAPPDATA\Programs\WorkBuddyAI\WorkBuddyAI.exe"
} finally {
  if ($null -eq $wbSopPreviousPort) {
    Remove-Item Env:WORKBUDDY_REMOTE_DEBUGGING_PORT -ErrorAction SilentlyContinue
  } else {
    $env:WORKBUDDY_REMOTE_DEBUGGING_PORT = $wbSopPreviousPort
  }
}
```

等待主窗口完成加载。本次重启后原会话“处理大文件”恢复；若没有自动恢复，手动打开目标会话。

## 4. 验证调试入口

```powershell
Invoke-RestMethod 'http://127.0.0.1:9223/json/version' |
  Select-Object Browser, 'Protocol-Version'
Invoke-RestMethod 'http://127.0.0.1:9223/json/list' |
  Select-Object id, title, type
Get-NetTCPConnection -LocalPort 9223 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess
```

验收条件：版本接口返回 `Browser` 和 `Protocol-Version`；目标列表包含 WorkBuddy 的
`page`；监听地址为本机回环地址。本次返回 `Chrome/138.0.7204.251` 和协议版本 `1.3`。
`/json/list` 的原始 URL 可能包含账号快照，不把完整 URL 输出贴入仓库或报告。

## 5. 采集当前页面

在应用里定位到要比对的正文、表格、代码块或工具行。需要比对工具细节时先展开相关过程。
每次采集使用独立目录，避免后一次覆盖前一次：

```powershell
$wbSopCapture = Join-Path $env:USERPROFILE (
  '.ygent\imports\workbuddy-debug-' + (Get-Date -Format 'yyyyMMdd-HHmmss-fff')
)
node scripts/wb-cdp.mjs "$wbSopCapture" 9223
Get-ChildItem -LiteralPath $wbSopCapture | Select-Object Name, Length
```

输出应包含 `connected: true`，并生成以下文件：

| 文件 | 内容 |
|---|---|
| `dom-styles.json` | 页面标题、视口和 DPR、已挂载正文、相关类名统计，以及指定选择器的 HTML、坐标和 computed style |
| `workbuddy.png` | 当前视口截图，不是整段会话的长截图 |

脚本自动排除带 `windowKind` 的辅助页面，避免把独立搜索窗口当成主对话页面。
DOM 和截图先后读取，采集稳定内容能减少两者之间的差异。
文件含真实对话，保存在用户私有目录；项目仓库只保存脚本、SOP 和整理后的规格。

## 6. 检查样式并建立对标记录

```powershell
$wbSopSnapshot = Get-Content -LiteralPath (
  Join-Path $wbSopCapture 'dom-styles.json'
) -Raw -Encoding utf8 | ConvertFrom-Json
$wbSopSnapshot.viewport
$wbSopSnapshot.samples |
  Where-Object count -gt 0 |
  Select-Object selector, count
($wbSopSnapshot.samples |
  Where-Object selector -eq '.cr-markdown p').samples |
  Select-Object text, rect, styles
```

逐项记录“会话与内容位置、截图目录、视口、DPR、主题、应用缩放、选择器、样式值、Ygent 差距”。
两侧使用同一段已导入内容，保持窗口尺度、主题及缩放一致再比较。
需要取得另一处表格或工具行时，在 WorkBuddy 中定位并重新采集。

当前脚本的采集边界：

- 每个指定选择器最多保存前三个节点；单节点文本最多 1500 字符、HTML 最多 18000 字符。
- `visibleText` 最多 40000 字符，来自 `body.innerText`，可能包含已挂载但不在屏幕内的内容。
- 历史列表会按视口挂载，`count` 是当前 DOM 节点数，不能当作全会话数量。
- 默认没有覆盖所有工具行类名。若要采集其他组件，先查看 `classCounts`，定位实际节点，
  再扩展 `scripts/wb-cdp.mjs` 中的 `selectors`；使用哈希类名时要注意版本变化。
- computed style 应结合实际节点、继承关系、缩放和截图解释，不能直接作为通用设计 token。

## 7. 关闭调试

通过应用菜单或托盘正常退出 WorkBuddy，然后确认当前终端没有调试变量，再正常启动：

```powershell
Remove-Item Env:WORKBUDDY_REMOTE_DEBUGGING_PORT -ErrorAction SilentlyContinue
Start-Process "$env:LOCALAPPDATA\Programs\WorkBuddyAI\WorkBuddyAI.exe"
Get-NetTCPConnection -LocalPort 9223 -State Listen -ErrorAction SilentlyContinue |
  Select-Object LocalAddress, LocalPort, OwningProcess
```

确认 WorkBuddy 不再监听该端口。若仍监听，检查是否旧实例未退出，或变量在用户/系统环境中另有配置。
只删除终端变量不会关闭已经运行的 CDP；必须退出调试实例。

## 8. 常见问题

| 现象 | 处理 |
|---|---|
| 连接拒绝 / 请求超时 | 确认启动时设置了变量、旧实例已退出、主窗口已加载、端口一致 |
| 端口被占用 | 查询 `OwningProcess`，换空闲端口；不结束不明进程 |
| `WorkBuddy renderer target not found` | 检查主窗口是否仍在加载；升级后检查主页面 URL 与脚本筛选条件 |
| `WebSocket is not defined` | 升级到 Node 22+，检查 `Get-Command node` 是否指向预期版本 |
| 选择器 `count` 为 0 | 确认已定位到相关内容，检查 `classCounts`；可能是折叠、虚拟列表或类名变化 |
| 截图显示搜索窗口 | 检查是否使用最新脚本；主页面筛选应排除带 `windowKind` 的辅助目标 |
| 重复采集后旧文件消失 | 同一输出目录会覆盖两个文件；按第 5 步创建带时间戳的新目录 |
| 脚本超时或断连 | 等待页面稳定后重新采集；连接超时为 10 秒，单个 CDP 请求为 20 秒 |

## 9. 本次实测发现与相关资料

当前 WorkBuddy AI 页面实际使用 `.cr-markdown`、`.cr-self-message`、`.cr-input-box`。
已挂载的 DOM 没有旧资料中的 `.cb-markdown` 和 `.cb-task-tool-item-inner`。
在本次 1200 × 762、DPR 1 的快照中，正文段落的 computed style 约为
`15.0001px / 26.2502px`。这是该环境下的实测值，不应概括为所有版本和缩放状态的固定规格。

因此 `lib-chat-ui` 中仍存在的旧样式只作为辅助资料；当前对话区的对标依据是实际 DOM 和 computed style。
本次验证了调试与采集能力，Ygent 的 1:1 对齐需要逐项实现和验收。

- [真实对话数据转换与导入](workbuddy-reference-import.md)
- [历史静态分析与 ASAR 提取方式](reference/workbuddy/chat-tool-fold.md)
- [运行时采集脚本](../scripts/wb-cdp.mjs)
- [对话区对标路线图](ygent-chat-parity.md)