内容
# 巢穴
**一款开源的智能开发环境：一个常驻 AI 协调器，带有记忆，一支隔离在 git 工作树中的编码工作者舰队，以及一个任务控制中心 — 所有这些都在您的机器上运行。**
一个长寿命的守护进程托管 **主代理** 会话，注册您的仓库，记住项目上下文，并生成 **工作者** 在并行编码 — 每个工作者都在其自己的 git 工作树和分支中，在您选择的 AI 后端（**Claude 或 Codex**）。桌面应用程序、CLI 和 Slack 是薄客户端：您可以随时关闭它们，守护进程将继续工作。
<p align="center">
<img src="https://github.com/user-attachments/assets/a4eb2001-deaf-4738-92c1-435d1b216ce6" alt="用自然语言提问 → 主代理生成工作者 → 审查者自动生成 → 注意力铃声告诉您需要什么" width="920">
</p>
观看完整的 90 秒演示 — 真实运行：真实工作者，真实提交，真实自动化。
https://github.com/user-attachments/assets/38face67-d553-4c51-9741-b0942ca337cd
<table>
<tr>
<td width="50%"><img src="https://github.com/user-attachments/assets/3b339393-c0ec-4bdb-8e81-8817dae8d845" alt="舰队：每个仓库的工作者，状态，后端和成本 — 每个工作者都有自己的记录和终端"></td>
<td width="50%"><img src="https://github.com/user-attachments/assets/f9cb81ec-31d8-4e40-a790-e50cccc673aa" alt="自动化规则：cron，间隔，Slack 和工作者结算触发器驱动主代理或工作者生成"></td>
</tr>
<tr>
<td align="center"><sub><b>舰队</b> — 每个仓库的工作者，状态，后端和成本；每个工作者都有自己的记录，差异和终端。</sub></td>
<td align="center"><sub><b>自动化</b> — cron / 间隔 / Slack / 工作者结算触发器，带有每个规则的模型，后端和预算。</sub></td>
</tr>
<tr>
<td colspan="2"><img src="https://github.com/user-attachments/assets/b958b17d-2bc6-4776-a65e-84e4d9267829" alt="注意力铃声排名当前需要您关注的内容：阻塞的问题，失败和未审查的结果"></td>
</tr>
<tr>
<td colspan="2" align="center"><sub><b>注意力铃声</b> — 一个排名队列，列出当前需要您关注的内容：阻塞的问题，失败和未审查的结果。</sub></td>
</tr>
</table>
## 为什么选择巢穴
- **始终在线，不受标签限制。** 守护进程拥有会话，工作者，记忆和自动化。客户端连接和断开；夜间运行不受影响；对话在重新连接时恢复 — 包括工具调用和推理。
- **真正的舰队，安全并行。** 每个工作者都有自己的工作树 + 分支（`rookery/<id>`）。没有任何内容影响您的检出；您审查差异并告诉工作者提交，推送和打开拉取请求。
- **两个大脑，一个控制平面。** 主代理，工作者，自动化和 Slack 线程各自选择后端 — Claude 或 Codex — 带有每个表面模型/努力控制，实时模型目录，甚至 **跨提供商分叉** （在 Codex 上继续 Claude 对话，或反之亦然）。
- **反应灵敏的舰队，不只是服从。** 自动化在计划（cron / 每 N 分钟），Slack 消息或 **当工作者结算** 时触发 — 因此“实现工作者完成 → 生成审查者在其分支上”是一种规则，而不是一种仪式。
- **诚实的信号。** 工作者状态是真实的：`idle` 表示 *所有已分配的工作都已完成* — 工作者在后台 shell 上等待显示 `background`，并且仅在真正的终点处触发完成通知。 **注意力铃声** 排名当前需要您关注的内容：阻塞的问题，失败和未审查的结果。
- **驱动并被驱动。** 从 Slack （线程 = 会话）或公开舰队作为 **MCP 服务器** 并从 Claude Code，Cursor 或 Codex 驱动巢穴 — 代码从未离开您的机器。
- **无人值守工作的防护栏。** 每个工作者/自动化的生命周期美元预算，回合上限，针对不受信任的输入（Slack 文本，工作者输出）的提示注入防护，以及 everywhere 失败关闭的默认值。
## 您可以使用巢穴做什么
### 任务控制（桌面）
会话和实时舰队的概览：流式对话，带有计划卡和指标，每个工作者的记录/差异/检查点/成本，集成的工作区（文件资源管理器，git 面板，Monaco 编辑器/差异，终端在每个工作树中），可停靠的窗格和带有 Claude 和 Codex 标签的使用仪表盘。韩语/英语用户界面。
从聊天中自然语言生成工作者，从生成对话框或 **直接从 GitHub 问题或 Linear 票** — 任务从票证正文中预填充。
### 能力中心
注册一个本地能力包，查看其完整的文件摘要，并将其分配给
所有 Rookery 或存储库，会话或工作者。受众过滤器针对主代理，
工作者或 Side 代理以及 UI，Slack，自动化或外部来源。更具体的
分配覆盖更广泛的分配，包括已禁用的分配用作墓碑。
**目录** 选项卡处理注册，验证，信任，刷新，删除和仅写入机密；
**分配** 管理范围和受众； **有效** 显示本机库存加上
Rookery 或已注册存储库预览的确定性所需状态，或实时主代理或工作者的所需和应用的修订版。预览目标允许您选择 Claude 或
Codex 和主代理或工作者，然后再开始对话。 Rookery 预览故意
仅限于范围；提供商本地全局库存需要一个具体的存储库或实时目标。
受信任的软件包适用于 **Claude 和 Codex**，无需更改用户的 `~/.claude`，
`~/.codex/config.toml` 或存储库提供商文件。说明会追加到回合
提示。Claude 通过生成的本地插件加载技能和 MCP；Codex 从
Rookery 拥有的，特定于目标的 `CODEX_HOME` 目录加载它们。主代理在他们的
下一个回合时更新；新启动或延迟恢复的工作者会在其提供商流打开时应用一次。已经运行的工作者报告 **需要重新加载**，可以立即重新加载
（空闲时）或在当前回合边界安排重新加载。重新加载保留工作者
行，工作树，记录，提供商本地对话，模型，努力，权限模式
和生命周期预算。
对于常见路径，请使用 **目录 → 添加 MCP** 或 **导入技能**。每个操作都会创建一个
未经信任的单一生成的软件包，而不启用任何地方。审查和信任条目，
然后使用 **设置 → 能力** 进行广泛的 Rookery 默认设置或
**存储库 → 存储库设置 → 能力** 进行存储库覆盖。每个行选择
`继承`，`启用` 或 `禁用` 独立于 UI 启动的主代理和工作者代理，
并且可以在不创建会话或工作树的情况下打开匹配的有效预览。自定义受众
混合 UI 和 Slack/自动化/外部或 Side 仅在高级分配中可编辑。
要添加多个 MCP 服务器作为一个原子包，请使用 **目录 → 构建 MCP 包**。
选择一个已注册的存储库并添加任意数量的 stdio 或 Streamable HTTP 服务器，
包括参数边界，公共环境/标头值，写入机密环境/标头值，
承载身份验证，工具允许/拒绝列表和所需服务器行为。 Rookery 编写一个
私有公共仅限清单在 `~/.rookery/capability-packs/` 下，
单独存储机密值，并为选定的主代理/工作者受众创建启用的存储库本地 UI 绑定。
新的软件包在您展开其突出显示的目录卡，审查它并信任确切的摘要之前保持不受信任。此流程创建和删除生成的软件包；
编辑现有的生成的软件包，请删除并重新创建它在此 UI 版本中。
在活动的主代理或工作者聊天中，斜杠自动补全从该确切
会话的能力快照中解析。 `/capabilities`，`/skills`，`/hooks` 和 `/mcp` 打开
匹配的能力中心视图，而 `/btw` 和 `/side` 使用相同的操作注册表
打开一个 Side 问题。托管的技能仅当选定的目标可以调用它们时才插入
提供商原生语法（Claude 的 `/name` 和 Codex 的 `$name`）；库存仅提供商命令
不作为死亡提示提供。
已注册的存储库可以检查一个选择加入的共享索引在
`.rookery/capabilities.json`；其包路径包含在
`.rookery/capabilities/` 下。 Rookery 发现并监视这些软件包，但绝不信任或
自动绑定它们。内容更改使确切的摘要信任决策无效，直到新的摘要被审查。
删除，禁用或删除索引条目是该存储库拥有的目录行的权威墓碑。
从 [`docs/examples/capability-pack`](docs/examples/capability-pack/) 开始：
1. 打开能力中心 → 目录并导入示例包目录。
2. 审查文件和公共 MCP 配置，然后信任显示的摘要。
3. 如果需要保存声明的机密；机密值绝不会返回到 UI。
4. 创建分配，运行下一个 Claude 或 Codex 回合（或启动/恢复匹配
的工作者），并检查匹配的所需/应用的修订版的有效。
使用以下命令运行隔离的 Slice 9 预览边界烟雾测试：
```bash
npm run build && npm run smoke:capabilities:slice9
```
Rookery 将受信任的字节复制到一个不可变的
`~/.rookery/capability-runtime/<revision>/` 目录启动时。生成的
文件仅包含环境别名；写入机密值仅在选定的提供商
子环境中传递，并且绝不会返回到 UI 或写入插件/TOML
配置中。 Codex 主代理和工作者各自接收一个单独的生成的家，
配置，滚动树和机密别名覆盖。对于带有包相对 `cwd` 的 stdio MCP，
Rookery 在不可变的运行时生成一个小的 Node 启动器，以便
声明的工作目录被尊重而不调用 shell。
对于带有机密的 Codex 启动，Rookery 还禁用 Codex shell 快照并删除
托管的别名在模型调用的 shell 环境中使用固定公共覆盖；
没有机密名称或值被放置在 argv 中。
在守护进程启动时，Rookery 仅保留有效的 schema-2 运行时修订版仍然
由一个权威会话或工作者期望，并删除过时的修订版和中断的暂存
目录而不遵循符号链接。
### 舰队
主代理跨注册的存储库路由任务，生成工作者，监视它们，引导它们（发送后续/中断），并在它们完成时唤醒。后续指令继续相同的
工作者会话，具有完整的上下文。守护进程重新启动后，工作者从磁盘重新水化 — 差异，停止和恢复保持工作。
### 自动化
规则 = **触发器 × 操作**，在自动化页面构建：
| 触发器 | 操作 |
|---|---|
| Cron 时间表 · 每 N 分钟 · Slack 消息匹配 · **工作者结算** （空闲 / 停止 / 失败） | 运行主代理回合 · 生成工作者 |
模板变量（`{{message}}`，`{{branch}}`，`{{tail}}`，…）将触发器的上下文带入提示 — 始终作为不受信任的输入进行保护。失败在注意力铃声中显示。
### Slack
线程是一个会话：提及 `@rookery` 或使用助理面板，并且相同的线程在守护进程重新启动时保持相同的对话。工具调用呈现为实时计划卡；工作活动可以中继到一个频道。访问是允许列表控制的，并且关闭失败。参见下面的 [Slack 设置](#slack-设置)。
### 从其他代理使用 Rookery （外部 MCP）
将舰队公开为 MCP 服务器（**设置 → 通用 → 外部 MCP**，默认为关闭）：
```bash
claude mcp add rookery --transport http "http://127.0.0.1:8787/mcp-ext/<token>"
```
- **只读**：列出工作者，检查状态/记录/差异。
- **完全控制**：还可以生成，引导和停止工作者。
> ⚠️ 完全控制允许外部代理驱动以 `bypassPermissions` 运行的工作者。仅为受信任的客户端启用；如果 URL 泄漏，请从设置中旋转令牌。
## 安装
- **macOS (Apple Silicon):** [⬇ `.dmg`](https://github.com/CChuYong/rookery/releases/latest/download/rookery-arm64.dmg)
- **Linux (x86_64):** [⬇ `.AppImage`](https://github.com/CChuYong/rookery/releases/latest/download/rookery-x86_64.AppImage)
- **Windows (x64):** [⬇ `.exe` 安装程序](https://github.com/CChuYong/rookery/releases/latest/download/rookery-x64-setup.exe)
## 快速入门
**桌面应用程序 — 无需先决条件。** 下载它上面，启动，完成：应用程序捆绑其自己的 Node 运行时并为您启动和管理守护进程。第一个运行检查清单将引导您完成其余部分 — 连接 Claude （在设置中粘贴 API 密钥，或自动拾取现有的 `claude 登录`），选择一个工作文件夹，启动会话并生成您的第一个工作者。 Codex 是可选的 — 认证 `codex` CLI 或设置应用密钥以解锁第二个后端。
**无头 / CLI** — 需要 **Node.js ≥ 22**：
```bash
export ANTHROPIC_API_KEY=sk-ant-...
node dist/index.js daemon # 在前台运行守护进程
node dist/index.js # 或使用 CLI（如果没有运行的守护进程则自动启动）
```
从源代码构建（Node.js ≥ 22）：
```bash
npm install && npm run build # 守护进程/CLI → dist/
npm -w apps/desktop run dev # 桌面应用程序（开发），从 Node 22 shell 运行
```
架构和贡献者文档位于 [`docs/`](docs/README.md) （从那里开始）和 `AGENTS.md`。
## 后端和身份验证
两个后端到达相同的编排和工具；每个会话/工作者/自动化/Slack 线程选择后端 — Claude 或 Codex（或 CLI 上 `--provider claude|codex`）。
- **Claude** — 应用内 API 密钥（**设置 → Anthropic API 密钥**）或 `ANTHROPIC_API_KEY`；回退到 Claude Code OAuth（`claude 登录`）。所有权限模式支持。
- **Codex** — 应用内密钥（**设置 → Codex API 密钥**）或 `codex 登录`。模型/努力选择器由实时模型目录驱动。 Codex **主代理** 仅 `bypassPermissions`（工作者不受影响）。
## 数据处理
**离开您机器的内容：** 提示和响应，引用的存储库代码/差异/终端输出，以及（如果连接）Slack 消息文本 — 发送到运行它们的 LLM 提供商。Claude 表面与 Anthropic 聊天；Codex 表面将相同的数据路由到 OpenAI。提供商始终明确并且可为每个表面选择 — 在指向第二个供应商的敏感代码之前请查看它。
**保留本地内容：** 所有其他内容。会话历史，记忆，集成令牌，日志和工作者工作树生活在 `~/.rookery` 下（在启动时强化为 `0700`/`0600`）。桌面应用程序在首次运行显示一次性数据传输同意屏幕。
## 安全注意事项
主代理和工作者以 `permissionMode: "bypassPermissions"` 运行（无头守护进程没有 TTY 用于批准提示）：他们自动批准工具使用，包括 bash 和文件写入，在他们的工作目录中。工作树隔离将工作者包含在他们自己的副本中，并且 USD 预算/回合上限绑定运行成本 — 但仅在受信任的环境和路径上运行rookery。
## Slack 设置
1. 在 https://api.slack.com/apps 创建一个应用。
2. 启用 **Socket 模式** → 发出 App 级令牌（范围 `connections:write`）→ `SLACK_APP_TOKEN`（xapp-…）。
3. **OAuth & Permissions** → Bot Token Scopes：`assistant:write`，`chat:write`，`app_mentions:read`，`im:history`，`channels:history` → 安装到工作区 → `SLACK_BOT_TOKEN`（xoxb-…）。
4. 启用 **Agents & Assistants** 功能；订阅 `app_mention`，`assistant_thread_started`，`message.im` 和 `message.channels`（Slack 自动化触发器所需；邀请机器人到目标频道）。
粘贴两个令牌到 **设置 → Slack** （或导出它们作为无头运行的环境变量）。允许列表是关闭失败的：空允许列表和允许所有关闭时，禁止所有人。 Slack 线程默认在 Claude 上运行；`slackProvider: codex` 切换它们（仅 `bypassPermissions`，像所有 Codex 主代理一样）。
## 许可证和第三方通知
rookery 的源代码在 [Apache License 2.0](LICENSE) 下许可。
⚠️ rookery 建立在 **Anthropic Claude Agent SDK** 上，这是 **专有软件（ Anthropic PBC 版权所有，保留所有权利）** ，并且 **不受** 此 Apache-2.0 许可的保护。使用或分发 rookery 受 Anthropic 的 [商业条款](/www.anthropic.com/legal/commercial-terms) / [消费者条款](https://www.anthropic.com/legal/consumer-terms)，[使用政策](https://www.anthropic.com/legal/aup) 和 [Claude Code 法律条款](https://code.claude.com/docs/en/legal-and-compliance)。
简而言之： **自带凭证**；不要为其他用户共享或路由订阅凭证；多租户托管服务需要 Anthropic 的批准。 Apache-2.0 许可仅涵盖该项目的代码 — 查看 [NOTICE](NOTICE) 以获取完整的第三方通知。
