概述
Windows-Use 是一个强大的自动化代理系统，能够在 GUI 层面直接与 Windows 操作系统交互。该系统作为 AI 代理与 Windows OS 之间的桥梁，使 AI 代理能够执行打开应用程序、点击按钮、输入文本、执行 shell 命令、捕获 UI 状态等任务，而无需依赖传统的计算机视觉模型。Windows-Use 基于 ReAct（Reasoning and Acting）模式构建，通过观察-思考-行动的循环执行复杂任务，支持多种 LLM 提供商（Ollama、Google Gemini、Anthropic Claude、Mistral 等），使任何 LLM 都能执行计算机自动化任务，而无需依赖特定的专用模型。
核心概念和术语
ReAct 模式
ReAct（Reasoning and Acting）是一种结合推理和行动的 AI 代理模式。代理通过观察环境状态、进行推理思考、选择行动、执行行动、观察结果的循环过程完成任务。Windows-Use 实现了 ReAct 模式，代理在每个步骤中评估当前状态、思考下一步行动、执行工具调用、观察执行结果，直到任务完成或达到最大步数限制。
工具注册机制
Windows-Use 使用工具注册机制管理所有可用的操作工具。每个工具都是一个函数，通过 @Tool 装饰器注册，包含工具名称、参数模式和描述信息。工具注册表（Registry）负责工具的注册、查询和执行，提供统一的工具调用接口。这种设计使系统易于扩展，开发者可以轻松添加新的工具。
桌面状态捕获
桌面状态捕获是 Windows-Use 理解当前环境的核心机制。系统通过 Windows UI Automation API 遍历无障碍树，识别所有可见的交互元素（按钮、输入框、链接等）和可滚动元素，构建桌面状态的文本描述。系统可选择性地包含视觉截图，为支持视觉的 LLM 提供额外的上下文信息。状态捕获在每个行动步骤后执行，确保代理始终了解当前环境。
消息系统
Windows-Use 使用消息系统管理代理与 LLM 之间的通信。消息类型包括系统消息（SystemMessage）、人类消息（HumanMessage）、AI 消息（AIMessage）和图像消息（ImageMessage）。系统消息包含代理的指令和工具描述，人类消息包含观察结果和桌面状态，AI 消息包含代理的思考和行动，图像消息包含可选的视觉截图。消息系统支持多轮对话，维护完整的对话历史。
提示词模板系统
Windows-Use 使用模板系统生成提示词，将系统信息、工具描述、桌面状态等动态内容填充到模板中。提示词模板包括系统提示词、观察提示词、行动提示词、答案提示词等，每个模板都有特定的格式和内容要求。模板系统使提示词管理更加灵活，便于调整和优化。
内存工具
内存工具是 Windows-Use 提供的持久化存储机制，用于在任务执行过程中保存和检索信息。内存工具将信息存储为 Markdown 文件，保存在 .memories 目录中，支持创建、读取、更新、删除操作。内存工具使代理能够在复杂的多步骤操作中维护上下文，跟踪计划进度，积累知识，在未来的步骤中引用缓存的信息。
关键特性
不依赖计算机视觉
Windows-Use 不依赖传统的计算机视觉技术或特定的微调模型。系统通过 Windows UI Automation API 直接获取 UI 元素的结构化信息，包括元素类型、名称、位置、状态等。这种设计降低了系统复杂度，减少了设置时间，同时提高了准确性和可靠性。可选的视觉功能（截图）仅用于增强 AI 代理的理解能力，而非必需，使系统能够与任何 LLM 配合工作。
多 LLM 提供商支持
Windows-Use 支持多种 LLM 提供商，包括 Ollama（本地模型）、Google Gemini、Anthropic Claude、Mistral、OpenAI、Groq、Cerebras 等。系统通过统一的 BaseChatLLM 协议接口抽象不同提供商的差异，使代理能够无缝切换不同的 LLM。这种设计提供了灵活性，用户可以根据需求、成本和性能选择最适合的 LLM。
ReAct 推理循环
Windows-Use 实现了完整的 ReAct 推理循环，代理在每个步骤中评估当前状态、思考下一步行动、执行工具调用、观察执行结果。系统维护完整的对话历史，包括所有观察、思考和行动，使代理能够基于完整上下文做出决策。推理循环支持最大步数限制和连续失败重试机制，确保任务执行的稳定性和可控性。
丰富的工具集
Windows-Use 提供了丰富的工具集，覆盖桌面操作的主要场景。工具包括鼠标操作（点击、移动、拖拽）、键盘操作（输入文本、快捷键）、滚动操作、应用程序管理（启动、切换、调整大小）、Shell 命令执行、网页抓取、内存管理等。每个工具都有详细的描述和参数说明，帮助 LLM 正确理解和使用工具。
可选视觉支持
Windows-Use 支持可选的视觉模式，当启用时会在每个步骤中捕获桌面截图，并作为图像消息发送给支持视觉的 LLM。视觉模式为 LLM 提供了额外的上下文信息，有助于理解复杂的 UI 布局和视觉元素。系统支持截图缩放和标注，适应不同分辨率的屏幕和性能需求。
自动窗口最小化
Windows-Use 支持自动窗口最小化功能，在执行任务时自动最小化代理窗口，避免遮挡目标应用程序。这个功能通过上下文管理器实现，在任务执行期间自动最小化，任务完成后恢复窗口状态。自动最小化提高了用户体验，使代理能够更好地观察和操作目标应用程序。
遥测和监控
Windows-Use 集成了轻量级的隐私友好遥测系统，用于收集代理行为数据，帮助改进可靠性、调试失败、理解代理在真实环境中的行为。遥测数据包括查询内容、执行步数、成功/失败状态、使用的模型和提供商等信息。用户可以通过环境变量禁用遥测功能。
错误处理和重试
Windows-Use 实现了完善的错误处理机制，包括 LLM 调用失败重试、工具执行错误捕获、最大步数限制、连续失败检测等。系统在 LLM 调用失败时会自动重试，最多重试指定次数。工具执行错误会被捕获并返回给代理，代理可以根据错误信息调整策略。连续失败检测机制可以提前终止可能无法完成的任务。
架构设计
Windows-Use 采用分层架构设计，将功能划分为代理层、工具层、服务层和 LLM 层。代理层负责推理循环和任务协调，工具层提供具体的操作能力，服务层封装底层系统调用，LLM 层抽象不同提供商的差异。这种设计实现了关注点分离，提高了代码的可维护性和可扩展性。
设计原则
- 协议抽象：通过协议接口抽象不同 LLM 提供商的差异
- 工具化设计：将操作能力封装为工具，便于管理和扩展
- 模板化提示词：使用模板系统管理提示词，便于调整和优化
- 错误恢复：完善的错误处理和重试机制，提高系统稳定性
- 可观测性：集成遥测系统，支持监控和调试
关键设计决策
- 选择 ReAct 模式：结合推理和行动，适合复杂的 GUI 自动化任务
- 不依赖计算机视觉：降低复杂度，提高可靠性，支持任何 LLM
- 工具注册机制：统一管理工具，便于扩展和维护
- 消息系统：标准化通信格式，支持多轮对话和视觉输入
- 内存工具：支持跨任务持久化，提高复杂任务的处理能力
核心流程
代理执行流程
flowchart TD
启动代理["启动代理<br/>Agent.invoke()"] --> 初始化状态["初始化状态<br/>获取桌面状态"]
初始化状态 --> 构建系统提示["构建系统提示词<br/>包含工具描述和系统信息"]
构建系统提示 --> 构建观察提示["构建观察提示词<br/>包含桌面状态和用户查询"]
构建观察提示 --> 调用LLM["调用 LLM<br/>获取代理响应"]
调用LLM --> 解析响应["解析代理响应<br/>提取思考和行动"]
解析响应 --> 判断完成{"任务完成?"}
判断完成 -->|是| 返回答案["返回最终答案"]
判断完成 -->|否| 执行工具["执行工具调用<br/>Registry.execute()"]
执行工具 --> 获取结果["获取工具执行结果"]
获取结果 --> 更新状态["更新桌面状态<br/>重新捕获状态"]
更新状态 --> 构建新观察["构建新的观察提示词"]
构建新观察 --> 步数检查{"达到最大步数?"}
步数检查 -->|是| 返回错误["返回错误：达到最大步数"]
步数检查 -->|否| 调用LLM
返回答案 --> 记录遥测["记录遥测数据"]
返回错误 --> 记录遥测
记录遥测 --> 结束["结束"]
classDef init fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
classDef llm fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
classDef tool fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
classDef result fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
class 启动代理,初始化状态,构建系统提示,构建观察提示 init
class 调用LLM,解析响应 llm
class 执行工具,获取结果,更新状态,构建新观察 tool
class 判断完成,步数检查,返回答案,返回错误,记录遥测,结束 result
ReAct 推理循环
sequenceDiagram
participant Agent as Agent
participant LLM as LLM
participant Registry as Tool Registry
participant Desktop as Desktop Service
participant UI as Windows UI
Agent->>Desktop: 获取桌面状态
Desktop->>UI: 遍历 UI 树
UI-->>Desktop: 返回 UI 元素
Desktop-->>Agent: 返回桌面状态
Agent->>LLM: 发送消息（系统提示+观察）
LLM-->>Agent: 返回响应（思考+行动）
Agent->>Agent: 解析响应，提取行动
alt 任务完成
Agent->>Registry: 执行 Done Tool
Registry-->>Agent: 返回答案
else 继续执行
Agent->>Registry: 执行工具（如 Click Tool）
Registry->>Desktop: 调用桌面服务
Desktop->>UI: 执行操作（如点击）
UI-->>Desktop: 操作结果
Desktop-->>Registry: 返回结果
Registry-->>Agent: 返回工具结果
Agent->>Desktop: 获取新的桌面状态
Desktop-->>Agent: 返回新状态
Agent->>LLM: 发送消息（观察+结果）
LLM-->>Agent: 返回响应
end
工具执行流程
flowchart TD
调用工具["调用工具<br/>Registry.execute()"] --> 查找工具["查找工具<br/>根据工具名称"]
查找工具 --> 工具存在{"工具存在?"}
工具存在 -->|否| 返回错误["返回错误：工具不存在"]
工具存在 -->|是| 验证参数["验证参数<br/>使用 Pydantic 模型"]
验证参数 --> 参数有效{"参数有效?"}
参数有效 -->|否| 返回错误["返回错误：参数验证失败"]
参数有效 -->|是| 执行工具函数["执行工具函数<br/>传入 desktop 和参数"]
执行工具函数 --> 工具成功{"执行成功?"}
工具成功 -->|否| 捕获异常["捕获异常"]
工具成功 -->|是| 返回结果["返回成功结果<br/>ToolResult"]
捕获异常 --> 返回错误结果["返回错误结果<br/>ToolResult"]
classDef input fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
classDef validate fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
classDef execute fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
classDef result fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
class 调用工具,查找工具 input
class 工具存在,验证参数,参数有效 validate
class 执行工具函数,工具成功 execute
class 返回结果,捕获异常,返回错误结果,返回错误 result
LLM 调用流程
flowchart TD
准备消息["准备消息列表<br/>SystemMessage + HumanMessage + AIMessage"] --> 判断视觉模式{"use_vision=True?"}
判断视觉模式 -->|是| 添加图像["添加 ImageMessage<br/>包含截图"]
判断视觉模式 -->|否| 使用文本消息
添加图像 --> 调用LLM["调用 LLM.invoke()"]
使用文本消息 --> 调用LLM
调用LLM --> 调用成功{"调用成功?"}
调用成功 -->|否| 重试检查{"重试次数<最大值?"}
重试检查 -->|是| 重试调用["重试调用 LLM"]
重试检查 -->|否| 返回错误["返回错误：LLM 调用失败"]
重试调用 --> 调用LLM
调用成功 -->|是| 解析响应["解析响应<br/>ChatLLMResponse"]
解析响应 --> 提取数据["提取代理数据<br/>思考、评估、行动"]
提取数据 --> 返回数据["返回 AgentData"]
classDef prepare fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
classDef llm fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
classDef retry fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
classDef result fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
class 准备消息,判断视觉模式,添加图像,使用文本消息 prepare
class 调用LLM,调用成功 llm
class 重试检查,重试调用 retry
class 解析响应,提取数据,返回数据,返回错误 result
核心组件
Agent 类
Agent 类是 Windows-Use 的核心组件，负责协调整个代理系统的运行。Agent 类管理工具注册表、桌面服务、LLM 客户端、提示词生成器等组件，实现 ReAct 推理循环。
初始化流程
Agent 类在初始化时创建工具注册表，注册所有可用工具，初始化桌面服务、LLM 客户端、遥测服务等组件。Agent 支持自定义指令、浏览器选择、最大步数、视觉模式、自动最小化等配置选项。
执行流程
Agent 的 invoke 方法实现完整的任务执行流程。方法首先获取初始桌面状态，构建系统提示词和观察提示词，然后进入 ReAct 循环。在循环中，Agent 调用 LLM 获取响应，解析响应提取思考和行动，执行工具调用，观察结果，更新状态，直到任务完成或达到最大步数。
错误处理
Agent 实现了完善的错误处理机制，包括 LLM 调用失败重试、最大步数检查、连续失败检测等。系统在出现错误时会记录遥测数据，返回错误信息，确保任务执行的稳定性。
Tool Registry（工具注册表）
工具注册表负责管理所有可用工具，提供工具的注册、查询和执行功能。
工具注册
工具通过 @Tool 装饰器注册，装饰器接收工具名称和参数模式。工具函数包含工具的描述和实现逻辑，参数模式使用 Pydantic 模型定义，支持类型验证和文档生成。
工具查询
工具注册表提供 get_tools_prompt 方法，生成所有工具的提示词描述，包括工具名称、描述和参数模式。提示词用于构建系统提示词，帮助 LLM 理解可用工具。
工具执行
工具注册表提供 execute 方法，根据工具名称查找工具，验证参数，执行工具函数，返回执行结果。方法使用 Pydantic 模型验证参数，确保参数类型和格式正确。
Desktop Service（桌面服务）
桌面服务封装了与 Windows 操作系统交互的核心功能，包括状态捕获、应用管理、输入操作等。
状态捕获
桌面服务提供 get_state 方法，捕获当前桌面状态，包括活动应用、打开的应用列表、交互元素、可滚动元素等。方法支持可选的视觉模式，可以包含桌面截图。
应用管理
桌面服务提供应用启动、切换、调整大小等功能。应用启动通过 PowerShell 命令从开始菜单启动，使用模糊匹配查找目标应用。应用切换通过窗口句柄操作实现，支持最小化窗口的恢复。
输入操作
桌面服务封装了鼠标和键盘操作，包括点击、移动、拖拽、文本输入、快捷键等。操作使用 PyAutoGUI 和 UIAutomation 实现，提供统一的接口。
Shell 命令执行
桌面服务提供 PowerShell 命令执行能力，通过 Base64 编码传递命令，支持超时控制和错误处理。命令在工作目录（用户主目录）中执行，返回命令输出和状态码。
Prompt Service（提示词服务）
提示词服务负责生成各种提示词模板，将动态内容填充到模板中。
系统提示词
系统提示词包含代理的指令、工具描述、系统信息等。模板从 system.md 文件加载，填充系统信息（操作系统版本、默认语言、浏览器、用户信息等）和工具描述。
观察提示词
观察提示词包含当前桌面状态、工具执行结果、用户查询等。模板从 observation.md 文件加载，填充桌面状态信息（活动应用、交互元素、可滚动元素等）和工具结果。
行动提示词
行动提示词包含代理的思考和行动信息。模板从 action.md 文件加载，填充代理的评估、思考和行动参数。
答案提示词
答案提示词包含代理的最终答案。模板从 answer.md 文件加载，填充代理的评估、思考和最终答案。
LLM 抽象层
LLM 抽象层通过 BaseChatLLM 协议接口抽象不同 LLM 提供商的差异，使代理能够无缝切换不同的 LLM。
协议接口
BaseChatLLM 协议定义了 LLM 客户端必须实现的接口，包括 model_name、provider 属性和 invoke 方法。协议使用 Python 的 Protocol 类型，支持运行时检查。
LLM 实现
Windows-Use 提供了多个 LLM 实现，包括 ChatOllama、ChatGoogle、ChatAnthropic、ChatMistral、ChatOpenAI 等。每个实现封装了对应提供商的 SDK，实现统一的接口。
消息格式转换
不同 LLM 提供商使用不同的消息格式，LLM 实现负责将 Windows-Use 的消息格式转换为提供商要求的格式。例如，Anthropic Claude 使用特定的消息格式，Google Gemini 支持图像输入等。
Tree Service（UI 树服务）
UI 树服务负责构建和遍历 Windows 无障碍树，识别交互元素和可滚动元素。
UI 树遍历
UI 树服务通过 UIAutomation API 遍历 Windows 无障碍树，识别所有可见的 UI 元素。服务使用递归方式遍历树结构，支持浏览器 DOM 元素的特殊处理。
元素识别
UI 树服务识别可交互的 UI 元素和可滚动的 UI 元素。服务通过检查元素的控制类型、可见性、启用状态等属性判断元素是否可交互，通过检查 ScrollPattern 判断元素是否可滚动。
并行处理
UI 树服务使用线程池并行处理多个应用程序的 UI 树遍历，提高状态捕获效率。服务支持重试机制，处理遍历过程中的异常情况。
Telemetry Service（遥测服务）
遥测服务负责收集和发送代理行为数据，帮助改进系统可靠性和调试问题。
事件收集
遥测服务收集代理执行过程中的关键事件，包括查询内容、执行步数、成功/失败状态、使用的模型和提供商等信息。事件使用 Pydantic 模型定义，确保数据结构的一致性。
数据发送
遥测服务将收集的事件发送到 PostHog 服务，支持批量发送和异步处理。服务在代理执行完成或出现错误时发送事件，确保数据的及时性。
隐私保护
遥测服务支持通过环境变量禁用，用户可以设置 ANONYMIZED_TELEMETRY=false 禁用遥测功能。服务设计为隐私友好，不收集敏感信息。
Memory Tool（内存工具）
内存工具提供持久化存储机制，用于在任务执行过程中保存和检索信息。
文件存储
内存工具将信息存储为 Markdown 文件，保存在 .memories 目录中。文件使用相对路径或绝对路径指定，支持目录结构。
操作支持
内存工具支持创建、读取、更新、删除操作。创建操作创建新文件并写入内容，读取操作读取文件内容（支持行范围），更新操作支持替换和插入两种模式，删除操作删除文件。
跨任务持久化
内存工具使代理能够在复杂的多步骤操作中维护上下文，跟踪计划进度，积累知识。信息在任务之间持久化，可以在未来的步骤中引用。
缺点和局限性
平台限制
Windows-Use 仅支持 Windows 操作系统（Windows 7 到 Windows 11），无法在其他平台上运行。这限制了系统的适用范围，对于需要跨平台支持的场景，需要开发其他平台的实现。
语言依赖
某些功能（如应用启动）高度依赖 Windows 的默认语言。对于使用非英语语言的 Windows 系统，某些功能可能无法正常工作。这限制了系统在国际化场景下的使用。
性能限制
UI 树遍历和状态捕获是计算密集型操作，在处理大量应用程序和复杂 UI 结构时可能较慢。虽然系统使用并行处理优化性能，但在极端情况下仍可能出现延迟。视觉模式的截图和标注也会增加处理时间。
步数限制
Windows-Use 设置了最大步数限制（默认 25 步），防止代理陷入无限循环。对于复杂的任务，可能需要更多的步骤才能完成，步数限制可能导致任务无法完成。用户需要根据任务复杂度调整最大步数。
LLM 依赖
Windows-Use 完全依赖 LLM 的推理能力，LLM 的质量直接影响代理的性能。如果 LLM 无法正确理解工具描述、桌面状态或任务要求，代理可能无法完成任务或执行错误的操作。不同 LLM 的性能差异较大，需要选择合适的 LLM。
错误恢复能力
虽然系统实现了错误处理和重试机制，但在某些情况下，代理可能无法从错误中恢复。例如，如果代理执行了错误的操作导致应用程序状态异常，代理可能无法识别问题并恢复。系统缺乏主动的错误检测和恢复策略。
安全性考虑
Windows-Use 具有完整的系统访问权限，可以执行不可逆的操作。系统需要谨慎使用，避免在无法容忍风险的环境中部署。虽然提供了安全建议（使用虚拟机或 Windows Sandbox），但系统本身不提供沙箱或隔离层。
工具限制
某些工具的功能可能有限。例如，Type-Tool 设计用于输入文本，不适合在 IDE 中编程，因为它会将整个程序作为一个文本块输入。某些复杂的操作可能需要多个工具组合才能完成，增加了任务复杂度。
测试覆盖
由于 Windows GUI 自动化的复杂性，系统的测试覆盖可能不足。不同应用程序的 UI 结构差异很大，难以进行全面测试。某些边缘情况可能未被发现和处理。
文档和示例
虽然代码结构清晰，但文档和示例可能不够完善。新开发者可能需要花费较多时间理解架构和代码组织方式。某些高级功能的使用方法可能需要更多文档说明。
