Files
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

20 KiB

AI 开发提示词:PACS 医疗客户端监控与控件自动化工具

一、你的角色

你是一名资深 Windows 桌面开发工程师、Windows UI Automation 专家、医疗软件集成工程师和测试驱动开发工程师。

请为我设计并开发一套完整的 PACS 医疗客户端监控、窗口识别、控件拾取、列表读取、页面识别和截图工具。

我需要的是可以逐步编译、运行、测试和交付的真实项目,而不是概念方案、伪代码或仅供参考的示例。

开发过程中必须充分考虑 Windows 7、Windows 10、Windows 11 的兼容性,以及医疗客户端常见的传统控件、第三方控件、嵌入式浏览器、自绘控件和权限限制。

所有功能必须围绕实际可验证的 Windows API 和系统能力实现。对于技术上无法保证的功能,必须明确说明限制,并提供可行的替代方案,不允许虚构 API 或承诺不可能实现的能力。


二、项目核心目标

开发一个独立运行的 Windows 桌面工具,用于监控指定 PACS 客户端的窗口和控件。

工具应当允许用户:

  1. 使用十字拾取器快速选择屏幕上的任意窗口或控件。
  2. 查看被选中控件的完整属性、父子层级及可访问性信息。
  3. 监控指定列表控件,读取列表行、列、单元格和选中项。
  4. 尝试在目标列表的右键菜单中增加自定义读取入口;不支持时,通过本工具的悬浮操作按钮或独立控制面板执行读取。
  5. 针对特定页面建立读取规则,并在页面出现时自动执行。
  6. 对指定窗口进行截图,包括窗口正常显示、被遮挡和最小化时的截图能力评估与实现。
  7. 导出控件信息、读取结果、截图和诊断日志。
  8. 通过统一配置适配不同 PACS 软件和不同 Windows 版本。

本项目主要用于经过授权的医疗客户端监控和系统集成。默认只读,不得擅自修改患者信息、检查数据或医疗业务记录。


三、技术选型与兼容性原则

3.1 核心技术

首选以下技术:

  • 开发语言:C#。
  • 主运行环境:.NET Framework 4.8,明确验证 Windows 7 SP1、Windows 10、Windows 11 的实际部署条件。
  • 窗口识别:Windows 原生 Win32 API。
  • 控件识别:微软原生 UI Automation。
  • 控件操作:UI Automation Control Patterns。
  • 传统控件补充:Win32 API、Windows 消息、必要时 MSAA/IAccessible。
  • 图像处理:根据需要引入兼容的 OpenCV 版本。
  • OCR:作为可选扩展模块,支持中文界面文字识别。
  • 配置文件:JSON。
  • 日志:结构化文本日志,支持日志滚动和异常记录。
  • 自动化测试:使用与目标框架兼容的测试框架和独立测试项目。

不使用 FlaUI,不引入 FlaUI.UIA2 或 FlaUI.UIA3。

3.2 原生 UI Automation

通过系统程序集引用:

  • UIAutomationClient
  • UIAutomationTypes

核心命名空间:

  • System.Windows.Automation

重点使用:

  • AutomationElement
  • AutomationElement.FromHandle
  • TreeWalker
  • TreeScope
  • PropertyCondition
  • AutomationElement.FindAll
  • ValuePattern
  • TextPattern
  • InvokePattern
  • SelectionPattern
  • SelectionItemPattern
  • ExpandCollapsePattern
  • ScrollPattern
  • Automation.AddAutomationEventHandler
  • Automation.AddStructureChangedEventHandler

必须在实际开发时核实具体 API、事件、控件模式以及对应系统版本的支持情况。

3.3 Win32 API

按需使用:

  • EnumWindows
  • EnumChildWindows
  • FindWindow
  • FindWindowEx
  • GetWindowText
  • GetClassName
  • GetWindowThreadProcessId
  • IsWindowVisible
  • IsIconic
  • GetWindowRect
  • GetClientRect
  • GetWindowPlacement
  • GetForegroundWindow
  • GetAncestor
  • GetWindowLongPtr,按目标架构和系统版本进行兼容封装
  • SetWinEventHook
  • GetGUIThreadInfo
  • PrintWindow
  • SendMessageTimeout
  • RegisterWindowMessage
  • GetDpiForWindow 等版本相关 API 的能力检测与降级封装

对于 Windows 7 不存在的 API,必须使用版本检测、动态加载或兼容实现,禁止直接调用后导致程序在旧系统上启动失败。

3.4 架构原则

  1. 不允许依赖 FlaUI。
  2. UI Automation 与 Win32 API 必须分层封装。
  3. 业务逻辑不得直接散落大量 P/Invoke。
  4. 不得把 HWND、UIA 元素和图像识别结果混为同一种对象。
  5. 每个读取结果必须保留来源、时间、识别方式和可信状态。
  6. 所有操作都必须支持超时、异常捕获和取消。
  7. 不能保证读取成功时,应明确返回不支持或无法确认,不得伪造数据。
  8. 所有关键模块都必须提供可独立运行的测试。

四、功能一:十字拾取器

开发一个类似 Spy++、Inspect 工具的十字拾取器,用于快速识别 PACS 窗口和控件。

4.1 操作方式

主界面提供“拾取控件”按钮。

用户按下按钮后:

  1. 鼠标指针切换为十字准星。
  2. 实时显示当前指针下方的窗口和控件信息。
  3. 可以按住鼠标左键拖动十字准星。
  4. 松开鼠标后,确定当前目标。
  5. 支持按 Esc 取消。
  6. 支持拾取顶层窗口、子窗口和 UIA 元素。
  7. 支持拾取成功后自动高亮目标区域。

不得让拾取器自身的窗口被错误识别为目标。

4.2 实时信息

拾取过程中尽可能显示:

  • HWND。
  • PID。
  • 进程名。
  • 窗口标题。
  • 窗口类名。
  • 父窗口 HWND。
  • 顶层窗口 HWND。
  • 窗口矩形。
  • 客户区矩形。
  • 窗口是否可见。
  • 窗口是否最小化。
  • UIA Name。
  • AutomationId。
  • ControlType。
  • ClassName。
  • FrameworkId。
  • NativeWindowHandle。
  • IsEnabled。
  • IsOffscreen。
  • BoundingRectangle。
  • 支持的 Pattern。
  • UIA Provider 是否可正常访问。
  • 目标识别失败原因。

对于不能获得的属性,返回 null 或明确的错误状态。

4.3 拾取算法

请实现以下策略:

  1. 通过鼠标位置定位底层 HWND。
  2. 获取窗口层级和进程信息。
  3. 尝试从 UIA 的鼠标位置定位能力中获取 UIA 元素。
  4. 如果 UIA 不可用,则退回 Win32 窗口信息。
  5. 如果目标是无真实子窗口的自绘控件,应提示用户此目标可能需要图像识别。
  6. 不得把屏幕坐标对应的 HWND 直接认定为真实业务控件。

请分析并选择合适的 API,包括 WindowFromPoint、GetAncestor、AutomationElement.FromPoint 等。

4.4 高亮显示

高亮框必须:

  • 不遮挡目标控件。
  • 不获取鼠标输入。
  • 不抢夺目标窗口焦点。
  • 不影响目标应用操作。
  • 支持 DPI 缩放和多显示器。
  • 支持取消和自动消失。

高亮框优先采用透明、无激活的独立窗口。


五、功能二:列表控件监控和右键操作

这是项目重点功能。

需要能够对 PACS 工作列表、检查列表、患者列表、报告列表等控件进行识别、读取和监控。

5.1 列表识别

支持尽可能识别以下控件:

  • ListView。
  • DataGrid。
  • Table。
  • Tree。
  • ComboBox。
  • ListBox。
  • 第三方表格。
  • 自绘列表。
  • 嵌入式网页表格。

需要识别:

  • 列名。
  • 行数。
  • 列数。
  • 当前选中行。
  • 当前选中单元格。
  • 单元格文本。
  • 行标识。
  • 列标识。
  • 当前排序状态(如果可获得)。
  • 滚动状态。
  • 可见行与总行数。
  • 控件坐标。
  • 当前数据读取方式。
  • 数据是否完整。
  • 读取失败原因。

优先使用 UIA 的 GridPattern、TablePattern、SelectionPattern、SelectionItemPattern、TextPattern 等适用模式。

对于不支持上述 Pattern 的列表,依次尝试:

  1. UIA 子元素遍历。
  2. Win32 原生控件消息。
  3. MSAA/IAccessible。
  4. 经授权的应用官方接口。
  5. OCR 和图像分析。

不得假设所有表格都有 GridPattern。

不得把屏幕上可见的文字直接当作完整的数据源。

5.2 右键菜单集成

实现两种方案,并评估可行性。

方案 A:在目标 PACS 列表的右键菜单中添加“读取选中数据”。

方案 B:在本工具中提供独立的右键操作或悬浮按钮。

对于方案 A,必须先判断菜单属于哪种类型:

  • 原生 Win32 菜单。
  • UIA 暴露的菜单。
  • 目标程序自绘菜单。
  • 第三方框架菜单。
  • Web 页面上下文菜单。

只有在目标软件明确支持插件、扩展、菜单注册或其他合法扩展机制时,才优先采用原生菜单集成。

不得默认认为可以从外部进程安全地向任意 PACS 软件的内部右键菜单插入菜单项。

如果无法安全实现,应采用方案 B。

5.3 方案 B:独立读取按钮

主界面或浮动工具栏提供:

  • 读取选中行。
  • 读取当前单元格。
  • 读取整个列表。
  • 读取当前页面。
  • 导出 JSON。
  • 导出 CSV。
  • 复制读取结果。
  • 刷新控件信息。

用户在 PACS 列表上选中一行后,点击本工具按钮即可读取。

执行读取前必须确认:

  • 目标窗口 PID 与配置一致。
  • 目标控件身份仍然有效。
  • 当前选中项确实存在。
  • 控件未被销毁或替换。
  • 读取操作不会改变患者数据或检查数据。

5.4 右键事件监控

支持通过合适的 Windows 事件机制和应用内交互观察目标控件的操作状态。

必须区分:

  • 观察右键发生。
  • 获取右键位置。
  • 获取当前选中项。
  • 拦截右键事件。
  • 修改目标程序的右键菜单。

这些是不同的能力,不得混为一谈。

默认不全局拦截鼠标,不注入目标进程,不修改 PACS 内部代码。


六、功能三:特定页面读取

需要设计可配置的页面识别规则,针对指定 PACS 页面自动读取信息。

6.1 页面规则

每个页面可以配置:

  • 页面名称。
  • 目标进程名。
  • 主窗口标题关键词。
  • 主窗口类名。
  • HWND 识别规则。
  • 父窗口和子窗口关系。
  • 页面关键控件。
  • 必须存在的 UIA 元素。
  • 页面识别条件。
  • 读取任务列表。
  • 读取间隔。
  • 超时时间。
  • 触发事件。
  • 页面退出条件。

禁止仅依赖窗口标题判断页面身份,因为多个页面可能共享同一个标题。

6.2 页面识别方式

采用组合式识别:

  1. 进程和顶层窗口。
  2. 窗口标题和类名。
  3. UIA 控件树特征。
  4. 特征控件的 Name、AutomationId、ControlType。
  5. 页面内独特的文本或按钮。
  6. 必要时通过 OCR 辅助判断。

每个页面规则应有唯一 ID 和版本号。

6.3 触发方式

支持:

  • 手动读取。
  • 用户切换到目标页面时读取。
  • 窗口结构变化时读取。
  • 指定控件出现时读取。
  • 轮询检查页面状态。
  • 页面识别成功后执行一次读取。
  • 仅在页面数据发生变化时读取。

事件驱动优先,轮询作为补充。

需要防止事件重复触发、读取循环、线程阻塞、窗口销毁和控件失效。

6.4 输出格式

统一返回:

  • 页面规则 ID。
  • 目标窗口信息。
  • 页面识别结果。
  • 控件路径。
  • 字段名。
  • 字段值。
  • 读取方式。
  • 读取时间。
  • 数据可信状态。
  • 错误代码。
  • 错误说明。

不得默认把患者姓名、身份证号、检查结果等敏感数据写入普通调试日志。


七、功能四:指定窗口截图

需要支持对指定窗口截图,而不只是对整个屏幕截图。

7.1 基础功能

支持:

  1. 指定 HWND 截图。
  2. 指定进程的主窗口截图。
  3. 指定窗口客户区截图。
  4. 指定窗口完整区域截图。
  5. 指定子窗口截图。
  6. 定时截图。
  7. 页面识别成功后自动截图。
  8. 读取失败时自动保存诊断截图。
  9. 保存 PNG、JPEG。
  10. 截图与控件信息、日志关联。

截图记录应包含:

  • HWND。
  • PID。
  • 进程名。
  • 窗口标题。
  • 窗口状态。
  • 截图时间。
  • 截图方式。
  • 截图是否完整。
  • 失败原因。
  • 文件路径。

7.2 窗口显示时截图

请分别实现并比较:

  • PrintWindow。
  • BitBlt。
  • Graphics.CopyFromScreen。
  • Windows Graphics Capture(作为可选的高版本方案)。

根据目标窗口、系统版本和实际测试选择适用方式。

需要说明:

  • CopyFromScreen 截取的是屏幕可见内容,窗口被遮挡时会受影响。
  • PrintWindow 的效果取决于目标应用的绘制实现,不能保证对所有窗口有效。
  • 某些 DirectX、OpenGL、GPU 加速或特殊渲染界面可能产生黑屏、空白或不完整图像。

7.3 最小化窗口截图

必须把最小化截图作为独立测试项目。

不能简单声称 PrintWindow 可以对所有最小化窗口截图。

请设计如下流程:

  1. 检查目标窗口是否最小化。
  2. 尝试在不改变目标窗口状态的前提下执行可用截图方式。
  3. 验证截图是否有效,不能只判断 API 是否返回成功。
  4. 如果失败,记录失败原因。
  5. 尝试适用的替代方法。
  6. 只有在用户明确授权时,才允许临时恢复窗口。
  7. 如需恢复窗口,优先使用独立窗口状态快照,并尽可能恢复原来的最小化状态、前台窗口和焦点。
  8. 提示用户:恢复窗口可能造成屏幕闪动、改变前台状态,不能保证完全无感。
  9. 对 GPU 加速、自绘控件和视频区域,提供能力限制说明。

请特别分析以下几种情形:

  • 普通 Win32 窗口最小化。
  • WPF / WinForms 窗口最小化。
  • DirectX / OpenGL 渲染窗口最小化。
  • PACS 影像浏览器最小化。
  • 窗口被其他窗口遮挡但未最小化。
  • 窗口位于其他桌面或远程会话。

如果系统或目标应用不支持真正的最小化后台截图,必须明确返回“无法保证”,不能生成空白截图并当作成功。


八、监控引擎

设计一个独立监控服务,支持:

  • 多窗口监控。
  • 多个页面规则。
  • 多个列表控件。
  • 控件失效检测。
  • 页面进入和退出事件。
  • 定时任务。
  • 超时取消。
  • 读取任务队列。
  • 错误重试。
  • 运行状态查询。
  • 暂停和恢复。
  • 启动和停止。
  • 异常自动恢复。
  • 防止重复任务。
  • 资源释放。
  • 日志滚动。

每个监控任务必须具备独立的任务 ID。

不允许在 UIA 事件回调中执行耗时读取或截图操作;应把任务交给后台工作队列。

需要正确处理 UIA 元素在页面变化后失效的情况,必要时重新获取元素。


九、数据安全和权限要求

由于目标是 PACS 医疗客户端,必须遵守以下要求:

  1. 默认只读。
  2. 不自动修改患者信息。
  3. 不自动删除或提交医疗记录。
  4. 不绕过登录、访问控制或权限验证。
  5. 不擅自注入目标进程。
  6. 不修改目标程序内存。
  7. 不绕过软件授权。
  8. 日志默认不保存完整患者敏感信息。
  9. 截图应提供保存目录、保留期限和清理规则。
  10. 支持脱敏模式。
  11. 对导出数据记录操作来源和时间。
  12. 对可能改变业务状态的操作提供二次确认。
  13. 不应将真实患者数据上传到外部 OCR 或 AI 服务,除非经过明确授权和安全审查。

十、界面设计

主界面至少包括:

10.1 窗口列表

显示:

  • 窗口标题。
  • 进程名。
  • PID。
  • HWND。
  • 类名。
  • 可见状态。
  • 最小化状态。

支持刷新、搜索和手动绑定窗口。

10.2 控件检查器

显示:

  • 控件树。
  • 控件属性。
  • 父子关系。
  • 坐标。
  • 可访问性状态。
  • 支持的 Pattern。
  • 读取结果。
  • 错误信息。

支持十字拾取器定位并高亮控件。

10.3 列表读取器

支持:

  • 当前选中行读取。
  • 当前单元格读取。
  • 全部可访问行读取。
  • 列名读取。
  • JSON / CSV 导出。
  • 手动刷新。

10.4 页面规则管理

支持新增、编辑、删除、启用、禁用、测试页面规则。

10.5 截图管理

支持选择窗口、截图方式、定时截图、最小化截图测试、查看截图状态和打开保存目录。

10.6 监控日志

支持按任务、时间、窗口、错误类型筛选日志。


十一、兼容性策略

Windows 7

  • 必须针对 Windows 7 SP1 实机验证。
  • 检查 .NET Framework 4.8 的安装条件。
  • 禁止未经检测就直接调用新系统 API。
  • 对高版本 API 使用动态加载和功能降级。
  • 测试 UIA、Win32、MSAA 的实际能力。
  • 不得假设所有新式 UIA 功能均存在。

Windows 10

  • 测试不同 DPI 缩放。
  • 测试多显示器。
  • 测试管理员权限和普通权限。
  • 测试不同 PACS 客户端架构。
  • 测试窗口遮挡和最小化截图。

Windows 11

  • 测试现代桌面窗口。
  • 测试高 DPI。
  • 测试高权限窗口。
  • 测试 UIA 事件和控件失效。
  • 测试多显示器与远程桌面场景。

统一原则

同一份业务代码优先覆盖三个系统。

对不同系统的差异使用能力检测和适配层,而不是把整个项目复制成三个版本。


十二、测试驱动开发要求

必须采用分阶段 TDD。

每个模块按以下顺序开发:

  1. 编写需求和验收标准。
  2. 编写测试。
  3. 编写最小实现。
  4. 编译。
  5. 运行测试。
  6. 处理失败。
  7. 补充边界测试。
  8. 更新文档。
  9. 再开发下一模块。

必须提供:

  • 单元测试。
  • Windows 集成测试。
  • 目标客户端手工验收清单。
  • Win7、Win10、Win11 兼容性矩阵。
  • 异常恢复测试。
  • 性能测试。
  • 资源释放测试。

无法在当前开发环境验证的内容必须标记为“待目标系统实测”,不能伪造测试结果。


十三、验收标准

窗口识别

  • 能枚举符合权限范围的顶层窗口。
  • 能获取 HWND、PID、标题、类名。
  • 能筛选指定 PACS 进程。
  • 能定位目标窗口。
  • 能正确处理窗口销毁。

十字拾取器

  • 能拾取窗口。
  • 能尝试拾取 UIA 元素。
  • 能显示基本属性。
  • 能取消拾取。
  • 能高亮目标。
  • 不得将工具自身窗口错误识别为目标。

列表读取

  • 能识别目标列表。
  • 能读取实际可访问的行列数据。
  • 能读取当前选中项。
  • 能报告无法读取的控件。
  • 不得把不完整结果伪装成完整结果。

页面识别

  • 能根据配置识别指定页面。
  • 能避免重复触发。
  • 能在页面切换后重新绑定控件。
  • 能记录读取结果和错误。

截图

  • 能指定 HWND 截图。
  • 能截图客户区。
  • 能验证截图是否有效。
  • 能测试最小化窗口截图。
  • 不能实现的截图场景必须返回明确状态。

兼容性

  • Windows 7 SP1。
  • Windows 10。
  • Windows 11。

三个系统均需完成实际运行测试,不能仅凭编译成功就宣布兼容。


十四、AI 必须交付的内容

请按以下顺序输出:

  1. 完整技术方案。
  2. 系统架构图。
  3. 项目目录结构。
  4. 依赖清单及版本选择理由。
  5. Windows API 兼容性清单。
  6. 数据模型和接口定义。
  7. 第一阶段完整可编译代码。
  8. 单元测试和集成测试。
  9. 第二阶段完整代码。
  10. 后续阶段开发计划。
  11. 部署说明。
  12. Windows 7、Windows 10、Windows 11 测试清单。
  13. 已知限制和替代方案。
  14. 打包与发布方案。

每次只实现一个可编译、可验证的阶段。不要一次生成大量互相依赖、无法编译的代码。

如果输出内容过长,应按文件拆分,明确文件路径、完整代码和执行步骤。

不得用伪代码代替核心实现。不得省略关键依赖。不得假设目标 PACS 软件提供不存在的接口。

首先请完成:

第一阶段:项目基础架构 + 窗口枚举 + 十字拾取器 + UIA 控件属性检查 + 控件树导出。

要求给出完整项目代码、依赖配置、编译步骤、运行方式、测试用例和兼容性风险。完成后再继续列表读取、页面监控和截图功能。