diff --git a/docs/代码导览.md b/docs/代码导览.md index f2b21ce..a4a8f46 100644 --- a/docs/代码导览.md +++ b/docs/代码导览.md @@ -1,5 +1,7 @@ # 代码导览(接手必读) +> 想先"看懂整体"再看细节:先读 **[最小系统.md](最小系统.md)**——从一条四步链路开始,一层层加图讲清楚。 + > 目的:拿到这份代码的人,能在几分钟内知道**哪个功能在哪个文件**、**改动要动哪里**、**哪些地方有坑**。 > > 项目:.NET Framework 4.8 + WinForms,只读的 Windows UI 自动化检查/监控工具。 diff --git a/docs/最小系统.md b/docs/最小系统.md new file mode 100644 index 0000000..8f43f1f --- /dev/null +++ b/docs/最小系统.md @@ -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 代码块的内容贴到 左侧,右侧立刻出图; +> - 推送到 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`(路径语法与常见问题)。