Skip to content
BranchesTags

Repository files navigation

ORCH - AI Agent Runtime

把你的 AI 工具组织成一支协同工作的工程团队。
ORCH 是一个 AI agent runtime，可以协调 Claude、Codex、Cursor、OpenCode 和任意命令行工具并行处理任务。

GitHub Stars  npm  MIT License  Tests

来源 • 介绍 • 快速开始 • 核心能力 • 常用命令 • 架构 • 开发

项目来源与致谢

本仓库是基于原项目二次修改和维护的中文改版。

感谢原作者提供 ORCH 的基础设计、运行时架构和开源实现。本仓库在原项目基础上继续调整、修复和本地化说明文档；如需了解上游项目，请优先查看原仓库。

这是什么

ORCH 是一个面向工程自动化的 AI agent runtime。它不是单纯的 CLI 工具，而是一个可被 CLI、TUI 或其他 Node.js 应用调用的编排引擎。

你可以把它理解成一个本地运行的“AI 工程团队调度器”：

  • 把目标拆成任务。
  • 给不同 agent 分配任务。
  • 并行启动 Claude、Codex、Cursor、OpenCode 或 shell 命令。
  • 记录每次运行日志、状态和产物。
  • 用状态机控制任务流转。
  • 通过 git worktree 隔离不同 agent 的代码修改。
  • 在任务完成前要求提供 completion proof，避免“口头完成”。

默认状态都保存在项目目录下的 .orchestry/，不依赖数据库、云服务或 Docker。

快速开始

如果只是使用已经发布的 npm 包：

npm install -g @oxgeneral/orch
cd /path/to/your-project
orch

如果使用本仓库源码运行：

git clone https://github.com/MingTeer/ORCH-MING.git
cd ORCH-MING
npm install
npm run build
npm run dev

进入任意项目后初始化：

orch init
orch doctor
orch tui

创建一个 agent 和任务：

orch agent add "Backend" --adapter codex --role "实现后端任务"
orch task add "实现登录接口" --scope "src/auth/**" --completion-policy code_change
orch run --all

典型工作流

# 1. 部署一个预设团队
orch org deploy startup-mvp --goal "实现 OAuth 登录和基础用户系统"

# 2. 启动所有可执行任务
orch run --all

# 3. 查看状态
orch status

# 4. 查看任务和日志
orch task list
orch logs <run-id>

任务会经过：

todo -> in_progress -> review -> done
                 \-> retrying / failed / cancelled

默认情况下，任务不会直接跳过审核。agent 完成后需要进入 review 或 done，并附带变更文件、证据文件或 review 结果。

核心能力

多 agent 并行调度

ORCH 可以同时调度多个 agent，每个 agent 使用自己的 adapter：

Adapter 用途
claude 调用 Claude Code CLI
codex 调用 OpenAI Codex CLI
cursor 调用 Cursor 相关命令
opencode 调用 OpenCode，多 provider 支持
shell 执行任意 shell 命令或脚本

只要一个工具能在终端里运行，就可以通过 shell adapter 纳入 ORCH 的任务流。

Git worktree 隔离

每个任务可以在独立 git worktree 中运行，避免多个 agent 同时修改同一份工作区。

常见模式：

  • shared：直接使用当前工作区。
  • worktree：为任务创建独立分支和 worktree。
  • isolated：更强隔离的任务执行空间。
  • workspace_path：使用指定的外部 workspace 路径。

Completion proof

为了减少“agent 说完成但没有实际产物”的情况，ORCH 会校验任务完成证据：

  • files_changed：任务实际修改的文件。
  • evidence_files：测试报告、截图、日志等证据。
  • review_results：自动 review 结果。
  • scope：限制任务允许修改的文件范围。
  • baseline_files_allowlist：忽略已知的基线变更文件。

示例：

orch task proof <task-id> \
  --files-changed "src/auth/login.ts,test/unit/auth.test.ts" \
  --evidence "coverage/auth-report.txt" \
  --reverify

Headless serve 模式

orch serve 可以作为无界面的后台 daemon 运行，适合 CI/CD、服务器或长期任务队列：

orch serve
orch serve --once
orch serve --log-format json
orch serve --log-file ./orch.log

常用参数：

参数 说明
--once 处理当前 todo 任务后退出
--tick-interval <ms> 调整调度轮询间隔
--log-format json|text 输出 JSON 或文本日志
--log-file <path> 同时写入日志文件
--verbose 输出更详细的 agent 事件

常用命令

项目初始化

orch init
orch doctor
orch config edit

Agent

orch agent add <name> --adapter codex --role "后端工程师"
orch agent list
orch agent enable <agent-id>
orch agent disable <agent-id>

Task

orch task add "修复登录 bug" -p 1
orch task add "补充测试" --scope "test/**" --completion-policy evidence
orch task list
orch task show <task-id>
orch task assign <task-id> <agent-id>
orch task cancel <task-id>

Goal

orch goal add "完成支付模块" --description "接入 Stripe，补齐测试和文档"
orch goal list
orch goal status <goal-id> achieved

Team / Org

orch org list
orch org deploy startup-mvp
orch org deploy startup-mvp --goal "构建一个发票 SaaS"
orch org export my-team

orch team create backend --lead <agent-id>
orch team join <team-id> <agent-id>
orch team add-task <team-id> <task-id>

运行与观察

orch run <task-id>
orch run --all
orch serve
orch serve --once
orch status
orch logs <run-id>
orch tui

命令别名：

orchestry
orch
ao

架构说明

ORCH 采用分层 DDD 结构，并通过依赖注入连接各层。核心引擎不依赖 CLI/TUI，因此可以作为库被其他 Node.js 应用直接调用。

Domain
  -> Application
  -> Infrastructure
  -> CLI / TUI

目录结构：

src/
  domain/           # 模型、状态机、领域错误
  application/      # Orchestrator、服务、事件总线
  infrastructure/
    adapters/       # Claude、OpenCode、Codex、Cursor、Shell
    storage/        # YAML / JSON / JSONL 文件存储
    process/        # 进程管理和 PID 检测
    workspace/      # Git worktree 和 workspace 管理
    skills/         # Markdown skill 加载
  cli/              # Commander.js 命令
  tui/              # Ink + React 终端界面

核心设计：

  • src/container.ts 提供轻量容器和完整容器。
  • src/domain/transitions.ts 定义任务状态机。
  • src/application/orchestrator.ts 负责 reconcile、dispatch、collect 三阶段 tick loop。
  • src/infrastructure/adapters/interface.ts 定义 agent adapter 接口。
  • .orchestry/ 保存运行状态、任务、agent、goal、run 日志和上下文。

开发与测试

npm run dev
npm run build
npm run typecheck
npm test
npm run coverage

单文件测试：

npm test -- test/unit/application/orchestrator-resilience.test.ts

按名称筛选：

npm test -- --grep "state machine"

本仓库当前验证状态：

  • npm run typecheck 通过。
  • npm test 通过，2006 个测试通过，2 个跳过。

系统要求

项目 最低要求 推荐
操作系统 macOS / Linux / WSL2 macOS / Linux
Node.js >= 20 最新 LTS
CPU 2 核 4 核以上
内存 4 GB 8 GB 以上
磁盘 300 MB 1 GB 以上

ORCH 本身较轻量，主要资源消耗来自被启动的 agent CLI 进程。

安全与数据

  • 不需要数据库。
  • 不需要云端账号。
  • 默认所有状态保存在本地 .orchestry/。
  • 使用 git worktree 时，不会直接修改 main 分支。
  • agent 运行失败、超时或进程异常时会进入失败/重试/取消流程。

请注意：ORCH 会启动外部 CLI 工具，这些工具的行为取决于你配置的 adapter 和命令。对重要项目使用前，建议先在测试仓库里验证流程。

许可证

本项目继承原项目的 MIT License。版权声明见 LICENSE。

再次感谢原项目 oxgeneral/ORCH 及 Agents Organizations Contributors 的开源工作。

About

No description, website, or topics provided.

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages