isphere-ai-bridge/docs/internal-sandbox-operator-runbook.md

内网沙盒操作员运行手册

本手册供能够访问内网测试沙盒的操作员使用；该沙盒中可以人工打开并登录 iSphere / IMPlatformClient。

目标是为外网协调环境生成一个“已登录状态下的只读现场采集包”。

1. 安全边界

只允许执行以下动作：

人工打开 iSphere / IMPlatformClient
人工正常登录
保持主窗口可见
运行 version
运行 self_check
运行 scan_windows
运行 dump_uia
把 JSON / 文本文档输出复制进采集包

禁止执行以下动作：

自动登录
搜索联系人
打开会话
发送消息
发送文件
接收/下载文件
使用复制出来的凭据
提取密码/token/cookie/私钥
注入进程
hook
读取目标进程内存
绕过终端安全/安防
运行离线证据包中复制出来的可执行文件

2. 在内网沙盒中准备仓库

在仓库根目录打开 PowerShell。

示例：

cd E:\isphere-ai-bridge

如果仓库路径不同，请使用实际路径。下面所有命令都假设当前目录是仓库根目录。

检查仓库状态：

git status --short --branch

建议稍后把该输出记录到采集包中，文件名为：

metadata/repo-status.txt

3. 验证 helper 和 Go MCP 准备情况

运行 helper 验证：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1

期望的高层结果：

ok=true
helper version=0.1.0
uia_available=true 或有效布尔值

如果内网沙盒已安装 Go，也运行：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1

期望的高层结果：

ok=true
tool_count=4
helper_name=ISphereWinHelper
action_tools_present=false

如果没有 Go，不要在采集窗口内临时安装无关工具，除非操作员已获得批准。下面的 C# helper 兜底流程足以采集同样四个只读 helper 操作。

4. 创建采集目录

选择一个采集编号。推荐格式：

YYYY-MM-DD-internal-sandbox-<short-name>

示例：

$captureId = "2026-07-08-internal-sandbox-a"
$captureRoot = "runs\internal-sandbox-live-capture\$captureId"
New-Item -ItemType Directory -Force -Path `
  "$captureRoot\metadata", `
  "$captureRoot\helper", `
  "$captureRoot\windows", `
  "$captureRoot\uia", `
  "$captureRoot\notes" | Out-Null

5. 记录元数据

记录操作系统版本：

Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, CsUserName |
  Format-List | Out-File -FilePath "$captureRoot\metadata\os-version.txt" -Encoding UTF8

记录进程列表：

Get-Process | Sort-Object ProcessName |
  Select-Object ProcessName, Id, MainWindowTitle, Path |
  Format-Table -AutoSize | Out-File -FilePath "$captureRoot\metadata\process-list.txt" -Encoding UTF8

记录仓库状态：

git status --short --branch | Out-File -FilePath "$captureRoot\metadata\repo-status.txt" -Encoding UTF8

创建来源说明：

@"
capture_id: $captureId
source_environment: 内网测试沙盒
operator: <填写操作员姓名或角色>
capture_time_local: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz")
iSphere manually logged in: 是/否
client opened before capture: 是/否
main window visible: 是/否
operations used: version, self_check, scan_windows, dump_uia
forbidden actions performed: no
this package is N12R live evidence, not current-environment N12 pass
"@ | Set-Content -Path "$captureRoot\metadata\source-notes.txt" -Encoding UTF8

打包前，请把 是/否 字段改成真实情况。

6. 人工登录

1. 使用内网沙盒的正常方式打开 iSphere / IMPlatformClient。
2. 按公司正常流程人工登录。
3. 如需 SSO/MFA，请正常完成。
4. 不要使用复制出来的凭据，也不要使用离线证据文件。
5. 保持 iSphere 主窗口可见，不要最小化。

除非正常登录流程本身需要，否则不要点击联系人或会话。不要发送或接收任何内容。

7. 设置 helper 路径变量

运行 verify-win-helper.ps1 后，helper 应位于：

runs\win-helper\ISphereWinHelper.exe

设置变量：

$helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe"

8. 采集 helper 版本

@{
  protocol = "isphere.helper.v1"
  request_id = "n12r-version"
  op = "version"
  timeout_ms = 5000
  args = @{}
} | ConvertTo-Json -Depth 8 -Compress |
  & $helper --json |
  Set-Content -Path "$captureRoot\helper\version.json" -Encoding UTF8

9. 采集 self_check

@{
  protocol = "isphere.helper.v1"
  request_id = "n12r-self-check"
  op = "self_check"
  timeout_ms = 5000
  args = @{}
} | ConvertTo-Json -Depth 8 -Compress |
  & $helper --json |
  Set-Content -Path "$captureRoot\helper\self-check.json" -Encoding UTF8

10. 扫描可见窗口

@{
  protocol = "isphere.helper.v1"
  request_id = "n12r-scan-windows"
  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

打开扫描结果，根据进程名、标题、类名、可见性、边界和评分识别最可能的 iSphere / IMPlatformClient 窗口：

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

11. 保存所选窗口元数据

把 <HWND> 替换为扫描输出中的目标窗口句柄，例如 0x001A0B2C。

$selectedHwnd = "<HWND>"

$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

12. 采集 UIA dump

先使用保守限制：

@{
  protocol = "isphere.helper.v1"
  request_id = "n12r-dump-uia-main"
  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

如果 dump 过大或被截断，可以调整限制后再重复一次，并另存为附加文件，例如：

uia/dump-uia-main-depth10-children150.json

采集期间不要点击、输入、发送、上传、下载或修改 iSphere 客户端状态。

13. 创建脱敏 UIA 副本

创建用于共享的副本：

Copy-Item -LiteralPath "$captureRoot\uia\dump-uia-main.json" -Destination "$captureRoot\uia\dump-uia-main-redacted.json" -Force

然后人工检查 dump-uia-main-redacted.json，在广泛共享前脱敏可见敏感文本。

需要脱敏：

人员姓名
电话号码
邮箱
消息文本
联系人名称
组织敏感内容
类似凭据/token 的字符串
敏感业务文档标题

尽量保留结构性 selector 字段：

control_type
automation_id
class_name
framework_id
bounds
is_enabled
is_offscreen
children shape

14. 写操作员备注

@"
打开的客户端: <iSphere / IMPlatformClient>
登录方式: 人工正常公司流程
是否使用 MFA/SSO: 是/否，不包含任何秘密
所选窗口 hwnd: $selectedHwnd
选择该窗口的原因: <进程/标题/类名/评分原因>
已做脱敏: <简要列表>
采集问题: <简要列表>
forbidden actions performed: no
"@ | Set-Content -Path "$captureRoot\notes\operator-notes.txt" -Encoding UTF8

15. 复制出去前验证采集包

运行：

$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 package files present: $captureRoot" | Tee-Object -FilePath "$captureRoot\metadata\verification-summary.txt"

检查 JSON 是否可解析：

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

16. 打包传输

压缩采集目录：

Compress-Archive -LiteralPath $captureRoot -DestinationPath "$captureRoot.zip" -Force

把目录或 zip 复制回外网仓库环境，并放到：

runs/internal-sandbox-live-capture/<capture-id>/

17. 回报内容

告知协调会话：

N12R 采集包已准备好。
路径: runs/internal-sandbox-live-capture/<capture-id>/
人工 iSphere 登录: 是
采集期间主窗口可见: 是
forbidden actions performed: no

随后由协调会话验证返回包。不要把原始当前环境 N12 标记为通过。