# 代码导览(接手必读) > 目的:拿到这份代码的人,能在几分钟内知道**哪个功能在哪个文件**、**改动要动哪里**、**哪些地方有坑**。 > > 项目:.NET Framework 4.8 + WinForms,只读的 Windows UI 自动化检查/监控工具。 > 解决方案:`pacs_win_uia.sln`(主工程 `src/pacs_win_uia`,测试夹具 `tests/uia-fixture`,回归测试 `tests/regression`)。 --- ## 一、一分钟建立全局印象 ``` Program.cs 进程入口 ├─ 无参数 → 单实例:第一个进程当 owner 并开 MainForm,后面的进程把请求转发给它 └─ --read-saved/-config → 无界面读取(也可以被转发到正在运行的 GUI 实例里执行) MainForm(UI/MainForm.cs) 三栏主界面:窗口列表 | 控件树/列表结果 | 属性 + 控件监控列表 ├─ 窗口列表 NativeWindowService(Win32 枚举) ├─ 控件树 ControlTreeService → UIA / MSAA / Win32 三个来源 ├─ 路径与定位 ControlPath(XPath)+ ControlLocatorService(回读) ├─ 控件监控列表 ControlMonitorEditorControl → ControlMonitorStore(JSON) ├─ 悬浮条 FloatingBarManager + FloatingToolbarForm └─ 拾取控件 CrosshairPicker + TargetProbeService + PickerOverlayForm ``` 数据流(最重要的一条): ``` 窗口(PID/类名/标题) → 控件树快照(ControlTreeNode) → XPath 路径(ControlPath) ↓ 监控项 JSON(只存稳定定位信息) ↓ 回读:重新读树 → XPath 求值 → 唯一命中 → 读值/画框 ``` **核心原则**(改代码前请先接受这四条,否则很容易改出"看起来能用但定位到错控件"的 bug): 1. **找不准就说找不到**。XPath 多处命中、树读取不完整、路径语法不对,一律明确报错,绝不"取第一个"。 2. **动态的东西不落盘**。RuntimeId、实时值、焦点状态、会变的 Name 都不写进长期配置。 3. **跨进程调用可能永久卡住**。任何 UIA/MSAA 调用都要有预算(`ReadBudget`)、独立线程和取消,不能占 UI 线程。 4. **只读**。不注入、不改目标、不点击目标控件(连拾取时的鼠标左键都用低级钩子吞掉)。 --- ## 二、"我要改 X,看哪个文件" | 我想改… | 主要文件 | 备注 | |---|---|---| | 主界面布局/按钮/三栏比例 | `UI/MainForm.cs` | 布局自检 `VerifyLayout()` 会报错,改动后看日志 | | 控件树怎么显示、要不要闪烁 | `UI/ControlTreeReconciler.cs` | 增量更新,绝不清空重建 | | 拾取为什么选到容器 | `Services/UiAutomationService.cs` 的 `FromHandleAtPoint` | 命中后向深处收敛 | | 拾取的蓝框/黄框(层级) | `Services/TargetProbeService.cs`(FillHierarchyFrames)+ `UI/PickHierarchyOverlayForm.cs` | 蓝=光标所在窗口,黄=向上遍历的控件链 | | 控件树读取来源与顺序 | `Services/ControlTreeService.cs` | Auto = UIA → MSAA → Win32 | | UIA 快照/缓存/Pattern | `Services/UiAutomationService.cs` | 统一 RawView + CacheRequest | | 列表读取(行列/单元格/降级) | `Services/ListReaderService.cs` | 最长的文件,见其顶部导览 | | 取值(Name/Value/Text/选中/焦点/OCR) | `Services/ControlValueReader.cs` | valueKey 的语义都在这里 | | Path(XPath)生成与求值 | `Services/ControlPath.cs` | **定位核心**,改这里影响全局 | | 保存路径时的字段与校验 | `Services/ControlLocatorBuilder.cs` | 与回读共用匹配逻辑 | | 回读定位(含窗口匹配) | `Services/ControlLocatorService.cs` | 唯一命中才返回 | | 监控项 JSON 读写 | `Services/ControlMonitorStore.cs` | 加载宽松、保存严格 | | 监控列表 UI/编辑/定位 | `UI/ControlMonitorEditorControl.cs` | Path 可 F2 编辑、双击多行编辑 | | 设置界面 | `UI/SettingsForm.cs` | 各页保存到 `AppSettings` | | 设置的默认值与兼容 | `Models/AppSettings.cs` | `Normalize()` 是兼容旧 JSON 的地方 | | 悬浮条的显示条件/跟随 | `Services/FloatingBarManager.cs` | 见下面"悬浮条规则" | | 悬浮条外观(自绘/透明) | `UI/FloatingToolbarForm.cs` | layered window,注意 GDI 释放 | | 遮挡/可见性判断 | `Services/WindowVisibility.cs` | 两个 API 用途不同,见文件头 | | 高亮框/跟随 | `Services/HighlightFollower.cs` | 跟随锚点窗口的相对偏移 | | 全部控件框绘制 / 侧边按钮与过滤 | `UI/NodeMapOverlayForm.cs` | 只在前台窗口且未遮挡处绘制;点框即选中控件树节点并刷新控件属性 | | 拾取器 | `Picker/CrosshairPicker.cs` + `UI/PickerOverlayForm.cs` | 不抢焦点、吞左键 | | 单实例/转发 | `Services/SingleInstanceService.cs` + `Program.cs` | Mutex + 命名管道 | | 无界面读取 | `Services/HeadlessConfigReader.cs` | 每条独立计时,统计口径在文件头 | | 截图 / OCR | `Services/ScreenshotService.cs`、`Services/OcrClient.cs` | OCR 默认关闭 | | 命令时机与退出清理 | `Services/CommandRunner.cs`、`Services/ProcessJob.cs` | 退出时结束整棵进程树 | | 日志 | `Diagnostics/AppLog.cs` | GUI 启动会自建控制台窗口 | --- ## 三、几条容易踩的坑(都是踩过的) - **不要在 UI 线程做 UIA/MSAA 调用**:Provider 挂住时界面直接冻结。后台线程 + `ReadBudget` + 序号丢弃旧结果。 - **不要用会变的显示文本做身份**:控件名可能随患者/文件/语言/计数变化。身份只用 AutomationId / ClassName / RuntimeId(运行期)/ HWND(Win32)。 - **不要清空重建控件树**:300ms 刷新时清空会闪烁并丢失选择/展开,用 `ControlTreeReconciler`。 - **不要"取第一个匹配"**:不确定就报错,让人重新拾取。 - **PropertyGrid 正在编辑时不要去 rebind**:会打断用户输入,`MainForm` 里有专门判断。 - **悬浮条的"名称"不是定位条件**:定位条件是进程名/窗口类/标题关键词 + 可选导入 XPath。 - **拾取到"容器"要往深处收敛**:提供者的命中测试经常先给容器(实测 Windows 11 记事本正文返回 `Pane[NotepadTextBox]`),拾取会在命中后往下找"包含光标的更深控件",并且只拿到容器时会在 600ms 后自动重探一次。改这块看 `UiAutomationService.FromHandleAtPoint` 与 `MainForm.ScheduleDeeperPickRetry`。 - **输入框/富文本的内容常常不在 `Name` 里**:WinForms 文本框的 `Name` 就是内容,但 WinForms 富文本、Chromium/CEF、UWP 文本框的 `Name` 可能是通用标题(例如 `RichEdit Control`),内容只在 `Value`/`Text` 模式里。取内容请用跨来源键 **`文本内容`**(顺序 Value → Text → Name,MSAA 侧 = accValue → accName,Win32 侧 = 窗口标题);新增/拾取控件时它已经是默认的 valueKey。 - **旧路径格式已停用**:`[Uia] A[id] > B:name`、`Type[id]` 之类不再执行,只保留给人工编辑修正。 - **本工具自己的窗口不算遮挡**:主界面/设置窗口压住目标不影响悬浮条显示(否则在设置页里根本测不了)。 - **bin\Debug 的 exe 被运行时锁定**:改完代码要编译时,先关掉正在运行的工具,或编译到别的输出目录。 --- ## 四、悬浮条显示规则(当前版本) 只有**同时**满足下面条件才会显示: 1. 悬浮条 `Enabled = true`,且至少有一个启用的按钮; 2. 窗口条件(进程名 / 窗口类 / 标题关键词)已填写的部分**全部**满足,且**唯一**匹配到一个窗口; - 匹配时**优先选可见窗口**,跳过 UWP 留下的最小化同名框架窗口; 3. 如果导入了监控项 XPath,该 XPath 在该窗口里**唯一命中**; 4. 勾选了"窗口可见且未被遮挡时才显示"时:锚定窗口存在、可见、未最小化,且**没有被别的程序完全遮住**(部分遮挡不影响;本工具自己的窗口一律忽略)。 检测结果显示"当前不显示"时,会说明卡在哪一步,并在被外部程序遮挡时点名是哪个窗口。 --- ## 四·三、空树自动开无障碍(浏览器/CEF/UWP) 读到**空树 / 只有窗口边框 / 里面有渲染窗口却没有子树**时,`ControlTreeService` 会自动请求目标开启无障碍(`AccessibilityActivationService`)并等 900ms 重读一次: - 目标确实开了:节点数变多,采用新结果,状态栏说明"重读后节点 N → M"; - 目标没暴露:如实说明"该目标没有向系统暴露无障碍树",不会假装读到了; - 同一窗口 60 秒内只自动激活一次; - 主程序里**只嵌了一块浏览器区域**(部分 DOM)同样适用:激活只影响那块渲染窗口,重读后它和原生控件一起出现在同一棵树里,**不会改写根窗口**; - 不想要工具动目标:设置 →「界面」里关掉"读到空树时自动请求目标开启无障碍"。 ## 四·五、配置文件位置(都在 exe 同目录) | 文件 | 用途 | |---|---| | `control-monitors.json` | 控件监控定义(界面「保存」写入) | | `settings.json` | 应用设置(界面、悬浮条、命令、OCR…) | | `out.json` | `--read-saved` 的默认输出 | 旧版本的 `control-monitors.json` 在 `%LocalAppData%\pacs_win_uia\`:**首次读取会自动复制到 exe 同目录**(原文件保留不动);如果 exe 目录不可写,则退化为直接读旧位置,保存时会明确报错。`--read-saved` 在没有新文件时也会用旧位置兜底。 ## 五、测试与验证 - 回归测试(纯内存,不需要目标程序): ``` dotnet msbuild tests\regression\RegressionTests.csproj -t:Build -p:Configuration=Debug -v:minimal tests\regression\bin\Debug\RegressionTests.exe ``` 想同时保留正在运行的工具实例时,加 `-p:OutputPath=<临时目录>\` 编译到别处再运行。 - 跨进程手工夹具:`tests\run-fixture.cmd`(见 `tests/README.md`)。 - **重要**:不要在本进程里用 UIA 读本工具自己的窗口,会原生崩溃。验证 UIA 逻辑必须用独立进程的夹具。 - 真机验收清单:控件树内容、拾取后树一致、列表读取行列、Path 往返(复制→按 path 定位)、 监控项保存后无界面 `--read-saved` 命中、悬浮条按条件显示/隐藏、遮挡/最小化行为。 --- ## 六、想要继续开发,建议的顺序 1. 先跑一次界面 + 回归测试,确认基线正常; 2. 改一个功能点,同时补一条回归用例(`tests/regression` 里新增 `Register` 项); 3. 涉及跨进程读取的改动,用独立夹具实测,不要只看编译通过; 4. 改完在 `TODO.md` 记录"已验证 / 未验证",未在真实 PACS 上测过的不要写成已完成。