📦 Orbi 详细部署教程

Orbi 是一个本地的 AI 软件开发“工厂”。你只需要在 GitHub 上创建一个 Issue，Orbi 就会自动认领它，在隔离的环境中调用 AI 编程代理 Pi 来开发、测试并创建 Pull Request，最后还会经过独立的代码审查和合并门禁。整个过程基于 GitHub Issue 和标签管理，无需额外的数据库或后台进程。

⚙️ 部署前准备

Orbi 依赖于几个核心命令行工具，请确保它们在系统 PATH 中可用。

工具	用途	验证命令
uv	Python 包和环境管理	`uv --version`
Pi	AI 编程代理	`pi --version` 且 `pi --print "ok"`
GitHub CLI (`gh`)	与 GitHub 交互	已完成 `gh auth login`，并通过 `gh auth status` 验证
systemd (用户模式)	任务调度和服务管理 (Linux)	`systemctl --user status`

🚀 安装与初始配置

步骤 1: 克隆仓库并安装 Orbi

git clone https://github.com/orbi-build/orbi.git && cd orbi

# 使用 uv 以可编辑模式安装 Orbi 包
uv tool install --force --reinstall --editable --python /usr/bin/python3 .

提示：--python 参数请指向你系统 Python 3 的实际路径（如 python3）。

步骤 2: 创建配置文件

1	cp .orbi.example.toml orbi.toml

编辑 orbi.toml 文件，至少需要配置：

repo_dir: 指定你要让 Orbi“管理”的 Git 仓库的本地路径。
GitHub 相关设置：确保 Orbi 有权访问该仓库。

步骤 3: 运行一次性设置

此命令会检查 gh 认证、创建必要的 GitHub 标签 (ai-ready, ai-blocked 等)、安装 systemd 单元文件。

1	orbi setup --config orbi.toml

步骤 4: 手动触发一次运行（验证）

1	PYTHONPATH=src python3 -m orbi.runner --config orbi.toml

这会模拟执行一次任务循环，用于检查配置是否正确。

步骤 5: 检查部署健康状态

1	orbi doctor --config orbi.toml

运行只读诊断，确认所有组件就绪。

⚙️ 核心工作流程

配置完成后，Orbi 会通过 systemd 用户定时器每隔 5 分钟自动运行。其自动化流程如下：

认领任务：监听带有 ai-ready 标签的 GitHub Issue。
准备环境：基于当前 main 分支的 commit SHA，创建一个隔离的 worktree 和功能分支。
AI 开发：启动 Pi 代理，在隔离环境中完成规划、编码、测试和验证。
提交与 PR：AI 停止后，Orbi 会同步最新代码、推送分支，并创建 PR，PR 正文中会包含 Fixes #N。
独立审查与合并：PR 创建后，会触发另一个独立的审查会话，修复发现的问题。只有经过审查的提交才能合并，AI 永远不会 直接推送或合并到受保护的分支。

🛠️ 日常操作与监控

分发新任务：在 GitHub 仓库中创建一个 Issue，并为其打上 ai-ready 标签。Orbi 会在下一个 tick 认领它。
查看队列状态：orbi status --config orbi.toml
跟进 AI 会话：orbi session --run-id <运行ID> --config orbi.toml
查看日志：通过 journalctl --user -u orbi-runner 查看 Orbi 运行日志。所有日志和 GitHub 进度评论都带有相同的 run_id，便于追溯完整时间线。

⚠️ 故障处理与恢复

任务失败：Orbi 会区分可恢复和不可恢复故障。
- 可恢复故障会留在同一个 PR 中继续修复。
- 不可恢复故障会将 Issue 标记为 ai-blocked，等待人工介入决策。
手动干预：对于 ai-blocked 的 Issue，你可以查看日志和会话记录，分析原因后手动修复或关闭 Issue。

❓ 常见问题

Q: Orbi 需要一直运行吗？
- A: 不需要。Orbi 通过 systemd 用户定时器 每隔 5 分钟触发一次，平时没有常驻进程。
Q: AI 开发过程中，我的代码会被泄露吗？
- A: Orbi 本身运行在你的机器上，且不会主动上传任何数据。它只会通过你的 GitHub CLI 与 GitHub 交互。代码安全取决于你配置的 AI 提供商（如 Pi 所使用的 API）。
Q: 如何手动停止 Orbi？
- A: 可以禁用 systemd 定时器：systemctl --user stop orbi-runner.timer。
Q: 可以在公司内部使用 Orbi 吗？
- A: 可以。项目采用 Sustainable Use License，允许在个人和公司内部免费、无限地使用和修改 Orbi。唯一的限制是不能直接销售 Orbi 本身（如将其作为服务托管或嵌入付费产品）。
Q: Orbi 支持哪些 AI 模型？
- A: Orbi 调用的是 Pi 代理，因此支持 Pi 所能连接的所有模型提供商（如 OpenAI、Anthropic、本地模型等）。具体可在 Pi 的配置中设置。