dev-orchestrator

Name: dev-orchestrator
Author: rysweet

github.com/rysweetAgent 工作流7690 次安装21 周前更新

代码仓库

关于 dev-orchestrator

amplihack 中用于非简单开发和调查任务的默认编排 Skill。它会分类请求、拆分工作流、执行配方流程并验证结果。

主要功能

01分类任务类型与目标
02拆分并行工作流
03执行受约束的配方流程
04限制嵌套会话深度
05检查结果并处理故障

适用场景

01协调包含多个部分的开发工作
02按既定流程调查代码库
03实现后验证结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rysweet/amplihack --skill dev-orchestrator

安装后在 Claude Code 中输入/dev-orchestrator确认已加载。

详细介绍

开发编排器技能

用途

这是 amplihack 中所有非简单开发和调查任务的默认编排器。它取代了 ultrathink-orchestrator 技能。

当用户要求你构建、实现、修复、调查或创建任何非简单内容时，此技能会确保：

任务已分类 — 问答 / 运维 / 调查 / 开发
目标已制定 — 明确成功标准
工作流已识别 — 自动拆分并行任务
已使用配方运行器 — 以代码强制执行工作流
结果已验证 — 通过复盘确认目标已达成

工作原理

User request
     │
     ▼
[Classify] ──→ Q&A ──────────────────→ analyzer agent (technical/code questions)
     │
     ├──────→ Ops ────────────────────→ builder agent
     │
     └──→ Development / Investigation
             │
         [Recursion guard] (AMPLIHACK_SESSION_DEPTH vs AMPLIHACK_MAX_DEPTH=3)
             │         │
           ALLOWED   BLOCKED → [announce-depth-limited banner]
                                    ↓
                           [execute-single-fallback-blocked]
                                    ↓
                           [Execute round 1 (single-session)]
             │
         [Decompose]
             │         │
             1 ws     N ws ──→ [multitask parallel] + tree context in env
             │
         [Execute round 1]
             │
         [Reflect] ──→ ACHIEVED ──→ [Summarize]
             │
           PARTIAL/NOT_ACHIEVED
             │
         [Execute round 2]
             │
         [Reflect] ──→ ACHIEVED ──→ [Summarize]
             │
           PARTIAL/NOT_ACHIEVED
             │
         [Execute round 3 (final)]
             │
         [Final reflect + Summarize]

会话树强制机制（防止无限递归）：

每个子进程都会继承 AMPLIHACK_TREE_ID、AMPLIHACK_SESSION_DEPTH、AMPLIHACK_MAX_DEPTH
深度 >= 3：递归保护机制会阻止生成子工作流，并调整为单会话模式
每棵树最多允许 10 个并发会话；超出的会话按 FIFO 顺序排队
状态跟踪在 /tmp/amplihack-session-trees/{tree_id}.json 中

激活

此技能会针对开发和调查关键词自动激活。根据 CLAUDE.md，它也是 默认行为——任何非简单任务都应调用此技能。

UserPromptSubmit 钩子会通过注入分类提示来强化此机制，指示 Claude 对开发 / 调查任务调用 Skill(skill="dev-orchestrator")。

执行说明

阅读此技能后的下一个操作必须包含一次 Bash 工具调用，以执行 run_recipe_by_name("smart-orchestrator")。 如果你的运行时要求调用 report_intent（例如 Copilot CLI），则应与 Bash 启动操作并行发出——在同一响应中调用这两个工具。此限制意味着，在 Bash 启动操作之前，不得执行或以其替代任何_其他_实质性操作（读取文件、调用 TodoWrite、调用 Agent 或输入回复）。

如果你发现自己在做其他事情，而不是启动配方运行器，那你就是在绕过工作流。停下。返回上一步。运行配方运行器。

开发和调查任务只有一条执行路径：配方运行器。没有“选项 B”。没有“我会手动按步骤执行”。也没有“让我先快速……”配方运行器就是工作流。跳过它，就意味着跳过 23 步流程、递归保护机制、目标验证以及有其存在理由的质量关卡。

此技能激活后，PostToolUse 钩子会监控每次工具调用。如果检测到在没有配方运行器证据的情况下调用了 3 次工具，就会触发硬性警告。不要等到警告出现——立即运行配方运行器。

激活此技能时：

必需：立即通过 Recipe Runner 执行

你接下来的工具调用必须包含启动 recipe runner（如果你的运行时要求，还需同时调用 report_intent）。关键：Claude Code 的 run_in_background 会在约 10 分钟后终止进程。Recipe 工作流可能需要数小时。执行时必须使用 tmux 会话：

LOG_FILE=$(mktemp /tmp/recipe-runner-output.XXXXXX.log)
chmod 600 "$LOG_FILE"
tmux new-session -d -s recipe-runner "env -u CLAUDECODE PYTHONPATH=src python3 -c \"
import os
os.environ.pop('CLAUDECODE', None)

from amplihack.recipes import run_recipe_by_name

result = run_recipe_by_name(
    'smart-orchestrator',
    user_context={
        'task_description': '''TASK_DESCRIPTION_HERE''',
        'repo_path': '.',
    },
    progress=True,
)
print(f'Recipe result: {result}')
\" 2>&1 | tee \"$LOG_FILE\""
echo \"Recipe runner log: $LOG_FILE\"

要点：

env -u CLAUDECODE ——取消设置，以便启动嵌套的 Claude Code 会话
PYTHONPATH=src python3 ——使用 PATH 上的解释器，同时强制从已检出的仓库源代码树导入（不要硬编码 .venv/bin/python）
run_recipe_by_name ——委托给 Rust 二进制文件；不再需要 adapter 参数
progress=True ——实时输出 recipe-runner 的 stderr，以便 tmux 日志显示嵌套步骤的活动
chmod 600 "$LOG_FILE" ——确保 tmux 日志仅对当前用户可见
tmux new-session -d ——创建分离会话，无超时限制，断开连接后仍会继续运行
使用以下命令监控：tail -f "$LOG_FILE" 或 tmux attach -t recipe-runner

重启过时的 tmux 会话：某些运行时（例如 Copilot CLI）会阻止执行 tmux kill-session，因为该命令没有指定数字 PID。请改用以下任一符合 shell 策略的替代方法：

# Option A (preferred): use a unique session name per run to avoid collisions
tmux new-session -d -s "recipe-$(date +%s)" "..."

# Option B: locate the tmux server PID and terminate with numeric kill
tmux list-sessions -F '#{pid}' 2>/dev/null | xargs -I{} kill {}

# Option C: let tmux itself handle it — send exit to all panes
tmux send-keys -t recipe-runner "exit" Enter 2>/dev/null; sleep 1

如果使用选项 A，请将 tail -f / tmux attach 命令改为使用相同的会话名称。

不要使用 run_in_background 执行 recipe——它会在约 10 分钟后被终止（Issue #2909）。

对于开发和调查任务，recipe runner 是必需的执行路径。 务必首先尝试 smart-orchestrator。

以下常见说辞均不可接受：

“我先了解一下代码库”——recipe 会在步骤 0 完成这项工作
“我会手动遵循工作流步骤”——不行，recipe 会强制执行这些步骤
“recipe runner 可能无法运行”——先尝试；如果失败，请报告错误
“这是个简单任务”——无论简单还是复杂，recipe runner 都能处理

只有问答和运维任务可以绕过 recipe runner：

问答：直接回复（分析器 Agent）
运维：Builder Agent（直接执行，不涉及工作流步骤）

错误恢复：自适应策略（而非降级）

当 smart-orchestrator 失败时，必须让失败清晰可见并报告出来—— 绝不能隐瞒失败或悄悄降级。该配方会通过内置的自适应策略步骤自动处理错误恢复，但如果你在配方之外发现故障，请遵循以下流程：

1. 提供包含完整上下文的错误信息：

报告确切的错误、失败的步骤以及日志输出。绝不要只说“出了点问题”——务必提供具体的失败详情。

2. 提交包含复现详情的 Bug 报告：

对于基础设施故障（导入错误、缺少环境变量、未找到二进制文件、分解结果无效），请提交 GitHub issue：

gh issue create \
  --title "smart-orchestrator infrastructure failure: <one-line summary>" \
  --body "<full error context, reproduction command, env details>" \
  --label "bug"

3. 评估替代策略：

如果 smart-orchestrator 在基础设施层面失败（而非任务本身有误），你可以直接调用特定工作流配方。这是一种自适应策略——必须明确说明，不得悄悄执行：

分类	直接调用的配方	允许的情况
调查	`investigation-workflow`	smart-orchestrator 在解析／分解／启动阶段失败
开发	`default-workflow`	smart-orchestrator 在解析／分解／启动阶段失败

示例：

# ANNOUNCE the strategy change first — never do this silently
print("[ADAPTIVE] smart-orchestrator failed at parse-decomposition: <error>")
print("[ADAPTIVE] Switching to direct investigation-workflow invocation")
run_recipe_by_name("investigation-workflow", user_context={...}, progress=True)

**这并不意味着可以绕过 smart-orchestrator。**务必先尝试使用它。只有当 smart-orchestrator 在基础设施层面失败时，才允许直接调用。“任务看起来很简单”不属于基础设施故障。

4. 检测空洞的成功：

配方在结构上可能顺利完成（所有步骤均以 0 退出），但产生的结果为空或毫无意义——例如 Agent 报告“未找到代码库”，或明明没有执行任何工作，反思步骤却标记为 ACHIEVED。执行后，请检查：

各轮结果包含实际发现或代码变更（而非“我无法访问……”）
对于开发任务，存在 PR URL 或具体产出
至少有一项成功标准经过可验证的评估

如果结果空洞，请向用户报告具体的空输出。Agent 没有完成任何有意义的工作时，不要宣布成功。

必需的环境变量

配方运行器需要以下环境变量才能正常运行：

变量	用途	默认值
`AMPLIHACK_HOME`	amplihack 安装目录的根路径（用于查找资源）	自动检测
`AMPLIHACK_AGENT_BINARY`	要使用的 Agent 二进制文件（claude、copilot 等）	`claude`
`AMPLIHACK_MAX_DEPTH`	嵌套会话的最大递归深度	`3`
`AMPLIHACK_NONINTERACTIVE`	设为 `1` 以跳过交互式提示	未设置

如果未设置 AMPLIHACK_HOME 且自动检测失败，parse-decomposition 和 activate-workflow 将因“orch_helper.py not found”而失败。请将其设为包含 amplifier-bundle/ 的目录。

执行后：反思并验证

执行完成后，请验证目标是否已达成。如果没有：

缺少信息：询问用户
可修复的缺口：使用剩余工作说明重新调用
基础设施故障：提交 Bug 报告并尝试自适应策略

强制执行：PostToolUse 工作流守卫

PostToolUse 钩子（workflow_enforcement_hook.py）会在调用此技能后主动监控每次工具调用。它会跟踪：

是否调用了 /dev 或 dev-orchestrator（设置标志）
是否实际执行了配方运行器（清除标志）
在没有工作流证据的情况下，已进行了多少次工具调用

如果连续 3 次或更多工具调用都没有配方运行器执行证据，该钩子会发出严重警告。这不是建议，而是意味着你违反了强制工作流。状态存储在 /tmp/amplihack-workflow-state/ 中。

任务类型分类

类型	关键词	操作
问答	"what is"、"explain"、"how does"、"how do I"、"quick question"	直接回答
操作	"clean up"、"delete"、"git status"、"run command"	builder Agent（直接执行，不执行工作流步骤）
调查	"investigate"、"analyze"、"understand"、"explore"	investigation-workflow
开发	"implement"、"build"、"create"、"add"、"fix"、"refactor"	smart-orchestrator
混合*	同时包含调查和开发关键词	拆分为调查和开发工作流

* 混合任务不是一种独立的 task_type——编排器会将其归类为开发任务，并拆分为多个工作流（一个调查工作流，一个开发工作流）。

工作流拆分示例

请求	工作流
"implement JWT auth"	1 个：auth（default-workflow）
"build a webui and an api"	2 个：api + webui（并行）
"add logging and add metrics"	2 个：logging + metrics（并行）
"investigate auth system then add OAuth"	2 个：调查 + 实现（顺序执行）
"fix bug in payment flow"	1 个：bugfix（default-workflow）

覆盖选项

单个工作流覆盖：在配方的 user_context 中传入 force_single_workstream: "true"，以阻止自动并行拆分，无论任务结构如何。这是一个编程选项（不能直接通过 /dev 设置）：

run_recipe_by_name(
    "smart-orchestrator",
    user_context={
        "task_description": task,
        "repo_path": ".",
        "force_single_workstream": "true",  # disables parallel decomposition
    }
)

无需修改配方上下文即可强制执行单工作流： 运行 /dev 前设置 AMPLIHACK_MAX_DEPTH=0。这会使递归守卫阻止并行派生，并让所有任务回退到单会话模式：

export AMPLIHACK_MAX_DEPTH=0  # set in your shell first
/dev build a webui and an api  # then type in Claude Code

注意：必须在启动 Claude Code 之前于 Shell 中设置此环境变量——不能将它以内联前缀的形式加在 /dev 命令前。它会影响所有深度检查，而不仅仅是并行工作流派生。

权威来源

配方：amplifier-bundle/recipes/smart-orchestrator.yaml
并行执行：.claude/skills/multitask/orchestrator.py
开发工作流：amplifier-bundle/recipes/default-workflow.yaml
调查工作流：amplifier-bundle/recipes/investigation-workflow.yaml
CLAUDE.md：将其定义为默认编排器

与其他技能的关系

技能	关系
`ultrathink-orchestrator`	已弃用 — 重定向至此处
`default-workflow`	此编排器在处理单个开发任务时会调用
`investigation-workflow`	此编排器在处理研究任务时会调用
`multitask`	此编排器在处理并行工作流时会调用
`work-delegator`	相互独立 — 用于由待办事项驱动的任务委派

入口

主要入口：/dev <task description>
自动激活：通过 CLAUDE.md 默认行为和钩子注入
旧版入口：/ultrathink <task>（已弃用的别名 → 重定向至 /dev）

状态信号参考

编排器使用两种状态信号格式：

执行状态（来自构建 Agent）

出现在每轮执行步骤的末尾：

STATUS: COMPLETE — 本轮工作已全部完成
STATUS: CONTINUE — 本轮之后仍有更多工作
STATUS: PARTIAL — 最后一轮（第 3 轮）已达到部分完成
STATUS: DEPTH_LIMITED —（旧版，不再输出；请改用 BLOCKED 路径）

目标状态（来自审查 Agent）

出现在反思步骤的末尾：

GOAL_STATUS: ACHIEVED — 所有成功标准均已满足，任务已完成
GOAL_STATUS: PARTIAL -- [description] — 部分标准已满足，仍需继续工作
GOAL_STATUS: NOT_ACHIEVED -- [reason] — 未达成目标，需要再进行一轮

目标导向循环使用 GOAL_STATUS 信号来决定是否运行第 2 轮或第 3 轮。

BLOCKED 路径（递归保护）：当多工作流启动因深度限制而受阻时，编排器会调整为单会话执行：

announce-depth-limited — 打印警告横幅并提供补救信息
execute-single-fallback-blocked — 在单个构建 Agent 会话中执行完整任务（会先行说明，而非静默执行 — 横幅会明确显示策略变更）

支持 Markdown

登录后评论

基本信息

作者: rysweet
仓库: rysweet/amplihack
分类: Agent 工作流
安装次数: 90
GitHub Stars: 76

报告问题