Files
pacs_win_uia/TODO.md
T
zimoyin b4c736d58b 基线提交:三来源控件树/拾取 + 无界面读取 + 设置框架
在继续做界面收敛与监控引擎之前先固化当前可编译、可运行的状态,便于回退。

已完成:
- 控件树与拾取支持三种来源:UIA / MSAA(oleacc) / Win32(EnumChildWindows),可下拉切换与自动降级
- 列表读取:祖先链 + 向下查找 + 子元素遍历降级;区分「没找到」与「找到但取不到值」
- 无界面读取:--read-config / --read-saved,输出 JSON(含逐步 resolution 诊断)
- 监控列表:结构化定位字段(进程/窗口类/标题关键词/UIA 路径/MSAA PathKey/Win32 类名+序号)
- 设置框架:settings.json(随输出目录拷贝,不嵌入 exe)+ 设置界面 + 命令生命周期钩子 + 悬浮按钮
- 控制台日志、布局自检、控件树搜索、窗口列表前台高亮

已知未实现:OCR(仅配置占位)、截图、监控引擎(事件监听)。

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-12 14:33:49 +08:00

302 lines
35 KiB
Markdown
Raw 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.
# TODO
> 当前代码按阶段开发;未在目标 Windows/PACS 环境实测的能力不得标记为已完成。项目源码位于 `src/pacs_win_uia`,Rider 入口为根目录 `pacs_win_uia.sln`。
## 当前阶段:项目基础架构、窗口枚举、UIA 检查与控件树
- [x] 使用 MSBuild 完成 Debug 与 Release 的完整编译(当前环境已使用 `dotnet msbuild` 验证)
- [x] 将源码整理到 Rider 可见的 `src/pacs_win_uia` 目录,并更新 `pacs_win_uia.sln`
- [x] 添加基础应用程序清单,声明 Windows 7/10/11 兼容性与基础 DPI 感知策略(Per-Monitor DPI 仍需目标系统验证)
- [x] 补充 Windows 10/11 supportedOS 清单 GUID
- [x] 实现十字拾取器基础流程:Esc 取消、鼠标释放确认、工具自身窗口排除、非激活高亮
- [x] 拾取覆盖层改为点击穿透并使用 Win32 光标轮询,避免把覆盖层自身当作目标
- [x] 将十字拾取器的 Win32 坐标与 UIA `System.Windows.Point` 坐标统一(多显示器负坐标仍需实机验证)
- [x] 限制拾取预览为单个并发探测,并合并最新坐标,避免鼠标移动造成无限 UIA 任务堆积
- [x] 探测任务发生异常时观察并终止当前拾取确认重试,避免故障 Provider 无限重试
- [x] 拾取初次显示前同步标记原生覆盖层可见状态,避免初始 WindowFromPoint 自命中
- [x] 覆盖层首次显示使用 `SW_SHOWNOACTIVATE`,降低初始探测时的焦点变化
- [x] 鼠标释放确认前重新解析当前底层 HWND,避免静止光标下接受旧控件缓存
- [ ] 进一步验证覆盖层显示/隐藏与前台窗口交互,确保目标焦点不被改变
- [x] 成功拾取后清除旧高亮;无效目标不触发 `Picked`
- [x] 拾取异常/取消路径清理当前确认状态并关闭高亮
- [x] 释放确认前清空旧探测结果,必须取得当前坐标的新探测
- [x] 拾取确认不再在 UI 线程同步调用 UIA;当前坐标没有完成预览时明确返回未确认结果
- [ ] 验证十字拾取器不抢占目标焦点,并在 Windows 7/10/11 与高 DPI 多屏环境手工验收
- [ ] 记录并尽可能恢复拾取前的前台窗口/焦点;当前实现不保证完全无感恢复
- [x] 修复拾取覆盖层命中问题:覆盖层短暂隐藏解析底层 HWND,确认点击仍由覆盖层接收
- [x] 增加覆盖层 MouseDown/MouseUp 确认路径,降低极短鼠标点击被 40ms 轮询漏掉的概率
- [ ] 验证极短鼠标点击/极短 Esc 按键不会因 40ms 轮询而丢失
- [ ] 处理跨进程 UIA Provider 同步调用无法被强制终止的限制;必要时迁移到独立辅助进程
- [x] 使树读取任务在窗口切换时通过独立 CancellationTokenSource 发起取消(同步卡住的 Provider 仍可能无法立即退出)
- [x] 在窗口/控件切换和窗体关闭时使旧树读取结果失效
- [x] 拾取新目标时使旧窗口检查任务失效
- [x] 拾取新目标时重置控件树导出按钮和检查按钮状态
- [x] 释放确认使用同一屏幕坐标解析 HWND,避免 Cursor.Position 二次读取漂移
- [x] 树读取完成回调增加窗口句柄/序号和窗体句柄销毁保护
- [x] ControlType 属性读取加入逐项异常捕获
- [x] 深度限制下真实叶节点不再误标记为不完整
- [ ] 为 UIA 属性逐项错误、Pattern 枚举和控件树部分失败补充自动化测试
- [x] 减少每个控件重复 Pattern 探测:优先使用 `GetSupportedPatterns()`,仅在无结果时回退查询
- [ ] 清理快照中的长期 `AutomationElement` 引用;导出/显示模型应优先只保留可序列化快照
- [x] 列表读取前重新按 HWND/RuntimeId 绑定当前 UIA 元素,避免复用失效代理(先在降级抢救路径上按 HWND 重新绑定;常规路径仍复用拾取时的元素)
- [ ] 高亮框改为经过实机验证的跨进程点击穿透窗口
- [x] 拾取结果对 Win32/UIA 进程 ID 做一致性检查,拒绝跨进程目标拼接
- [x] 已知 HWND 的拾取使用该窗口 UIA 树内的坐标元素解析,减少同进程弹窗错配
- [x] 窗口内坐标拾取使用全局节点预算,避免递归分支重复消耗上限
- [x] 在窗口/控件切换时清理旧列表结果并使进行中的列表读取失效
- [ ] 在控件失效后按 HWND/RuntimeId 重新绑定 UIA 元素,而不是跨线程长期复用原代理
- [ ] 增加窗口枚举、模型、控件树限制和 JSON 导出的自动化测试
- [x] 修复窗口列表无选中项时清理旧树、旧元素和旧导出状态
- [x] 修复拾取按钮首次启动不可用问题
- [ ] 为窗口刷新改为后台快照或先做廉价可见性/PID 过滤,避免阻塞 WinForms UI
- [x] 窗口枚举使用明确结果对象,保留 EnumWindows 失败状态
- [ ] 增加独立的 Windows UIA 测试夹具(按钮、文本框、树和列表)
- [ ] 在 Windows 7 SP1、Windows 10、Windows 11 实机验证窗口枚举和 UIA 能力
- [ ] 验证普通权限访问高权限目标时的明确降级状态,不绕过 UIPI
- [x] 修正窗口样式辅助 API 的 64 位入口声明(实际调用仍需目标系统验证)
- [ ] 验证 32 位/64 位目标进程、100%/125%/150%/200% DPI、多显示器与 RDP 场景
- [ ] 为 JSON 导出增加敏感数据提示、脱敏策略和导出来源/时间记录
- [ ] 编写第一阶段用户操作手册和验收记录
## 第二阶段:列表控件读取
- [x] 设计统一列表读取结果模型(来源、时间、完整性、可信状态和错误)
- [x] 实现 UIA `GridPattern` 和 `TablePattern` 的只读单元格读取(`ListReaderService`)
- [x] 实现 `SelectionPattern` 的只读选中项读取基础版(选择-only 控件也会返回选中项结果)
- [x] 补充 ValuePattern/TextPattern/Name 的值来源状态,并区分“元素存在但未暴露值”与真实空字符串
- [x] 在主界面增加“读取选中控件列表”入口,并显示总行列、已读行/单元格、错误数和选中项数量
- [x] 列表单元格不再吞掉取消/超时异常;Value/Text/Name 读取失败会保留单元格错误状态
- [x] 失败单元格也保留 RowId/ColumnId,便于诊断和导出定位
- [x] 取消/超时返回时保留已经读取的行列,并在最终成功前再次检查软截止时间(同步 UIA Provider 调用仍只能软超时)
- [x] 保持 Grid/Table 读取的累积结果对象,使超时/取消结果保留已读取的来源、行数和单元格
- [x] 取消/超时异常在读取器入口使用累积结果处理,不丢失已读取行列
- [x] 行对象在首个单元格读取前加入结果,保留取消/超时时的当前行部分数据
- [x] 选中项读取失败后重新计算最终状态,避免 `Success` 与 `IsComplete=false` 矛盾
- [x] SelectionPattern Provider 异常降级为部分结果,不覆盖已读取的表格数据
- [x] 选中项结果增加 RowId 字段(当前优先使用 AutomationId,完整行映射仍需目标控件验证)
- [ ] 补充 SelectionItem 行/单元格映射和当前选中项模型
- [ ] 为 DataGridView 结果面板添加列名映射及单元格错误详情展开
- [x] 实现 UIA 子元素遍历降级并区分可见数据与完整数据(见「本轮修复」一节)
- [x] TablePattern 失效时尝试回退 GridPattern(Provider 行为仍需实测)
- [ ] 评估 Win32 ListView/ListBox/TreeView 消息读取
- [ ] 评估 MSAA/IAccessible 降级
- [ ] 支持读取列名、可见行、当前单元格和全部可访问行
- [ ] 为大表格增加单元格预算/分页策略,避免一次性物化过大的二维结果
- [x] 导出 CSV 时限制 provider 声明的异常大列数,避免生成超大空字段(当前上限 10000 列)
- [x] CSV 稀疏单元格按 ColumnIndex 计算列数,避免高索引列被静默丢弃
- [x] CSV 对公式样式值增加文本前缀,避免电子表格执行导出内容
- [x] CSV 导出补充逐行/逐单元格错误、ValueSource、选中项和读取时间等完整元数据
- [x] 添加独立列表 JSON/CSV 导出服务(`ListResultExporter`)
- [x] 在主界面接入列表 JSON/CSV 导出、用户确认和敏感数据提示
- [x] 导出格式以保存对话框 FilterIndex 为准,并自动规范化扩展名
- [ ] 输出列表 JSON 与 CSV 的脱敏版本,并记录导出来源/时间
- [x] 增加列表读取器的 UI 结果面板,显示已读取行和单元格状态
- [x] 读取结果面板显示不可用单元格的错误文本占位
- [x] 使用 DataTable 显示列表列名和单元格值,避免 DataGridView 直接绑定字典
- [x] DataTable 列数设置上限并处理重复列名,避免异常 Provider 导致 UI 崩溃
- [x] 新拾取开始时隐藏上一目标高亮
- [x] 切换窗口或控件时清空旧列表结果表格
- [x] 单元格 ValuePattern/TextPattern 访问的取消和超时异常继续向读取器传播
- [x] ValuePattern/TextPattern 普通 Provider 异常会回退到下一种只读值来源
- [ ] 增加结果面板的列名、错误详情和选中项专用视图
- [ ] 增加 PACS 真实列表手工验收,禁止把屏幕文字直接当作完整数据源
### 本轮修复(拾取隐藏、控件树、界面、监控列表、列表读取降级、日志)
- [x] 拾取时隐藏主界面,拾取完成后恢复并把前台窗口交还给原窗口(避免抢焦点)
- [x] 拾取完成后以被拾取元素为根自动读取并显示控件树,并切到「控件树」页
- [x] 窗口列表选中项变化后自动读取控件树(350ms 防抖 + 按 HWND 去重 + 单飞),保留「检查选中窗口」手动入口
- [x] 窗口列表加入分组分割线与搜索(标题 / 进程名 / PID),“有标题且可见”的窗口排在主要窗口组
- [x] 主界面按屏幕工作区自适应(工作区小于期望尺寸时最大化),右侧属性区放入横向滚动宿主
- [x] 右侧属性网格下方新增「控件监控列表」编辑器:控件Path、RuntimeId、所在页面特征、内容Key,可增删改并保存为 JSON
- [x] 控件监控定义校验规则集中到 `ControlMonitorRules`,一次返回全部问题;保存前会 `EndEdit` 并显示逐行错误
- [x] 控制台日志(`AppLog`):纯 GUI 启动时自建控制台窗口,终端/IDE 管道启动时复用现有标准输出,关闭控制台不会终止程序
- [x] 列表读取改为「被拾取元素 + 上级元素」候选链:先找 GridPattern/TablePattern,找不到再降级为子元素遍历
- [x] 候选链不会越过顶层窗口,并且绝不会探测或下钻桌面元素(否则会枚举全机器窗口)
- [x] 新增 `Notices`(降级提示与 `Errors` 分离)与 `TotalRowsKnown`(区分“逻辑总行数”和“当前已实现行数”)
- [x] 遍历降级按来源区分取值顺序:编辑类单元格优先 ValuePattern(其 Name 是标签而非内容),其余优先 Name
- [x] 跳过行头/表头/滚动条等非数据单元格,避免列错位;整行只有表头单元格时视为表头带而不是数据行
- [x] GridPattern/TablePattern 能读到行列但单元格全部失败时,改用子元素遍历抢救单元格值,并按 HWND 重新绑定元素
- [x] 连续 10 个单元格读取失败即停止继续调用(避免把已崩坏的 Provider 打爆),并明确提示“无法取值 ≠ 列表为空”
- [x] 新增**向下查找**:拾取到整个窗口/页面容器时(列表在被拾取元素内部),在被拾取元素内 BFS 最多 4 层、600 个节点寻找列表(含无 Pattern 的行容器遍历降级)
- [x] 所有 Pattern 搜索(向上 + 向下)都排在所有遍历降级之前:窗口的布局面板在形状上“也像行”,遍历若先跑就会返回假列表并挡住真正的 Grid/Table
- [x] 遍历结果里“读不到值的行”超过一半时判定为布局容器而不是列表,不再把窗口面板当成行
- [x] 列表读取未成功时自动打印被拾取元素及上级的结构诊断(ControlType/Class/框架/PID/支持的 Pattern/子元素),控件树只有根节点时也明确提示“该元素没有暴露任何 UIA 子元素”
- [x] 修复界面区域丢失:重构右侧时遗漏了中间栏,导致「控件树/列表结果」标签页从未加入窗体、界面上完全看不到。现为三栏:窗口列表 | 控件树/列表结果 | 属性 + 控件监控列表
- [x] 新增启动时布局自检:列出每个关键区域,任何一个没有被加入窗体都直接记为错误(避免"代码写了但界面没有"这类静默缺陷)
- [x] 控件树只有根节点时,400ms 后自动重试一次:Chromium/CEF/Electron/WebView2 的无障碍树是按需激活的,首次查询常常只返回根节点
- [ ] 以上向下查找、容器判定与无障碍激活重试仍需要在真实 PACS(OCS)上复测;OCS 窗口的 UIA 暴露情况见下
#### 第二轮现场反馈修复
- [x] 修复拾取器点左键后不关闭:UIA 探测挂住时拾取会永远停留。现在点击有 1.2 秒硬期限,超时按 **Win32 窗口信息**确认目标(该路径无 UIA 调用,不会挂),无论如何都会关闭覆盖层并恢复界面
- [x] 拾取看门狗不再清掉待确认的点击(此前会把用户已经按下的左键请求丢弃)
- [x] 拾取探测改到独立线程(`LongRunning`),卡死的 Provider 不再占用线程池
- [x] 拾取只拿到顶层窗口时(浏览器内核/套壳应用首次查询往往如此),600ms 后按同一坐标**自动重探一次**,拿到更深的元素就改用该元素
- [x] 列表遍历不再把"控件类元素"当容器:Button / Edit / Text / CheckBox / ComboBox / MenuItem / TabItem / Slider / ProgressBar / Header / ScrollBar 等一律跳过(这正是"向上第 1 级的 ControlType.Button"假结果的来源)
- [x] 遍历结果只有 1 行 1 列时判定为"不是列表",改为如实报告未找到(不再把单个控件的内容当成列表)
- [x] 结构诊断改为只要结果来自遍历降级或行列数 ≤1 就打印,不再只在 Unsupported/Failed 时打印
- [x] 主界面尺寸按屏幕比例自适应:小屏不超屏、大屏不再过小(本机 2560x1528 → 2048x1298,此前固定 1400x850)
- [x] 右侧新增「控件摘要」:类型 / 名称 / AutomationId / 类名 / 框架 / PID / HWND / 支持的模式 / **控件 Path**(Path 在后台线程生成,不阻塞界面)
- [x] 右侧分栏比例调整(属性网格 52% / 控件监控列表 48%),属性网格最小内容宽度从 460 降到 360,避免属性值被横向滚动条推到看不见的位置
- [x] 拾取后窗口列表按**顶层窗口 HWND** 同步选中(此前拾取到子窗口时列表没有对应行,所以看起来"没有同步")
#### 第三轮现场反馈修复(截图定位)
- [x] 修复「控件监控列表」只有 150x150:UserControl 加入面板时没有设置 `Dock=Fill`,一直是默认尺寸,所以列显示不全、"大小特别小"
- [x] 布局自检增加**尺寸检查**:列出每个区域的实际尺寸,小于预期就报错(只检查父级关系查不出"已加入窗体但仍是默认 150x150"这类问题)
- [x] 属性网格下方的说明栏(此前只重复属性名,被判为"毫无作用")改为显示**字段含义**:为 `UiaElementInfo` 逐属性补 `[Description]`,说明该字段是什么、为空意味着什么、以及排查时的注意点
- [x] UIA Pattern 名称规范化:`TransformPatternIdentifiers.Pattern` 这类原始名统一显示为 `TransformPattern`,并补充 Transform/ScrollItem/Toggle/RangeValue/MultipleView 到已知模式表
- [x] 监控列表列宽调整(控件Path 权重 50、RuntimeId 110、页面特征 35、内容Key 130),窄栏时 Path 不再被挤没
- [x] 本机验证:屏幕 2560x1528 → 主界面 2048x1298;窗口列表 474x1088、控件树 717x1102、属性网格 783x491、控件监控列表 783x535;布局自检"异常区域 0 个"
#### OCS 客户端的实测结论(截图 + 日志已确认)
- 目标窗口 `OCS - 浏览器列表` 的 `ClassName = Chrome_WidgetWin_1`、`FrameworkId = Win32`、`PID = 24368`,控件树**只有根节点**,`SupportedPatterns` 只有 `WindowPattern / TransformPattern`。即:这是 **Chromium/CEF 套壳应用,且没有开启无障碍支持**,UIA 完全看不到里面的渲染内容(拾取、控件树、列表读取都只能拿到窗口本身),400ms 激活重试也无效
- [ ] 用微软 `Inspect.exe` / Accessibility Insights 对同一个窗口做交叉验证:若它们同样只能看到窗口,则确认是目标程序未暴露,而不是本工具的问题
- [ ] 对这类客户端评估非 UIA 路线(Win32 消息 / OCR / 图像识别),并在 README 中明确标注该限制,不允许把"读不到"包装成"读到了空列表"
#### 第四轮:控件树与拾取改为三来源(UIA + MSAA + Win32)
- [x] 新增统一节点模型 `ControlTreeNode`(组合 `UiaElementInfo` / `MsaaNodeInfo` / `NativeWindowInfo`,每节点带来源标记)
- [x] 新增 **Win32 树**(`Win32TreeReader`):一次 `EnumChildWindows` 拿全部后代,按 `GA_PARENT` 重建层级,`GetWindowInfo` 一次拿窗口/客户区矩形与样式;标题走 `SendMessageTimeout(WM_GETTEXT, SMTO_ABORTIFHUNG)`,隐藏窗口不取标题;过滤 message-only 与 DWM cloaked 窗口
- [x] 新增 **MSAA 树**(`MsaaService` + `MsaaTreeReader`):用框架自带 `Accessibility.IAccessible`(不手写 vtable),`AccessibleObjectFromWindow(OBJID_CLIENT)` 失败回退 `OBJID_WINDOW`,`AccessibleChildren` 分批读取并按运行时类型分派"简单子 ID / 子对象",每个对象读完立即 `ReleaseComObject`
- [x] 工具条新增「控件树来源」下拉框(自动 / UIA / MSAA / Win32,默认自动)与「尝试激活目标无障碍」实验按钮(默认不自动启用)
- [x] 自动模式按 UIA → MSAA → Win32 取第一个**有内容**的来源(只有根节点视为没内容),并在状态栏说明实际用了哪个来源
- [x] 拾取改为三来源:Win32(`WindowFromPoint` + `ChildWindowFromPointEx` 逐级下钻,每级 `ScreenToClient`)→ UIA → MSAA;非 UIA 目标也能高亮(统一用 `Bounds`)
- [x] MSAA 拾取改为在**已下钻到的最深窗口上做 `accHitTest`**(实测:全局 `AccessibleObjectFromPoint` 只返回顶层窗口对象,而在 ListView 窗口上 `accHitTest` 直接返回"列表"角色与其真实矩形)
- [x] 窗口标题读取全部改为 `SendMessageTimeout`:`GetWindowText` 是跨进程 `WM_GETTEXT`,会让窗口刷新卡住
- [x] `UiAutomationService` 的私有 `TreeReadState` 抽成共享的 `ReadBudget`,三个读取器统一受"深度 / 节点数 / 截止时间 / 取消"约束
- [x] 本机自检(独立宿主进程)实测:UIA 56 节点、MSAA 167 节点(中文角色名)、Win32 7 个原生窗口且**包含 ListView 句柄**;自动模式正确选中 UIA;拾取下钻到 `WindowsForms10.SysListView32` 子窗口
- [ ] 在真实 PACS / OCS 上分别切三个来源复测;对 OCS 点一次「尝试激活目标无障碍」看 UIA 是否出现内容
#### 三来源的边界(必须同时写进文档与界面)
- 可靠:选定根窗口的**每个后代 HWND 都会出现在 Win32 树里**(HWND / 类名 / 窗口矩形 / 客户区矩形)
- 尽力而为:窗口标题(跨进程、UIPI 或目标无响应时为空)、以及任何控件内容(取决于目标是否提供 UIA / MSAA)
- 做不到:`asInvoker`(中完整性)读不到提权进程;GPU/自绘且无提供者的界面三来源都看不到;MSAA 对列表的保真度低于 UIA(`SysListView32` 行一般是简单子 ID,通常只有第一列文本)
- 三个来源是独立视图,**不保证互相对应**,跨进程一律不合并
- 本轮不改 DPI 感知(仍 system aware):混合 DPI 下 Win32 矩形与 UIA 矩形可能不一致,单屏不受影响;PerMonitorV2 需要单独一轮
#### 第五轮:拾取标记修复 + valueKey/value + 无界面读取(CLI/JSON)
- [x] **修复拾取标记不准**:UIA 只返回顶层窗口时,之前会用 UIA 元素的矩形覆盖高亮框,于是框住整个窗口。现在只在矩形**更小**时才替换(实测:在列表行上拾取,Bounds 从 860x560 的窗口变成 1266x285 的列表)
- [x] UIA 只拿到窗口本身时不再停止:继续在已下钻到的最深窗口上做 MSAA `accHitTest`;两者都没有时新增 `IsWindowOnlyPick`,状态栏明确写"只拾取到窗口(UIA/MSAA 都没有暴露内部控件),不要以为工具坏了"
- [x] 拾取下钻去掉 `CWP_SKIPTRANSPARENT`(DirectUIHWND 这类透明样式窗口正是内容宿主),并把下钻链(逐级 HWND)写进日志
- [x] 修复 MSAA 可能**重复释放同一个 COM 对象**(`accHitTest` 可能返回与根对象相同的实例,二次 `ReleaseComObject` 会导致访问违例)
- [x] `EnumChildWindows` 返回 0 个句柄不再误报为"失败",改为"该窗口没有子窗口"(OCS 就是这种情况)
- [x] 控件树不完整的占位原因 `DescendantIncomplete` 改为显示**第一个具体原因**(达到深度上限/节点上限/超时/取消/读取失败)
- [x] 监控列表新增 **valueKey / value 两列**:valueKey 为可编辑下拉框(按来源预置可用键,也允许手填),value 预填添加时的当前值
- [x] 监控列表新增「来源」列(自动/UIA/MSAA/Win32),并把定位详情(进程/窗口类/UIA 路径/MSAA PathKey/Win32 路径/RuntimeId)显示在下方说明栏,避免 7 列挤在一起
- [x] 「添加当前控件」按**当前节点来源**填充:定位字段 + valueKey 默认值 + value(UIA→Name,MSAA→accName,Win32→窗口标题);MSAA/Win32 拾取结果同样可以加入监控列表
- [x] 监控配置新增结构化定位字段(进程名/窗口类/标题关键词/UIA 路径段/MSAA PathKey/Win32 类名+序号/valueKey/value),**老文件仍可读**(全部为可空新增字段)
- [x] **枚举持久化为可读字符串**(`"Source": "Win32"`):DataContractJsonSerializer 默认把枚举写成数字,手写配置会因 `"Win32"` 解析失败而被判为无效文件(这个 bug 是被无界面模式当场发现的)
- [x] **新增无界面读取**:`pacs_win_uia.exe --read-config <配置> [--output <json>] [--timeout 10] [--activate] [--help]`,无参数时行为完全不变;退出码 0=全部命中 / 1=有未命中或取不到值 / 2=参数或配置错误
- [x] 无界面返回 JSON 含每条的:found / resolvedSource / valueKey / value / valueAvailable / attributes / **resolution 逐步诊断** / error / elapsedMs,以及本次可见窗口列表与汇总
- [x] 空路径 = "顶层窗口本身"(可监控窗口标题/类名/可见性);**回退来源只定位到窗口本身时不算命中**,避免把"没找到控件"报成成功
- [x] 实测(本机 Notepad,真实跨进程):窗口按 进程名+类名 匹配成功;`窗口标题` 取到 `*使用教程+常见问题.txt - Notepad`;UIA `ClassName` 取到 `Notepad`;Win32 路径解析到真实子窗口 `NotepadTextBox 0x1309EA`;故意写错的 UIA 路径如实报"第 1 段未匹配"并给出同级元素数量
- [ ] 用你真实的 PACS 配置跑一次 `--read-config`,确认定位字段与取到的值符合预期
#### 第六轮:用一个真实配置暴露出的定位问题(已修)
- [x] **根因**:保存 UIA 路径时,向上走的过程停在"任何一个带 HWND 的 Window 类型元素"上。UWP(设置/ApplicationFrameHost → `Windows.UI.Core.CoreWindow`)和 XAML 里都存在这类内层窗口元素,于是路径被记录成"相对于内层窗口",而回读时从顶层窗口开始找 → 第 1 段永远匹配不上(实测症状:`第 1 段(Group[...])未匹配:同类元素 0 个`)
- [x] **保存侧修正**:路径改为一律相对**根窗口**记录(`GetAncestor(GA_ROOT)`),经过内层窗口元素时记日志提示
- [x] **回读侧容错 1**:完整路径失败后,自动改用窗口内的内层窗口元素(带 HWND 的 Window 类型,BFS 限深 4/限 200 节点)作为起点重试
- [x] **回读侧容错 2**:仍失败时,允许**跳过最多 2 个开头段**,在整个窗口内搜索,且**必须唯一命中**才采用;采用时在 resolution 里明确写出"层级与保存时不同,建议重新添加该控件",绝不静默猜测
- [x] 实测(你自己保存的那条"设置 → 个性化"配置):`found=true`、`valueKey=Name`、`value="个性化"`、退出码 0,并给出跳过 1 段唯一命中的说明
- [x] 顺带确认 UWP 的一个事实:设置窗口的 `ApplicationFrameWindow` 属于 `ApplicationFrameHost`(PID 19448),而真正的内容 `Windows.UI.Core.CoreWindow` 属于**另一个进程**(设置自己,PID 21180),其子树是 XAML(`Custom[PermanentNavigationView]` 等)。窗口定位必须用**框架窗口**的进程名+类名(已如此处理),控件路径则由 UIA 跨进程自动接续
- [x] 控件树的"直接子元素"诊断输出补上 `HWND` 与 `Framework`,这类"内层窗口元素"问题下次一眼可见
- [ ] 在界面上**重新添加一次**该控件,让保存的路径变成相对根窗口的干净路径(旧路径虽然现在能容错命中,但会多一条提示)
#### 第七轮:控件树加载慢 / 只读到标题栏 / 无界面默认路径
- [x] **定位并修复路径少一层的 bug**:保存 UIA 路径时,向上走到"父级是根窗口"就 break,导致**根窗口的直接子元素没有被记录**——每条路径整体少一层。实测修复后:记事本文本框 → `Pane#0`、第二个 Pane → `Pane#1`,与窗口的真实子元素一致
- [x] **控件树读取提速**:改用 `CacheRequest`(一次性缓存全部属性与 Pattern)+ 每个父级一次 `FindAll(Children)` 批量取子元素,取代"每个节点一次属性往返 + 每个兄弟一次 GetNextSibling"。56 个节点的窗口:**372~547ms → 187~231ms**;`RuntimeId` 改为按需读取(省掉每节点一次跨进程调用,只在"添加当前控件"时取)
- [x] **"只读到标题栏"的真相**:UWP(设置/计算器)、CEF 套壳应用的内容树是**异步生成**的,窗口刚出现时确实只有边框。现在:① 只读到边框就等 700ms 重读一次(日志写明两次的节点数);② 仍只有边框时自动改读**内层内容窗口**(UWP `CoreWindow` / 浏览器渲染窗口);③ 还是只有边框时状态栏明确说明,而不是把 4 个按钮当成答案
- [x] 读取期间控件树显示 `正在读取控件树…(来源)` 占位节点,状态栏每 500ms 刷新"已 X.X 秒",不再让"空/只有边框"看起来像读完了
- [x] 实测:真实"设置"窗口现在一次读到 **114 个节点**(含 `Custom[PermanentNavigationView]` 等 XAML 内容)
- [x] **无界面默认路径**:新增 `--read-saved` = 读取界面保存的配置(`%LocalAppData%\pacs_win_uia\control-monitors.json`)并把结果写到 **exe 同目录的 out.json**(从 `bin\Debug` 运行即 `bin\Debug\out.json`);`--read-config` / `--output` 省略路径时也用同一套默认值;解析出的两个路径打印到 stderr,stdout 保持纯 JSON
- [x] 实测:`pacs_win_uia.exe --read-saved --timeout 3` → 读取你自己的那条配置,`found=true`、`value=个性化`、退出码 0
- [x] 回归:三来源控件树、拾取下钻、列表读取(三例均 5 行 × 3 列)、监控列表加载全部正常;Release 与 Debug 均已编译
#### 第八轮:区域标题 / 启用列 / 选中状态
- [x] 每个区域加**标题栏**(浅灰底、加粗 22px),不用再靠内容猜是什么:窗口列表 / 控件摘要 / 控件属性 / 控件监控列表;布局自检也纳入了这 4 个标题(实测各 22px、异常区域 0 个)
- [x] 监控列表新增**「启用」复选框**列:停用的条目保留在配置里但无界面模式会跳过它
- 持久化字段命名为 `Disabled` 且缺省省略,**老配置文件没有该字段 = 全部启用**(不会因为新增字段把已保存的监控全部停用)
- 点击复选框立即提交(`CurrentCellDirtyStateChanged` + `CommitEdit`),否则要等焦点离开才写回对象
- [x] `valueKey` 新增**「选中状态」**(跨来源键):
- UIA:`SelectionItemPattern.Current.IsSelected` → 是 / 否;该控件不支持该 Pattern 时明确报"无法判断是否被选中(列表行/列表项通常支持)"
- MSAA:读状态位 → 是 / 有焦点但未选中 / 否
- Win32:窗口本身没有选中概念,会明确报不支持
- 另有 UIA 专用键 `IsSelected`(true/false 原文)
- [x] 无界面 JSON 汇总新增 `Skipped`(停用跳过数),`Total` 改为"配置里的条目总数",于是 `命中 + 未定位 + 取不到值 + 跳过 = 总数`
- [x] 实测:停用条目被跳过(`Skipped=1`,报告里不含它);`选中状态` 对不支持的就是明确报错、对 MSAA 任务栏返回"否";`accRole` 返回"客户区"
#### 第九轮:界面收敛 + 监控项增强 + 设置框架
- [x] 去掉「控件摘要」区域(`ControlPathBuilder` 随之删除);每个区域的标题只剩必要信息(第 11 条:窗口列表标题不再带描述)
- [x] 「内容Key」在界面上一律显示为**别名**(JSON 字段名仍是 `ContentKey`,老配置可读)
- [x] **RuntimeId 不再为空**:树快照仍是按需读取(省每节点一次跨进程调用),但选中节点/拾取目标时会读一次再刷新属性网格
- [x] 监控列表列改为 `启用 | 控件Path | 别名 | 来源 | valueKey | 焦点 | 超时秒`:隐藏 value 列;**页面特征移到属性网格**可编辑(**留空 = 不校验页面特征**,校验规则同步放宽)
- [x] **点行头三角即定位**:新增 `定位到控件` 与 `刷新状态` 按钮,行头点击也触发;定位成功后在屏幕上画出与拾取器同一套**不抢焦点的高亮框**,并把该行「焦点」列填上
- [x] 「刷新状态」逐条定位并读焦点,**每条独立计时**,一条等不到不影响其他
- [x] 新增跨来源 valueKey **`焦点状态`**(UIA `HasKeyboardFocus` / MSAA `STATE_SYSTEM_FOCUSED` / Win32 比前台窗口),`HasKeyboardFocus` 纳入缓存不增加每节点调用
- [x] 监控项新增 `TimeoutSeconds`(0 = 用全局 `--timeout`);无界面读取优先用条目自己的超时,每条独立计时
- [x] 窗口列表:**前台窗口**(屏幕上最上方那个)浅黄底色 + 提示,最小化窗口灰字
- [x] 控件树搜索:默认一行(搜索框 / 仅显示匹配 / ▲▼ / 匹配 N 项 / 更多…),「更多」展开 名称·路径·AutomationId·类名·类型·仅焦点元素;过滤时保留祖先链,匹配项高亮,▲▼ 循环跳转
- [x] 「列表结果」不再看起来没用:标签页上方常驻说明栏,读不到时写明状态/来源/原因与三步建议(换来源 → 激活无障碍 → 该控件可能不暴露表格结构)
- [x] **窗口匹配分级降级**:进程名+类名+标题 → 进程名+类名 → 进程名+标题 → 仅进程名,并在 resolution 里写明命中级别与"建议重新添加"。原因:WinForms 窗口类名带版本哈希,**程序升级后类名会变**;标题关键词可能随内容(文件名/患者名)变化
- [x] **独立设置文件 `settings.json`**:exe 同目录、随编译拷到 Debug/Release(`None` + `PreserveNewest`,**不嵌入 exe**,工程内 0 个 `EmbeddedResource`);文件缺失自动生成默认值,文件损坏记日志并回退默认值(实测:故意写坏 JSON 仍能正常启动,"异常区域 0 个")
- [x] **设置界面**:关于(版本 + 如实写明能力边界 + 两个配置路径)/ 界面 / 悬浮按钮 / 命令 / OCR;保存后才写盘
- [x] **命令执行**(工具生命周期钩子):`启动执行` `结束执行` `on`(按间隔持续,可停)`once`(启动时一次);通过 `cmd.exe /c` 以当前用户身份运行,带超时、捕获 stdout/stderr、输出进控制台日志;界面可增删改、立即执行、启停
- [x] **悬浮按钮条**:置顶、不抢焦点(`ShowWithoutActivation` + `WS_EX_NOACTIVATE`)、可拖动、位置存设置;按钮可配置(读取选中控件列表 / 定位到控件 / 读取全部监控项 / 检查选中窗口 / 拾取控件)
- [ ] **OCR 本轮未实现**:设置里只有字段与横幅说明("本轮未实现,仅保存配置"),不假装能识别。实现需要引入引擎与中文语言包,并明确截图可能含患者信息、默认不上传外部服务
- [x] 回归:三来源控件树(UIA 56 / MSAA 167 / Win32 7,含 ListView 句柄)、拾取下钻、列表读取三例 5 行×3 列、布局自检 93 个控件"异常区域 0 个"、`--read-saved` 仍 found/取值(实测读到 `系统`,随设置页面变化)
#### 本轮暴露的限制(已实测,非推测)
- [ ] **WinForms `DataGridView` 的单元格值无法通过 UIA 读取**:`TablePattern` 能给出正确的行列数,但 `GetItem` 每次都抛 `E_UNEXPECTED`/`ElementNotAvailable`,随后该 HWND 的整个 UIA Provider 失效(连 `FromHandle` 都失败)。当前实现会如实报告 Partial + 明确提示,不会伪造数据。若要读取,需要评估 Win32 消息 / 跨进程读取方案(见下方待办)
- [ ] 遍历降级读到的行数只是“当前已实现的行”,虚拟化或滚动出视图的行读不到;UI 已显示为“未知(已读 N 行)”,仍需要在真实 PACS 上确认可接受
- [ ] 旧式 `SysListView32` 通过 MSAA 桥只暴露第一列文本时,子列可能只有 `Name`,需要在真实 PACS 列表上复核
- [ ] 列表读取期间仍可能被卡死的 Provider 占住后台线程;已改为独立线程(`LongRunning`,不占线程池)并限制并发读取数,但无法强制中断
- [ ] 用 `CacheRequest` 降低跨进程调用次数(当前每个元素仍是多次 `.Current.*` 查询),读大表时建议做
- [ ] 控件监控列表目前只做“定义与保存”,尚未接入页面识别与自动读取(属于第四/五阶段)
## 第三阶段:独立操作面板与右键能力评估
- [ ] 调查目标 PACS 是否提供官方插件、扩展或菜单注册机制
- [ ] 无合法扩展机制时禁止外部进程菜单注入,采用独立操作条
- [ ] 实现读取选中行、当前单元格、刷新、复制和导出操作
- [ ] 区分观察右键、获取右键位置、拦截右键和修改菜单
## 第四阶段:页面规则与自动读取
- [ ] 设计带唯一 ID 和版本号的 JSON 页面规则
- [ ] 组合进程、顶层窗口、标题关键词、类名、UIA 特征和关键控件识别
- [ ] 实现页面进入、退出、变化判断和事件防抖
- [ ] 控件失效后重新绑定,防止重复触发和读取循环
- [ ] 增加手动测试规则功能
## 第五阶段:监控引擎
- [ ] 实现多窗口、多页面规则和独立任务 ID
- [ ] 将 UIA 事件回调限制为投递后台任务,不在回调中执行耗时读取/截图
- [ ] 实现任务队列、超时取消、重试、暂停、恢复、启动、停止和状态查询
- [ ] 实现资源释放、异常恢复、日志滚动和敏感信息脱敏
## 第六阶段:截图
- [ ] 实现窗口完整区域、客户区和子窗口截图
- [ ] 对比 `PrintWindow`、`BitBlt`、`Graphics.CopyFromScreen`
- [ ] 独立测试最小化、遮挡、GPU、DirectX、OpenGL 和 PACS 影像区域
- [ ] 评估 Windows Graphics Capture 的高版本可选实现
- [ ] 未验证成功时返回“无法保证”,禁止将空白截图标记为成功
## 安全、部署与发布
- [ ] 默认只读,不注入目标进程、不修改内存、不绕过登录或授权
- [ ] 配置截图保存目录、保留期限、清理规则和脱敏模式
- [ ] 检查 .NET Framework 4.8 前置条件并制作安装包
- [ ] 代码签名、部署、卸载和 Windows 7/10/11 发布矩阵验证