Claude-Code-Workflow/.claude/skills/skill-generator/specs/execution-modes.md

Execution Modes Specification

两种 Skill 执行模式的详细规范定义。

---

模式概览

特性	Sequential (顺序)	Autonomous (自主)
执行顺序	固定（数字前缀）	动态（编排器决策）
阶段依赖	强依赖	弱依赖/无依赖
状态管理	隐式（阶段产出）	显式（状态文件）
适用场景	流水线任务	交互式任务
复杂度	低	中-高
可扩展性	插入子阶段	添加新动作

---

Mode 1: Sequential (顺序模式)

定义

阶段按固定顺序线性执行，每个阶段的输出作为下一阶段的输入。

目录结构

phases/
├── 01-{first-step}.md
├── 02-{second-step}.md
├── 02.5-{sub-step}.md      # 可选：子阶段
├── 03-{third-step}.md
└── ...

执行流程

┌─────────┐     ┌─────────┐     ┌─────────┐
│Phase 01 │────▶│Phase 02 │────▶│Phase 03 │────▶ ...
└─────────┘     └─────────┘     └─────────┘
     │               │               │
     ▼               ▼               ▼
  output1.json   output2.md      output3.md

Phase 文件规范

# Phase N: {阶段名称}

{一句话描述}

## Objective

{详细目标}

## Input

- 依赖: {上一阶段产出}
- 配置: {配置文件}

## Execution Steps

### Step 1: {步骤}
{执行代码或说明}

### Step 2: {步骤}
{执行代码或说明}

## Output

- **File**: `{输出文件}`
- **Format**: {JSON/Markdown}

## Next Phase

→ [Phase N+1: xxx](0N+1-xxx.md)

适用场景

• 文档生成: 收集 → 分析 → 组装 → 优化
• 代码分析: 扫描 → 解析 → 报告
• 数据处理: 提取 → 转换 → 加载

优点

• 逻辑清晰，易于理解
• 调试简单，可逐阶段验证
• 输出可预测

缺点

• 灵活性低
• 难以处理分支逻辑
• 用户交互受限

---

Mode 2: Autonomous (自主模式)

定义

无固定执行顺序，由编排器 (Orchestrator) 根据当前状态动态选择下一个动作。

目录结构

phases/
├── orchestrator.md          # 编排器：核心决策逻辑
├── state-schema.md          # 状态结构定义
└── actions/                 # 独立动作（无顺序）
    ├── action-{a}.md
    ├── action-{b}.md
    ├── action-{c}.md
    └── ...

核心组件

1. Orchestrator (编排器)

# Orchestrator

## Role

根据当前状态选择并执行下一个动作。

## State Reading

读取状态文件: `{workDir}/state.json`

## Decision Logic

```javascript
function selectNextAction(state) {
  // 1. 检查终止条件
  if (state.status === 'completed') return null;
  if (state.error_count > MAX_RETRIES) return 'action-abort';
  
  // 2. 根据状态选择动作
  if (!state.initialized) return 'action-init';
  if (state.pending_items.length > 0) return 'action-process';
  if (state.needs_review) return 'action-review';
  
  // 3. 默认动作
  return 'action-complete';
}

Execution Loop

while (true) {
  state = readState();
  action = selectNextAction(state);
  if (!action) break;
  
  result = executeAction(action, state);
  updateState(result);
}

#### 2. State Schema (状态结构)

```markdown
# State Schema

## 状态文件

位置: `{workDir}/state.json`

## 结构定义

```typescript
interface SkillState {
  // 元信息
  skill_name: string;
  started_at: string;
  updated_at: string;
  
  // 执行状态
  status: 'pending' | 'running' | 'completed' | 'failed';
  current_action: string | null;
  completed_actions: string[];
  
  // 业务数据
  context: Record<string, any>;
  pending_items: any[];
  results: Record<string, any>;
  
  // 错误追踪
  errors: Array<{
    action: string;
    message: string;
    timestamp: string;
  }>;
  error_count: number;
}

初始状态

{
  "skill_name": "{skill-name}",
  "started_at": "{ISO8601}",
  "updated_at": "{ISO8601}",
  "status": "pending",
  "current_action": null,
  "completed_actions": [],
  "context": {},
  "pending_items": [],
  "results": {},
  "errors": [],
  "error_count": 0
}

#### 3. Action (动作)

```markdown
# Action: {action-name}

## Purpose

{动作目的}

## Preconditions

- [ ] 条件1
- [ ] 条件2

## Execution

{执行逻辑}

## State Updates

```javascript
return {
  completed_actions: [...state.completed_actions, 'action-name'],
  results: {
    ...state.results,
    action_name: { /* 结果 */ }
  },
  // 其他状态更新
};

Next Actions (Hints)

• 成功时: action-{next}
• 失败时: action-retry 或 action-abort

### 执行流程

┌─────────────────────────────────────────────────────────────────┐ │ Orchestrator Loop │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ Read │────▶│ Select │────▶│ Execute │ │ │ │ │ │ State │ │ Action │ │ Action │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ▲ │ │ │ │ │ │ ▼ │ │ │ │ │ ┌──────────┐ │ │ │ │ └───────────│ Update │◀────────────────────────┘ │ │ │ │ State │ │ │ │ └──────────┘ │ │ │ │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Termination? │ │ │ │ - completed │ │ │ │ - max_retries │ │ │ │ - user_abort │ │ │ └──────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

### 动作目录 (Action Catalog)

在 `specs/action-catalog.md` 中定义：

```markdown
# Action Catalog

## Available Actions

| Action | Purpose | Preconditions | Effects |
|--------|---------|---------------|---------|
| action-init | 初始化状态 | status=pending | status=running |
| action-process | 处理待办项 | pending_items.length>0 | pending_items-- |
| action-review | 用户审核 | needs_review=true | needs_review=false |
| action-complete | 完成任务 | pending_items.length=0 | status=completed |
| action-abort | 中止任务 | error_count>MAX | status=failed |

## Action Dependencies Graph

```mermaid
graph TD
    INIT[action-init] --> PROCESS[action-process]
    PROCESS --> PROCESS
    PROCESS --> REVIEW[action-review]
    REVIEW --> PROCESS
    REVIEW --> COMPLETE[action-complete]
    PROCESS --> ABORT[action-abort]

### 适用场景

- **交互式任务**: 问答、对话、表单填写
- **状态机任务**: Issue 管理、工作流审批
- **探索式任务**: 调试、诊断、搜索

### 优点

- 高度灵活，适应动态需求
- 支持复杂分支逻辑
- 易于扩展新动作

### 缺点

- 复杂度高
- 状态管理开销
- 调试难度大

---

## 模式选择指南

### 决策流程

用户需求分析 │ ▼ ┌────────────────────────────┐ │ 阶段间是否有强依赖关系？ │ └────────────────────────────┘ │ ├── 是 → Sequential │ └── 否 → 继续判断 │ ▼ ┌────────────────────────────┐ │ 是否需要动态响应用户意图？ │ └────────────────────────────┘ │ ├── 是 → Autonomous │ └── 否 → Sequential

### 快速判断表

| 问题 | Sequential | Autonomous |
|------|------------|------------|
| 输出结构是否固定？ | ✓ | ✗ |
| 是否需要用户多轮交互？ | ✗ | ✓ |
| 阶段是否可以跳过/重复？ | ✗ | ✓ |
| 是否有复杂分支逻辑？ | ✗ | ✓ |
| 调试是否需要简单？ | ✓ | ✗ |

---

## 混合模式

某些复杂 Skill 可能需要混合使用两种模式：

phases/ ├── 01-init.md # Sequential: 初始化 ├── 02-orchestrator.md # Autonomous: 核心交互循环 │ └── actions/ │ ├── action-a.md │ └── action-b.md └── 03-finalize.md # Sequential: 收尾

**适用场景**:
- 初始化和收尾固定，中间交互灵活
- 多阶段任务，某阶段需要动态决策