wehub-resource-sync
191c479d43
CI / gate (push) Failing after 3s
Doc sync / Classify and draft docs (push) Has been cancelled
CI / Pytest (tools) (push) Has been cancelled
CI / Pytest (codex-parity) (push) Has been cancelled
CI / Pytest (databricks) (push) Has been cancelled
CI / Pytest (inner-rest) (push) Has been cancelled
CI / Pytest (integration-mock) (push) Has been cancelled
CI / Pytest (repl-sdk) (push) Has been cancelled
CI / Pytest (runtime-policies) (push) Has been cancelled
CI / Pytest (server-approvals) (push) Has been cancelled
CI / Pytest (server-rest) (push) Has been cancelled
CI / Pytest (spec-llms) (push) Has been cancelled
CI / Pytest (misc) (push) Has been cancelled
CI / Pytest (runner-app) (push) Has been cancelled
CI / Pytest (runtime-core) (push) Has been cancelled
CI / Pytest (runtime-harnesses) (push) Has been cancelled
CI / Pytest (server-integration) (push) Has been cancelled
CI / Pytest (stores) (push) Has been cancelled
CI / Pytest (stores-postgres) (push) Has been cancelled
CI / Pytest (stores-mysql) (push) Has been cancelled
CI / Coverage report (push) Has been cancelled
401 lines
19 KiB
Markdown
401 lines
19 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/omnigent-ai/omnigent) · [上游 README](https://github.com/omnigent-ai/omnigent/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
|
||
# <img src="https://raw.githubusercontent.com/omnigent-ai/omnigent/main/docs/images/omnigent-logo.svg" alt="" height="38" valign="middle" /> Omnigent
|
||
|
||
### 面向所有 AI 智能体的开源元 harness（meta-harness）。
|
||
|
||
Omnigent 是一款开源 **元 harness（meta-harness）**，为 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 以及你自写的智能体提供统一的编排层：无需重写即可切换或组合 harness，执行策略与沙箱隔离，并从任意设备——终端、浏览器、手机或原生桌面应用——实时协作。
|
||
|
||
[](https://pypi.org/project/omnigent/)
|
||
[](https://github.com/omnigent-ai/omnigent/blob/main/LICENSE)
|
||
[](https://discord.gg/omnigent)
|
||
|
||
|
||
[omnigent.ai](https://omnigent.ai) · **[⬇️ 下载 macOS 桌面应用](https://omnigent.ai/download/mac)**
|
||
|
||
</div>
|
||
|
||
<p align="center">
|
||
<img src="https://raw.githubusercontent.com/omnigent-ai/omnigent/main/docs/images/omnigent-desktop.png" alt="Omnigent 桌面应用：新建会话，侧边栏中显示已固定和按项目分组的会话" width="720" />
|
||
</p>
|
||
|
||
---
|
||
|
||
## 为什么选择 Omnigent？
|
||
|
||
Omnigent 让你能够：
|
||
|
||
- **📱 在任意设备上使用智能体，包括手机。** 会话
|
||
随你而行：在终端开始，在浏览器继续，在手机上接着做。消息、子智能体、终端和文件保持同步。
|
||
|
||
- **🤖 监管多个智能体。** 在同一会话中混合使用 Claude Code、Codex、Cursor、OpenCode、
|
||
Hermes、Pi 以及自定义智能体（在 YAML 中定义）。让一个智能体审查另一个的工作，或将任务拆分给各有所长的多个智能体。
|
||
|
||
- **🔌 使用任意模型。** 第一方 API 密钥、Claude/ChatGPT 订阅
|
||
或任意兼容网关，均为一等公民。
|
||
|
||
- **🤝 协作。** 共享会话，让队友与你的智能体
|
||
聊天、实时观看其工作、在你的机器上共同驾驶，或分叉对话后在各自环境中继续。
|
||
|
||
- **☁️ 在云沙箱中运行智能体。** 无需笔记本电脑：在一次性 [Modal](https://modal.com), [Daytona](https://www.daytona.io),
|
||
[Islo](https://islo.dev), [E2B](https://e2b.dev),
|
||
[CoreWeave](https://docs.coreweave.com/products/sandboxes),
|
||
[Kubernetes](https://kubernetes.io), [OpenShell](https://github.com/NVIDIA/OpenShell),
|
||
[Boxlite](https://github.com/boxlite-ai/boxlite), 或
|
||
[Databricks](https://www.databricks.com) 沙箱中运行会话，可通过
|
||
CLI 启动，或由服务器按会话配置（*托管主机 managed hosts*）。
|
||
|
||
- **🛡️ 治理你的智能体。** 创建
|
||
[策略](#6-govern-your-agents-with-policies)，在危险操作执行前暂停等待你批准、
|
||
限制支出，或限制智能体可使用的工具。
|
||
策略可作用于整个服务器、单个智能体或单条聊天。
|
||
|
||
---
|
||
|
||
## 快速入门
|
||
|
||
### 1. 安装
|
||
|
||
一条命令即可安装 Omnigent 及其所需的一切：
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh
|
||
```
|
||
|
||
<details>
|
||
<summary>想手动安装？</summary>
|
||
|
||
Omnigent 需要 **Python 3.12+**。安装 `omnigent` 包：
|
||
|
||
```bash
|
||
uv tool install omnigent # or: pip install "omnigent"
|
||
```
|
||
|
||
或使用 [Homebrew](https://github.com/omnigent-ai/homebrew-tap):
|
||
|
||
```bash
|
||
brew install omnigent-ai/tap/omnigent
|
||
```
|
||
|
||
或直接从仓库安装：
|
||
|
||
```bash
|
||
uv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>工具链与先决条件（若安装程序提示缺少工具）</summary>
|
||
|
||
- **`uv`**（必需）。https://docs.astral.sh/uv/getting-started/installation/
|
||
安装程序可为你完成配置。
|
||
- **`git`**（必需）。
|
||
- **Node.js 22 LTS 或更高版本**，并安装 **`npm`**，用于通过 npm 安装的 coding
|
||
harness（Claude、Codex、OpenCode、Pi）。`omnigent run` 会安装你选择的
|
||
harness CLI。
|
||
https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
|
||
- **Kiro CLI**（可选），用于 `omnigent kiro`：使用
|
||
`curl -fsSL https://cli.kiro.dev/install | bash` 安装，然后用 Kiro 登录。
|
||
Kiro 工具审批可在嵌入式 Terminal 中响应；支持的一次性审批也会以 Chat 卡片形式出现。详见
|
||
`docs/kiro-native-elicitation.md`。
|
||
- **`tmux`**，原生 `omnigent <harness>` 终端包装器
|
||
（`claude`、`codex`、`cursor`、`hermes`、`kiro`、`pi`）
|
||
所需（`brew install tmux` / `apt install tmux`；安装程序可
|
||
为你安装）。
|
||
- **`bubblewrap`**（`bwrap`），**仅限 Linux**。原生 `omnigent <harness>`
|
||
终端包装器与 `pi` harness 将每个智能体
|
||
终端包裹在 `bwrap` 操作系统沙箱中；在 Linux 上该隔离为强制要求，因此缺少
|
||
`bwrap` 二进制文件会导致这些终端无法启动
|
||
（`apt install bubblewrap`；安装程序可为你安装）。macOS
|
||
使用内置的 `seatbelt` 沙箱，无需额外组件。
|
||
- **Databricks**（可选）。若要将 Databricks 工作区用作模型
|
||
提供方，请安装带 `databricks` extra 的 Omnigent：
|
||
`uv tool install "omnigent[databricks]"` —— 或在引导
|
||
安装程序中传入 `... | sh -s -- --extra databricks`。登录
|
||
工作区还需使用 [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/install).
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Windows（原生）</summary>
|
||
|
||
Omnigent 可在 Windows 上以降级模式原生运行。`install_oss.sh`
|
||
引导程序仅支持 POSIX，因此请直接用 `uv` 安装：
|
||
|
||
```powershell
|
||
uv tool install --python 3.12 omnigent
|
||
# or from the repo:
|
||
uv tool install --python 3.12 git+https://github.com/omnigent-ai/omnigent.git
|
||
```
|
||
|
||
Windows 上可用：`omnigent server`、Web UI，以及基于 SDK 的
|
||
harness（`omnigent run <agent.yaml>` 配合 claude-sdk / cursor / codex
|
||
harness）。智能体在 Windows **Job Object** 下运行，以 containment 进程树。
|
||
|
||
Windows 上**不可用**（这些功能请使用 Linux/macOS 或 WSL）：
|
||
|
||
- 原生 `omnigent claude` / `omnigent codex` / `omnigent cursor`
|
||
tmux/PTY 终端包装器（请改用 SDK harness 或 Web UI）；
|
||
- `bwrap`/`seatbelt` 文件系统与网络沙箱隔离及 L7 出口代理
|
||
—— Job Object 后端可 containment 进程树并强制执行资源限制，但**不会**隔离文件系统或网络。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>更新到新版本</summary>
|
||
|
||
当 PyPI 上有更新的版本时，Omnigent 会显示一行提示（每个版本一次）并指向此处。更新方法：
|
||
|
||
```bash
|
||
omni upgrade # detects how you installed, drains & stops the local
|
||
# server, then runs the matching upgrade command
|
||
omni upgrade --check # just report whether a newer release is available
|
||
```
|
||
|
||
`omni upgrade` 会在停止本地服务器前等待进行中的智能体会话结束（传入 `--force` 可立即停止）；下一次执行 `omni` 命令
|
||
即可在新版本上重启服务器。源码检出请改用 `git pull` 更新。使用 `OMNIGENT_NO_UPDATE_CHECK=1` 可关闭该提示。
|
||
|
||
检查会查询你配置的包索引——遵循 `UV_INDEX_URL` /
|
||
`PIP_INDEX_URL` 以及 `uv.toml` / `pip.conf`（默认为 PyPI），因此私有
|
||
镜像开箱即用；必要时可用 `OMNIGENT_INDEX_URL` 覆盖。
|
||
|
||
</details>
|
||
|
||
### 2. 启动你的第一个智能体
|
||
|
||
`omnigent` 会与你一起选择模型，并在终端中启动会话。它
|
||
还会在 `http://localhost:6767` 启动本地 Web UI，在浏览器或局域网内的手机上显示同一会话（见步骤 4）。
|
||
[桌面应用](https://omnigent.ai/docs/interact/desktop) 将同一 UI
|
||
封装在原生窗口中，并提供操作系统通知（可配置提示音）和 Dock 角标 ——
|
||
[下载 macOS 版](https://omnigent.ai/download/mac).
|
||
|
||
> [!NOTE]
|
||
> 安装后 PATH 上会有同一 CLI 的两个名称：`omnigent` 和
|
||
> 更短的 `omni`。二者可互换使用。
|
||
|
||
> [!TIP]
|
||
> 首次运行时，Omnigent 会读取你环境中已有的模型凭据（已登录的 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`，或 `claude` / `codex` CLI），并提供一个作为默认选项。
|
||
|
||
```bash
|
||
omnigent
|
||
```
|
||
|
||
或启动特定的 agent 运行时：
|
||
|
||
```bash
|
||
omnigent claude # Claude Code, in a session your team can join
|
||
omnigent codex # Codex
|
||
omnigent cursor # Cursor
|
||
omnigent opencode # OpenCode
|
||
omnigent hermes # Hermes Agent (Nous Research)
|
||
omnigent pi # Pi
|
||
```
|
||
|
||
#### 🐙 Polly 与 🟠🔵 Debby
|
||
|
||
仓库自带两个示例 agent，非常适合作为首次体验：
|
||
|
||
```bash
|
||
omnigent run examples/polly/
|
||
omnigent run examples/debby/
|
||
|
||
# ...or on a different harness (sub-agents keep their own):
|
||
omnigent run examples/polly/ --harness <harness>
|
||
omnigent run examples/debby/ --harness <harness>
|
||
```
|
||
|
||
**🐙 Polly** 是一位多 agent 编程编排者，她自己不写代码。她担任技术负责人：负责规划，将工作委派给并行 git worktree 中的编程子 agent（Claude Code、Codex 或 Pi），然后把每个 diff 交给与编写者不同厂商的审查者审核。由你来合并。
|
||
|
||
**🟠🔵 Debby** 是一位拥有两个「脑袋」的头脑风暴伙伴，一个是 Claude，一个是 GPT。你提出的每个问题都会同时发给两个脑袋，她会将两个答案并排展示。输入 `/debate`，两个脑袋会先互相评判几轮，再达成一致。（她需要 Claude 和 OpenAI 两种凭据；参见第 3 步。）
|
||
|
||
**更喜欢用浏览器？** 启动服务器并将你的机器注册为主机：
|
||
|
||
```bash
|
||
omnigent server start # start the local server and web UI in the background
|
||
omnigent host # (separate terminal) register this machine as a host
|
||
```
|
||
|
||
在 Web UI 中点击 **New Chat**，选择你的机器，即可开始。使用 `omnigent server status` 查看状态；使用 `omnigent stop` 停止所有服务。
|
||
|
||
### 3. 选择与切换模型
|
||
|
||
```bash
|
||
omnigent setup
|
||
```
|
||
|
||
按 agent 分组添加凭据、设置默认项或移除凭据。Omnigent 支持四种类型的凭据：
|
||
|
||
| | 类型 | 说明 |
|
||
|---|---|---|
|
||
| 🔑 | **API key** | Anthropic、OpenAI 等官方厂商提供的 API 密钥 |
|
||
| 🎟️ | **Subscription（订阅）** | Claude Pro/Max 或 ChatGPT 套餐，通过官方 `claude` / `codex` CLI |
|
||
| 🌐 | **Gateway（网关）** | 任何 OpenAI 或 Anthropic 兼容的 `base_url` 和密钥（OpenRouter、LiteLLM、Ollama、vLLM、Azure） |
|
||
| 🧱 | **Databricks** | Databricks 工作区配置文件（需要 `databricks` extra） |
|
||
|
||
默认项按 agent 分别设置，因此 Claude 默认项和 Codex 默认项可以并存。你也可以在会话中途使用 `/model` 命令切换模型。
|
||
|
||
<details>
|
||
<summary>Gateway 基础 URL（OpenRouter、Ollama）</summary>
|
||
|
||
添加 **Gateway** 凭据时，`omnigent setup` 会要求输入基础 URL 和密钥。基础 URL 取决于你将其指向哪个 agent：
|
||
|
||
| 提供商 | 适用于 | 基础 URL | 密钥 |
|
||
|---|---|---|---|
|
||
| **OpenRouter** | Claude Code | `https://openrouter.ai/api` | 你的 OpenRouter 密钥（`sk-or-…`） |
|
||
| **OpenRouter** | Codex / OpenAI agents | `https://openrouter.ai/api/v1` | 你的 OpenRouter 密钥（`sk-or-…`） |
|
||
| **Ollama**（本地） | Codex / OpenAI agents | `http://localhost:11434/v1` | 任意值（Ollama 会忽略） |
|
||
|
||
对于 Claude Code，请指向 OpenRouter 的 Anthropic 兼容端点（`…/api`，**而非** `…/api/v1`）。对于 Codex 和 OpenAI-agents harness，请使用 OpenAI 兼容的 `…/api/v1`。
|
||
|
||
</details>
|
||
|
||
### 4. 部署服务器（并在手机📱上使用）
|
||
|
||
在具有稳定 URL 的服务器上运行 Omnigent（[`deploy/README.md`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md)) 为完整指南），你的会话即可从任何地方访问，包括手机。Web UI 专为移动端设计，因此你能获得与笔记本电脑同步的相同聊天、子 agent、终端和文件。
|
||
|
||
一个 `docker compose up` 即可在你拥有的任何主机（VPS、家用服务器）上运行服务器；**Render** 和 **Railway** 支持一键部署；**Fly.io**、**Hugging Face Spaces**、**Modal**、**Cloudflare**（serverless，缩容至零）以及 **Databricks Apps**（由 Lakebase Postgres 和 Unity Catalog Volumes 支持）也有涵盖——**Cloudflare quick tunnel**（公开）或 **Tailscale**（私有）可让你在不部署的情况下，从自己的笔记本电脑访问正在运行的服务器。服务器还可以为每个会话配置云端沙箱（*managed hosts*），因此无需笔记本电脑保持在线。完整的目标列表、数据库选项和沙箱配置请参阅 [`deploy/README.md`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md).
|
||
|
||
服务器启动后，登录并将你的笔记本电脑注册为主机：
|
||
|
||
```bash
|
||
omnigent login https://your-host # sign in once; run / attach / host reuse the token
|
||
omnigent host https://your-host # new sessions can now run on this machine
|
||
```
|
||
|
||
> [!TIP]
|
||
> 在你自己的网络中无需部署。在手机上打开你机器的局域网地址（例如 `http://192.168.x.x:6767`）。
|
||
|
||
### 5. 与团队协作
|
||
|
||
Omnigent 支持**多用户账户**，通过一个环境变量控制：
|
||
|
||
```bash
|
||
OMNIGENT_AUTH_ENABLED=1 omnigent server start
|
||
```
|
||
|
||
**[第 4 步](#4-deploy-a-server-and-use-it-from-your-phone)中的 Docker 部署会为你启用该功能**（其中 `OMNIGENT_AUTH_ENABLED` 默认为 `1`）。
|
||
|
||
#### 邀请队友
|
||
|
||
打开 Web UI（本地使用 `http://localhost:6767`，或使用主机的 URL），以 `admin` 身份登录；首次运行会打印密码并保存在本地。然后打开 **Admin → Members → Invite** 创建一次性邀请链接，无需邮件服务器。将链接发送出去；队友打开链接、设置密码后即可加入。注册仅限邀请。
|
||
|
||
<!-- TODO: Admin → Members → Invite 界面截图。 -->
|
||
|
||
> [!NOTE]
|
||
> 队友需要能够访问服务器。本地服务器仅在你的网络内可访问；对于网络外的用户，请部署一个常驻主机（参见[第 4 步](#4-deploy-a-server-and-use-it-from-your-phone)）。
|
||
|
||
#### 共同编程
|
||
|
||
- **共享实时会话。** 在 Web UI 中点击 **Share** 并发送链接；队友可以实时观看你的 agent 工作并与之聊天。
|
||
- **共同操作（Co-drive）。** 队友会协同接入你正在运行的会话；他们的消息在**你的**机器上执行。非常适合结对编程，或在调查中途将键盘交给领域专家。
|
||
|
||
```bash
|
||
omnigent attach <session_id>
|
||
```
|
||
|
||
- **分叉（Fork）。** 将对话克隆到你自己的机器上，从分叉点独立继续。
|
||
|
||
```bash
|
||
omnigent run --fork <session_id>
|
||
```
|
||
|
||
> [!TIP]
|
||
> 希望团队使用已有的登录方式（**Google、GitHub、Okta、Microsoft**）登录？在已部署的服务器上设置 `OMNIGENT_OIDC_ISSUER` 以及 client ID 和 secret，然后重启。完整操作指南、域名白名单以及仅限代理的 `header` 认证模式请参阅 [`deploy/README.md#auth`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md#auth).
|
||
|
||
### 6. 使用策略管控 agent
|
||
|
||
**策略（Policies）** 决定 agent 可以执行哪些操作：运行 shell 命令、编辑文件、消耗 token。策略会检查每一项操作，并选择允许、阻止，或暂停并先征求你的同意。
|
||
|
||
- **在 Web UI 中**：打开会话的信息面板，浏览可用策略并开启或关闭。
|
||
- **在聊天中**：直接提问。*「添加一项策略，在运行 shell 命令前先征求我的同意。」* agent 会为你配置。
|
||
|
||
想要适用于所有人或特定 agent 的默认策略？在服务器配置或 agent 的 YAML 中定义：
|
||
|
||
```yaml
|
||
policies:
|
||
approve_shell:
|
||
type: function
|
||
handler: omnigent.policies.builtins.safety.ask_on_os_tools # ask before shell / file writes
|
||
cap_calls:
|
||
type: function
|
||
handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
|
||
factory_params:
|
||
limit: 50 # cap how many tools one session can call
|
||
budget:
|
||
type: function
|
||
handler: omnigent.policies.builtins.cost.cost_budget
|
||
factory_params:
|
||
max_cost_usd: 5.00 # hard spend cap...
|
||
ask_thresholds_usd: [3.00] # ...with a soft warning on the way
|
||
```
|
||
|
||
策略分三层叠加：**全服级**（admin）、**按 Agent**（developer）与**按会话**（you），更严格的会话规则会优先校验。支出上限与访问限制以内置能力（builtins）提供。
|
||
|
||
完整目录与信任模型请参阅[策略指南](https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md)。
|
||
|
||
---
|
||
|
||
## 编写你自己的 Agent
|
||
|
||
Agent 是一个简短的 YAML 文件：包含你的提示词（prompt）与工具——本地 Python 函数、MCP 服务器，以及 supervisor 可委派任务的子 Agent（sub-agents）。你不必亲手编写：Agent 可以构建 Agent，因此在任意 Omnigent 对话中描述你想要的 Agent，它就会为你生成该文件。
|
||
|
||
```yaml
|
||
name: my_agent
|
||
prompt: You are a helpful data analyst.
|
||
|
||
executor:
|
||
harness: claude-sdk # or: claude-native, codex, codex-native, cursor,
|
||
# cursor-native, hermes, hermes-native, opencode,
|
||
# pi, pi-native, openai-agents
|
||
|
||
tools:
|
||
# A local Python function (schema auto-generated from the signature)
|
||
word_count:
|
||
type: function
|
||
callable: mypackage.mymodule.word_count
|
||
|
||
# Tools from an MCP server (a local command, or a remote URL)
|
||
docs:
|
||
type: mcp
|
||
url: https://example.com/mcp
|
||
|
||
# A sub-agent the supervisor can delegate to
|
||
researcher:
|
||
type: agent
|
||
prompt: Search for relevant information and summarize it.
|
||
tools:
|
||
word_count: inherit
|
||
```
|
||
|
||
运行方式：
|
||
|
||
```bash
|
||
omnigent run path/to/my_agent.yaml
|
||
```
|
||
|
||
同一文件还可声明子 Agent 与 reviewer。更完整的示例请参阅 Polly：[`examples/polly/`](https://github.com/omnigent-ai/omnigent/tree/main/examples/polly/),，以及[Agent YAML 规范](https://github.com/omnigent-ai/omnigent/blob/main/docs/AGENT_YAML_SPEC.md))了解完整 schema。
|
||
|
||
---
|
||
|
||
## 参与贡献
|
||
|
||
欢迎贡献。环境搭建、运行检查与提交 Pull Request 的方式请参阅 [CONTRIBUTING.md](https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md)。
|
||
|
||
要新增或修改对 harness（Claude、Codex、Cursor、OpenCode、Hermes、Pi 等）的支持？请运行 [harness test bench](https://github.com/omnigent-ai/omnigent/tree/main/tests/harness_bench)，对照实际行为检查其能力矩阵（capability matrix）。
|
||
|
||
|
||
### 贡献者
|
||
|
||
感谢所有出色的贡献者！
|
||
|
||
<a href="https://github.com/omnigent-ai/omnigent/graphs/contributors">
|
||
<img src="https://contrib.rocks/image?repo=omnigent-ai/omnigent" />
|
||
</a>
|