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

22 KiB
Raw Permalink Blame History

最小系统(一层层看懂这个工具)

读法:从第 0 层看起,每加一层只多一个概念,配一张图。看完 04 层,这个工具你就懂八成了; 58 层是界面与周边功能;最后几节是排错对照表和"读代码的顺序"。

图都用 Mermaid(文字转图)语法写:```mermaid 代码块里的文字就是图。

怎么看到图(任选一种):

  • VS Code / Rider:装 Markdown 预览的 Mermaid 插件(VS Code 用 "Markdown Preview Mermaid Support"),预览即可;
  • Typora / Obsidian:直接预览;
  • 不想装东西:把某个 ```mermaid 代码块的内容贴到 https://mermaid.live 左侧,右侧立刻出图;
  • 推送到 GitLab/GitHub 后,网页上会自动渲染。

想改图:直接改代码块里的文字,不用画图工具。


第 0 层:最小系统 = 一条四步链路

整个工具,剥掉所有界面和周边功能,只剩四步:

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 里的控件又没有独立窗口。所以第一步先锁定"哪一棵树"。

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 上的"控件信息"有三套互不相通的体系。工具同时用,按顺序取第一个有内容的:

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:

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 不是内容:

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 层:把上面四步变成"能长期用"

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 层:界面(三栏 + 两个浮层)

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(控件监控)

{
  "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 秒)

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. 无界面读取(给自动化/脚本用)

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["参数或配置错误"]

常用命令:

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. 读不到东西时,按这个顺序查

flowchart TD
    A["先把窗口选对<br/>(窗口列表里能搜到吗)"] --> B["看控件树有没有这个节点<br/>(换来源 / 自动开无障碍 / 检查是否自绘)"]
    B --> C["看 Path 能不能唯一命中<br/>(杂项 → 按 path 定位)"]
    C --> D["看 valueKey 是否合适<br/>(内容在 Name 还是 Value/Text)"]

附:三张补充图

时序图:从按下"拾取控件"到拿到路径

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 横条

状态图:悬浮条什么时候显示

stateDiagram-v2
    [*] --> 检查配置
    检查配置 --> 隐藏: 未启用 / 没有启用按钮
    检查配置 --> 找窗口: 有进程名或类名或标题
    找窗口 --> 隐藏: 没有匹配窗口 / 匹配到多个
    找窗口 --> 查XPath: 唯一命中(优先可见窗口,跳过最小化的同名窗口)
    查XPath --> 隐藏: 导入的 XPath 未唯一命中
    查XPath --> 查可见性: 命中
    查可见性 --> 显示: 锚定窗口未被别的程序完全遮住
    查可见性 --> 隐藏: 被别的程序完全遮住 / 最小化
    显示 --> 隐藏: 条件不再满足
    隐藏 --> 找窗口: 下一次节拍(默认 300ms)

注意:本工具自己的窗口不算遮挡——否则在设置页里根本测不了。


核心类关系(一页看完)

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(路径语法与常见问题)。