内容
<div align="center">
<img src="public/orca-mark.png" alt="Orca" width="96" />
# Orca
### 您编码代理的本地总部
Orca 是一个**本地优先的守护进程**，您的 Claude Code、Codex 或其他支持 MCP 的代理可以注册到该进程中进行工作。编排代理在严格的服务器强制合约下生成**执行器**代理；Orca 监督它们，捕获它们的输出，并显示整个舰队作为一个实时、只读的树，您可以从桌面或手机通过 Tailscale 观看。
您在正常的 CLI 或桌面代理中继续工作。Orca 是让这些代理依赖于**其他**代理而不会失去对其正在发生的事情的跟踪的工具。
[](LICENSE)
</div>
---
## Orca 的功能
您已经在运行编码代理。难点在于*协调*：哪个代理在哪个项目中工作，它生成了什么，是否完成，是否合格 — 以及如何在不亲自监护终端的情况下终止失控的代理。Orca 正是用于此目的的控制平面，并且仅此而已。
- **代理注册自己。** 代理告诉 Orca “在此注册”及其工作目录。Orca 隐含地创建了一个项目，以该目录为键，并将编排记录绑定到代理的作用域租约。任何支持 MCP 的代理都符合条件 — Orca 不关心 CLI 或版本。
- **编排器在合约下生成执行器。** 编排器向 Orca 提供任务；Orca 启动执行器，并带有正确的沙盒/权限标志和工作区监狱，代理无法逃脱。编排器编写指令；合约约束执行器可以执行的操作。
- **守护进程监督 — 您不需要。** Orca 拥有执行器进程，捕获其输出到进程自己的流 (`--json` / `stream-json`)，将进程退出视为权威完成信号，并回收无声挂起。无需询问代理“它怎么样？”。
- **您观察，不需要驱动。** 仪表板是**只读**的：项目 → 它们的编排器（每个编排器都有一个自我生成的标题）→ 它们生成的执行器，具有实时状态标签（`工作中`、`审核中`、`等待批准`、`已完成`）。已完成的执行器变灰并消失。唯一的控制是一个两阶段的**紧急停止**，用于失控的代理。
- **在您的手机上，私密地。** 仪表板是一个渐进式网页应用，通过您自己的 Tailscale 网络提供服务 — 没有公共暴露，HttpOnly-cookie 配对，关闭远程访问。
## 循环
```
您，在 Claude Code / Codex Orca 守护进程 仪表板（只读）
───────────────────────── ─────────── ─────────────────────
"在此注册" ──MCP──▶ 项目 = 现实路径（当前工作目录） ▶ ▸ 我的项目（网页/...）
编排器绑定到您 · 身份验证重构
"生成一个执行器来 X" ──MCP──▶ 启动，沙盒，捕获 ├ 重写范围 · 工作中
监督 → 退出 = 完成 └ 添加测试 · 已完成
```
## 快速入门
```bash
npm install
npm start # Orca 守护进程在 http://127.0.0.1:3000 (打开它：树)
```
通过 MCP 将代理指向它（编排器角色生成作用域租约）：
```bash
# 从您的 Orca 检出中运行 — 包未发布到 npm，因此请将客户端指向捆绑的服务器的绝对路径：
claude mcp add orca -- node "$PWD/src/mcp-server.js" # 或：codex mcp add orca -- node "$PWD/src/mcp-server.js"
```
然后，在该代理内，注册并生成：
```
在 Orca 中为我的当前目录注册，标题为“身份验证重构”
生成一个只读侦察执行器来总结 src/，然后报告回来
```
在 `http://127.0.0.1:3000` 或配置 Tailscale 后在手机上查看（参见 `docs/tailscale-mobile-access.md`）。
## 合约
执行器受三个服务器端网关的约束 — 而不是通过提示文本：
- **作用域工具租约** — 在每次 MCP/HTTP 调用时检查的 SHA-256 令牌允许列表，因此执行器只能调用其角色授予的工具。
- **现实路径工作区监狱** — 执行器在其编排器的目录（或每个通道的 git 工作树）中运行，无法逃脱。
- **CLI 的自身沙盒** — 例如 codex `--sandbox read-only` （操作系统强制执行的，真正的只读侦察）与 `--sandbox workspace-write` （写入被限制在工作区内）。
命名合约（只读*侦察*与可以写入和请求批准的*构建器*）将这些网关绑定在单个选择后面，正在开发中。
## 架构
零依赖的 Node HTTP 服务器 + 一个手工滚动的标准输入/输出 MCP 桥。单个始终运行的守护进程持有注册表（项目，编排器，执行器通道），调度程序启动和回收执行器，工具租约身份验证和 Tailscale/渐进式网页应用远程界面。状态是一个单独的本地 `.orca/state.json`；秘密永远不会离开盒子。
## 状态
在 macOS 上验证通过手机访问。注册 → 生成 → 监督循环已通过真实的 Claude 执行器验证（生成，运行在存储库中，输出捕获，完成）和两阶段紧急停止杀死活动代理。Windows/Linux 是未来的验证目标。这是一个正在积极发展的项目。
## 许可证
[Apache-2.0](LICENSE)。
