8.7 KiB
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 与安装路径：
Set-Location 'C:\Users\Administrator\code\ygent'
node --version
Test-Path "$env:LOCALAPPDATA\Programs\WorkBuddyAI\WorkBuddyAI.exe"
Node 应为 22+，安装路径应返回 True。如果 WorkBuddy 安装在其他位置，替换后续启动路径。
完成正在运行的任务，保存输入框草稿，然后通过应用的“退出”菜单或托盘退出应用。
只关闭窗口可能留在托盘，不能视为进程已退出。
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 永久写入。启动后恢复当前终端原有值：
$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. 验证调试入口
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. 采集当前页面
在应用里定位到要比对的正文、表格、代码块或工具行。需要比对工具细节时先展开相关过程。 每次采集使用独立目录，避免后一次覆盖前一次：
$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. 检查样式并建立对标记录
$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，然后确认当前终端没有调试变量，再正常启动：
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 对齐需要逐项实现和验收。