hyprdesk

<div align="center"> <img src="desktop/src/assets/brand/readme-hero.png" alt="HyprDesk — router → workers" width="100%" /> # HyprDesk **协调一支AI编码代理团队，在您的桌面端。** 一个 **路由器** 代理——您与之交互的代理——**领导**：它思考、调查、设计、编写关键代码，并将执行**委托**给**工作器**代理，每个代理都在其自己的真实终端中。它们都通过一个**本地双向MCP隧道** — **A2A（代理到代理）在您的机器上运行**。 [](https://github.com/Mats2208/hyprdesk/actions/workflows/ci.yml) [](https://github.com/Mats2208/hyprdesk/releases/latest) [](https://github.com/Mats2208/hyprdesk/releases/latest) [](https://github.com/Mats2208/hyprdesk) [](https://tauri.app) [](https://www.rust-lang.org) [](https://react.dev) [](https://modelcontextprotocol.io) [](LICENSE) <br/> <table> <tr> <td align="center"><strong>3 引擎</strong><br/>_{Claude · Codex · OpenCode}</td> <td align="center"><strong>路由器 → N 工作器</strong><br/>_{并行，实时终端}</td> <td align="center"><strong>本地 A2A 隧道</strong><br/>_{双向 MCP}</td> <td align="center"><strong>git 工作树</strong><br/>_{隔离 + 合并回}</td> <td align="center"><strong>文件编辑器</strong><br/>_{VS Code 风格 · ⌘S 保存}</td> </tr> </table> **自由混合引擎 — Claude Code、Codex 和 OpenCode 每个都可以是路由器**或**工作器 — 带有 AI 构建的代理配置文件、git 工作树隔离、应用内文件编辑器和高级、简约的 UI（黑暗 / 浅色 / 高对比度）。在 macOS 和 Windows 上运行。** </div> --- ## 它构建了什么，由它自己 **[→ HyprDesk 官网](https://mats2208.github.io/hyprdesk/)** — 一个滚动驱动的 WebGL 站点。**HyprDesk 构建了它。** <p align="center"> <a href="https://mats2208.github.io/hyprdesk/"><img src="docs/landing-tunnel.png" alt="HyprDesk 官网的 A2A 隧道动作 — 路由器核心在负载下燃烧，数据包在三个引擎之间的线路上移动" width="900"/></a> </p> 一个路由器（Claude）和四个工作器，每个都在其自己的 git 工作树中。路由器读取两个参考项目，**冻结架构合约**，然后分发 — 一个工作器每个文件，因此四个代理可以并行编写而永远不会触及同一行。它在合并之前检查每个分支并拒绝违反规则的分支。 **75 分钟，不间断。** 整个源代码在 [`web/`](web/) 中，git 历史记录在这一行之上：`models:`、`scene:`、`director:`、`style:` 和四个 `hyprdesk/*` 分支的合并。给他们的确切简报是 [`web/PROMPT.md`](web/PROMPT.md)。 他们交付了一个 **44 KB 程序化 GLB** （从存储库中的 Blender 脚本生成 — 模型是**可复制的**，不是下载的），一个源自滚动的确定性相机和一个 **27 检查验证套件**，在真正的 GPU 上运行并控制构建（232 fps 中位数，零控制台错误，`prefers-reduced-motion` 完全遵守）。 > 最有趣的时刻不是速度。 而是当路由器遇到简报中的矛盾并且**停止并询问**（`ask_user`）— 提出每个选项的精确权衡。 当它在自己的测试套件中发现一个**错误**时，它说： *"我编写的三个文档错误是由我 — 合约作者引起的。"* > > 这就是路由器的重点。 它不是调度器。 --- ## 示范 <p align="center"> <img src="docs/router-workers.png" alt="路由器将任务委派给五个并行工作器 — 每个代理都在其自己的实时终端中" width="900"/> </p> <p align="center">_{一个路由器（Claude）并行委派给四个工作器 — **后端**、**前端**、**测试**（Claude）和**视觉**（Codex）— 每个都在其自己的实时终端中隔离的 git 工作树中，通过本地 A2A 隧道报告回来。 视觉工作器是 Codex，因为图像生成被路由到可以执行它的引擎。}</p> <p align="center"> <img src="docs/home.png" alt="HyprDesk 首页 — 创建或打开工作区" width="900"/> </p> <p align="center">_{首页：创建工作区或打开现有文件夹。 高级，近单色 UI（黑暗 / 浅色 / 高对比度），无边框 VS Code 风格标题栏。}</p> --- ## 它做什么 一个桌面应用程序，其中一个代理**领导**其他代理团队 — 所有代理都通过本地 MCP 隧道连接，在隔离的 git 分支中工作，带有内置的文件编辑器和文件树。 | | 功能 | 详情 | |---|---------|---------| | **领导代理** | 路由器领导和委托 | 路由器进行重思考（调查、设计、编写关键代码）并使用 `spawn_worker` / `send_to_worker` 委托执行 — 不是一个简单的调度器 | | **多引擎** | Claude · Codex · OpenCode | 任意一个作为路由器**或**工作器。 角色作为**系统提示**注入 — 没有浪费回合。 模型和推理努力可针对每个代理进行选择 | | **本地 A2A** | 双向 MCP 隧道 | 代理通过 `tiny_http` 控制服务器相互咨询和报告；您可以随时跳转到任何终端 | | **配置文件** | AI 构建或手动配置文件 | 用自然语言描述一个代理 → 元代理使用您实际验证的模型构建配置文件（引擎 + 模型 + 努力 + 配置文件 + 颜色）。 或**手动**构建一个 | | **委托** | 按配置文件，或询问您 | 路由器查看您的配置文件（`list_profiles`）并委托给正确的一个 — 或询问您使用哪一个（`ask_user`）而不是生成通用工作器 | | **团队** | 一次启动一组配置文件 | 使用共享目标预生成一组配置文件；它们保持活跃并向路由器报告 | | **隔离** | git 工作树 + 合并回 | 在 git 仓库中，每个工作器都有自己的分支/工作树，因此它们永远不会冲突；路由器将分支**集成**到主分支（`merge_worker`） | | **审查** | 合并前由批评者审查 | 路由器读取工作器的 diff（`review_worker`）并在合并前验证 — 没有盲合并 | | **内存** | 路由器在会话之间保存内存 | 路由器维护一个工作区内存文档（`save_memory`）并在重新打开时重新注入 — 它带有上下文恢复 | | **文件编辑器** | VS Code 风格，应用内 | 浏览工作区文件树并在真实编辑器中打开文件（CodeMirror，延迟加载）— 语法高亮每个语言，**⌘/Ctrl+S 保存** | | **令牌效率** | Ponytail 技能，始终在线 | 每个代理（路由器 + 工作器）加载 [Ponytail](https://github.com/DietrichGebert/ponytail) “懒惰高级开发人员”技能 — 更少的代码，更少的令牌，无质量损失 | | **预览** | 嵌入式浏览器 | 应用内浏览器（iframe 用于 localhost/HTML，本机 webview 用于外部站点）带有 `localhost:PORT` 自动检测，当代理启动开发服务器时 | | **工作区** | 多工作区保持活动 | 在选项卡中一次打开多个项目；无需杀死代理或燃烧令牌（所有代理都在后台保持活动） | | **打开任意文件夹** | 非破坏性链接 | 链接一个真实的现有项目作为工作区 — 永远不会删除您的文件夹；其状态独立存在，不会污染您的仓库 | | **主题** | 高级和可配置 | 近单色黑暗 / 浅色 / 高对比度主题，可配置 UI 和单色字体和大小，均来自可搜索的架构驱动的设置面板 | | **权限** | 自主或询问 | *自主*（绕过，流程自主）或*询问*（审查每个编辑/命令） | | **持久性** | 会话恢复 | 重新打开工作区，代理通过 `--resume` （会话 ID）恢复 | | **跨平台** | macOS · Windows | 在两者上原生运行（npm-shim CLIs 解析为其在 Windows 上的真实可执行文件）— 菜单栏，多个窗口，将图像粘贴到任何磁贴中，命令调色板（⌘K），可重新映射的键绑定，以及标题栏中的 GLM（z.ai）配额 | ## 安装 ### 下载安装程序 **[→ 最新版本](https://github.com/Mats2208/hyprdesk/releases/latest)** — `.dmg` 用于 macOS（通用：Intel + Apple Silicon），`.exe` 用于 Windows。 不需要工具链。 您只需要确保代理 CLI 本身： **[`claude`](https://docs.claude.com/en/docs/claude-code)** 已安装并登录（必需），以及可选的 **`codex`** / **`opencode`**. HyprDesk 驱动您已经使用的 CLI — 它不提供或替换它们。 > **构建未签名。** 签名需要付费的 Apple / Microsoft 开发人员帐户，并且目前没有一个 — 因此操作系统会在首次启动时发出警告。 就是这个警告，不是诊断。 > - **macOS** — Gatekeeper 阻止首次打开。 右键单击应用程序 → **打开** → **打开**。 仅一次。 > - **Windows** — SmartScreen 显示“Windows 保护了您的 PC”。 **更多信息** → **继续运行**。 ### 或从源代码构建 > **要求** — macOS 或 Windows · [Node 20+](https://nodejs.org) · [pnpm](https://pnpm.io) · [Rust/Cargo](https://rustup.rs) · `git` 在 PATH 中。 > 在 **Windows** 上，还需要安装 **[Visual Studio C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)**（“使用 C++ 进行桌面开发”）— Rust 的 MSVC 链接器。 > 另外，还需要安装代理 CLI 并登录： **[`claude`](https://docs.claude.com/en/docs/claude-code)** （必需），以及可选的 **`codex`** / **`opencode`**。 **1. 克隆并安装** > Node 工作区位于 **`desktop/`**，不在仓库根目录 — 在上一级运行 `pnpm install` 会失败并出现 `ERR_PNPM_NO_PKG_MANIFEST` 错误。 ```bash git clone https://github.com/Mats2208/hyprdesk cd hyprdesk/desktop pnpm install ``` **2. 开发中运行**（带有热重载的窗口） ```bash pnpm tauri dev ``` **3. 构建应用** ```bash pnpm tauri build # → HyprDesk.app（macOS）或 .msi / .exe（Windows） ``` > 在 macOS 上，从 Finder 启动继承了一个最小的 PATH — HyprDesk 在启动时解析您的真实登录 shell PATH，以便找到 `claude` / `codex` / `node`。 在 Windows 上，GUI 应用已经继承了完整的 PATH，并且 npm-shim CLIs 自动解析为其真实的可执行文件。 ## 快速开始 1. **创建工作区**（`~/HyprDesk/` 中的新文件夹）或**打开现有文件夹**（您的真实项目 — 链接，非破坏性）。 2. 选择**路由器引擎**（Claude / Codex / OpenCode）。 3. **与路由器交谈**像任何代理一样： > *"调查代码库并使用后端构建一个带有后端的登陆页面。"* 它委托实时工作器在隔离的分支中工作并报告回来；您可以实时观看它们的差异（`review_worker`），集成它们（`merge_worker`），并在内置编辑器中编辑任何文件。 ## 架构 ```mermaid flowchart TB subgraph APP["HyprDesk · Tauri v2"] FE["React + xterm.js<br/>终端磁贴 · 文件编辑器 · 文件树"] BE["Rust backend<br/>PtyManager · 控制服务器 · git 工作树"] FE <-->|invoke / events| BE end BE -->|PTY| R["路由器代理<br/>claude / codex / opencode"] BE -->|PTY| W1["工作器"] BE -->|PTY| W2["工作器"] HUB(["控制服务器<br/>(隧道 · tiny_http)"]) R <-->|MCP 工具| HUB W1 <-->|MCP 1 | MCP 工具| HUB W2 <-->|MCP 工具| HUB ``` - **前端** (`desktop/src/`): React + xterm.js。模块化 — 状态库 (`store/`)、钩子 (`hooks/`)、布局壳 (`layout/`：活动栏、侧面板和文件树、磁贴网格、状态栏)、文件编辑器 (`FileTile.tsx`，CodeMirror)、命令注册表 (`commands/`)、主题令牌系统 (`theme/`)、架构驱动的设置 (`settings/`）、以及引导程序。 - **后端** (`desktop/src-tauri/src/`): Rust/Tauri — `lib.rs` （`PtyManager` + 命令 + Windows npm-shim 分辨率）、`control.rs` （HTTP 控制服务器 = 隧道中心 + 工作器登记册）、`engines.rs` （每引擎适配器 + 模型/努力/角色 + MCP/技能注入）、`worktree.rs` （隔离 + 合并）、`memory.rs` （路由器内存）、`fsops.rs` （文件读写/列表，用于应用内编辑器）、`workspace.rs`、`settings.rs` （配置 + 元代理 + GLM 配额）、`browser.rs` （原生 webview）。 - **代理的大脑** (`desktop/agent/`): 角色感知的 MCP 服务器（路由器工具 — `spawn_worker`, `send_to_worker`, `review_worker`, `merge_worker`, `ask_user`, `save_memory`, `list_playbooks`, `load_playbook` — 与工作器工具 — `report_to_router`, `ask_router`），以及下面的三个文本层。 ### 三个层：角色、剧本、技能 隧道使代理**对话**。这些是使它们**知道如何一起工作**。 | | 是什么 | 谁拥有 | 何时 | |---|---|---|---| | **角色** (`agent/*-role.md`) | 你是谁，你的工具，**你如何工作** | 路由器 / 工作器 | **始终**（系统提示） | | **剧本** (`agent/playbooks/`) | 你如何**编排**这种类型的项目 — 在分发前冻结的分割，在工作人员之间，什么首先启动，以及“完成”的验证门 | **路由器** | **按需** (`load_playbook`) — 它只为它使用的一个付费上下文； | | **技能** (`agent/skills/`) | **领域**知识，用于任何人完成工作 | **工作器** | 按需 (`spawn_worker({skills})`) | 剧本是**编排，而不是领域知识**：`landing-3d` 不教您 Three.js — 它告诉路由器如何将 3D 登陆页面分成四个代理，哪些工作器是关键路径，什么是“完成”的含义。它们是从**真实运行**中转录的，而不是发明的：[`landing-3d`](desktop/agent/playbooks/landing-3d.md) 是构建 [此网站](https://mats2208.github.io/hyprdesk/) 的剧本。 技能被注入为**文本到代理的角色**，因此它们适用于**任何引擎** — Claude, Codex 或 OpenCode。 ### 它如何委托 ```mermaid sequenceDiagram actor You participant R as 路由器 participant H as 控制服务器 participant W as 工作器 You->>R: "构建一个带有后端和前端的商店" R->>H: spawn_worker(task, engine|profile) H->>W: 一个 PTY 被创建 + 任务被注入 W-->>W: 独立工作（自己的分支） W->>H: report_to_router(summary, paths) H->>R: 将报告注入其 PTY R->>H: review_worker → merge_worker R->>You: 审查，迭代或委托下一步 ``` ## 支持的引擎 | 引擎 | 路由器 | 工作器 | 注入角色 | |--------|:------:|:------:|------------------| | Claude Code | ✅ | ✅ | `--append-system-prompt` | | Codex | ✅ | ✅ | `-c developer_instructions=…` | | OpenCode | ✅ | ✅ | 配置中的 `instructions` | ## 仓库布局 ``` desktop/ → HyprDesk 应用（Tauri v2 + React + Rust） — 主项目 src/ 前端：store/ · hooks/ · layout/ · commands/ · theme/ · settings/ · onboarding/ src-tauri/src/ Rust 后端（PTYs，隧道，引擎，工作树/git，工作区，内存） mcp/ 角色感知的 MCP 服务器 + 角色（路由器/工作器） cli/ → 早期原型：独立路由器→工作器 CLI 协调器 ``` ## 安全 默认情况下，代理在**自主模式**下运行（权限绕过： `--dangerously-skip-permissions` 在 claude 上， `--dangerously-bypass-approvals-and-sandbox` 在 codex 上，开放权限在 opencode 上），因此它们在没有每次请求批准的情况下工作 — 这就是委托的意义。切换到 **“询问”** 模式在设置中审查每个编辑/命令。爆炸半径是工作区文件夹。**在受信任的本地机器上运行，带有受信任的任务和输入。** ## 路线图 **已完成** - [x] 工作区 + 持久性（恢复）+ 卫生环境 - [x] 双向 MCP 隧道 + 可混合的多引擎（claude/codex/opencode） - [x] 多工作区保持活动在选项卡中 - [x] 打开外部文件夹（链接，非破坏性） - [x] 原生桌面集成 — macOS **和** Windows（菜单，窗口，npm-shim CLI 分辨率） - [x] AI 构建的代理配置文件（每个工作区：模型/努力/角色）+ 手动配置文件 - [x] 工作器重用 (`list_workers`) + 路由器作为领导者 - [x] git 工作树每个工作器 + 路由器合并回 - [x] 可配置的权限模式（自动 / 询问） - [x] 委托配置文件 (`list_profiles`) + `ask_user` - [x] 合并前由批评者审查 (`review_worker`) + 路由器在会话之间保存内存 - [x] 一次启动一组配置文件 - [x] **高级，近单色 UI** （VS Code *Dark Modern* 启发的）带有黑暗 / 浅色 / 高对比度主题 - [x] **架构驱动的设置** （主题 · 字体 · 提供者 API 密钥 · 可重新映射的键绑定）+ 引导 - [x] **内置文件编辑器** （CodeMirror）+ 文件树 — 打开，编辑和保存任何工作区文件 - [x] **Windows 支持** — npm-shim CLI 分辨率，独立的 MCP 包，本地路径 - [x] **始终在线的令牌效率** — [Ponytail](https://github.com/DietrichGebert/ponytail) 技能注入到每个代理 - [x] **编排鲁棒性** — 交付确认，崩溃安全的工作树，死工作器通知 **下一个** - [ ] 每个工作区的隧道路由（多窗口）· 将工作器恢复到它们的工作树中 - [ ] 路由器为每个工作器建议的领域技能（UI / 后端 / 测试） - [ ] Linux 支持 · 应用程序签名/验证 · 新的截图 - [ ] 贡献 ## 贡献 欢迎提交问题和 PR — 先阅读 **[CONTRIBUTING.md](CONTRIBUTING.md)**（有一条规则：*功能代码最小化，无膨胀*）。 ```bash cd desktop && pnpm install pnpm tauri dev # 带有热重载的窗口 ``` 然后 **运行应用程序并使用您更改的内容** — 这驱动真正的 PTY 和真正的代理，因此绿色类型检查证明很少。 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 隧道、PTY、worktree 和会话持久性等实际工作原理，包括我们已经遇到的陷阱。 在触摸后端之前阅读它。 - **[AGENTS.md](AGENTS.md)** — 如果您将编码代理指向此仓库。 - **[TODO.md](TODO.md)** — 下一步。 ## 许可证 在 **[MIT License](LICENSE)** 下发布 — © 2026 Mateo ([@Mats2208](https://github.com/Mats2208)). <div align="center"> **使用 Rust · React · Tauri v2 · 通过 [MCP](https://modelcontextprotocol.io) 连接** 如果 HyprDesk 对您有帮助，请在社区中为它加星并分享。 </div>