SuperAPI AI 工具集

orch-runtime

编程与开发

查看项目

更新于 10-18 16:38

技能介绍

历史版本与核实范围

本页恢复撤回前父提交中的完整orch-runtime主指南,并提供全文中文翻译。发布者于2026-03-31(UTC)通过回退提交撤回该文件;本页标明这一历史状态,不能据此确认原安装命令当前仍取得相同内容。2026-10-19核对路径历史、撤回提交、父提交完整文件树、blob、译文及MIT许可;原始元数据、13个代码块与许可声明保留。配套CLI、代理适配器和其他文件未另行恢复,安装、代理调用、消息发送、目标创建和示例命令均未执行,当前运行效果未实测。

发布者固定提交原文

撤回提交

完整主指南

ORCH 运行时集成

当你需要将工作移交给由 ORCH 管理的持久化、有状态的 AI 代理团队时使用本技能——ORCH 是用于协调 Claude Code、OpenCode、Codex 和 Cursor 代理的 TypeScript CLI 运行时。

与 ECC 的进程内子代理(短暂、单会话)不同,ORCH 代理是:

  • 持久化的——在进程重启和会话结束后仍然存在
  • 有状态的——任务通过正式状态机流转(todo → in_progress → review → done)
  • 具备故障恢复能力的——失败时自动重试,并具有可配置的重试预算
  • 可通信的——代理之间发送直接消息并向团队广播

何时使用

  • 任务跨越多个 Claude 会话(>1 个上下文窗口)
  • 你需要一个后台代理在你处理其他事情时运行
  • 你希望在任务被标记为完成之前设置人工审核关卡
  • 你有一支由专门代理(后端、QA、审核者)组成的团队,它们应当协同工作
  • 你需要任务状态转换的审计轨迹

前置条件

npm install -g @oxgeneral/orch

验证安装:

orch --version
orch agent list

核心概念

状态机

ORCH 中的每个任务都遵循受管理的生命周期:

todo → in_progress → review → done
              ↓
           retrying (on failure, up to N attempts)
              ↓
           failed

没有任务会直接跳转到 done——review 关卡确保了可问责性。

代理注册表

代理持久化在 .orchestry/agents/ 中。每个代理具有:

  • adapter:claude | opencode | codex | cursor | shell
  • model:要调用的 AI 模型
  • role:系统提示词
  • approval_policy:auto | suggest | manual

共享上下文

使用 orch context set/get 作为所有代理都可读取的键值存储。这是 ORCH 与 ECC 会话之间的共享内存层。

从 Claude Code 派发任务

1. 添加任务并分配给代理

# Find available agents
orch agent list

# Create task with description and priority
orch task add "Implement OAuth2 middleware" \
  -d "Add OAuth2 bearer token validation to Express. Files: src/middleware/auth.ts" \
  -p 2 \
  --assignee <agent-id>

2. 从当前 Claude 会话传递上下文

# Share findings from your ECC session with ORCH agents
orch context set security-findings "XSS vulnerability in src/views/profile.tsx:42 — unsanitized user input passed to innerHTML"

# Share a file reference
orch context set current-pr "https://github.com/org/repo/pull/123"

# Share structured analysis
orch context set arch-decision "Use JWT with RS256, not HS256. See: docs/adr/0012-auth.md"

3. 监控任务进度

# List active tasks
orch task list --status in_progress

# Watch the live dashboard
orch tui

# Stream logs from a specific run
orch logs --tail 50

4. 收集结果

# Read context set by the ORCH agent after completion
orch context get implementation-result
orch context get test-coverage-report

# Show full task details
orch task show <task-id>

与 /orchestrate 集成

将 ECC 的进程内编排与 ORCH 结合用于长周期任务:

## Hybrid Workflow Example

### Phase 1: In-process planning (ECC)
/orchestrate feature "Add OAuth2 middleware"
→ planner generates implementation plan
→ architect reviews design
→ Output: HANDOFF document in context

### Phase 2: Persistent execution (ORCH)
orch context set ecc-handoff "<paste HANDOFF document>"
orch task add "Implement OAuth2 per handoff" \
  -d "$(orch context get ecc-handoff)" \
  -p 1 --assignee <backend-agent-id>

### Phase 3: Async review gate
# ORCH enforces review state before marking done
# Agent transitions: in_progress → review → done
orch task list --status review  # see tasks awaiting review

代理通信

# Send a message to a specific agent mid-task
orch msg send <agent-id> "Prioritize security hardening over performance" \
  -s "Updated requirements"

# Broadcast to entire team
orch msg broadcast "New requirement: FIPS compliance required" \
  -s "Compliance update"

# Check team inbox
orch msg inbox <agent-id>

目标驱动工作流

对于多任务项目,设置一个目标来关联相关任务:

# Create a goal
orch goal add "Implement full authentication system" \
  -d "OAuth2 + session management + 2FA. Target: Sprint 24."

# Add tasks under the goal
orch task add "OAuth2 middleware" -p 1 --goal <goal-id>
orch task add "Session store (Redis)" -p 2 --goal <goal-id> --depends-on <oauth-task-id>
orch task add "2FA via TOTP" -p 2 --goal <goal-id> --depends-on <session-task-id>

# Monitor goal progress
orch goal show <goal-id>

故障恢复模式

自动重试配置

在 .orchestry/agents/<id>.yaml 中为每个代理配置重试预算:

max_retries: 3
retry_delay_ms: 5000

当任务失败时,ORCH 会自动将其转换为 retrying 状态,并在延迟后重新派发。

停滞检测

ORCH 的编排器 tick 循环会检测僵尸进程和停滞任务。如果代理超过 stall_timeout_ms,任务将自动重试或失败。

上下文存储模式

将 ORCH 上下文存储用作 ECC 会话与 ORCH 代理之间的黑板:

# ECC session writes analysis
orch context set code-analysis-result "Found 3 N+1 queries in UserService"

# ORCH Backend agent reads and acts
# (agent's role prompt: "read context key 'code-analysis-result' and fix the issues")
orch task add "Fix N+1 queries per analysis" \
  -d "Read: orch context get code-analysis-result" -p 1 --assignee <backend-id>

# QA agent writes test results back
orch context set qa-result "PASS: all 47 tests green, coverage 94%"

# Back in ECC session, collect
orch context get qa-result

编程式 API

ORCH 导出了完整的引擎 API,可用于嵌入 Node.js 应用:

import { TaskService, AgentService, OrchestratorService } from '@oxgeneral/orch';

// Use ORCH engine programmatically from your Claude skill
const tasks = await TaskService.list({ status: 'review' });
const pending = tasks.filter(t => t.priority === 1);

最佳实践

  1. 一个任务 = 一个原子工作单元——避免巨型任务;使用 --depends-on 进行分解
  2. 传递丰富的上下文——代理在 -d 中带有文件路径、约束和示例时表现更好
  3. 使用审核关卡——不要跳过 review → done;它可以发现代理的错误
  4. 上报问题前先检查日志——在创建新任务之前使用 orch logs --tail 100
  5. 上下文键有命名空间——使用 qa-、arch-、security- 等前缀以避免冲突
  6. 团队用于并行工作——使用 orch team list 查看分组;将任务分配给团队成员以实现并行

参考资料

原始元数据

name: orch-runtime
description: Dispatch tasks to a persistent ORCH agent team from Claude Code. Use when you need long-running or multi-session AI workflows that survive beyond a single Claude context window.
origin: community

原作者与许可

MIT License

Copyright (c) 2026 Affaan Mustafa

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.