# 最小系统(一层层看懂这个工具) > 读法:从**第 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` | --- ## 第 8 层:两个配置文件里到底有什么 两个文件都在 **exe 同目录**,纯文本 JSON,可以手改、可随包分发。 ### settings.json(应用设置) | 节 | 关键字段 | 作用 | |---|---|---| | `Ui` | `AutoReadTreeOnSelect` | 窗口列表选中一行就自动读树 | | | `AutoActivateAccessibility` | 读到空树/只有边框时自动请求目标开启无障碍(默认 true) | | | `TreeMaxDepth` / `TreeMaxNodes` / `TreeTimeoutSeconds` | 控件树的深度/节点/超时上限 | | | `TreeRefreshIntervalMs` | 实时刷新间隔(默认 300ms) | | | `HighlightForegroundWindow` | 窗口列表里给前台窗口上色 | | | `SettingsWindowX/Y/Width/Height` | 设置窗口上次的位置(0 = 没记录) | | `FloatingButton` | `RefreshIntervalMs` | 悬浮条跟随/条件检查节拍(默认 300ms) | | | `Bars[]` | 每条悬浮条:名称、启用、透明度、相对偏移、显示条件(进程/类/标题/导入 path)、按钮列表 | | `Commands` | `Triggers[]` | 命令时机(启动/退出/定时/单次)与命令、超时 | | `Ocr` | `Enabled` `BaseUrl` `Language` `MinConfidence` `TimeoutSeconds` `SaveScreenshots` `ScreenshotDirectory` | 本地 OCR 服务(**默认关闭**) | | `Screenshot` | `Directory` `AllowRestoreMinimized` `RestoreSettleMs` | 截图目录与"是否允许临时恢复最小化窗口" | | `Read` | `DefaultTimeoutSeconds` `SkipDisabled` | 无界面读取的默认等待与是否跳过停用条目 | ### control-monitors.json(控件监控) ```json { "Version": 1, "Items": [ { "Id": "guid", "ContentKey": "patient_id", // 别名:结果里的键名,只能字母数字下划线点连字符 "ControlPath": "/Window[1]//Edit[@AutomationId='PatientId']", // 唯一权威定位 "Source": "Auto", // Auto / Uia / Msaa / Win32 "ProcessName": "MyPacs", // 窗口条件(三件套) "WindowClass": "PacsMainWindow", "WindowTitleKeyword": "工作站", "ValueKey": "文本内容", "TimeoutSeconds": 0, // 0 = 用 --timeout "Disabled": false, // 缺省 = 启用(停用条目无界面模式会跳过) "PageFeatures": "可选备注,留空表示不校验页面" } ] } ``` | 字段 | 说明 | |---|---| | `ControlPath` | 定位唯一权威;匹配 0 个/多个都是明确失败,不会猜 | | `Source` | 优先用哪个来源;Auto = UIA → MSAA → Win32 | | `ProcessName` / `WindowClass` / `WindowTitleKeyword` | 找顶层窗口的三件套,填了就必须都满足 | | `ValueKey` | 读什么(见第 9 层);留空 = 只定位不取值 | | `TimeoutSeconds` | 这条自己的等待秒数,0 = 用全局 `--timeout` | | `Disabled` | true = 停用(界面上是"启用"复选框的反面) | **旧字段**(只为让老文件还能读出来人工修):`UiaPath`、`MsaaPathKey`、`Win32Path`、`UiaPathFromInnerWindow`。 新保存不会再写这些,**旧路径格式也不会被执行**(不会静默变成别的东西)。 **不落盘的字段**:`RuntimeId`、`Value`、`FocusState`——它们只描述"此刻",写进长期配置会误导。 ### out.json(无界面读取的结果) `Summary`(Total / Found / Missing / ValueUnavailable / Skipped)+ `Windows[]`(当时的窗口清单)+ `Items[]` (每条:`found`、`resolvedSource`、`valueKey`、`value`、`valueAvailable`、`attributes`、`resolution`(逐步诊断)、`error`、`elapsedMs`)。 --- ## 第 9 层:取值键(valueKey)全表 跨来源键(三个来源都能选,内部各自映射): | 键 | 含义 | |---|---| | `文本内容` | 控件的内容文本(UIA:Value→Text→Name;MSAA:accValue→accName;Win32:窗口标题) | | `选中状态` | 是/否(列表行、列表项、树节点) | | `焦点状态` | 是/否(UIA HasKeyboardFocus / MSAA 状态位 / Win32 比前台窗口) | | `列表行数` `列表列数` `列表选中项数` | 容器列表/表格的规模与选中数(UIA) | | `选中行文本` | 当前选中那一行的文字(在列表容器上直接读) | | `OCR文本` | 截图 + 本地 OCR(需在设置里开启;结果会标注"来自截图识别") | UIA 专用:`Name` `AutomationId` `ControlType` `ClassName` `FrameworkId` `RuntimeId` `IsEnabled` `IsOffscreen` `BoundingRectangle` `Value` `Text` `IsSelected` `HasKeyboardFocus` MSAA 专用:`accName` `accValue` `accRole` `accState` `accDescription` `accDefaultAction` `PathKey` Win32 专用:`窗口标题` `类名` `HWND` `窗口矩形` `客户区矩形` `可见` `最小化` `进程名` `PID` > 键是**可手填**的:填了工具不认识的键,会报"该来源不支持的属性名",并列出可用键——不会静默返回空。 --- ## 第 10 层:常见任务怎么做 ### A. 把一个控件加进监控(30 秒) ```mermaid flowchart LR A["① 选窗口
窗口列表点一下"] --> B["② 选控件
拾取,或在控件树里点节点"] B --> C["③ 看下方 Path 横条
确认 XPath"] C --> D["④ 监控列表「添加当前控件」
valueKey 默认 文本内容"] D --> E["⑤ 点该行「定位到控件」
确认唯一命中 + 画框"] E --> F["⑥ 勾「启用」→ 点「保存」"] ``` ### B. 盯住"表格现在有几行 / 选中了哪行" 1. 选中列表**容器**节点(例如 `DataGrid[FixtureListView]`); 2. 添加控件后,把 `valueKey` 改成 `列表行数`(或 `列表选中项数`、`选中行文本`); 3. 要盯"具体某一行"就用行路径:`.../DataItem[@IsSelected='true']` + `文本内容`。 ### C. 让悬浮条只在某个页面出现 1. 设置 → 悬浮按钮 → 新建/选中一条 → 勾「启用」; 2. 填窗口条件(进程名/窗口类/标题,可下拉选择),或点「导入监控项 path」从已有监控项继承; 3. 在按钮表格里增加按钮(点击执行什么); 4. 点「检测显示条件」看诊断:它会把"卡在哪一步"说清楚; 5. 保存。之后只要条件满足就显示,被别的程序完全遮住或最小化时自动隐藏。 ### D. 无界面读取(给自动化/脚本用) ```mermaid flowchart TD A["pacs_win_uia.exe --read-saved"] --> B{"已有实例在运行?"} B -->|"在"| C["把请求转给它执行
(绝不另开一个实例同步写文件)"] B -->|"不在"| D["本进程执行"] C --> E["读 control-monitors.json"] D --> E E --> F["逐条:等窗口 → 定位 → 取值"] F --> G["写 out.json(或 stdout)"] G --> H{"退出码"} H -->|"0"| I["全部命中且取到值"] H -->|"1"| J["有未命中 / 取不到值"] H -->|"2"| K["参数或配置错误"] ``` 常用命令: ```bat pacs_win_uia.exe --read-saved :: 结果写到 exe 同目录 out.json pacs_win_uia.exe --read-config D:\cfg\monitors.json --output - :: 写 stdout pacs_win_uia.exe --read-config --timeout 3 --activate --ocr :: 停 3 秒等窗口;先激活无障碍;强制开 OCR pacs_win_uia.exe --help ``` ### E. 读不到东西时,按这个顺序查 ```mermaid flowchart TD A["先把窗口选对
(窗口列表里能搜到吗)"] --> B["看控件树有没有这个节点
(换来源 / 自动开无障碍 / 检查是否自绘)"] B --> C["看 Path 能不能唯一命中
(杂项 → 按 path 定位)"] C --> D["看 valueKey 是否合适
(内容在 Name 还是 Value/Text)"] ``` --- ## 附:三张补充图 ### 时序图:从按下"拾取控件"到拿到路径 ```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`(路径语法与常见问题)。