admin/isphere-ai-bridge

Fork 0

Files

石头 747339ff23 docs: design N14 UIA selector report

2026-07-09 15:57:17 +08:00

10 KiB

Raw Blame History

N14 UIA Selector Report Design

日期：2026-07-09

1. 背景

N13 已合并到 main，当前已有：

internal/uiaselector/catalog.go：首批只读 selector catalog。
internal/uiaselector/dump.go：读取 N12R UIA dump fixture。
internal/uiaselector/matcher.go：离线匹配 selector，返回结构化节点摘要。
scripts/verify-n13-uia-selectors.ps1：验证 N13 包和边界。

N14 的目标是把 N13 的“可定位”能力变成可交付、可审计的离线报告能力，便于内网采集包返回后快速判断 selector 稳定性和覆盖情况。

2. 目标

N14 建设一个离线报告生成流程：

输入一个 UIA dump JSON 文件。
使用 DefaultCatalog() 对全部 selector 执行只读匹配。
输出机器可读 JSON 报告。
输出人工可读 Markdown 报告。
在严格模式下，如果存在未命中、歧义命中或非法 selector，则返回非零退出码。
报告不包含完整可见文本，只包含 has_name 和 name_length 这类派生字段。

N14 只处理离线文件，不访问正在运行的 iSphere，不调用 WinHelper，不新增 helper op，不新增 MCP tool。

3. 非目标

N14 不做以下事项：

连接内网 iSphere
live dump 当前窗口
新增 helper op
新增 MCP tool
点击控件
输入文本
打开会话
搜索联系人
发送消息
发送文件
接收文件
读取聊天内容
导出完整 visible text

N14 也不改变 N13 selector 语义。selector 的 allowed_use 继续固定为 read_only_locate。

4. 方案比较

方案 A：只扩展 PowerShell verifier

做法：在 scripts/verify-n13-uia-selectors.ps1 里临时拼接报告。

优点：改动小。

缺点：报告逻辑难测试，PowerShell 对 Go 内部类型不可见，后续难复用。

方案 B：新增 Go 报告模型和 CLI，PowerShell 只做包装

做法：在 internal/uiaselector 增加 report 生成器；新增一个小型 CLI，例如 cmd/uia-selector-report。PowerShell 脚本只调用 CLI 并检查输出。

优点：核心逻辑可单测；报告结构可稳定复用；CLI 可用于本地、CI 和证据包验收。

缺点：新增一个命令入口，需要少量命令行参数解析。

方案 C：把报告能力接到 MCP 工具

做法：新增 MCP 只读工具，对外暴露 selector report。

优点：未来可被外部客户端直接调用。

缺点：现在会扩大运行面，且 N13/N14 仍处在离线证据验证阶段，不适合作为本阶段目标。

推荐采用方案 B。

5. 推荐设计

N14 新增一个“离线报告生成器”，由 Go package 和 CLI 组成。

核心分层：

cmd/uia-selector-report/main.go
  解析参数，调用 report 生成器，写 JSON/Markdown 文件，设置退出码。

internal/uiaselector/report.go
  RunCatalogReport(root, catalog) -> Report
  WriteReportJSON(report, path)
  WriteReportMarkdown(report, path)

internal/uiaselector/report_test.go
  使用 N12R redacted fixture 验证报告结构、命中数量、文本脱敏和严格模式判断。

scripts/verify-n14-uia-selector-report.ps1
  运行 Go 测试，运行 CLI 生成报告，检查报告存在且不包含禁止字段或动作词。

N14 不需要新增独立 catalog 文件。首版直接复用 DefaultCatalog()。

6. 报告数据模型

建议 JSON 报告顶层结构：

{
  "ok": true,
  "source_dump": "internal/uiaselector/testdata/n12r-2026-07-09-uia-redacted.json",
  "catalog_size": 10,
  "matched_count": 10,
  "unmatched_count": 0,
  "ambiguous_count": 0,
  "generated_at_utc": "2026-07-09T00:00:00Z",
  "selectors": [
    {
      "selector_id": "main_window",
      "description": "iSphere / IMPlatformClient 主窗口",
      "allowed_use": "read_only_locate",
      "stability_score": 95,
      "evidence": {
        "capture_id": "2026-07-08-internal-sandbox-a",
        "uia_path": "root"
      },
      "matched": true,
      "match_count": 1,
      "matches": [
        {
          "path": "root",
          "control_type": "Window",
          "automation_id": "frmMain",
          "class_name": "WindowsForms10.Window.8.app.0.d3a00f_r29_ad1",
          "framework_id": "WinForm",
          "has_name": true,
          "name_length": 9
        }
      ],
      "warnings": []
    }
  ],
  "warnings": []
}

要求：

selectors[].matches[] 复用 NodeMatch 的安全摘要字段。
不输出 name、value、完整 visible text。
generated_at_utc 由调用方注入 clock，测试中使用固定时间，避免 golden 文件抖动。
ok=false 只用于报告生成过程失败或 catalog 非法；selector 未命中不让整个报告失败，但会影响严格模式退出码。

7. Markdown 报告格式

Markdown 报告用于人工审阅，建议结构：

# N14 UIA Selector Report

- Source dump: `...`
- Catalog size: 10
- Matched: 10
- Unmatched: 0
- Ambiguous: 0

## Summary

| Selector | Status | Matches | Stability | Evidence path |
| --- | --- | ---: | ---: | --- |
| main_window | matched | 1 | 95 | root |

## Selector Details

### main_window

- Description: iSphere / IMPlatformClient 主窗口
- Allowed use: read_only_locate
- Status: matched
- Match count: 1

Matches:

| Path | ControlType | AutomationID | ClassName | FrameworkID | HasName | NameLength |
| --- | --- | --- | --- | --- | --- | ---: |
| root | Window | frmMain | WindowsForms10.Window.8.app.0.d3a00f_r29_ad1 | WinForm | true | 9 |

Markdown 里同样禁止完整可见文本。

8. 严格模式

CLI 提供 -strict 参数。

严格模式规则：

报告生成失败：退出码 1。
任一 selector matched=false：退出码 2。
任一 selector match_count>1：退出码 3。
catalog 中存在 allowed_use != read_only_locate：退出码 4。
报告文本包含禁止字段或动作词：verifier 失败。

非严格模式下，未命中或歧义只写入报告和 warnings，CLI 仍返回 0。

9. CLI 参数

建议命令：

go run ./cmd/uia-selector-report `
  -dump internal/uiaselector/testdata/n12r-2026-07-09-uia-redacted.json `
  -out-json runs/n14-selector-report/n12r-selector-report.json `
  -out-md runs/n14-selector-report/n12r-selector-report.md `
  -strict

参数含义：

-dump：必填，UIA dump JSON 路径。
-out-json：可选，JSON 报告路径；为空则不写 JSON 文件。
-out-md：可选，Markdown 报告路径；为空则不写 Markdown 文件。
-strict：可选，启用严格退出码。

CLI 不接收 live hwnd，不接收进程名，不调用任何 Windows UI 自动化 API。

10. 测试策略

N14 implementation plan 必须采用 TDD。

核心测试：

TestRunCatalogReportMatchesAllN13Selectors
- 读取 N12R redacted fixture。
- 对 DefaultCatalog() 生成报告。
- 断言 catalog_size=10、matched_count=10、unmatched_count=0、ambiguous_count=0。
TestReportDoesNotExposeVisibleText
- 生成 JSON。
- 断言 JSON 不包含字段名 name 和 value。
- 断言 JSON 包含 has_name 和 name_length。
TestMarkdownReportDoesNotExposeVisibleText
- 生成 Markdown。
- 断言 Markdown 不包含已知 root visible text。
- 断言 Markdown 包含 structural fields：automation_id、control_type、class_name。
TestStrictModeClassifiesFailures
- 构造一个缺失 selector 的 catalog。
- 断言严格模式返回未命中退出分类。
TestCLIWritesJSONAndMarkdownReports
- 用 go run ./cmd/uia-selector-report 或拆分后的 main runner 测试。
- 断言输出文件存在，JSON 可解析，Markdown 有 Summary 表格。
TestReportRejectsNonReadOnlyCatalogEntries
- 构造 allowed_use=write 的 selector。
- 断言报告 ok=false 或严格模式分类为非法 catalog。

11. 验证脚本

新增：

scripts/verify-n14-uia-selector-report.ps1

职责：

确认 go 可用。
运行 go test ./internal/uiaselector -count=1。
运行 go test ./cmd/uia-selector-report -count=1，如果 CLI 有测试包。
调用 CLI 生成报告到 runs/n14-selector-report/。
解析 JSON 报告，确认 catalog/match 统计符合 N12R fixture。
扫描 JSON/Markdown 输出，确认不含：
- "name"
- "value"
- send_after_approval
- send_file_after_approval
- receive_file_after_approval
- open_conversation
- InvokePattern
- ValuePattern.SetValue

runs/ 已在 .gitignore 中忽略，报告输出不进入提交。

12. 文件规划

后续 implementation plan 建议新增或修改：

internal/uiaselector/report.go
internal/uiaselector/report_test.go
cmd/uia-selector-report/main.go
cmd/uia-selector-report/main_test.go
scripts/verify-n14-uia-selector-report.ps1

保持不修改：

native/ISphereWinHelper/Program.cs
internal/tools/winhelper.go
cmd/isphere-mcp/main.go

如果 implementation plan 中发现必须改 MCP/helper 文件，应停止并重新提交设计审批。

13. 风险和边界

主要风险：

报告误包含可见文本。
- 缓解：复用 NodeMatch，JSON/Markdown writer 做禁止字段扫描测试。
CLI 被误解为 live 工具。
- 缓解：命令名和参数只出现 dump 文件路径，不出现 hwnd/process/live。
strict 退出码影响 CI 使用。
- 缓解：默认非严格，验证脚本明确启用 -strict。
后续 selector 扩容导致 golden 报告抖动。
- 缓解：测试断言结构和统计，不依赖整份 golden 文本。

14. N14 验收条件

N14 可接受条件：

可以从 N12R redacted fixture 生成 JSON 报告。
可以从同一 fixture 生成 Markdown 报告。
报告显示 10 个 N13 selector 全部唯一命中。
报告不包含完整 visible text，不包含 name 或 value 字段。
-strict 在 N12R fixture 上返回 0。
verifier 脚本通过。
没有新增 MCP tool，没有新增 WinHelper op，没有修改 live action surface。

15. 推荐下一步

下一步写 N14 implementation plan，按以下任务拆分：

TDD 新增 report model 和 catalog report generator。
TDD 新增 JSON/Markdown writer。
TDD 新增 CLI。
新增 verifier 脚本。
跑全量验证并提交。

10 KiB Raw Blame History Unescape Escape