内容
PC 控制插件
直接Code 控制您的 Windows PCwindows-mcp](https.com/CursorTouch/Windows) MCP 服务器作为底层## 功能特点
- **桌面 UI 自动化** — 点击、滚动、拖切换应用、调整窗口大小
- **文件系统** —写入、复制、移动、和目录
- **PowerShell** — 执行任意 Power
- **截图** —和分析桌面截图
-表** — 读取、写入注册表键
-** — 列出和运行的进程
- **板** — 获取和贴板内容
- **通知** — 发送 Windows toast 通知
- **网页抓取** — 获取和提取网页内容
- **快照** — 检查屏幕上的 UI 元素及其坐标
- **多操作** — 批量选择和编辑多个 UI 元素
## 前置条件
- Node.js 18+
- OpenCode
- Python 3.11+
## 安装
###. 安装 npm 插件
在您的 OpenCode 配置目录（通常为 `%USERPROFILE%\.config\opencode`）：
cd %USERPROFILE%\opencode
npm install
```
或使用 PowerShell：
```powershell
cdconfig\opencode
npm install open-controller
```
###. 安装 MCP 服务器（）
```bash
pip-mcp
```
###. 添加到 OpenCode 配置
将 `"open-controller"` `%USERPROFILE%\.config\opencode\opencode.jsonc` 中的 `"plugin"` 数组尚未存在：
```jsonc
{
"plugin": [
"open-controller",
// ... 其他插件
]
}
```
### 4. 重启 OpenCode
尝试以下命令：
列出桌面文件"
- "截取屏幕截图"
打开 Chrome"
- "运行记事本"
## MCP 工具
插件通过 `windows-mcp` 服务器注册了 19 工具：
###
- **应用** — 启动、切换或调整应用程序窗口
- **快捷方式** — 执行键盘快捷方式（`ctrl、`win+r` 等）
### 桌面和 UI
- **快照** — 捕获桌面状态，包含 UI 交互元素和坐标
- **截图** — 快速截图，可选注解叠加层
- **点击** — 在坐标或 UI 元素标签上单击、双击、右击
- **输入** — 在坐标或 UI 元素中输入文本
- **滚动** — 在位置处垂直/水平滚动
- **移动** — 移动光标（悬停）或
- **等待 暂停执行一段时间
-直到** — 等待 UI 条件（文本存在、元素启用、窗口激活）
### 文件系统
- **文件系统 读取、写入、复制、删除、列出、获取信息（8 种模式）
### Shell
- **PowerShell** — 执行任意 PowerShell 命令，带超时
### 剪贴板
- **剪贴板** — 获取剪贴板文本
进程
- **进程 列出进程（按内存/名称排序） PID/名称终止
表
- **注册 — 获取、设置、列出 Windows 注册表键
### 通知
通知** — 发送 Windows通知
### 网页
- **抓取** —网页内容，带 模式
### 多选
- **多选**批量选择多个项目（复选框）
- **多编辑** — 在多个输入字段中输入文本
## 内置插件工具
插件中两个额外的工具：
工具 | 描述 |
||
| `pc-exec` | 执行任意 PowerShell 命令| `pc-s | 捕获桌面为 base64 PNG 图片 |
| `pc-mcp-status` | 运行 Python 导入和 `Desktop()` 烟雾测试，用于 MCP 服务器 |
| `pc-mcp-instructions` | 返回插件注入到代理中的系统指令 |
## 系统指令
每个会话，插件都会读取 [`instructions/WINDOWS_CONTROLLER.md`](instructions/WINDOWS_CONTROLLER.md) 并通过 `experimental.chat.system.transform` 钩子将其内容注入到代理的系统提示中。指令涵盖了 windows-mcp 用户在中最常见的故障模式：
- **前景验证** — 如何检测到 "我认为我在正确的窗口，但我的操作却到了" 的竞争情况，以及。
- **快照流** — 何时 `windows-mcp_Snapshot`，如何读取其如何解析标签 ID。
长文本输入** —windows-mcp_Type` 30+ 个字符住，以及何时到剪贴板 +。
- **义** — `M -32001: Request timed out` 不意味着操作失败意味着 30 秒的 MCP 客户端上限已经过去。用新的快照重试，不要循环。
- **边缘情况** — ARM64 主机、UAC / 安全桌面、RDP / 服务器会话、electron / sheet / canvas 应用程序。
完整文本随 npm 包一起在 `instructions/` 下提供。要在会话中查看它，请调用 `pc-instructions` —返回注入到系统提示中的确切文本 架构
Code
└── open-controller 插件（open-controller@.1）
-exec 工具（PowerShell）
├── pc-screenshot 工具（base64 PNG └── MCP 服务器：windows（Python）
├── 应用、快照、截图
点击、输入、滚动、等待
系统、PowerShell、
├── 剪贴板、进程、通知
抓取、多选
└── 快等待直到
```
1. 在 OpenCode加载
2. 预 MCP 服务器（导入 `.client` 并实例Desktop()`，以便 工具调用速度更快. 使用 `ANONY_TELEMETRY=false无缓冲标准输入在 OpenCode 中注册 MCP 服务器配置
4. 将 `pc-exec`、`pc-s、`pc-mcp 和 `pc-mcp` 添加为原生插件5. 通过 `experimental.transform` 钩 `instructions/WINDOWS.md` 的内容注入的系统提示中
将 `windows-m MCP 客户端超时设置为 小时**（720 毫秒），以便自动化调用不会达到 OpenCode 的 30 秒默认## 超时
插件覆盖了 `windows-mcp的 OpenCode MCP ，设置为 `cfg.mwindows-mcp"].timeout72000000` 小时）。这会自动适用于从头开始安装 `cp` 的用户，并防止在 `Snapshot`Keys` 或 `App启动）操作运行 OpenCode 的 30超时时出现 `M -32001: Request timed out` 失败。
要覆盖默认超时，请在启动 之前设置环境OPENCONTROLLER_MCP`。该值必须是以单位的正整数。
```cmd
setx OPENCONTROLLER_MCP_TIMEOUT_MS 1200000 :: 分钟
```
无效失的值会回退20 小时默认值。pc-exec` 有其自己的 60 秒上限；通过编辑 `src/index.ts` 中的 `PC_EXEC_TIMEOUT_MS` 可以提高该上限。
## 开发
插件源码位于 [GitHub 仓库](https://github.com/amazing-things/open-controller)。要进行本地修改：
```cmd
:: 克隆仓库
git clone https://github.com/amazing-things/open-controller.git
cd open-controller
:: 安装依赖
npm install
:: npm run build
::Code 中使用本地版本 将 "./path/to/open-controller" 添加到 opc 插件列表中
```
重启 OpenCode 以。
## 自动更新
从 v1.1.8 开始，插件会自行更新。在每个 OpenCode 会话启动会静默运行 ` open-controller version如果在注册表上有一个新版本，它会为您运行 install -g open。然后，Windows toast会要求您重启，以便加载新代码。
无需代理操作**在 `setImmediate`中发生，永远代理或您的会话。
** — 在Code 之前，在环境 `OPENCONTROLLERDATER=1` **CI 自动跳过 如果设置了 `、`CONTINUOUS_IN`、`GITHUB_ACTIONS` 或 `GITLAB更新器是一个。
- **重启以 — 运行的 Open进程在全局安装完成旧代码，直到您。
## 故障排除 `MCP error01: Request timed out `windows-mcp 工具上
这是故障模式。M客户端在 30 秒后取消调用。最可能首先）：. **首次工具调用 — 底层 `Desktop()` 初始化运行 UIA COM可能需要 5 秒的首次使用时间，在具有许多打开窗口的更长。v0.4 在期间预热 `Desktop但如果预热第一个 MCP 调用仍会费用。
2.重的 UIA 枚举** — 在窗口“启动无响应”时调用 `Snapshot` 可能会使 枚举挂起 秒以上。仅在响应窗口上使用 `windows-mcp_Type` / `windows_Click`。
3网络/遥测** — v1.0. `ANONY_TELEMETRY=false`，以避免在 MCP 服务器生命周期内进行 PostHog 分析调用。
4. **Shell 脚本** — `pc-exec` 默认超时现在为 60 秒。分割长脚本。
诊断步骤：
1. 从代理运行 `pc-mcp-status` — 它导入 `windows_mcp` 并实例化 `Desktop()` 一次。如果这返回 `init:ok`，则包是健康的。
检查 `~-mcp/server 和 `~-mcp/server.error 中的底层 Python 堆。
3. 如果存在，请在 MCP设置 `WINDOWS_MCPATCHDOG=（v1.0.4 从配置中读取它），以跳过 STA 事件泵并减少锁定竞争 许可证
MIT —阅 [LICENSE](原始 windows-mcp 由 [Jeomon George](https://github.com/CursorTouch
