174 lines
8.7 KiB
Markdown
174 lines
8.7 KiB
Markdown
# 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)
|