企业官网建设流程全解析

Skill Recorder如何在Windows上捕获屏幕事件？Koffi FFI与UI Automation实现完全指南

【免费下载链接】skill-recorderDesktop app that records your on-screen work session and uses the GitHub Copilot CLI to reconstruct it as an intent + ordered steps, then builds a reusable Skill or Automation for Microsoft Scout, Microsoft Copilot Cowork, or Copilot Studio.项目地址: https://gitcode.com/gh_mirrors/sk/skill-recorder

Skill Recorder 是一款跨平台（macOS + Windows）桌面应用，它在 Windows 上用Koffi FFI 直接调用 Win32 API捕获窗口切换与标题事件，用UI Automation读取浏览器地址栏 URL，再交给 GitHub Copilot CLI 重建为"意图 + 有序步骤"，最终生成可复用的 Skill 或 Automation（面向 Microsoft Scout、Copilot Cowork、Copilot Studio）。本文带你彻底看懂它在 Windows 上是如何捕获屏幕事件的，无需深入代码也能理解全貌。

Windows 上各数据源的捕获机制一览

Skill Recorder 的核心（录制控制器、事件总线、会话存储）是平台无关的，只有"从操作系统里取数据"这一层因平台而异。在 Windows 上，各事件源的工作方式如下：

📌 一个关键点：窗口标题在 Windows 上不需要任何系统权限（macOS 则需要辅助功能授权），这得益于 Koffi 直接走原生 Win32 API。

Koffi FFI：零权限捕获窗口事件

窗口切换和标题的捕获全部由 electron/collectors/windows-active-window.ts 完成。它通过 Koffi（koffi.load()，见 windows-active-window.ts#L14-L16）直接加载三个系统库：

• user32.dll——GetForegroundWindow（当前前台窗口）、GetWindowTextW（窗口标题）、GetWindow（遍历子窗口）等
• kernel32.dll——OpenProcess/QueryFullProcessImageNameW，把窗口还原到它的宿主进程，得到应用名
• dwmapi.dll——DwmGetWindowAttribute，获取窗口真实边界（含无边框扩展区域）

三个值得一提的工程细节：

1. 预编译 FFI，无需编译器。Koffi 自带win32-x64与win32-arm64的预编译 N-API 包，Windows 用户装完即用（依赖声明见 package.json）。
2. UWP 应用识别。Windows 现代应用（UWP）的前台窗口实际挂在applicationframehost.exe名下，windows-active-window.ts#L68-L75 会通过findUwpOwner()向下遍历子窗口，找到真正的宿主进程，再映射为友好名称（如 "Windows app"）。
3. 常见应用友好命名。chrome → Google Chrome、msedge → Microsoft Edge、code → Visual Studio Code等（windows-active-window.ts#L49-L59），让事件流对人和 AI 都可读。

UI Automation：读取浏览器地址栏 URL

浏览器 URL 是"标题之外最有价值的信号"。Windows 没有 macOS 那样的 AppleScript 脚本桥，所以 electron/collectors/windows-url-provider.ts 选择了另一条路——UI Automation（UIA）：

1. 托管进程：UIA 的 .NET 程序集（UIAutomationClient/UIAutomationTypes）只在 Windows PowerShell 5.1（每台 Win10/11 自带powershell.exe）里可靠可用。加载一次约需 0.5–1 秒，因此 Skill Recorder 启动一个常驻 PowerShell 托管进程，只加载一次 UIA，之后每收到一行 stdin 请求就返回一行结果（脚本见 windows-url-provider.ts#L56）。
2. 找地址栏：脚本从最前台窗口的 UIA 控件树出发，做广度优先遍历，寻找Edit控件且AutomationId为omnibox/addressEditBox/urlbar-input（或名称含 "address"）的控件，取其ValuePattern的值。
3. 防跑偏：遍历时剪掉Document子树（网页的可访问性树巨大且惰性加载），并设置节点数（600）与深度（8）上限，重页面也不会卡死。
4. 严格尽力而为：任何失败（超时 2 秒、无地址栏、权限怪异）都解析为null，绝不抛出、绝不阻塞轮询循环。

💡 与 macOS 相比，这个 UIA 方案还有个额外优势：连 Firefox 的地址栏也能读。另外，看起来像搜索词（含空格或无圆点）的值会被直接丢弃，避免把噪音当 URL 发射出去。

轮询节奏：事件流如何产生

采集由 electron/collectors/active-window.ts 中的ActiveWindowCollector驱动（构建逻辑见 electron/collectors/index.ts）：

• 基础轮询 1000ms；当最前台是浏览器时放慢到1600ms，避免高频读 URL 拖慢浏览器 UI
• 浏览器 URL 读取额外节流：至少间隔 1500ms，且仅在"应用切换 / 标题变化"时才触发
• 三类事件被发布到事件总线：
  • app.activate—— 最前台应用变化（含应用名、标题、窗口边界、进程信息）
  • app.title-change—— 同一应用内仅窗口标题变化
  • browser.url—— 活动标签页 URL 变化（含 host 字段）

这些事件最终写入会话的events.jsonl，是后续 AI 重建"意图 + 步骤"的核心原料。平台选择逻辑在 active-window.ts#L113-L120：Windows 走 Koffi 原生路径，macOS 走get-windows包。

自检：Doctor 信号与健康检查

打开录制 HUD，底部就有"doctor 行"（也可通过 IPC 调用doctor()）。在 Windows 上应确认两项：

• window tracking=koffi（而非provider missing）
• browser URLs=uia（当捕获级别包含 URL 时）

实操验证：一次冒烟测试

官方建议做一次真实录制来验证每个数据源都落到了events.jsonl（完整清单见 docs/windows-capture.md）。将捕获级别设为Full，然后：

1. 从 HUD 启动捕获（或Ctrl+Shift+R）
2. 应用切换/标题：在 Edge 和记事本之间 Alt-Tab，应看到app.activate与app.title-change事件
3. 浏览器 URL：在 Edge/Chrome 中访问两个站点，应看到browser.url事件；输入搜索词不应产生假事件
4. 剪贴板：复制一段文字，应看到clipboard.change事件
5. 视频：确认产物含video.webm、video-frames.json、快照与保留帧
6. 停止：会话在库中显示为recorded，分析应产出连贯的意图 + 有序步骤

⚠️ 某个数据源没产出时，先看 doctor 行，再看主进程日志里的一次性告警（如 "Browser URL capture is on but unavailable on this platform"）。

已知限制

来自官方文档 docs/windows-capture.md 的"Known limitations"：

• 浏览器 URL 是尽力而为的显示字符串，不是精确标签页 URL——对"按主机分段步骤"已够用
• 录制的终端仅限从录制浮窗打开的 PowerShell 会话（ConPTY），不监听已有的 PowerShell / Windows Terminal / cmd 窗口
• 语义级 UI 事件（焦点/调用/值变更，经由 UI Automation）在两个平台上都尚未实现
• Whisper 语音模型不随包分发，首次使用时需批准约 252MB 的一次性下载；录制与会话处理不等待它

延伸阅读：相关源码地图

一句话总结：窗口事件靠 Koffi FFI 直连 Win32，零权限零依赖；浏览器 URL 靠 UI Automation 走常驻 PowerShell 宿主，尽力而为、绝不阻塞——这两条腿，就是 Skill Recorder 在 Windows 上捕获屏幕事件的全部秘密。

【免费下载链接】skill-recorderDesktop app that records your on-screen work session and uses the GitHub Copilot CLI to reconstruct it as an intent + ordered steps, then builds a reusable Skill or Automation for Microsoft Scout, Microsoft Copilot Cowork, or Copilot Studio.项目地址: https://gitcode.com/gh_mirrors/sk/skill-recorder