# 最小系统(一层层看懂这个工具) > 读法:从**第 0 层**看起,每加一层只多一个概念,配一张图。看完 0~4 层,这个工具你就懂八成了; > 5~8 层是界面与周边功能;最后几节是排错对照表和"读代码的顺序"。 > > 图都用 **Mermaid**(文字转图)语法写:` ```mermaid ` 代码块里的文字就是图。 > > 怎么看到图(任选一种): > - VS Code / Rider:装 Markdown 预览的 Mermaid 插件(VS Code 用 "Markdown Preview Mermaid Support"),预览即可; > - Typora / Obsidian:直接预览; > - 不想装东西:把某个 ```mermaid 代码块的内容贴到 左侧,右侧立刻出图; > - 推送到 GitLab/GitHub 后,网页上会自动渲染。 > > 想改图:直接改代码块里的文字,不用画图工具。 --- ## 第 0 层:最小系统 = 一条四步链路 整个工具,剥掉所有界面和周边功能,只剩四步: ```mermaid flowchart LR A["目标程序
(PACS 客户端 / 记事本 / 浏览器)"] -->|"① 找窗口"| B["NativeWindowService
按 进程名 / 窗口类 / 标题 匹配"] B -->|"② 读控件树"| C["ControlTreeService
UIA → MSAA → Win32"] C -->|"③ 算路径"| D["ControlPath
XPath 唯一命中"] D -->|"④ 取值"| E["ControlValueReader
Value → Text → Name"] ``` - **第 0 层的关键词**:窗口 → 控件树 → 路径 → 值。 - 后面所有的功能(拾取、监控列表、悬浮条、控件框、无界面读取)都只是这四步的不同包装。 - 所以**遇到问题先问自己:卡在这四步里的哪一步?**(对应文件见文末对照表) --- ## 第 1 层:窗口是怎么找到的 目标程序可能开了好几个窗口,DLL 里的控件又没有独立窗口。所以第一步先锁定"哪一棵树"。 ```mermaid flowchart TD A["EnumWindows
枚举所有可见顶层窗口"] --> B["抓取快照
HWND / PID / 进程名 / 类名 / 标题 / 矩形"] B --> C{"按条件过滤
(保存监控时记下的线索)"} C -->|"进程名 + 窗口类 + 标题
全中"| D["✅ 最精确"] C -->|"只中进程名+窗口类"| E["⚠ 程序可能升级过
(窗口类会变)"] C -->|"只中进程名+标题"| F["⚠ 标题随内容变过"] C -->|"只有进程名"| G["⚠ 较宽,需要人工核对"] C -->|"多个候选"| H["❌ 报错要求补条件
绝不随便取第一个"] ``` 要点: - 匹配是**分级降级**的:越靠上越可信;用了下面几级,工具会在状态栏明说"需要人工核对"。 - **标题只用来找窗口**,不是控件路径的一部分(标题常含文件名/患者姓名,会变)。 - 窗口快照里还会存:是否可见、是否最小化、样式(`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["自动请求目标开启无障碍
(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
节点名=控件类型,属性=Name/AutomationId/ClassName/状态"] B --> C["算 CanonicalPath
AutomationId → ClassName+类型 → 类型序号"] end subgraph 回读 D["保存的 XPath"] --> E["重新读树 → 同一套 XML"] E --> F["求值"] F -->|"命中 1 个"| G["✅ 定位成功"] F -->|"0 个 / 多个"| H["❌ 明确报错
不猜、不取第一个"] 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["加控件
(拾取或选树节点)"] --> B["存成监控项 JSON
窗口条件 + XPath + valueKey"] B --> C["界面点一行
→ 定位 + 画框 + 选中树节点"] B --> D["无界面 --read-saved
→ 逐个定位取值 → out.json"] B --> E["悬浮条导入 path
→ 该控件出现时才显示按钮"] ``` - 监控 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["左:窗口列表
搜索/前台高亮"] M["中:控件树 + 列表结果
搜索 + 选中 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`(路径语法与常见问题)。