mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
9922d455da
- Introduced a comprehensive template for autonomous actions, detailing structure, execution, and error handling. - Added an orchestrator template to manage state and decision logic for autonomous actions. - Created a sequential phase template to outline execution steps and objectives for structured workflows. - Developed a skill documentation template to standardize the generation of skill entry files. - Implemented a Python script to compare search results between hybrid and cascade methods, analyzing ranking changes.
397 lines
10 KiB
Markdown
397 lines
10 KiB
Markdown
# 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 文件规范
|
|
|
|
```markdown
|
|
# 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 (编排器)
|
|
|
|
```markdown
|
|
# 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;
|
|
}
|
|
```
|
|
|
|
## 初始状态
|
|
|
|
```json
|
|
{
|
|
"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: 收尾
|
|
```
|
|
|
|
**适用场景**:
|
|
- 初始化和收尾固定，中间交互灵活
|
|
- 多阶段任务，某阶段需要动态决策
|