DeskPilot

DeskPilot

Windows 桌面智能体框架 —— 零配置操控任意陌生桌面软件

GOAI 2026 「新智基座 | Agent Infra」赛道参赛作品

---

项目定位

DeskPilot（Desktop Pilot，桌面领航员）使 AI Agent 能够在 100ms~2s 内理解任意 Windows 窗口，零配置即开即用地操作陌生软件。通过 SoftwareProfile 驱动的五级阶梯路径推理与四 Agent 协同闭环，在确定性、速度、安全性和可复用性上全面领先纯视觉方案。

核心能力

能力	说明
零配置软件探查	无 Profile 时自动从软件 UIA 运行时提取菜单/快捷键/交互模式，生成结构化 SoftwareProfile
五级阶梯路径兜底	快捷键 > 菜单 > Alt 助记符 > 元素直点 > 常识快捷键，非视觉通道确定性优先
四 Agent 协同闭环	Manager(编排) → Operator(执行) → Inspector(探查) → Verifier(验证)，端到端任务闭环
渐进式并行感知	L0 截图(30ms) → L1 UIA(50ms) → L2 视觉盲区补全(≤800ms) → L3 LLM决策(2s)
金融级安全护栏	dry_run 只读 + need_confirm 审批 + JSONL 全量审计，经 PTrade 金融场景实战验证
经验沉淀层	成功路径跨任务回写 Profile，快捷键经验 + 视觉标定锚点，Agent 越用越聪明
弹窗检测与恢复	执行后主动检测模态弹窗，错误弹窗触发恢复重试（如文件名消毒）

产品形态

DeskPilot 提供三种使用方式，共享同一核心能力层：

┌─────────────────────────────────────────────────────┐
│                 产品形态（三入口）                     │
├──────────────┬──────────────────┬───────────────────┤
│   CLI/SDK    │  MCP Server      │  AgentTeams Skill │
│  deskpilot   │  18 工具 · stdio │  Skill 接口封装    │
│  run/inspect │  供 AI 助手调用   │  供 Worker 加载    │
├──────────────┴──────────────────┴───────────────────┤
│                   核心能力层                          │
│  窗口管理 · 感知引擎 · SoftwareProfile · 执行器       │
│  安全护栏 · 审计日志 · 经验沉淀 · 弹窗检测            │
└─────────────────────────────────────────────────────┘

安装

要求：Windows 10/11，Python >= 3.11，交互式桌面会话。

pip install uv
uv venv .venv --python 3.11
.venv\Scripts\activate
uv pip install -e ".[dev]"

可选依赖组：[orchestration]（LangGraph）、[mcp]（MCP Server）、[registry]（Registry HTTP 服务端）。

快速上手

# 环境自检（依赖 / UIA / 截图 / OmniParser / LLM / DPI / 权限）
deskpilot doctor

# 执行任务（黄金链路：目标识别 → Profile 检查/探查 → 推理 → 执行 → 验证 → 重试）
deskpilot run "在记事本中输入 Hello DeskPilot"

# 探查陌生软件生成 Profile
deskpilot inspect Notepad

# 查看已探查的 Profile
deskpilot list-profiles

# Bench Mini 评测（每任务 3 次运行多数投票）
deskpilot benchmark --suite mini --runs 3

# 启动 MCP Server（供 Claude 等 AI 助手经 MCP 协议调用，需 [mcp] 可选组）
deskpilot mcp-serve

AgentTeams Skill 入口见 skill/SKILL.md（脚本调用： python skill/scripts/deskpilot_skill.py --task "..."）。 完整使用手册（安装/四种产品形态/评测/日志位置/FAQ）： docs/11_使用手册.md

架构概览

用户交互层
├── CLI (typer + rich)
├── MCP Server (stdio, 18 tools)
└── AgentTeams Skill

多 Agent 协作层
├── ManagerAgent    ── 任务分解 / DAG 编排 / Profile 路由
├── OperatorAgent   ── 渐进感知 / Profile 路径推理 / 安全检查 / 执行
├── InspectorAgent  ── UIA 探查 / SoftwareProfile 生成
└── VerifierAgent   ── 多信号加权验证 / 结果判定

感知执行层
├── 感知引擎 (L0 截图 → L1 UIA → L2 OmniParser → L3 LLM)
├── 执行器 (键鼠 / 快捷键 / 菜单 / 剪贴板)
└── 弹窗检测与恢复

知识管理层
├── SoftwareProfile Store (本地 JSON)
├── Registry Server (GitHub-based 社区共享)
└── ExperienceLearner (成功路径回写 + 视觉标定)

测试

pytest tests/unit -q              # 单元测试（不依赖真实窗口）
pytest tests -q                   # 全量（含真实 Windows 窗口集成测试）
python scripts/check_contracts.py # 契约签名快照检查
ruff check deskpilot tests        # 代码风格

项目结构

deskpilot/
├── agents/          # 四 Agent 实现（Manager/Operator/Inspector/Verifier）
├── core/            # 弹窗检测、窗口管理
├── perception/      # 感知引擎（截图/UIA/OmniParser/视觉补全）
├── profile/         # SoftwareProfile（存储/探查/规划/学习/Registry）
├── safety/          # 安全护栏（风险分级/审批/审计/语义判定）
├── integrations/    # MCP Server / Registry Server / Skill 集成
├── llm/             # LLM 客户端（host_reuse / self_managed 双模式）
└── eval/            # 评测框架（Bench Mini / Judge / Recorder）

docs/                # 16 篇设计文档
tests/               # 742 测试用例（716 单元 + 26 集成）
scripts/             # 安全扫描 / 契约检查 / 对比实验
skill/               # AgentTeams Skill 封装
submission/          # GOAI 初赛提交材料

详见 docs/07_开发实施规划.md（文件级架构 / 依赖 DAG / 排期 / 测试方案）。

量化指标

指标	数值
Bench Mini 成功率	15/15 (100%)
Profile 加速	+13%
L0/L1 感知延迟	<100ms
测试用例	742 全绿
契约签名	191 条零漂移
MCP 工具	18 个（stdio 实测通过）
设计文档	16 篇

竞品对比

维度	DeskPilot	UFO³	Agent-S2	Cua / UI-TARS
零配置	✅ 运行时探查	❌ 手动 app.yaml	❌ 需截图标注	❌ 纯视觉
操作路径	五级阶梯兜底	菜单为主	视觉+点击	纯视觉
安全护栏	四层纵深+审计	❌	❌	❌
感知延迟	<100ms (L0/L1)	~200ms	~5s	5-10s
经验沉淀	✅ Profile 回写	❌	❌	❌

已知限制与降级说明

• Win11 记事本「另存为」对话框为 WinUI 弹层（PopupWindowSiteBridge），文件名框/保存键 UIA 与键盘均不可达，落盘无法自动化（已文档化，集成测试降级验证推进路径）
• OmniParser sidecar 未启用时 L2 视觉补全跳过（L0/L1 不受影响）
• 剪贴板通道（CLIPBOARD_WRITE）会临时占用全局剪贴板：默认写前备份、操作后恢复，可用 DESKPILOT_CLIPBOARD_RESTORE=false 关闭恢复
• 常识快捷键库与助记符链为启发式兜底（置信度低于 Profile 实测数据），误匹配时依赖重试策略切换备选路径
• L0 程序级通道适配器（CLI/文件导入导出/URL Protocol/CDP）与 Alt KeyTips OCR 探查为路线图项，当前版本未实现
• LLM 未配置时 L3 决策降级为规则决策，无法解析的任务优雅失败
• 第三方与模型权重许可声明见 NOTICE.md

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解开发环境搭建、代码规范、PR 流程。

安全相关问题请通过 jileilight@outlook.com 或 GitHub Security Advisory 报告，详见 SECURITY.md。

许可证

Apache 2.0（OmniParser icon_detect 权重为 AGPL-3.0，独立分发，见 NOTICE.md）