# 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 建设一个离线报告生成流程：

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

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

## 3. 非目标

N14 不做以下事项：

```text
连接内网 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 组成。

核心分层：

```text
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 报告顶层结构：

```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 报告用于人工审阅，建议结构：

```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 参数

建议命令：

```powershell
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。

核心测试：

1. `TestRunCatalogReportMatchesAllN13Selectors`
   - 读取 N12R redacted fixture。
   - 对 `DefaultCatalog()` 生成报告。
   - 断言 `catalog_size=10`、`matched_count=10`、`unmatched_count=0`、`ambiguous_count=0`。

2. `TestReportDoesNotExposeVisibleText`
   - 生成 JSON。
   - 断言 JSON 不包含字段名 `name` 和 `value`。
   - 断言 JSON 包含 `has_name` 和 `name_length`。

3. `TestMarkdownReportDoesNotExposeVisibleText`
   - 生成 Markdown。
   - 断言 Markdown 不包含已知 root visible text。
   - 断言 Markdown 包含 structural fields：`automation_id`、`control_type`、`class_name`。

4. `TestStrictModeClassifiesFailures`
   - 构造一个缺失 selector 的 catalog。
   - 断言严格模式返回未命中退出分类。

5. `TestCLIWritesJSONAndMarkdownReports`
   - 用 `go run ./cmd/uia-selector-report` 或拆分后的 main runner 测试。
   - 断言输出文件存在，JSON 可解析，Markdown 有 Summary 表格。

6. `TestReportRejectsNonReadOnlyCatalogEntries`
   - 构造 `allowed_use=write` 的 selector。
   - 断言报告 `ok=false` 或严格模式分类为非法 catalog。

## 11. 验证脚本

新增：

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

职责：

1. 确认 `go` 可用。
2. 运行 `go test ./internal/uiaselector -count=1`。
3. 运行 `go test ./cmd/uia-selector-report -count=1`，如果 CLI 有测试包。
4. 调用 CLI 生成报告到 `runs/n14-selector-report/`。
5. 解析 JSON 报告，确认 catalog/match 统计符合 N12R fixture。
6. 扫描 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 建议新增或修改：

```text
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
```

保持不修改：

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

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

## 13. 风险和边界

主要风险：

1. 报告误包含可见文本。
   - 缓解：复用 `NodeMatch`，JSON/Markdown writer 做禁止字段扫描测试。

2. CLI 被误解为 live 工具。
   - 缓解：命令名和参数只出现 `dump` 文件路径，不出现 hwnd/process/live。

3. strict 退出码影响 CI 使用。
   - 缓解：默认非严格，验证脚本明确启用 `-strict`。

4. 后续 selector 扩容导致 golden 报告抖动。
   - 缓解：测试断言结构和统计，不依赖整份 golden 文本。

## 14. N14 验收条件

N14 可接受条件：

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

## 15. 推荐下一步

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

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