Files
zimoyin 0e4bccf3f5 最小系统文档补到 10 层:配置文件字段、valueKey 全表、常见任务步骤
- 第 8 层:settings.json 各节字段、control-monitors.json 逐字段(含旧字段与
  不落盘字段的说明)、out.json 结果结构
- 第 9 层:valueKey 全表(跨来源键 + UIA/MSAA/Win32 各自键),并说明键可手填、
  填错会明确报错
- 第 10 层:五个常见任务的照做步骤(加控件 / 盯表格行 / 悬浮条条件 /
  无界面读取含退出码流程图 / 读不到的排查顺序)
- 时序图、状态图、类图移到文末「附:三张补充图」,0~10 层保持连续好读
- 共 13 张 Mermaid 图
2026-10-13 20:34:24 +08:00

487 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 最小系统(一层层看懂这个工具)
> 读法:从**第 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` |
---
## 第 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["① 选窗口<br/>窗口列表点一下"] --> B["② 选控件<br/>拾取,或在控件树里点节点"]
B --> C["③ 看下方 Path 横条<br/>确认 XPath"]
C --> D["④ 监控列表「添加当前控件」<br/>valueKey 默认 文本内容"]
D --> E["⑤ 点该行「定位到控件」<br/>确认唯一命中 + 画框"]
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["把请求转给它执行<br/>(绝不另开一个实例同步写文件)"]
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["先把窗口选对<br/>(窗口列表里能搜到吗)"] --> B["看控件树有没有这个节点<br/>(换来源 / 自动开无障碍 / 检查是否自绘)"]
B --> C["看 Path 能不能唯一命中<br/>(杂项 → 按 path 定位)"]
C --> D["看 valueKey 是否合适<br/>(内容在 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`(路径语法与常见问题)。