spec-agent 2.0.2 → 2.0.3

package/orchestrator-v2-design.md

@@ -0,0 +1,193 @@
+# Spec-Agent Orchestrator v2 设计方案
+
+## 1. 目标与范围
+
+本方案用于将 `spec-agent` 从“产物生成工具”升级为“可持续推进执行的智能体编排器”。
+
+核心目标：
+
+- 自动调用 `spec-agent` CLI（pipeline/handoff/execute）
+- 基于产物做决策，不依赖人工记忆当前状态
+- 支持失败重试与中断恢复
+- 输出明确下一步动作，降低人工操作成本
+
+非目标（v2 不做）：
+
+- 自动提交 PR / 自动合并代码
+- 跨仓库复杂编排
+- 无约束的自动改代码
+
+---
+
+## 2. 总体架构
+
+建议采用 4 个职责清晰的 Agent 角色：
+
+- **Onboarding Agent**：检查安装与环境，确保首次可运行
+- **Pipeline Agent**：负责 scan -> analyze -> merge -> plan -> dispatch
+- **Execution Orchestrator Agent**：负责 handoff + execute 循环推进
+- **Failure Triage Agent**：负责错误分流、修复建议与重试策略
+
+说明：v2 初版可由一个主 Agent 执行上述职责；v2.1 后再拆分为多 Agent 角色。
+
+---
+
+## 3. 输入与输出契约
+
+### 3.1 关键输入产物
+
+- `output/manifest.json`
+- `output/spec_summary.json`
+- `output/task_plan.json`
+- `output/dispatch_plan.json`
+- `output/handoff/handoff_bundle.json`
+- `output/execution/run_state.json`
+- `output/execution/execution_report.json`
+- `output/execution/inbox/*.md`
+
+### 3.2 Orchestrator 统一上下文文件
+
+新增文件：
+
+- `output/orchestrator_context.json`
+
+用途：
+
+- 记录当前阶段、上次动作、最近错误、下一步建议
+- 为 Agent 提供单一事实源（single source of truth）
+
+建议结构：
+
+```json
+{
+  "version": "2.0.0-beta",
+  "updatedAt": "2026-04-02T10:00:00Z",
+  "workspace": "./output",
+  "state": "EXECUTION_RUNNING",
+  "lastAction": "spec-agent execute --workspace ./output --max-parallel 4",
+  "lastError": null,
+  "nextAction": "等待回填：--complete/--fail",
+  "metrics": {
+    "pending": 120,
+    "running": 4,
+    "succeeded": 33,
+    "failed": 2,
+    "blocked": 1
+  }
+}
+```
+
+---
+
+## 4. 状态机设计
+
+状态定义：
+
+- `INIT`
+- `READY`
+- `PIPELINE_RUNNING`
+- `PIPELINE_READY`
+- `EXECUTION_RUNNING`
+- `WAITING_FEEDBACK`
+- `PARTIAL_FAILED`
+- `DONE`
+
+状态转移规则（简化）：
+
+1. `INIT -> READY`：安装与环境检查通过
+2. `READY -> PIPELINE_RUNNING`：触发 pipeline
+3. `PIPELINE_RUNNING -> PIPELINE_READY`：产物齐全（task_plan + dispatch_plan）
+4. `PIPELINE_READY -> EXECUTION_RUNNING`：生成 handoff 并首次 execute
+5. `EXECUTION_RUNNING -> WAITING_FEEDBACK`：存在 running 任务，等待回填
+6. `WAITING_FEEDBACK -> EXECUTION_RUNNING`：回填完成，继续调度
+7. 任意状态 -> `PARTIAL_FAILED`：关键错误出现且不可自动恢复
+8. `EXECUTION_RUNNING -> DONE`：pending/running/blocked 归零
+
+---
+
+## 5. 决策规则（执行引擎）
+
+按优先级从上到下判断：
+
+1. 若 `spec-agent --version` 失败：
+   - 提示安装：`npm install -g spec-agent --registry=https://registry.npmjs.org/`
+2. 若 `dispatch_plan.json` 不存在：
+   - 执行 `spec-agent pipeline --input ./docs --output ./output`
+3. 若 `handoff_bundle.json` 不存在：
+   - 执行 `spec-agent handoff --workspace ./output --target cursor --include-summaries`
+4. 若 `run_state.json` 不存在：
+   - 执行 `spec-agent execute --workspace ./output --max-parallel 4`
+5. 若 `run_state` 中有 `running`：
+   - 进入等待反馈，不重复调度
+6. 若 `pending > 0` 且 `running = 0`：
+   - 再次执行 `execute` 调度
+7. 若 `failed` 增长：
+   - 调用故障分流策略，给出重试或人工介入建议
+
+---
+
+## 6. MVP 边界（先做可实验）
+
+v2 初版仅包含：
+
+- 安装检查与首轮 pipeline 引导
+- handoff + execute 调度闭环
+- `--complete / --fail` 回填推进
+- `orchestrator_context.json` 最小写入
+
+v2 初版不包含：
+
+- 自动代码生成与自动代码回填
+- 自动 PR 流程
+- 高级冲突自动修复
+
+---
+
+## 7. 失败分流策略
+
+错误类别与处理：
+
+- **安装类**（command not found）
+  - 给出安装命令与版本校验命令
+- **认证类**（npm ENEEDAUTH / E403）
+  - 给出登录或 2FA/token 指引
+- **配置类**（LLM key/base_url/model 缺失）
+  - 给出 `doctor --check-llm` 与变量模板
+- **执行类**（task failed）
+  - 记录 error，按 `--retry` 重试，超限标记 failed
+
+---
+
+## 8. 实施计划
+
+### Milestone A（1-2 天）
+
+- 落地 `orchestrator_context.json`
+- 实现决策函数（只读产物 -> 推荐命令）
+
+### Milestone B（2-3 天）
+
+- 将决策函数接入现有 Skill（onboarding + execution）
+- 支持一键“执行一轮”指令
+
+### Milestone C（2-3 天）
+
+- 加入失败分流模板（安装、认证、LLM、执行）
+- 增加轮次摘要输出（可复盘）
+
+---
+
+## 9. 验收标准
+
+- 新环境可从未安装状态引导至 `pipeline` 完成
+- 可连续推进至少 3 轮 execute，不丢失状态
+- 中断重开后可依据 `run_state` 和 `orchestrator_context` 恢复
+- 每轮输出明确下一步命令，不要求用户自行推断
+
+---
+
+## 10. 版本节奏对齐
+
+- `v1.x`：拆解 + 规划
+- `v2.x`：多 Agent 执行（Beta）
+- `v3.x`：多 Agent 闭环（执行 + 回填 + 验收）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-agent",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "CLI for requirement decomposition and agent-ready planning",
   "main": "dist/index.js",
   "bin": {

package/spec-agent-implementation.md

@@ -472,6 +472,21 @@ spec-agent execute --workspace ./workspace --fail T003 --error "build failed"
 
 ---
 
+### 3.14 orchestrate — 产物驱动决策（v2 beta）
+
+```bash
+spec-agent orchestrate --workspace ./workspace --input ./docs --target cursor --max-parallel 4
+```
+
+**功能**：
+
+- 读取 `manifest/spec/task_plan/dispatch/handoff/run_state/report` 等产物
+- 输出统一决策上下文 `orchestrator_context.json`
+- 基于当前产物状态给出下一条建议命令
+- 支持 `--format json` 供上层 Agent/Skill 程序化消费
+
+---
+
 ## 四、核心类型定义
 
 ```typescript

package/src/commands/orchestrate.ts

@@ -0,0 +1,282 @@
+import * as path from 'path';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { fileExists, readJson, writeJson } from '../utils/file';
+
+interface OrchestrateOptions {
+  workspace: string;
+  input?: string;
+  target: string;
+  maxParallel: string;
+  format: string;
+  dryRun?: boolean;
+}
+
+type OrchestratorState =
+  | 'INIT'
+  | 'READY'
+  | 'PIPELINE_RUNNING'
+  | 'PIPELINE_READY'
+  | 'EXECUTION_RUNNING'
+  | 'WAITING_FEEDBACK'
+  | 'PARTIAL_FAILED'
+  | 'DONE';
+
+interface ExecutionSummary {
+  pending: number;
+  running: number;
+  succeeded: number;
+  failed: number;
+  blocked: number;
+}
+
+interface OrchestratorContext {
+  version: string;
+  updatedAt: string;
+  workspace: string;
+  state: OrchestratorState;
+  checks: {
+    manifest: boolean;
+    specSummary: boolean;
+    taskPlan: boolean;
+    dispatchPlan: boolean;
+    handoffBundle: boolean;
+    runState: boolean;
+    executionReport: boolean;
+  };
+  metrics: ExecutionSummary;
+  lastAction: string | null;
+  lastError: string | null;
+  nextAction: string;
+  recommendedCommands: string[];
+}
+
+interface ExecutionReportLike {
+  summary?: Partial<ExecutionSummary>;
+  lastEvents?: Array<{ action?: string; detail?: string; taskId?: string }>;
+}
+
+interface RunStateLike {
+  tasks?: Record<string, { status?: string }>;
+}
+
+export async function orchestrateCommand(options: OrchestrateOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+  try {
+    const workspacePath = path.resolve(options.workspace);
+    const inputArg = options.input || './docs';
+    const maxParallel = Math.max(1, parseInt(options.maxParallel || '4', 10) || 4);
+    const target = (options.target || 'cursor').toLowerCase();
+    const contextPath = path.join(workspacePath, 'orchestrator_context.json');
+    const context = await buildOrchestratorContext({
+      workspaceArg: options.workspace,
+      inputArg,
+      target,
+      maxParallel,
+    });
+
+    if (!options.dryRun) {
+      await writeJson(contextPath, context);
+    }
+
+    if (options.format === 'json') {
+      logger.json(context);
+      return;
+    }
+
+    logger.info(`Orchestrator state: ${context.state}`);
+    logger.info(`Next action: ${context.nextAction}`);
+    logger.info(
+      `Metrics: pending=${context.metrics.pending}, running=${context.metrics.running}, succeeded=${context.metrics.succeeded}, failed=${context.metrics.failed}, blocked=${context.metrics.blocked}`
+    );
+    logger.info(`Context file: ${contextPath}`);
+    logger.info('Recommended commands:');
+    for (const cmd of context.recommendedCommands) {
+      logger.info(`  ${cmd}`);
+    }
+    if (options.dryRun) {
+      logger.warn('Dry run mode - context file not written');
+    }
+  } catch (error) {
+    logger.error(`Orchestrate failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+export async function buildOrchestratorContext(input: {
+  workspaceArg: string;
+  inputArg: string;
+  target: string;
+  maxParallel: number;
+}): Promise<OrchestratorContext> {
+  const workspacePath = path.resolve(input.workspaceArg);
+  const manifestPath = path.join(workspacePath, 'manifest.json');
+  const specPath = path.join(workspacePath, 'spec_summary.json');
+  const taskPlanPath = path.join(workspacePath, 'task_plan.json');
+  const dispatchPath = path.join(workspacePath, 'dispatch_plan.json');
+  const handoffPath = path.join(workspacePath, 'handoff', 'handoff_bundle.json');
+  const runStatePath = path.join(workspacePath, 'execution', 'run_state.json');
+  const reportPath = path.join(workspacePath, 'execution', 'execution_report.json');
+  const inputPath = path.resolve(input.inputArg);
+
+  const checks = {
+    manifest: await fileExists(manifestPath),
+    specSummary: await fileExists(specPath),
+    taskPlan: await fileExists(taskPlanPath),
+    dispatchPlan: await fileExists(dispatchPath),
+    handoffBundle: await fileExists(handoffPath),
+    runState: await fileExists(runStatePath),
+    executionReport: await fileExists(reportPath),
+  };
+
+  const metrics: ExecutionSummary = {
+    pending: 0,
+    running: 0,
+    succeeded: 0,
+    failed: 0,
+    blocked: 0,
+  };
+  let lastAction: string | null = null;
+  let lastError: string | null = null;
+  let runningTaskIds: string[] = [];
+  if (checks.executionReport) {
+    const report = await readJson<ExecutionReportLike>(reportPath);
+    metrics.pending = report.summary?.pending || 0;
+    metrics.running = report.summary?.running || 0;
+    metrics.succeeded = report.summary?.succeeded || 0;
+    metrics.failed = report.summary?.failed || 0;
+    metrics.blocked = report.summary?.blocked || 0;
+    const lastEvent = report.lastEvents && report.lastEvents.length > 0
+      ? report.lastEvents[report.lastEvents.length - 1]
+      : null;
+    if (lastEvent?.action) {
+      lastAction = `${lastEvent.action}${lastEvent.taskId ? `:${lastEvent.taskId}` : ''}`;
+    }
+    if (lastEvent?.action === 'failed' || lastEvent?.action === 'blocked') {
+      lastError = lastEvent.detail || `${lastEvent.action} event detected`;
+    }
+  }
+
+  if (checks.runState) {
+    const runState = await readJson<RunStateLike>(runStatePath);
+    const tasks = runState.tasks || {};
+    runningTaskIds = Object.entries(tasks)
+      .filter(([, value]) => value.status === 'running')
+      .map(([taskId]) => taskId)
+      .sort((a, b) => a.localeCompare(b));
+  }
+
+  const { state, nextAction, recommendedCommands } = decideNextAction({
+    checks,
+    metrics,
+    workspaceArg: input.workspaceArg,
+    inputArg: input.inputArg,
+    inputPathExists: await fileExists(inputPath),
+    target: input.target,
+    maxParallel: input.maxParallel,
+    runningTaskIds,
+  });
+
+  return {
+    version: '2.0.0-beta',
+    updatedAt: new Date().toISOString(),
+    workspace: workspacePath,
+    state,
+    checks,
+    metrics,
+    lastAction,
+    lastError,
+    nextAction,
+    recommendedCommands,
+  };
+}
+
+function decideNextAction(input: {
+  checks: OrchestratorContext['checks'];
+  metrics: ExecutionSummary;
+  workspaceArg: string;
+  inputArg: string;
+  inputPathExists: boolean;
+  target: string;
+  maxParallel: number;
+  runningTaskIds: string[];
+}): { state: OrchestratorState; nextAction: string; recommendedCommands: string[] } {
+  const { checks, metrics, workspaceArg, inputArg, inputPathExists, target, maxParallel, runningTaskIds } = input;
+  const pipelineCmd = `spec-agent pipeline --input ${inputArg} --output ${workspaceArg}`;
+  const handoffCmd = `spec-agent handoff --workspace ${workspaceArg} --target ${target} --include-summaries`;
+  const executeCmd = `spec-agent execute --workspace ${workspaceArg} --max-parallel ${maxParallel}`;
+  const statusCmd = `spec-agent status --workspace ${workspaceArg}`;
+
+  if (!checks.dispatchPlan) {
+    if (!inputPathExists) {
+      return {
+        state: 'INIT',
+        nextAction: 'Prepare input docs directory before running pipeline',
+        recommendedCommands: [
+          `mkdir ${inputArg}`,
+          '# put your requirement documents under docs/',
+          pipelineCmd,
+        ],
+      };
+    }
+    return {
+      state: checks.manifest ? 'PIPELINE_RUNNING' : 'READY',
+      nextAction: 'Run pipeline to produce planning artifacts',
+      recommendedCommands: [pipelineCmd, statusCmd],
+    };
+  }
+
+  if (!checks.handoffBundle) {
+    return {
+      state: 'PIPELINE_READY',
+      nextAction: 'Generate handoff bundle for execution loop',
+      recommendedCommands: [handoffCmd, executeCmd],
+    };
+  }
+
+  if (!checks.runState) {
+    return {
+      state: 'EXECUTION_RUNNING',
+      nextAction: 'Initialize execution state and schedule first batch',
+      recommendedCommands: [executeCmd],
+    };
+  }
+
+  if (metrics.running > 0) {
+    const completionIds = runningTaskIds.join(',');
+    const failExampleTask = runningTaskIds[0] || 'Txxx';
+    return {
+      state: 'WAITING_FEEDBACK',
+      nextAction: 'Collect worker feedback and apply --complete/--fail',
+      recommendedCommands: [
+        completionIds
+          ? `spec-agent execute --workspace ${workspaceArg} --complete ${completionIds}`
+          : `spec-agent execute --workspace ${workspaceArg} --complete Txxx`,
+        `spec-agent execute --workspace ${workspaceArg} --fail ${failExampleTask} --error "compile failed"`,
+        executeCmd,
+      ],
+    };
+  }
+
+  if (metrics.pending > 0) {
+    return {
+      state: 'EXECUTION_RUNNING',
+      nextAction: 'Schedule next executable batch',
+      recommendedCommands: [executeCmd],
+    };
+  }
+
+  if (metrics.failed > 0 || metrics.blocked > 0) {
+    return {
+      state: 'PARTIAL_FAILED',
+      nextAction: 'Investigate failed/blocked tasks then retry with execute',
+      recommendedCommands: [executeCmd, statusCmd],
+    };
+  }
+
+  return {
+    state: 'DONE',
+    nextAction: 'Execution loop completed',
+    recommendedCommands: [statusCmd],
+  };
+}

package/src/commands/round.ts

@@ -0,0 +1,189 @@
+import * as path from 'path';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { writeJson } from '../utils/file';
+import { pipelineCommand } from './pipeline';
+import { handoffCommand } from './handoff';
+import { executeCommand } from './execute';
+import { buildOrchestratorContext } from './orchestrate';
+
+interface RoundOptions {
+  workspace: string;
+  input: string;
+  target: string;
+  maxParallel: string;
+  retry?: string;
+  complete?: string;
+  fail?: string;
+  error?: string;
+  dryRun?: boolean;
+}
+
+export async function roundCommand(options: RoundOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+  try {
+    const workspaceArg = options.workspace || './output';
+    const inputArg = options.input || './docs';
+    const target = (options.target || 'cursor').toLowerCase();
+    const maxParallel = Math.max(1, parseInt(options.maxParallel || '4', 10) || 4);
+    const retry = String(Math.max(0, parseInt(options.retry || '1', 10) || 1));
+    const hasFeedback = Boolean((options.complete || '').trim() || (options.fail || '').trim());
+    const workspacePath = path.resolve(workspaceArg);
+    const contextPath = path.join(workspacePath, 'orchestrator_context.json');
+
+    const before = await buildOrchestratorContext({
+      workspaceArg,
+      inputArg,
+      target,
+      maxParallel,
+    });
+
+    let executedAction = 'none';
+    if (!options.dryRun) {
+      if (hasFeedback && before.checks.runState) {
+        executedAction = 'execute_feedback';
+        await executeCommand({
+          workspace: workspaceArg,
+          maxParallel: String(maxParallel),
+          retry,
+          complete: options.complete,
+          fail: options.fail,
+          error: options.error,
+          dryRun: false,
+        }, {} as Command);
+
+        const afterFeedback = await buildOrchestratorContext({
+          workspaceArg,
+          inputArg,
+          target,
+          maxParallel,
+        });
+
+        if (afterFeedback.metrics.pending > 0 && afterFeedback.metrics.running === 0) {
+          executedAction = 'execute_feedback_and_schedule';
+          await executeCommand({
+            workspace: workspaceArg,
+            maxParallel: String(maxParallel),
+            retry,
+            dryRun: false,
+          }, {} as Command);
+        }
+      } else if (!before.checks.dispatchPlan) {
+        executedAction = 'pipeline';
+        await pipelineCommand({
+          input: inputArg,
+          output: workspaceArg,
+          agents: 'auto',
+          chunkSize: '200kb',
+          minChunkSize: '10kb',
+          analyzeRetries: '1',
+          analyzeBudgetTokens: '0',
+          framework: 'vue3',
+          dryRun: false,
+        }, {} as Command);
+      } else if (!before.checks.handoffBundle) {
+        executedAction = 'handoff';
+        await handoffCommand({
+          workspace: workspaceArg,
+          output: 'handoff',
+          target,
+          includeSummaries: true,
+          dryRun: false,
+        }, {} as Command);
+      } else if (!before.checks.runState || (before.metrics.pending > 0 && before.metrics.running === 0)) {
+        executedAction = 'execute';
+        await executeCommand({
+          workspace: workspaceArg,
+          maxParallel: String(maxParallel),
+          retry,
+          dryRun: false,
+        }, {} as Command);
+      } else {
+        executedAction = 'wait_feedback';
+      }
+    }
+
+    const after = await buildOrchestratorContext({
+      workspaceArg,
+      inputArg,
+      target,
+      maxParallel,
+    });
+
+    if (!options.dryRun) {
+      await writeJson(contextPath, after);
+    }
+
+    logger.info(`Round action: ${executedAction}`);
+    logger.info(`State: ${after.state}`);
+    logger.info(`Next action: ${after.nextAction}`);
+    logger.info(
+      `Metrics: pending=${after.metrics.pending}, running=${after.metrics.running}, succeeded=${after.metrics.succeeded}, failed=${after.metrics.failed}, blocked=${after.metrics.blocked}`
+    );
+    logger.info('Recommended commands:');
+    for (const cmdLine of after.recommendedCommands) {
+      logger.info(`  ${cmdLine}`);
+    }
+    if (options.dryRun) {
+      logger.warn('Dry run mode - no command execution performed');
+    }
+    logger.json({
+      status: 'success',
+      executedAction,
+      state: after.state,
+      nextAction: after.nextAction,
+      metrics: after.metrics,
+      contextPath,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Round failed: ${message}`);
+    const recovery = inferRecoveryCommands(message, options);
+    if (recovery.length > 0) {
+      logger.info('Suggested recovery commands:');
+      for (const item of recovery) {
+        logger.info(`  ${item}`);
+      }
+    }
+    process.exit(1);
+  }
+}
+
+function inferRecoveryCommands(message: string, options: RoundOptions): string[] {
+  const workspaceArg = options.workspace || './output';
+  const inputArg = options.input || './docs';
+  const lower = message.toLowerCase();
+
+  if (lower.includes('not recognized') || lower.includes('command not found')) {
+    return [
+      'npm install -g spec-agent --registry=https://registry.npmjs.org/',
+      'spec-agent --version',
+    ];
+  }
+
+  if (lower.includes('eneedauth') || lower.includes('e403') || lower.includes('2fa')) {
+    return [
+      'npm login --registry=https://registry.npmjs.org/',
+      'npm profile get "two-factor auth" --registry=https://registry.npmjs.org/',
+    ];
+  }
+
+  if (lower.includes('api key') || lower.includes('llm') || lower.includes('configuration')) {
+    return [
+      `spec-agent doctor --workspace ${workspaceArg} --check-llm`,
+      '# set LLM_API_KEY / LLM_BASE_URL / LLM_MODEL then retry',
+    ];
+  }
+
+  if (lower.includes('manifest not found') || lower.includes('task plan not found') || lower.includes('dispatch_plan')) {
+    return [
+      `spec-agent pipeline --input ${inputArg} --output ${workspaceArg}`,
+      `spec-agent handoff --workspace ${workspaceArg} --target cursor --include-summaries`,
+    ];
+  }
+
+  return [
+    `spec-agent orchestrate --workspace ${workspaceArg} --input ${inputArg}`,
+    `spec-agent round --workspace ${workspaceArg} --input ${inputArg} --target ${(options.target || 'cursor')}`,
+  ];
+}