hyprdesk

<div align="center"> <img src="desktop/src/assets/brand/readme-hero.png" alt="HyprDesk — 路由器 → 工作线程" 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）并行委托给四个工作线程 — <strong>后端</strong>、<strong>前端</strong>、<strong>测试</strong>（Claude）和 <strong>视觉</strong>（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`） | | **审查** | 合并前审查 | 路由器读取工作线程的差异（`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 CLI 解析为其真实可执行文件在 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 CLI 被自动解析为其真实可执行文件。 ## 快速开始 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 后端<br/>PtyManager · 控制服务器 · git 工作树"] FE <-->|调用 / 事件| BE end BE -->|PTY| R["路由器代理<br/>claude / codex / opencode"] BE -->|PTY| W1["工作线程"] BE -->|PTY| W2["工作线程"] HUB(["控制服务器<br/>（隧道 · tiny_http）"] R <-->|MCP 工具| HUB W1 <-->|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(任务, 引擎|配置文件) H->>W: 创建 PTY + 注入任务 W-->>W: 自主工作（自己的分支） W->>H: report_to_router(摘要, 路径) 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 后端（PTY、隧道、引擎、工作树/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] **编排鲁棒性** — 交付确认，崩溃安全的工作树，死工作线程通知 **下一个** - [ ] 每个工作区的隧道路由（多窗口）· 将工作线程恢复到其工作树 - [ ] 路由器为每个工作线程建议的领域技能 - [ ] Linux 支持 · 应用签名/验证 · 新的截图 ## 贡献 问题和 PR 欢迎 — 先阅读 **[CONTRIBUTING.md](CONTRIBUTING.md)**（有一条规则：*功能代码最少，无膨胀*）。 ```bash cd desktop && pnpm install pnpm tauri dev # 带有热重载的窗口 # CI 运行的内容，在 Windows 和 macOS 上： pnpm exec tsc --noEmit pnpm build cd src-tauri && cargo clippy --all-targets -- -D warnings ``` 然后 **运行应用程序并使用您更改的内容** — 这驱动真正的 PTY 和真正的代理，因此绿色类型检查证明非常少。 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 隧道、PTY、工作树和会话持久性实际工作方式，包括我们已经遇到的陷阱。 在触及后端之前阅读它。 - **[AGENTS.md](AGENTS.md)** — 如果您将编码代理指向此存储库。 - **[TODO.md](TODO.md)** — 下一步是什么。 ## 许可证 在 **[MIT 许可证](LICENSE)** 下发布 — © 2026 Mateo ([@Mats2208](https://github.com/Mats2208)). <div align="center"> **使用 Rust · React · Tauri v2 · 通过 [MCP](https://modelcontextprotocol.io) 连接** 如果 HyprDesk 对您有帮助，请给它加星并与社区分享。 </div>