1. 桌面窗口信息采集到底难在哪如果你写过 Windows 桌面工具大概率遇到过这种需求想知道鼠标当前位置下面是哪个窗口它的句柄是多少、类名是什么、标题写了什么最好还能顺手截一张缩略图出来。听起来像 Spy 的简化版真动手写的时候会发现坑不少。核心难点集中在三件事上。第一是坐标到窗口的映射屏幕坐标只是一个点要拿到这个点下面的窗口句柄得靠WindowFromPoint这类 Win32 API而且它返回的不一定是完整窗口控件、桌面本身也都是窗口层级关系需要你自己判断。第二是窗口元信息的读取标题和类名分别要用GetWindowText和GetClassName这两个函数对缓冲区长度、字符编码都有要求传错了就是空字符串或者乱码。第三是缩略图生成GetWindowRect拿到矩形区域后用Graphics.CopyFromScreen从屏幕复制像素窗口被遮挡、最小化、跨屏的时候结果会和你预期不一样。这套链路本身不复杂但如果你还想把它接到大模型或者远程服务上做二次处理就会多出一层麻烦每个模型、每个服务都要单独配一套 Key 和地址代码里散落着各种 endpoint改一个地方要翻好几个文件。我这次的做法是用 TaoToken 统一 Key 来收敛这部分配置把窗口采集的本地逻辑和模型调用的网络逻辑解耦开settings.json 里只维护一份凭证后面接对话、接编码 Agent 都不用再动。这篇文章会从窗口句柄、类名到缩略图把整条 API 调用链路拆开讲给出可以直接复制的配置骨架和验证步骤。适合正在做桌面自动化、窗口监控、或者想把本地采集结果喂给模型的开发者。下面先从统一 Key 的配置讲起再进入窗口采集的代码实战。2. 用 TaoToken 统一 Key 收敛配置在动手写窗口采集之前先把凭证这层理清楚。桌面采集程序往往不是孤立跑的采集到的窗口标题、类名、缩略图很多时候要送到模型侧做识别、分类或者摘要。如果每个模型单独配 Keysettings.json 会迅速膨胀而且一旦要换模型或者加新能力改动面很大。TaoToken 的思路是提供一个统一的入口你只需要维护一份 API Key就能访问它支持的各类模型能力。对桌面采集这种场景来说好处很直接本地代码只关心把窗口信息发出去不关心背后是哪个模型、走哪个地址。配置集中在一个文件里迁移和排障都省事。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意这个 API 地址后面不加任何 UTM 参数直接用它作为 base_url 就行。你需要先在控制台创建 Key入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建完在 API Keys 页面可以查看和管理地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后不要硬编码进源码统一放进 settings.json用环境变量或者配置文件读取。这里给一个 settings.json 的骨架字段命名尽量贴近常见 SDK 的习惯方便你直接映射到代码里的配置对象{ taotoken: { base_url: https://taotoken.net/api, api_key: sk-你的Key, default_model: claude-sonnet-4-5, timeout_seconds: 60, max_retries: 2 }, window_capture: { poll_interval_ms: 300, max_title_length: 260, max_class_length: 256, thumbnail_enabled: true } }base_url固定写https://taotoken.net/api不要带斜杠结尾也不要在后面拼 UTM。api_key建议从环境变量注入比如代码里读TAOTOKEN_API_KEY配置文件里留占位符。window_capture这一段是给窗口采集用的poll_interval_ms控制轮询频率标题和类名的缓冲区长度对应后面 API 调用的参数thumbnail_enabled决定是否生成缩略图。注意Key 属于敏感凭证不要提交到公开仓库。settings.json 可以加进 .gitignore团队协作时用一份 settings.example.json 做模板。配置这层做完后面窗口采集的代码就只管调用不用再操心凭证散落的问题。如果你后面要接模型对话做窗口内容理解可以直接用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 这个入口试跑如果是长期跑编码或 Agent 任务Coding Plan 页面在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3. 窗口枚举与缩略图的可复制配置这一节进入正题把窗口句柄、类名、标题、缩略图这条链路用代码串起来。我用 C# WinForms 举例因为 Win32 API 的 P/Invoke 在 .NET 里写起来最直观其他语言思路一样只是调用方式不同。3.1 导入 Win32 API先把需要的几个函数声明出来。WindowFromPoint根据坐标拿句柄GetWindowText和GetClassName读元信息GetWindowRect拿窗口矩形。注意GetClassName和GetWindowText的字符串参数要用StringBuilder配合MarshalAs否则拿不到内容。using System; using System.Drawing; using System.Runtime.InteropServices; using System.Text; public static class Win32Api { [DllImport(User32.dll, CallingConvention CallingConvention.StdCall)] public static extern IntPtr WindowFromPoint(int x, int y); [DllImport(User32.dll, CallingConvention CallingConvention.StdCall)] public static extern int GetClassName( IntPtr hwnd, [Out, MarshalAs(UnmanagedType.LPStr)] StringBuilder lpString, int nMaxCount); [DllImport(User32.dll, CallingConvention CallingConvention.StdCall)] public static extern int GetWindowText( IntPtr hwnd, [Out, MarshalAs(UnmanagedType.LPStr)] StringBuilder lpString, int nMaxCount); [DllImport(User32.dll)] public static extern bool GetWindowRect(IntPtr hwnd, out RECT lpRect); [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left; public int Top; public int Right; public int Bottom; } }这里有个容易踩的坑GetWindowText对某些窗口返回的是空字符串比如部分 UWP 窗口或者自绘控件它们的标题不在标准位置。遇到这种情况不要以为是代码写错了换GetWindowTextLength先探长度或者改用 UI Automation 接口补充。3.2 从坐标到窗口信息接下来封装一个方法输入屏幕坐标输出句柄、标题、类名和矩形。这样后面无论用 Timer 轮询还是鼠标钩子都只调这一个方法。public class WindowInfo { public IntPtr Handle { get; set; } public string Title { get; set; } public string ClassName { get; set; } public Win32Api.RECT Rect { get; set; } } public static WindowInfo CaptureAt(int x, int y, int maxTitle, int maxClass) { IntPtr hwnd Win32Api.WindowFromPoint(x, y); if (hwnd IntPtr.Zero) return null; var sbTitle new StringBuilder(maxTitle); var sbClass new StringBuilder(maxClass); Win32Api.GetWindowText(hwnd, sbTitle, maxTitle); Win32Api.GetClassName(hwnd, sbClass, maxClass); Win32Api.RECT rect; Win32Api.GetWindowRect(hwnd, out rect); return new WindowInfo { Handle hwnd, Title sbTitle.ToString(), ClassName sbClass.ToString(), Rect rect }; }maxTitle和maxClass就用 settings.json 里的 260 和 256和 Win32 的常见上限对齐。句柄用IntPtr存转字符串显示的时候用hwnd.ToString()十六进制格式更符合习惯可以写成0x hwnd.ToInt64().ToString(X)。3.3 生成窗口缩略图缩略图这块思路是先用GetWindowRect拿到窗口在屏幕上的矩形然后创建一个同尺寸的 Bitmap用Graphics.CopyFromScreen把屏幕对应区域复制进去。注意矩形宽高要取绝对值有些窗口的 right 可能小于 left。public static Bitmap CaptureThumbnail(Win32Api.RECT rect) { int width Math.Abs(rect.Right - rect.Left); int height Math.Abs(rect.Bottom - rect.Top); if (width 0 || height 0) return null; var bmp new Bitmap(width, height); using (var g Graphics.FromImage(bmp)) { g.CopyFromScreen( rect.Left, rect.Top, 0, 0, new Size(width, height), CopyPixelOperation.SourceCopy); } return bmp; }这里要提醒一句CopyFromScreen复制的是屏幕上当前显示的内容如果目标窗口被其他窗口遮挡截出来的就是遮挡后的画面不是窗口本身的完整内容。想要拿到窗口真实内容得用PrintWindow或者BitBlt配合窗口 DC复杂度会高一些。做监控类工具时遮挡问题要提前想清楚必要时把目标窗口置顶再截。3.4 用 Timer 驱动轮询鼠标移动事件在桌面级别不好挂用 Timer 定时轮询是更省事的做法。按 settings.json 里的 300 毫秒来既不会太频繁也能跟上鼠标移动的节奏。private System.Windows.Forms.Timer _timer; private void InitTimer(int intervalMs) { _timer new System.Windows.Forms.Timer(); _timer.Interval intervalMs; _timer.Tick OnTick; } private void OnTick(object sender, EventArgs e) { var pos Cursor.Position; var info CaptureAt(pos.X, pos.Y, 260, 256); if (info null) return; lblHandle.Text 0x info.Handle.ToInt64().ToString(X); lblTitle.Text info.Title; lblClass.Text info.ClassName; var thumb CaptureThumbnail(info.Rect); if (thumb ! null) { pictureBox1.Image?.Dispose(); pictureBox1.Image thumb; } }启动和停止就控制_timer.Start()和_timer.Stop()。跑起来之后鼠标在屏幕上移动界面上的句柄、标题、类名和缩略图会实时刷新。实测下来300 毫秒的间隔在普通机器上 CPU 占用很低缩略图刷新也跟得上。4. 验证请求与成功结果代码写完怎么确认整条链路是通的分两步验证先验证窗口采集本身再验证和 TaoToken 的连通性。4.1 验证窗口采集启动程序后把鼠标依次移到几个不同类型的窗口上观察输出是否符合预期。可以对照下面这张表检查鼠标位置预期句柄预期类名预期标题桌面空白处非零Progman 或 WorkerW空或Program Manager记事本编辑区非零Edit空记事本标题栏非零Notepad文件名浏览器内容区非零Chrome_WidgetWin_1 或类似页面标题如果句柄一直是 0检查WindowFromPoint的坐标是不是屏幕坐标别传成窗口相对坐标。如果类名或标题是乱码检查StringBuilder的容量和MarshalAs的字符集设置。如果缩略图是黑屏多半是窗口被遮挡或者最小化了。4.2 验证 TaoToken 连通性窗口采集跑通后验证一下统一 Key 能不能正常调用。用 curl 发一个最小请求确认 base_url 和 Key 都生效curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }如果返回里能看到正常的文本内容说明 Key 和地址都没问题。这一步单独验证很有必要因为窗口采集和模型调用是两条独立的链路混在一起排障会很痛苦。想先在网页上试跑模型可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节看 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。4.3 把窗口信息送出去连通性确认后就可以把采集到的窗口信息组装成请求体发出去。比如把标题和类名拼成一段文本让模型判断这是什么类型的窗口string prompt $窗口标题{info.Title}\n窗口类名{info.ClassName}\n请判断这是什么类型的应用窗口。;请求体结构和上面 curl 一致把 prompt 放进 messages 的 content 里就行。缩略图如果要一起送转成 base64 放进多模态消息注意控制图片尺寸别把整屏原图直接塞进去。5. 本篇常见错排查窗口采集这条链路报错往往集中在几个固定位置。下面按现象整理方便你对照排查。句柄为 0 或一直不变。最常见的原因是坐标传错。WindowFromPoint要的是屏幕绝对坐标如果你从某个控件的 MouseMove 事件里拿e.X、e.Y那是控件相对坐标得用PointToScreen转换。另一个原因是 Timer 没启动或者 Tick 事件没绑定。标题或类名是空字符串。先确认缓冲区长度够不够260 和 256 是常见值但个别窗口标题很长可以适当加大。再确认StringBuilder是不是每次 Tick 都新建的复用同一个实例可能残留旧内容。如果某些窗口始终读不到标题那是窗口本身不通过标准接口暴露属于正常现象。缩略图黑屏或错位。黑屏通常是窗口被遮挡或最小化CopyFromScreen只能复制屏幕上可见的像素。错位一般是GetWindowRect返回的矩形包含了窗口阴影或边框和实际内容区有偏差可以改用DwmGetWindowAttribute拿扩展边框。跨屏或者高 DPI 场景下坐标缩放也要注意程序清单里声明 DPI 感知能减少这类问题。调用 TaoToken 返回 401 或 403。先检查 Key 有没有正确读取环境变量名和代码里读的是不是一致。再确认请求头字段Anthropic 风格用x-api-keyOpenAI 风格用Authorization: Bearer别混用。base_url 确认是https://taotoken.net/api不要多加路径或者拼错。请求超时。网络抖动或者模型响应慢都可能超时settings.json 里的timeout_seconds设成 60 比较稳妥max_retries给 2 次重试。如果持续超时先用 curl 单独测一下排除是代码问题还是网络问题。缩略图内存泄漏。Bitmap和Graphics都是非托管资源每次 Tick 新建的 Bitmap 如果不 Dispose跑久了内存会涨。上面代码里用了pictureBox1.Image?.Dispose()先释放旧的再赋新值这个顺序别写反。6. 把采集链路接到你的工作流里窗口信息采集本身是个很实用的能力但它的价值往往不在采集本身而在于采集之后怎么用。你可以把句柄和类名做成窗口切换器的索引把缩略图做成任务栏预览的替代品也可以把标题和类名送给模型做自动分类、敏感信息识别或者操作日志摘要。我自己的做法是把 settings.json 作为唯一的配置入口窗口采集参数和 TaoToken 凭证都放里面代码里只读配置不写死。这样换机器、换 Key、调轮询频率都只改一个文件。如果你后面要接长期跑的编码或 Agent 任务Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要管理多个 Key 的时候去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。有一个细节值得单独说轮询间隔不要设得太小。300 毫秒是个比较舒服的值再小会让缩略图刷新过于频繁CPU 和内存都吃不消。如果只是做窗口切换检测不需要缩略图间隔可以放到 500 毫秒甚至 1 秒。采集频率和资源占用之间要自己权衡别一上来就追求实时。最后提醒一句采集窗口信息涉及用户桌面内容做工具给自己用没问题如果要分发或者上生产隐私和权限这块要提前考虑清楚别把采集到的标题、缩略图随手传到不该传的地方。
