内容
<div align="center">
<img src="app/build/icon.png" alt="Windows 桌面伴侣" width="120" />
# Windows 桌面伴侣
**一个可以查看屏幕并在您的电脑上执行操作的浮动 AI 伴侣。**
您可以通过快捷键在任何地方召唤它。它可以查看您的屏幕，了解您正在使用的应用程序，在网络上查找信息，并执行实际操作，例如编辑配置、运行 PowerShell、驱动其他应用程序 — 在聊天窗口中批准任何有风险的操作。
[](https://github.com/wyofalcon/windows-desktop-companion/actions/workflows/ci.yml)
[](https://github.com/wyofalcon/windows-desktop-companion/releases)
[](LICENSE)
</div>
---
```
聊天窗口 ──stdin (stream-json)──▶ 无头 Claude 代码 (claude-sonnet-5)
◀──stdout (stream events)───────┘ │
├─▶ 内置工具：PowerShell、
│ 文件读取/编辑、网络搜索
└─▶ MCP 服务器 "windows-tools"
（截图、UIA、输入注入）
```
- **大脑：** `claude-sonnet-5`，在 **最大推理努力** 下，通过 Claude **Agent SDK** — 一个具有崩溃恢复功能的持久流式会话。
- **眼睛和手：** `windows-tools` MCP 服务器（截图、窗口枚举、UI 自动化，以及作为备用方案的原始输入注入）。
- **命令执行：** Claude 代码的内置 shell 工具，运行 **PowerShell**。
- **原则：** 优先考虑结构化控制（配置文件、CLI、`ms-settings:` URI、UI 自动化树）而不是像素点击。
<!-- 演示 GIF 待录制后添加：  -->
## 安装和运行（最终用户）
> [!IMPORTANT]
> 此工具允许 AI 模型 **运行命令并控制您的电脑**。在安装之前，请阅读 [SECURITY.md](SECURITY.md) — 您批准每个有风险的操作，但您是最后一道防线。
**要求**
- **Windows 10 或 11。**
- **[Claude 代码](https://claude.com/claude-code) 已安装并登录。** 伴侣是它的前端 — 验证 `claude --version` 在 PowerShell 中是否有效。您的登录凭证会被重用；订阅账户不需要 API 密钥。
**步骤**
1. 从 [**Releases**](https://github.com/wyofalcon/windows-desktop-companion/releases) 页面下载最新版本：
- **`Windows 桌面伴侣-Setup-x.y.z.exe`** — 安装程序（添加一个开始菜单快捷方式），**或**
- **`Windows 桌面伴侣-x.y.z-portable.exe`** — 单个便携式可执行文件，无需安装。
2. 运行它。Windows SmartScreen 可能会对未签名的版本发出警告 — **更多信息 → 运行任何方式**。
3. 按 **`Ctrl+Alt+Space`** （或窗口标题中显示的备用方案）召唤聊天窗口。输入内容即可开始对话。
所有内容都已捆绑：Python `windows-tools` 服务器作为自包含的 `windows-tools.exe` 交付，因此 **您不需要安装 Python**。
### 使用它
- **Esc** （或 **—** 头部按钮）将聊天窗口折叠成一个浮动的 **聊天头像气泡**，始终位于其他窗口之上。
- **点击** 它 → 聊天窗口在气泡旁边展开。**拖动** 它 → 吸附到最近的屏幕边缘并记住其位置。当大脑正在工作时，它会 **脉动**，当有回复/权限到达时，会显示一个琥珀色 **徽章**。**右键单击** → 打开聊天窗口 / 退出。
尝试：
- *"当前我的屏幕上是什么？"* → 它会截图并描述它。
- *"将 VS Code 切换到 Light+ 主题。"* → 它会编辑 `settings.json` （不是 GUI 点击）并确认。
- *"为什么我的键盘灯在闪烁？"* → 它会通过 PowerShell 识别设备，网络搜索供应商文档，并 **在进行任何更改之前询问**。
## 安全防护
每个操作都分为三个层级，在 [`app/src/main/bridge.ts`](app/src/main/bridge.ts) 中强制执行：
- **自动允许（只读）：** `screenshot`、`active_window`、`list_windows`、`ui_tree`、`find_element`、网络搜索、文件读取，以及严格的只读 PowerShell 允许列表（`Get-*`、`Test-Path`、`Select/Where/Sort/Measure`…）。
- **需要批准（需要允许点击）：** 文件编辑/写入、修改 PowerShell、`invoke_element`、`click`、`type_text`、`send_keys` — 每个操作都会显示一行描述。
- **始终询问，标记为危险：** 删除、注册表写入、磁盘操作、关闭应用程序 — 任何可能导致工作损失的操作。
权限决策在聊天窗口中进行，而不是在隐藏的终端中。有关完整模型，请参见 [SECURITY.md](SECURITY.md)。
## 从源代码构建
需要 **Node 20+**、**Python 3.11/3.12** 和 Claude 代码登录。完整的开发说明在 [CONTRIBUTING.md](CONTRIBUTING.md) 中；简要版本：
```powershell
# 1. 用于 MCP 服务器的 Python 虚拟环境
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
# 2. 开发版本 + 启动（有关 WSL 共享镜像的说明，请参见 run-companion.ps1）
./run-companion.ps1
```
**自行打包独立可执行文件：**
```powershell
./build-release.ps1 # -> .\release\ (NSIS 安装程序 + 便携式 .exe)
```
这会使用 PyInstaller 冻结 MCP 服务器，并使用 electron-builder 打包应用程序。标记的版本 (`git tag v0.1.0 && git push --tags`) 会在 `windows-latest` 上通过 [GitHub Actions](.github/workflows/release.yml) 构建相同的工件，并将它们附加到版本中。
## 它能在 Linux 上运行吗？
**否 — 仅限 Windows，设计如此。** 伴侣的核心价值（查看屏幕、读取 UI 自动化树、驱动应用程序）依赖于 Windows 特有的库（`pywinauto` 的 UIA 后端、`pywin32`、`comtypes`）和 PowerShell。Linux/X11 没有捆绑等效的表面，因此 Linux 版本将是一个聊天窗口，没有“眼睛和手” — 这会使目的失败。如果您想使用基于 AT-SPI/`xdotool` 的工具进行 Linux 端口移植，那是一个受欢迎的（大型）贡献。
## 项目布局
```
MSAI/
├─ .mcp.json # 为交互式 `claude` 注册 windows-tools
├─ requirements.txt # Python MCP 服务器依赖项
├─ run-companion.ps1 # 开发：构建 + 启动（镜像到本地）
├─ build-release.ps1 # 发布：PyInstaller + electron-builder
├─ scripts/make-icon.py # 重新生成 app/build/icon.{ico,png}
├─ prompts/companion-system-prompt.md
├─ mcp-server/ # windows-tools MCP 服务器（Python，stdio）
│ ├─ run.py · windows-tools.spec (PyInstaller)
│ └─ windows_tools/{server,screen,win,uia,inputs,dpi}.py
└─ app/ # Electron + TypeScript 聊天窗口
├─ electron.vite.config.ts · package.json (electron-builder 配置)
├─ build/icon.ico
└─ src/{main,preload,renderer}/…
```
## v1 范围之外
本地 Ollama “快速查询”通道（在桥中留有路由器缝隙）、OCR、设置 UI、开机自动启动、多显示器优化和语音。
## 许可证
[MIT](LICENSE) 2026 wyofalcon.
使用 [Claude 代码](https://claude.com/claude-code) 作为前端构建，使用 [Claude 代理 SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)。
