vigil

# Vigil ### 停止成为代码代理的消息总线 Vigil 为 Claude Code、Codex 和 OpenCode 提供了一个实时的管理器-工作树，每个节点都保留其原生 TUI 和完整的会话历史。详细信息向下流动，摘要向上汇总，管理器的上下文保持精简。 <p align="center"> <a href="https://www.youtube.com/watch?v=HsmSL7V-QOc"> <img src="./docs/media/social-preview.png" alt="观看 Vigil 协调实时代码代理树" width="100%" /> </a> </p> <p align="center"> <a href="https://www.youtube.com/watch?v=HsmSL7V-QOc"><strong>观看演示</strong></a> · <a href="https://butterlatte-zhang.github.io/vigil/"><strong>访问官网</strong></a> · <a href="https://github.com/butterlatte-zhang/vigil/releases/latest/download/Vigil-macos.dmg"> <img src="./docs/media/macos-badge.png" alt="下载 Vigil for macOS" width="180" /> </a> </p> <p align="center">_{macOS 14+ · Apple Silicon · 已签名和 notarized · 本地优先}</p> ## 功能 <table> <tr> <td width="40%" valign="middle"> <h3>树形结构，由管理器运行</h3> 将三个问题交给根管理器：它为问题 #1 和 #2 各自创建一个工作器，并将问题 #3 交给一个子管理器，子管理器再创建三个工作器。当工作器完成后，它们的結果会汇总到管理器的终端：详细信息向下流动，摘要向上汇总，管理器的上下文保持精简。顶部右侧的节点树实时显示整个树。 </td> <td width="60%"> <img src="./docs/media/tree-demo.png" alt="根管理器将三个问题分发到工作树，并收集汇总的结果" width="100%" /> </td> </tr> <tr> <td width="40%" valign="middle"> <h3>混合任意代理 CLI</h3> Claude Code、Codex 和 OpenCode 在同一棵树中协作：在这里，在一个 Claude 根节点的树中，问题 #3 的子管理器是 Codex — 使用相同的 Vigil 工具（spawn / send / kill / report）委托下去。每个节点都是 CLI 的原生 TUI；打开它并直接接管。 </td> <td width="60%"> <img src="./docs/media/codex-sub-manager.png" alt="Codex 作为子管理器，在 Claude 根节点树中创建工作器" width="100%" /> </td> </tr> <tr> <td width="40%" valign="middle"> <h3>完整的历史记录</h3> 每个节点的转录指针都被记录：已完成的会话保留在侧边栏中，打开一个会话会重建整个树 exactly 如它运行时一样 — 只读重放任何节点的完整转录，内置审计追踪每个代理实际执行的操作，根节点的会话信息和 token 使用情况也包含在内。按 Enter 键在每个 CLI 的原生机制下恢复。 </td> <td width="60%"> <img src="./docs/media/history-replay.png" alt="只读重放已完成的会话：历史树、完整转录和根节点的用法信息，按 Enter 键恢复" width="100%" /> </td> </tr> </table> - **设置是文件** — 所有配置都存放在 `~/.config/vigil/` 下的 JSON 文件中；没有设置面板（参见 [配置](#配置)） - **灵活的隔离** — 节点可以共享一个项目，具有明确的文件所有权或使用 `git worktree`；Vigil 从不强加隐藏的沙盒或分支策略 - **诚实是一条硬性规则** — 未检测到的代理 CLI 从不显示为可用；无法传递的消息会报错，而不是假装已发送 - **从不选择模型** — 模型按代理家族命名；如果整个链为空，Vigil 不传递模型标志，让 CLI 使用其自己的默认值 - **原生 macOS 应用** — 使用 Swift + SwiftUI 构建，而非 Electron - **GPU 加速** — 终端渲染由 libghostty 提供支持 - **键盘快捷键** — 跨会话、节点和通知的完整键盘导航，所有快捷键均为 ⌘ 修饰，以避免与代理的 TUI 冲突（参见 [键盘快捷键](#键盘快捷键)） - **开源** — GPL-3.0-or-later ## 安装 ### DMG（推荐） <a href="https://github.com/butterlatte-zhang/vigil/releases/latest/download/Vigil-macos.dmg"> <img src="./docs/media/macos-badge.png" alt="下载 Vigil for macOS" width="180" /> </a> 打开 `.dmg` 文件并将 Vigil 拖入您的应用程序文件夹。 首次启动时，macOS 可能会要求您确认打开来自已识别开发者的应用程序 — 点击 **打开** 继续。要求：macOS 14 或更高版本，Apple Silicon，并且在您的 `PATH` 中至少有一个代理 CLI：[Claude Code](https://code.claude.com)、[Codex](https://github.com/openai/codex) 或 [OpenCode](https://opencode.ai)。 ### 从源代码构建 需要 Xcode 26.2 / Swift 6.2.3： ```sh git clone https://github.com/butterlatte-zhang/vigil.git cd vigil/app swift run Vigil ``` 首次启动时，Vigil 会探测您的 `PATH` 中的已安装代理 CLI（claude → codex → opencode）并从中找到的内容初始化其注册表。打开一个项目，选择一个代理，输入一个任务，管理器就会启动。如果找不到代理 CLI，启动器会显示一个警告横幅而不是假装。 ## 为什么是 Vigil？ 运行许多代理并行会使 *您* 成为消息总线：计划器发出子任务提示，您手动打开 N 个终端，一个一个粘贴提示，然后手动在它们之间传输输出。代理树已经意味着一种结构 — Vigil 保留这种结构并自动化传输。 大多数基于终端的多代理工具扩展 *数量* 的代理：N 个并排会话，您在它们之间切换，所有对等节点，没有层次结构，每个节点都有自己的完整上下文。Vigil 扩展的是编排的 *深度* — 一个保持高级别的管理器，而工作器树处理细节，每个级别都有有限的上下文，汇总信息向上流动。您做出的权衡是结构：具有单父路由和级联杀死的树，而不是开放的网格。这种结构是重点 — 它使注意力、通信成本和上下文在树增长时不会爆炸。 ## Vigil 之道 Vigil 不会规定您如何使用代理。 **零输入接管。** 中央面板是一个真正的终端 — 也是唯一的输入表面。审批、对话和定向讨论都发生在每个工具的原生 TUI 中；权限通过代理的原生机制（例如 `claude --permission-mode`）进行。Vigil 观察和导航；它从不代表您按键。 **原始操作，而不是脚本。** spawn / send / kill / report 是仅有的结构操作，作为 MCP 工具暴露给代理，应用程序实际执行。树形结构和谁执行什么由您和您的管理器决定。 **先有事实真相。** 节点的身份是它启动的 CLI，而不是代理声称的身份；未检测到的节点不会被点亮；无法传递的消息会报错。观察层显示的每个状态都有可验证的事实作为支撑。 ## 键盘快捷键 每个全局快捷键均为 ⌘ 修饰 — 终端是唯一的输入表面，裸键、Escape、⇧Enter 和 Ctrl 家族直接传递给代理的 TUI。Vigil 不拦截任何这些按键。 ### 会话 | 快捷键 | 操作 | |----------|--------| | ⌘ T | 新会话（在当前项目中打开启动器） | | ⌘ O | 添加项目… | | ⌘ 1–9 | 跳转到会话 1–9 | | ⌃ ⌘ ] | 下一个会话 | | ⌃ ⌘ [ | 上一个会话 | | ⌘ ⇧ R | 重命名会话 | | ⌘ ⇧ W | 关闭会话 | ### 节点和通知 | 快捷键 | 操作 | |----------|--------| | ⌘ ⇧ ] | 下一个节点 | | ⌘ ⇧ [ | 上一个节点 | | ⌘ ⇧ U | 跳转到最新等待您的代理 | ### 面板 | 快捷键 | 操作 | |----------|--------| | ⌘ J | 显示/隐藏底部终端 | | ⌘ B | 显示/隐藏侧边栏 | | ⌘ , | 打开用户配置（打开 `~/.config/vigil` 作为项目） | ## 配置 所有内容都位于 `~/.config/vigil/` 下的文件中。注册表、角色和提示更改在下一次 `spawn` 时生效；运行时和外观更改会被监视并实时应用。 | 文件 | 控制内容 | |---|---| | `agents.json` | 代理注册表（= 启动器下拉列表）：二进制路径、类型、模型列表、额外参数、环境变量。同一类型的多个条目 = 多个提供者/代理。缺少的文件会回退到内置的 Claude 条目。注意：代理直接启动（无登录 shell），因此 shell 别名/函数和 `.zshrc` 导出不适用 — 将代理、基本 URL 和密钥放入条目的 `env` 中，将包装函数标志放入 `extraArgs` 中。 | | `roles.json` | `root` / `subManager` / `worker` 的每个角色设置：代理、模型、访问级别和提示追加/覆盖。项目级 `<repo>/.vigil/roles.json` 覆盖字段。 | | `prompts.json` | 每个角色（`root` / `subManager` / `worker`）注入的身份文本 + `extras` 块，用于机械追加的行（工具搜索 / 懒加载工具恢复，opencode 自己的行，根节点的重命名提示）。在首次启动时使用所有键设置为字符串 `"default"` 的内容进行种子；一旦存在，永不重写。空白、 `"default"`、缺失或 JSON `null` 的值使用 Vigil 的内置文本（它会随着版本演变）；任何其他文本都会逐字替换 — 删除文件以重新生成当前默认值，或删除/空白单个键以回退到该键的默认值。 `roles.json` 的 `promptOverride` 仍然替换整个组件（包括额外内容）；`promptAppend` 仍然追加在最后。 | | `launcher.json` | 启动器默认值（目前仅默认代理）。 | | `runtime.json` | 重新审视时间、注入阀门、侧边栏阈值、自动命名等 — 实时应用。 | | `appearance.json` | 主题和外观 — 实时应用。 | | `detected.json` | 每次启动时由 CLI 探测器重写；已安装类型的真实来源。 | 模型按家族命名：角色的 `model` 仅在其代理家族内绑定（claude / codex / opencode），因此 Claude 模型别名无法泄漏到 Codex 节点。如果整个链为空，Vigil 不传递模型标志，让 CLI 使用其自己的默认值 — Vigil 从不代表您选择模型。 ## 工作原理 状态仅单向移动。所有突变作为 `Command` 进入并作为 `Effect` 离开，都通过单个 `SessionStore` — 真相的唯一来源（一个 `@Observable` 单向存储）。UI 读取存储，从不直接触摸单元格；单元格从不触摸 UI；单元格从不触摸其他单元格。子树间流量始终通过最低共同祖先，因此通信图 *是* 树，不能形成循环。 每个节点在托管 PTY 内运行真正的代理 CLI。编排原语作为 MCP 工具暴露给代理，该工具表面由身份范围限定：根管理器获得 `spawn` / `send` / `kill`，子管理器还获得 `report`，叶工作器仅获得 `report`。这使得委托、通信和报告作为真正的工具调用，应用程序执行 — 而不是代理可能忽略的文字。 ## 会话重放和恢复 每个会话都保存在 `~/Library/Application Support/Vigil/sessions/<id>/` 下：编排事件流（spawn / send / kill / report）加上每个节点的转录。 已完成的会话保留在侧边栏中，按项目分组： - **点击** = 只读重放 — 树形骨架重建 exactly 如它运行时一样；重放任何节点的终端并审计每个代理实际执行的操作。 - **Enter** = 恢复 — 会话通过每个 CLI 的原生机制恢复（`claude --resume`、`codex resume`、`opencode --session`），包括之前的树形骨架。历史树中已死的 worker 可以同样的方式恢复 — 会话和节点恢复。 进程死亡和会话死亡是解耦的：会话安静后会被静默地清理，点击一下即可恢复，输入 Enter 键即可恢复 — 退出从不丢失任何内容。 ## 状态 Pre-1.0，正在积极开发中。Vigil 正在使用 *内部* 运行代理树 — 它自己使用上述编排模型。预计会有粗糙的边缘，预计配置界面和默认值会不断变化。 ## 贡献 欢迎贡献。通过贡献，您同意 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 中的许可条款。 - 打开并加入 GitHub 问题和讨论 - 分享您使用 Vigil 进行编排的内容 ## 许可证 Vigil 在 GPL-3.0-or-later 下开源。 如果您的组织无法遵守 GPL，请参阅 [商业许可](./COMMERCIAL-LICENSE.md)。