AI Process Manager (AIPM)

AI Process Manager — MCP 服务

为 AI Agent 提供结构化的 Windows 状态信息——无需截图。

此 MCP 服务将 AI Process Manager 本地 HTTP API 封装为工具，供 Claude Desktop、Cursor 和任何 MCP 客户端使用。Agent 无需捕获像素（每张 1080p 截图约需 2,765 个 token），而是从进程、窗口、控制台和 UI Automation 树中读取JSON 和文本（每次查询约需 15–150 个 token）。

要求： Windows 上正在运行 AIProcessManager.exe（系统托盘中）。Node.js ≥ 14。无需 npm 依赖。

为什么要做这个

计算机操作 Agent 常通过截图来“查看”桌面。这种方式速度慢（3–5 秒）、消耗 token 多，还会将像素数据发送给模型。AIPM 可通过 loopback 回答结构化问题：

问题	截图	AIPM 工具
渲染仍在运行吗？	约 2,765 个 token	check_process → 约 15 个 token
控制台输出是什么？	截图 + OCR	read_window → 约 30 个 token
导出完成了吗？	轮询 + 截图	wait_for(file_stable=...) → 一次调用

与截图相比，每次操作的感知 token 减少约 94–98%（每次查询从 2,765 个降至约 60 个 token；这两个输入来自 GET /analytics/summary 的 assumptions 块，并非基准测试数据）。

快速开始

1. 启动后端

确保 AIProcessManager.exe 正在系统托盘中运行。

2. 配置 MCP 客户端

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "ai-process-manager": {
      "command": "node",
      "args": ["C:\\path\\to\\ai-process-manager\\mcp\\server.js"]
    }
  }
}

Cursor 和其他使用 stdio 的 MCP 客户端也采用相同的 command / args 配置。可选环境变量 AIPM_API 可覆盖 API 基础 URL（默认：从 %LOCALAPPDATA%\AIProcessManager\endpoint.txt 读取，否则使用 http://127.0.0.1:9147）。

可选环境变量 AIPM_AGENT_NAME 用于在 API 的活动日志中标识此 Agent（默认为 mcp）。 每个请求都会携带 User-Agent: AIPM-Agent/<name> (<client>) mcp:<client>，API 会将 <name> 提取到 /audit、/activity 和 /notes 的 agent 字段中。如果多个 Agent 共用一个 MCP 客户端，请使用此变量，以便 GET /activity 能区分它们：

"env": { "AIPM_AGENT_NAME": "revisor" }

名称会规范化为 [a-z0-9._-]，最长 40 个字符。这是调用方声明的自身标识，仅用于可观测性和协作，绝不用于授权。任何人都可以在此填写任意名称；产品不会据此授予或拒绝权限。唯一的限制仍是默认拒绝的操作允许列表，该列表按应用分别设置。

3. 重启 MCP 客户端

工具会显示为 ai-process-manager。请先调用 health_check。

工具（28 个）

15 个感知工具和两个 UI 探测工具均标注为 readOnlyHint: true——客户端可以自动批准它们。七个 UI 操作工具标注为 readOnlyHint: false，只有用户选择启用后才会运行（参见隐私）。

工具	标题	端点
aipm_ja_faz	AIPM 已经能做这件事了吗？编写代码或使用 shell 之前先询问	GET /?q=
health_check	状态、应使用的操作类别以及真实输入启用状态	GET / + GET /forgepilot/status
check_process	检查进程是否正在运行	GET /processes
list_processes	列出正在运行的进程	GET /processes
list_windows	列出已打开的窗口	GET /windows
get_system_status	获取系统状态（CPU、RAM、GPU、磁盘）	GET /system
get_taskbar	显示任务栏应用	GET /taskbar
read_window	读取窗口中的文本	GET /window/text
get_ui_tree	获取窗口的 UI 元素树	GET /ui/tree
wait_for	等待条件满足	GET /wait
get_recent_events	列出近期 PC 事件	GET /events/history
check_file	检查文件或文件夹	GET /filesystem/watch
get_app_knowledge	获取针对某个应用学到的操作方案	GET /knowledge/app
get_economy_stats	获取令牌经济统计数据	GET /analytics/summary
get_audit_log	查看 API 审计日志	GET /audit
read_notes	读取本地 Agent 公告板	GET /notes

UI 工具——先查看状态，再选择启用操作：

工具	标题	端点
ui_find	查找可交互的 UI 元素	GET /ui/find
ui_find_at	查找屏幕像素位置下的 UI 元素	POST /ui/find_at
ui_act	按意图执行操作（决定使用 UIA 还是真实输入）	POST /ui/act
ui_invoke	点击 UI 元素	POST /ui/invoke
ui_set_value	设置 UI 字段的值	POST /ui/set_value
ui_send_keys	使用模拟按键输入文本（最后手段）	POST /ui/send_keys
ui_drag	将一个元素拖到另一个元素上	POST /ui/drag
ui_select_option	在下拉菜单中选择选项	POST /ui/select_option
focus_window	将窗口置于前台	POST /ui/focus

本地遥测（仅将元数据写入本地存储）：

工具	标题	端点
report_task_outcome	报告任务结果（遥测）	POST /telemetry/task
report_action_outcome	报告 UI 操作结果（遥测）	POST /telemetry/action

本地 Agent 协作（仅存储在此机器上）：

工具	标题	端点
post_note	在 Agent 公告板上发布留言	POST /notes

读取深层 UI 树（Chromium/Electron）

get_ui_tree 的默认 depth=4，足以应对原生 Win32 应用。Chromium/Electron 应用（VS Code、Slack、Discord、Claude Desktop、Teams）会将内容埋在约 10 层 Pane/Group 包装器之下——深度较低时，响应中只有空窗格。对此类应用，请将 depth 设为 15-20（最大值为 30），并通过 max_nodes 限制开销（默认值为 200，最大值为 1000）：限制开销的是 max_nodes，而不是 depth。 当响应包含 truncated: true 时，表示树已被截断——在对窗口作出任何判断之前，请使用更高的 depth/max_nodes 重试。

操作：两类方式，选错是最常见的失败原因

这是 Agent 默认最容易出错的部分，因为它们见过的其他所有计算机操作工具都要求窗口位于前台。而在这里，大多数工具并非如此：

ui_act 会在以下两类方式中自动为你选择——点击／输入／选择时请先尝试使用它。 它会尝试 UI Automation，仅当 UIA 报告该元素缺少相应模式时，才会自动改用真实输入（intent=escolher 时绝不会这样做，因为物理点击会触发元素，而不是在元素内选择选项）；并通过 mecanismo（uia／fisico）告知你实际运行的是哪一种。遇到目标不明确时，它还会拒绝操作并返回 409 alvo_ambiguo，同时提供带有 rect 的候选项；而不会像下面的工具那样，静默地选中第一个名称匹配项。下文将介绍每种方式的含义，以及何时应直接调用其中一种。

类别	工具	窗口需要位于前台吗？
按元素操作（UI Automation）	ui_invoke、ui_set_value、ui_select_option	不需要。 窗口即使被其他窗口遮挡、未获得焦点也能操作，用户还可以在别处继续输入。
通过合成输入操作	ui_send_keys、ui_drag	需要。 否则会返回 janela_nao_esta_em_primeiro_plano。

原因：第一类方式通过应用的辅助功能提供程序进行交互，不受 Z 顺序影响；第二类方式会发出真实的键盘／鼠标事件，而 Windows 会将这些事件发送给当前位于前台的窗口，而不是你传入的 hwnd。

直接调用这两类方式时：每次都先从按元素操作开始。 不要「以防万一」先调用 focus_window：那会抢走用户当前的前台窗口，却毫无益处。只有在 ui_set_value 确实对该字段返回 valor_nao_aplicado（受控框架中的 contenteditable）之后，才使用 ui_send_keys；而 ui_drag 仅用于确实只能通过拖动来移动的情况——UIA 没有拖动模式。

如果 focus_window 本身因 foco_nao_aplicado 失败，不要反复尝试第二类方式：没有前台焦点，它就无法成功。health_check 会在 executor／forgepilot 下报告真实输入组件（ForgePilot）的状态，并在组件已安装但已停止时发出警告。

隐私

不会有任何关于你的数据离开本机。没有远程遥测、云服务或账户。 只有一种出站请求；该请求不携带任何关于你的信息，而且你可以将其关闭：

更新检查。 引擎每天会向 GitHub 的公开 Releases API 查询是否存在更新版本。请求会发送到 GitHub，而不是我们这里：不含标识符、遥测数据，也不含任何关于你的机器或应用的信息。你可以在托盘菜单中关闭此功能；关闭后完全不会发出出站请求。 AIPM 的其他所有功能都在本地运行。

网络

• 后端仅监听环回接口（127.0.0.1:9147），不会监听 0.0.0.0，因此局域网中的其他设备无法访问。
• 每个请求都必须携带值为 localhost 或 127.0.0.1 的 Host 标头；其他值均会被拒绝，并返回 403 forbidden_host（防范 DNS 重绑定，避免你访问的网页驱动 API）。
• 此 MCP 服务只会发出一种类型的出站调用：向该本地地址发起 HTTP 请求。它会发送 User-Agent，值为 mcp:<your MCP client name>，这样本地审计日志就能显示发出请求的 Agent。

默认只读

• 15 个感知工具和 ui_find 都是纯读取工具。ui_find_at 在语义上也是只读的，但其像素探测会使用受保护的 POST；这 17 个工具均带有 readOnlyHint: true。
• 7 个 UI 操作工具（ui_act、ui_invoke、ui_set_value、ui_send_keys、ui_drag、ui_select_option、focus_window）会返回 403 action_denied，直到用户同时完成以下两项操作：在托盘菜单中启用 Agent 操作，并将目标进程添加到按应用设置的允许列表中。这两项默认均未启用，且设置按应用分别生效——允许 Notepad 并不意味着允许浏览器。

遥测存储的内容——仅元数据

记录内容：应用／进程名称、元素角色（Button、Edit……）、Agent 请求的元素名称、操作（invoke／set_value／focus）、成功或失败、耗时（毫秒）以及失败原因。以下两项机械约束让“仅元数据”可以验证，而不只是承诺：

1. 操作记录存储的是 Agent 请求的内容，而不是应用显示的内容。 角色和名称来自 Agent 自己的 role=／name_contains= 参数。实际在屏幕上解析到的元素名称绝不会被写入，因此工具看到的内容永远不会变成遥测数据。
2. 失败原因来自封闭词汇表（elemento_nao_encontrado、ui_timeout、erro_uia、outro……）。任何其他字符串都会被存储为 outro。因此，异常消息（其中可能包含文件路径或屏幕文本）不会写入磁盘。

**绝不存储：**屏幕内容、read_window 读取的窗口文本、ui_set_value 输入的文本（value=）、文件内容、按键记录、屏幕截图。被动学习到的 UI 结构（ui_shape）只包含计数、UIA 角色名称、深度和布尔值：exposes_text 表示是否存在文本，named_controls 表示有名称的元素数量，绝不包含文本本身。

**脱敏：**记录任何请求之前，都会将 value= 和 api_key= 替换为 ***，因此 get_audit_log 和磁盘上的查询日志都不会泄露输入的文本或密钥。

**坦诚说明一项细节：**审计／查询日志会存储请求行，因此其他查询参数仍会以可读形式保留——例如，check_file(path=D:/videos/out.mp4) 会按该路径记录，check_process(title_contains=...) 也会保留该片段。这是记录 Agent 请求内容的本地日志。只有 value= 和 api_key= 会脱敏。

数据存储位置及删除方法

所有内容都位于 %LOCALAPPDATA%\AIProcessManager\ 下：

路径	内容
db\*.jsonl、db\rollup.json	遥测数据：任务、操作、查询、UI 结构、计数器
ledger.jsonl	具有防篡改哈希链的已报告／已执行操作日志（仅元数据）
actions.cfg	操作层是否启用，以及每个应用的允许列表
update.json	更新检查偏好设置（开／关）及其缓存：上次检查时间、最新标签、已忽略的标签
log.txt、endpoint.txt	应用日志和当前使用的 API 地址

要清除数据：从托盘退出应用，然后删除该文件夹（或只删除 db\，以重置学习数据和用量计数器；删除 actions.cfg 会关闭操作层）。不会在其他位置写入任何内容，/audit 环形缓冲区仅驻留内存中——应用关闭时就会消失。你可以使用 get_audit_log、get_economy_stats 和 GET /analytics/actions 检查存储的所有内容。

故障排除

症状	含义	解决方法
connection_refused	AIProcessManager.exe 未运行	从“开始”菜单启动（绿色托盘图标）
action_denied	操作层已关闭，或应用不在允许列表中	托盘菜单 → Agent 操作，然后允许该应用
api_paused	用户从托盘暂停了 API	托盘菜单 → 恢复 API
空的 Pane 树	对 Chromium／Electron 应用而言，depth 太低	使用 depth=17 重试 get_ui_tree

每个错误负载都包含一个提供相同指导的 next_action 字段。

覆盖范围（实测，真实）

技术栈	读取状态	语义操作
Win32 / WinForms / WPF / UWP	✅ 完整	✅
Delphi VCL（旧版业务应用）	✅ 完整	✅
Console（cmd、PowerShell、Windows Terminal）	✅ 文本	—
Chromium / Electron（Chrome、Cursor、Claude Desktop）	✅ 唤醒辅助功能树后	✅
使用旧版 MSAA 桥接的 Electron（例如 Discord）	⚠️ 可唤醒，但每个节点约需 120 ms——目前太慢	⚠️
Java Swing	⚠️ 需要 Java Access Bridge	计划中

我们会刻意公布目前尚不可用的功能——在依赖它之前，你应该了解其适用范围。

行为说明：首次读取 Chromium/Electron 窗口时，会请求其激活辅助功能树——这与屏幕阅读器发出的标准请求相同。此后，该应用会持续计算辅助功能数据（这会占用该应用的 CPU），并且不会自行休眠。原生 Win32 应用不受影响。

免费与付费

• **免费且开源（MIT）：**此 MCP 服务。
• 免费（闭源）：AIProcessManager.exe 后端——传感器。你可以免费运行它。
• **付费：**AIPM Pilot，一款自主计算机操作 Agent，通过使用 AIPM 的结构化感知来端到端驱动应用。

支持此项目

如果 AIPM 为你节省了 token，可以考虑赞助。

许可证

MCP 服务采用 MIT 许可证。后端和 AIPM Pilot 是独立产品。