# N12R 内网操作员最小重做步骤 日期：2026-07-09 适用对象：内网测试沙盒操作员。 目的：修正本次 N12R 返回包中 `selected-window.json` 缺失和 `dump_uia` 失败的问题，重新生成一个可被外网校验接受的 N12R 采集包。 ## 1. 本次失败原因 本次返回包被外网校验拒收，核心原因是窗口句柄写错了。 日志中写成了： ```powershell $selectedHwnd = "<0x290E6E>" ``` 这是错误写法。`` 里的尖括号只是提示格式，实际填写时必须删掉。 正确写法是： ```powershell $selectedHwnd = "0x290E6E" ``` 因为多了尖括号，后续窗口匹配失败： ```text selected hwnd not found in scan result: <0x290E6E> ``` 所以： 1. `windows/selected-window.json` 没有生成。 2. `dump_uia` 使用了无效 hwnd。 3. `uia/dump-uia-main.json` 返回 `WINDOW_NOT_FOUND`。 ## 2. 重做前确认 在内网测试沙盒中打开 PowerShell，进入仓库根目录： ```powershell cd E:\isphere-ai-bridge ``` 确认 iSphere / IMPlatformClient 已经人工登录，并且主窗口可见、没有最小化。 不要执行以下动作： ```text 搜索联系人 打开会话 发送消息 发送文件 接收/下载文件 自动登录 注入 hook 读取内存 绕过安防 ``` ## 3. 推荐做法：重新运行 scan_windows 窗口句柄可能已经变化，所以推荐先重新扫描窗口。 如果沿用原采集编号： ```powershell $captureId = "2026-07-08-internal-sandbox-a" $captureRoot = "runs\internal-sandbox-live-capture\$captureId" $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe" ``` 重新扫描可见窗口： ```powershell @{ protocol = "isphere.helper.v1" request_id = "n12r-scan-windows-retry" op = "scan_windows" timeout_ms = 5000 args = @{ include_all_visible = $true } } | ConvertTo-Json -Depth 8 -Compress | & $helper --json | Set-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 ``` 查看候选窗口： ```powershell Get-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json | Select-Object -ExpandProperty data | Select-Object -ExpandProperty windows | Where-Object { $_.process_name -match "iSphere|IMPlatform|IMPP" -or $_.title -match "iSphere|IMPlatform|IMPP" } | Format-Table hwnd,pid,process_name,title,class_name,visible,score -AutoSize ``` 从输出中选择 iSphere / IMPlatformClient 主窗口的 `hwnd`。 示例中之前的候选值是： ```text 0x290E6E ``` 如果这次扫描输出变了，请使用新的 `hwnd`。 ## 4. 正确保存 selected-window.json 把下面命令中的 `0x290E6E` 改成你刚刚确认的真实窗口句柄。 注意：不要加尖括号。 正确： ```powershell $selectedHwnd = "0x290E6E" ``` 错误： ```powershell $selectedHwnd = "<0x290E6E>" ``` 保存所选窗口元数据： ```powershell $selectedHwnd = "0x290E6E" $scanObj = Get-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json $selected = $scanObj.data.windows | Where-Object { $_.hwnd -eq $selectedHwnd } | Select-Object -First 1 if (-not $selected) { throw "selected hwnd not found in scan result: $selectedHwnd" } $selected | ConvertTo-Json -Depth 8 | Set-Content -Path "$captureRoot\windows\selected-window.json" -Encoding UTF8 ``` 确认文件已经生成： ```powershell Test-Path -LiteralPath "$captureRoot\windows\selected-window.json" ``` 期望输出： ```text True ``` ## 5. 重新执行 dump_uia ```powershell @{ protocol = "isphere.helper.v1" request_id = "n12r-dump-uia-main-retry" op = "dump_uia" timeout_ms = 15000 args = @{ hwnd = $selectedHwnd max_depth = 8 include_text = $true max_children = 100 } } | ConvertTo-Json -Depth 12 -Compress | & $helper --json | Set-Content -Path "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8 ``` 检查结果是否成功： ```powershell $dump = Get-Content "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8 | ConvertFrom-Json $dump.ok $dump.error ``` 期望： ```text True ``` 并且 `$dump.error` 应为空或为 `null`。 如果仍然是 `WINDOW_NOT_FOUND`，说明窗口句柄已经失效。请回到第 3 步重新扫描并选择新的 hwnd。 ## 6. 重新创建脱敏副本 ```powershell Copy-Item -LiteralPath "$captureRoot\uia\dump-uia-main.json" -Destination "$captureRoot\uia\dump-uia-main-redacted.json" -Force ``` 然后人工打开： ```text $captureRoot\uia\dump-uia-main-redacted.json ``` 脱敏可见敏感文本，例如： ```text 人员姓名 手机号 邮箱 消息文本 联系人名称 敏感业务标题 类似 token / 密码 / cookie 的字符串 ``` 尽量保留这些结构字段： ```text control_type automation_id class_name framework_id bounds is_enabled is_offscreen children ``` ## 7. 修正 source-notes.txt 打开： ```text $captureRoot\metadata\source-notes.txt ``` 把这些字段从 `是/否` 改成真实值： ```text iSphere manually logged in: 是 client opened before capture: 是 main window visible: 是 ``` 如果真实情况不是“是”，不要继续打包，先重新完成对应动作。 ## 8. 修正 operator-notes.txt 打开： ```text $captureRoot\notes\operator-notes.txt ``` 不要保留 `<...>` 示例内容。请改成真实说明。 示例： ```text 打开的客户端: iSphere / IMPlatformClient 登录方式: 人工正常公司流程 是否使用 MFA/SSO: 是，不包含任何秘密 所选窗口 hwnd: 0x290E6E 选择该窗口的原因: process_name 为 IMPlatformClient，标题为国网甘肃省电力公司，visible=True，score=65 已做脱敏: 已检查 dump-uia-main-redacted.json，移除可见敏感文本 采集问题: 首次把 hwnd 写成 <0x290E6E> 导致失败，本次已修正为 0x290E6E 后重新采集 forbidden actions performed: no ``` ## 9. 复制出去前必须验证 运行必需文件检查： ```powershell $required = @( "$captureRoot\metadata\source-notes.txt", "$captureRoot\helper\version.json", "$captureRoot\helper\self-check.json", "$captureRoot\windows\scan-windows.json", "$captureRoot\windows\selected-window.json", "$captureRoot\uia\dump-uia-main.json", "$captureRoot\uia\dump-uia-main-redacted.json", "$captureRoot\notes\operator-notes.txt" ) foreach ($path in $required) { if (-not (Test-Path -LiteralPath $path)) { throw "missing required file: $path" } } "N12R retry package files present: $captureRoot" | Tee-Object -FilePath "$captureRoot\metadata\verification-summary.txt" ``` 运行 JSON 解析检查： ```powershell Get-Content "$captureRoot\helper\version.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null Get-Content "$captureRoot\helper\self-check.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null Get-Content "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null Get-Content "$captureRoot\windows\selected-window.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null Get-Content "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null Get-Content "$captureRoot\uia\dump-uia-main-redacted.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null ``` 检查 UIA dump 必须是成功： ```powershell $dump = Get-Content "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8 | ConvertFrom-Json if (-not $dump.ok) { throw "dump_uia failed: $($dump.error | ConvertTo-Json -Depth 8 -Compress)" } ``` ## 10. 重新压缩返回 ```powershell Compress-Archive -LiteralPath $captureRoot -DestinationPath "$captureRoot.zip" -Force ``` 把新的 zip 或目录返回给外网协调环境。 返回时请同时说明： ```text N12R 重采/补采包已准备好。 路径: runs/internal-sandbox-live-capture/2026-07-08-internal-sandbox-a/ 人工 iSphere 登录: 是 采集期间主窗口可见: 是 forbidden actions performed: no 本次已修正 hwnd，不再包含尖括号；selected-window.json 已生成；dump_uia ok=true ``` ## 11. 外网收到后如何判断 外网协调环境会重新运行： ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-n12r-return-package.ps1 ` -PackageRoot <返回包目录> ` -ReportPath <包外报告路径> ``` 只有 validator 输出： ```text Decision: ACCEPT ``` 才能进入 N13 selector 设计。