新增 docs/最小系统.md:从一条四步链路逐层讲到完整系统(10 张 Mermaid 图)

- 第 0 层最小系统:找窗口 → 读控件树 → 算路径 → 取值
- 逐层展开:窗口匹配分级 / 三来源控件树与自动开无障碍 / XPath 生成与回读 /
  valueKey 降级 / 监控与无界面读取 / 界面三栏与两个浮层 / 周边功能
- 另有时序图(拾取全过程)、状态图(悬浮条何时显示)、类图(核心类关系)、
  排错对照表(症状 → 先看哪里)、读代码顺序
- 顶部说明怎么把 Mermaid 文字渲染成图(VS Code 插件 / Typora / mermaid.live)
- 代码导览顶部加了指向它的链接
This commit is contained in:
zimoyin
2026-10-13 20:33:22 +08:00
parent 697d80fbcf
commit 2c6d2de9f5
2 changed files with 333 additions and 0 deletions
+2
View File
@@ -1,5 +1,7 @@
# 代码导览(接手必读)
> 想先"看懂整体"再看细节:先读 **[最小系统.md](最小系统.md)**——从一条四步链路开始,一层层加图讲清楚。
> 目的:拿到这份代码的人,能在几分钟内知道**哪个功能在哪个文件**、**改动要动哪里**、**哪些地方有坑**。
>
> 项目:.NET Framework 4.8 + WinForms,只读的 Windows UI 自动化检查/监控工具。
+331
View File
@@ -0,0 +1,331 @@
# 最小系统(一层层看懂这个工具)
> 读法:从**第 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`(路径语法与常见问题)。