Files
pacs_win_uia/docs/最小系统.md
T
zimoyin 2c6d2de9f5 新增 docs/最小系统.md:从一条四步链路逐层讲到完整系统(10 张 Mermaid 图)
- 第 0 层最小系统:找窗口 → 读控件树 → 算路径 → 取值
- 逐层展开:窗口匹配分级 / 三来源控件树与自动开无障碍 / XPath 生成与回读 /
  valueKey 降级 / 监控与无界面读取 / 界面三栏与两个浮层 / 周边功能
- 另有时序图(拾取全过程)、状态图(悬浮条何时显示)、类图(核心类关系)、
  排错对照表(症状 → 先看哪里)、读代码顺序
- 顶部说明怎么把 Mermaid 文字渲染成图(VS Code 插件 / Typora / mermaid.live)
- 代码导览顶部加了指向它的链接
2026-10-13 20:33:22 +08:00

332 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 最小系统(一层层看懂这个工具)
> 读法:从**第 0 层**看起,每加一层只多一个概念,配一张图。看完 0~4 层,这个工具你就懂八成了;
> 5~8 层是界面与周边功能;最后几节是排错对照表和"读代码的顺序"。
>
> 图都用 **Mermaid**(文字转图)语法写:` ```mermaid ` 代码块里的文字就是图。
>
> 怎么看到图(任选一种):
> - VS Code / Rider:装 Markdown 预览的 Mermaid 插件(VS Code 用 "Markdown Preview Mermaid Support"),预览即可;
> - Typora / Obsidian:直接预览;
> - 不想装东西:把某个 ```mermaid 代码块的内容贴到 <https://mermaid.live> 左侧,右侧立刻出图;
> - 推送到 GitLab/GitHub 后,网页上会自动渲染。
>
> 想改图:直接改代码块里的文字,不用画图工具。
---
## 第 0 层:最小系统 = 一条四步链路
整个工具,剥掉所有界面和周边功能,只剩四步:
```mermaid
flowchart LR
A["目标程序<br/>(PACS 客户端 / 记事本 / 浏览器)"] -->|"① 找窗口"| B["NativeWindowService<br/>按 进程名 / 窗口类 / 标题 匹配"]
B -->|"② 读控件树"| C["ControlTreeService<br/>UIA → MSAA → Win32"]
C -->|"③ 算路径"| D["ControlPath<br/>XPath 唯一命中"]
D -->|"④ 取值"| E["ControlValueReader<br/>Value → Text → Name"]
```
- **第 0 层的关键词**:窗口 → 控件树 → 路径 → 值。
- 后面所有的功能(拾取、监控列表、悬浮条、控件框、无界面读取)都只是这四步的不同包装。
- 所以**遇到问题先问自己:卡在这四步里的哪一步?**(对应文件见文末对照表)
---
## 第 1 层:窗口是怎么找到的
目标程序可能开了好几个窗口,DLL 里的控件又没有独立窗口。所以第一步先锁定"哪一棵树"。
```mermaid
flowchart TD
A["EnumWindows<br/>枚举所有可见顶层窗口"] --> B["抓取快照<br/>HWND / PID / 进程名 / 类名 / 标题 / 矩形"]
B --> C{"按条件过滤<br/>(保存监控时记下的线索)"}
C -->|"进程名 + 窗口类 + 标题<br/>全中"| D["✅ 最精确"]
C -->|"只中进程名+窗口类"| E["⚠ 程序可能升级过<br/>(窗口类会变)"]
C -->|"只中进程名+标题"| F["⚠ 标题随内容变过"]
C -->|"只有进程名"| G["⚠ 较宽,需要人工核对"]
C -->|"多个候选"| H["❌ 报错要求补条件<br/>绝不随便取第一个"]
```
要点:
- 匹配是**分级降级**的:越靠上越可信;用了下面几级,工具会在状态栏明说"需要人工核对"。
- **标题只用来找窗口**,不是控件路径的一部分(标题常含文件名/患者姓名,会变)。
- 窗口快照里还会存:是否可见、是否最小化、样式(`GWL_STYLE`/`GWL_EXSTYLE`)——排查"为什么命中的是这一层"很有用。
对应代码:`Services/NativeWindowService.cs`、`Services/WindowMatcher.cs`、`Services/ControlLocatorService.cs`(匹配窗口那部分)。
---
## 第 2 层:控件树从哪来(三个来源)
Windows 上的"控件信息"有三套互不相通的体系。工具同时用,按顺序取第一个**有内容**的:
```mermaid
flowchart TD
R["ControlTreeService.Read(窗口HWND)"] --> U{"UIA 读得到内容吗?"}
U -->|"只有根节点/只有标题栏"| ACT["自动请求目标开启无障碍<br/>(Chromium/CEF/UWP 常见)"]
ACT --> U2{"重读后有内容吗?"}
U2 -->|"有"| OK["用 UIA 树"]
U2 -->|"还是没有"| M{"MSAA 读得到内容吗?"}
U -->|"有"| OK
M -->|"有"| OKM["用 MSAA 树"]
M -->|"没有"| W{"Win32 有多少子窗口?"}
W -->|"有"| OKW["用 Win32 树"]
W -->|"没有"| EMPTY["如实报告:该目标没有暴露内部控件"]
```
三个来源各自能看到什么(**不要混用**):
| | UIA | MSAA | Win32 |
|---|---|---|---|
| 能看到 | 控件类型、名称、AutomationId、模式(Value/Text/Grid…) | 传统控件、列表行(保真度低) | **每个真实子窗口**(HWND/类名/矩形) |
| 看不到 | 未开无障碍的自绘界面 | 部分现代控件细节 | 自绘区域内的"控件" |
| 代价 | 跨进程调用,可能卡住 | 同左 | 本机枚举,最快最稳 |
要点:
- 树一律按 **RawView** 读(包含不可见/非"控件"元素),因为那才是你眼睛看到的那棵树。
- 读树用 `CacheRequest` 一次性批量取属性,否则每个节点都是一次跨进程调用,大窗口会慢到几秒。
- 读完后会给每个节点算好 `CanonicalPath`(见第 3 层),并**由容器反推每行的选中状态**(WinForms 列表的行自身不报选中)。
对应代码:`Services/ControlTreeService.cs`、`Services/UiAutomationService.cs`、`Services/MsaaTreeReader.cs`、`Services/Win32TreeReader.cs`、`Services/ReadBudget.cs`。
---
## 第 3 层:路径(XPath)——定位的核心
路径不是"一串名字",而是**在快照上跑 XPath 1.0**:
```mermaid
flowchart LR
subgraph 生成
A["控件树节点"] --> B["把树写成 XML<br/>节点名=控件类型,属性=Name/AutomationId/ClassName/状态"]
B --> C["算 CanonicalPath<br/>AutomationId → ClassName+类型 → 类型序号"]
end
subgraph 回读
D["保存的 XPath"] --> E["重新读树 → 同一套 XML"]
E --> F["求值"]
F -->|"命中 1 个"| G["✅ 定位成功"]
F -->|"0 个 / 多个"| H["❌ 明确报错<br/>不猜、不取第一个"]
end
```
可以用在路径里的东西:
| 写法 | 含义 |
|---|---|
| `/Window[1]/Tab[@AutomationId='FixtureTabs']/…` | 一级级往下(绝对路径,含窗口根) |
| `//DataItem[...]` | 任意深度找(层级会变时更耐用,但要确认唯一) |
| `@Name` `@AutomationId` `@ClassName` `@ControlType` `@Source` | 属性条件 |
| `@IsSelected` `@IsFocused` `@IsOffscreen` `@IsEnabled` | 状态条件(值 `'true'`/`'false'`) |
| `contains(@Name,'保存')`、`and`、`or` | 部分匹配与组合 |
| `DataItem[2]` | 同级第几个(**最后手段**,结构一变就指错) |
**Name 会变怎么办**:优先 `AutomationId` → 稳定祖先 + `ClassName` → 稳定辅助节点 → 名称的稳定片段 → 序号。
详细原则见 `docs/XPath定位.md`。
对应代码:`Services/ControlPath.cs`(求值/生成)、`Services/ControlLocatorBuilder.cs`(怎么算路径)、`Services/ControlLocatorService.cs`(怎么回读)。
---
## 第 4 层:取值(valueKey)
定位到节点后,"读什么"由 valueKey 决定。最容易踩的坑是 **Name 不是内容**:
```mermaid
flowchart TD
A["valueKey = 文本内容"] --> B{"ValuePattern 有值吗?"}
B -->|"有"| Z["✅ 用它"]
B -->|"没有"| C{"TextPattern 有值吗?"}
C -->|"有"| Z
C -->|"没有"| D{"Name 非空吗?"}
D -->|"有"| Z
D -->|"都没有"| E["❌ 报错并列出各自原因"]
```
- 记事本文档:`Name = 文本编辑器`(标题),内容在 `Value`/`Text` 里;
- WinForms 文本框:`Name` 就是内容;
- 所以**新增控件默认用 `文本内容`**,两头都吃得下。
其它常用键:`Value` `Text` `选中状态` `焦点状态` `选中行文本` `列表行数` `列表列数` `列表选中项数` `OCR文本`。
对应代码:`Services/ControlValueReader.cs`、`Models/ControlLocator.cs`(键清单)。
---
## 第 5 层:把上面四步变成"能长期用"
```mermaid
flowchart LR
A["加控件<br/>(拾取或选树节点)"] --> B["存成监控项 JSON<br/>窗口条件 + XPath + valueKey"]
B --> C["界面点一行<br/>→ 定位 + 画框 + 选中树节点"]
B --> D["无界面 --read-saved<br/>→ 逐个定位取值 → out.json"]
B --> E["悬浮条导入 path<br/>→ 该控件出现时才显示按钮"]
```
- 监控 JSON **只存稳定信息**:窗口条件、XPath、valueKey、超时;RuntimeId、当前值、焦点这类"此刻状态"不落盘。
- 无界面读取每条独立计时,结果分四类计数:命中 / 未定位 / 取不到值 / 已停用跳过。
- 配置文件都在 **exe 同目录**(`control-monitors.json`、`settings.json`、`out.json`),整包拷走即可。
对应代码:`Services/ControlMonitorStore.cs`、`Services/HeadlessConfigReader.cs`、`Services/FloatingBarManager.cs`。
---
## 第 6 层:界面(三栏 + 两个浮层)
```mermaid
flowchart LR
subgraph 主界面
L["左:窗口列表<br/>搜索/前台高亮"]
M["中:控件树 + 列表结果<br/>搜索 + 选中 Path 横条"]
R["右:控件属性 + 控件监控列表"]
end
L -->|"选中窗口"| M
M -->|"选中节点"| R
R -->|"点一行"| M
```
两个浮层(都不抢焦点、点击穿透):
| 浮层 | 什么时候出现 | 有什么 |
|---|---|---|
| 拾取层级框 | 拾取悬停预览 | **蓝框=光标所在窗口**,**黄框=向上遍历的控件链** |
| 控件框面板 | 杂项 →「绘制所有控件框」 | 每个控件一个框;右侧面板:父节点/上一个/下一个(高亮整条祖先链)、复制 Path、搜索、类型过滤、大小位置、悬停标签 |
对应代码:`UI/MainForm.cs`、`UI/ControlMonitorEditorControl.cs`、`Picker/CrosshairPicker.cs`、`UI/PickHierarchyOverlayForm.cs`、`UI/NodeMapOverlayForm.cs`。
---
## 第 7 层:周边(按需了解)
| 功能 | 一句话 | 文件 |
|---|---|---|
| 单实例 | 第二个进程不干活,把请求转给已运行的实例(Mutex + 命名管道) | `Services/SingleInstanceService.cs`、`Program.cs` |
| 命令时机 | 启动/退出/定时/单次执行命令;退出时连命令拉起的子进程一起结束 | `Services/CommandRunner.cs`、`Services/ProcessJob.cs` |
| 截图 | PrintWindow → BitBlt → 屏幕拷贝,并校验不是全黑/全白 | `Services/ScreenshotService.cs` |
| OCR | 本地服务,默认关闭;只读值失败时可降级为"截图识别",会标注来源 | `Services/OcrClient.cs` |
| 列表读取 | Grid/Table 模式 → 遍历降级;读不到就如实报告,不伪造 | `Services/ListReaderService.cs` |
---
## 一张时序图:从按下"拾取控件"到拿到路径
```mermaid
sequenceDiagram
participant U as 用户
participant M as MainForm
participant P as CrosshairPicker
participant T as TargetProbeService
participant X as 目标程序
U->>M: 点「拾取控件」
M->>M: 隐藏主界面(并记住原前台窗口)
M->>P: Start()
P->>P: 显示全屏透明覆盖层 + 低级鼠标钩子
U->>P: 移动鼠标
P->>T: 探测光标处的窗口/元素
T->>X: WindowFromPoint / UIA FromPoint
X-->>T: 窗口 + 元素 + 矩形
T-->>P: 蓝框(窗口)+ 黄框(控件链)
P->>P: 只在鼠标下的框上画标签
U->>P: 松开左键(点击被钩子吞掉,不会点中目标控件)
P->>M: Picked(结果)
M->>M: 恢复主界面并把前台还给原窗口
M->>M: 从顶层窗口读同一棵树 → 展开并选中该节点
M->>M: 加入控件监控列表(未启用)+ 显示 Path 横条
```
---
## 一张状态图:悬浮条什么时候显示
```mermaid
stateDiagram-v2
[*] --> 检查配置
检查配置 --> 隐藏: 未启用 / 没有启用按钮
检查配置 --> 找窗口: 有进程名或类名或标题
找窗口 --> 隐藏: 没有匹配窗口 / 匹配到多个
找窗口 --> 查XPath: 唯一命中(优先可见窗口,跳过最小化的同名窗口)
查XPath --> 隐藏: 导入的 XPath 未唯一命中
查XPath --> 查可见性: 命中
查可见性 --> 显示: 锚定窗口未被别的程序完全遮住
查可见性 --> 隐藏: 被别的程序完全遮住 / 最小化
显示 --> 隐藏: 条件不再满足
隐藏 --> 找窗口: 下一次节拍(默认 300ms)
```
> 注意:**本工具自己的窗口不算遮挡**——否则在设置页里根本测不了。
---
## 核心类关系(一页看完)
```mermaid
classDiagram
class MainForm {
+三栏界面
+拾取/定位/绘制框
}
class ControlTreeService {
+Read(hwnd) ControlTreeResult
}
class ControlTreeNode {
+Uia / Msaa / Window
+Children
+CanonicalPath
}
class ControlPath {
+Build(root,node)
+Select(root,xpath)
+PreparePaths(root)
}
class ControlLocatorService {
+FindTargetWindow(def)
+Resolve(def,hwnd)
}
class ControlValueReader {
+TryRead(node,valueKey)
}
class ControlMonitorStore {
+Load() / Save()
}
MainForm --> ControlTreeService : 读树
ControlTreeService --> ControlTreeNode : 产出
ControlTreeNode --> ControlPath : 算路径
MainForm --> ControlLocatorService : 回读定位
ControlLocatorService --> ControlPath : 求值
ControlLocatorService --> ControlValueReader : 取值
MainForm --> ControlMonitorStore : 保存配置
```
---
## 排错对照表(症状 → 先看哪里)
| 症状 | 最可能原因 | 先看 |
|---|---|---|
| 控件树只有一行 | 目标没暴露(自绘/未开无障碍) | 第 2 层;状态栏说明;设置里开自动激活 |
| 树里有节点但拾取不到 | 命中测试给的是容器 | `UiAutomationService.FromHandleAtPoint`(命中后向深处收敛) |
| Path 匹配 0 个 | 层级变了 / 名字变了 / 选错窗口 | 第 3 层;用 `//` + 稳定祖先 |
| Path 匹配多个 | 条件太宽 | 加 `@AutomationId` 或祖先范围 |
| 读到的是标题不是内容 | valueKey 用了 `Name` | 改成 `文本内容` |
| 列表读不到 | 只有 UIA 的 Grid/Table/遍历 | `ListReaderService`;看它打印的结构诊断 |
| 悬浮条不显示 | 条件不满足(它会给原因) | 第 6 层状态图 |
| 界面少了一块 | 控件没加进窗体/没 Dock | 启动日志的"界面布局检查完成:异常区域 N 个" |
| 启动就崩 | 构造函数里用了还没赋值的字段 | `Program.cs` 的兜底日志 + "构造 MainForm"冒烟 |
---
## 读代码的顺序(建议)
1. `Program.cs` —— 启动分支与单实例;
2. `Services/ControlTreeService.cs` —— 三来源怎么选;
3. `Services/ControlPath.cs` —— 路径怎么算、怎么求值;
4. `Models/ControlTreeNode.cs` —— 一个节点里有什么;
5. `Services/ControlValueReader.cs` —— 取值键清单与降级;
6. `UI/MainForm.cs` —— 界面怎么把这些串起来(文件顶部有"要改 X 看哪个方法"的索引)。
配套阅读:`docs/代码导览.md`(模块地图 + 坑)、`docs/XPath定位.md`(路径语法与常见问题)。