Execute Plan Skill

本 Skill 提供计划执行工作流的核心知识，包括计划格式规范、任务解析规则、依赖分析算法和批次执行策略。

---

1. 计划格式规范

1.1 支持的格式

格式	文件扩展名	检测方式
Markdown	.md	文件扩展名 + 任务模式检测
YAML	.yaml, .yml	文件扩展名 + tasks: 键检测

1.2 Markdown 计划格式

任务标记模式（按优先级检测）：

## Task 1: 实现用户认证模块
描述：实现基于 JWT 的用户认证...

## Task 2: 添加数据库迁移
描述：...

### 1. 创建 API 端点
描述：...

### 2. 添加单元测试
描述：...

- [ ] 重构认证中间件
- [ ] 添加错误处理
- [ ] 更新文档

1. **创建用户服务**
   - 文件: `src/services/user.ts`
   - 描述: ...

2. **添加数据验证**
   - 文件: `src/validators/user.ts`
   - 描述: ...

1.3 YAML 计划格式

title: "用户认证系统实现"
description: "实现完整的用户认证流程"

tasks:
  - id: T-001
    title: "创建用户模型"
    description: "定义 User 数据模型和相关类型"
    files:
      - src/models/user.ts
      - src/types/user.ts
    dependencies: []
    complexity: low

  - id: T-002
    title: "实现认证服务"
    description: "实现登录、注册、Token 刷新逻辑"
    files:
      - src/services/auth.ts
    dependencies:
      - T-001
    complexity: medium

1.4 任务字段规范

字段	必填	类型	说明
id	否	string	任务 ID（自动生成如 T-001）
title	是	string	任务标题
description	否	string	任务描述
files	否	string[]	涉及的文件列表
dependencies	否	string[]	依赖的任务 ID
complexity	否	enum	low/medium/high
test_files	否	string[]	相关测试文件

---

2. 任务解析规则

2.1 Markdown 任务提取

解析优先级：

1. ## Task N: 模式
2. ### N. 模式
3. - [ ] 模式
4. N. **xxx** 模式

示例解析：

## Task 1: 创建用户服务

实现用户 CRUD 操作的服务层。

**文件**：
- `src/services/user.ts`
- `src/types/user.ts`

**依赖**：无

**测试**：
- `tests/services/user.test.ts`

解析结果：

{
  "id": "T-001",
  "title": "创建用户服务",
  "description": "实现用户 CRUD 操作的服务层。",
  "files": ["src/services/user.ts", "src/types/user.ts"],
  "dependencies": [],
  "test_files": ["tests/services/user.test.ts"],
  "complexity": "medium"
}

2.2 复杂度推断

如果计划未显式指定复杂度，根据以下规则推断：

条件	复杂度
涉及文件 ≤ 2 且无依赖	low
涉及文件 3-5 或有 1-2 个依赖	medium
涉及文件 > 5 或有 > 2 个依赖	high

2.3 ID 自动生成

如果任务无 ID，按顺序生成：

• T-001, T-002, T-003, ...

---

3. 依赖分析算法

3.1 显式依赖

计划中通过 dependencies 字段声明的依赖关系。

3.2 隐式依赖检测

自动检测以下隐式依赖：

1. 同文件修改：多个任务修改同一文件时，按任务顺序形成依赖链
2. 类型/接口依赖：任务 A 创建类型，任务 B 使用该类型
3. 导入依赖：任务 A 创建模块，任务 B 导入该模块

3.3 拓扑排序

使用 Kahn 算法进行拓扑排序：

def topological_sort(tasks, dependencies):
    in_degree = {t.id: 0 for t in tasks}
    for deps in dependencies.values():
        for dep in deps:
            in_degree[dep] += 1

    queue = [t for t in tasks if in_degree[t.id] == 0]
    result = []

    while queue:
        task = queue.pop(0)
        result.append(task)
        for t in tasks:
            if task.id in dependencies.get(t.id, []):
                in_degree[t.id] -= 1
                if in_degree[t.id] == 0:
                    queue.append(t)

    if len(result) != len(tasks):
        raise CyclicDependencyError("检测到循环依赖")

    return result

3.4 循环依赖检测

如果检测到循环依赖：

1. 停止执行
2. 报告循环涉及的任务
3. 建议解决方案（拆分任务或重新排序）

---

4. 批次执行策略

4.1 批次划分原则

1. 依赖优先：同一批次内的任务不应有依赖关系
2. 复杂度平衡：每批包含的 high 复杂度任务不超过 1 个
3. 大小限制：每批任务数不超过配置的 batch_size

4.2 批次生成算法

def generate_batches(sorted_tasks, batch_size, max_parallel):
    batches = []
    current_batch = []
    completed = set()

    for task in sorted_tasks:
        # 检查依赖是否已完成
        deps_satisfied = all(d in completed for d in task.dependencies)

        # 检查是否可以并行（无同文件修改）
        can_parallel = not any(
            set(task.files) & set(t.files)
            for t in current_batch
        )

        if deps_satisfied and can_parallel and len(current_batch) < batch_size:
            current_batch.append(task)
        else:
            if current_batch:
                batches.append(current_batch)
                completed.update(t.id for t in current_batch)
            current_batch = [task]

    if current_batch:
        batches.append(current_batch)

    return batches

4.3 批次内并行

同一批次内的任务可以并行执行，条件：

1. 任务之间无依赖
2. 任务不修改同一文件
3. 并行数不超过 max_parallel

---

5. 置信度评估标准

5.1 任务置信度

每个任务的置信度基于以下因素：

因素	权重	评分标准
文件存在性	30%	目标文件/目录是否存在或可创建
描述清晰度	25%	任务描述是否明确可执行
依赖可满足	25%	依赖任务是否已定义且无循环
复杂度合理	20%	复杂度评估是否合理

5.2 计划整体置信度

整体置信度 = 所有任务置信度的加权平均

权重：

• high 复杂度任务：权重 3
• medium 复杂度任务：权重 2
• low 复杂度任务：权重 1

5.3 置信度决策

整体置信度	行为
≥ 80	自动继续执行
60-79	展示验证结果，询问用户是否继续
40-59	建议调整计划后重试
< 40	停止，报告计划无法执行

---

6. TDD 执行流程

6.1 每个任务的 TDD 周期

1. RED Phase
   ├─ 识别或创建测试文件
   ├─ 编写失败的测试用例
   └─ 运行测试确认失败

2. GREEN Phase
   ├─ 实现最小代码使测试通过
   └─ 运行测试确认通过

3. REFACTOR Phase
   ├─ 重构代码（保持测试通过）
   ├─ 运行 lint 检查
   └─ 运行类型检查

6.2 TDD 跳过条件

以下情况可跳过 TDD：

1. 纯配置文件修改
2. 文档更新
3. 样式/格式调整

---

7. 常见问题处理

7.1 计划格式无法解析

症状：无法识别任务列表

解决：

1. 检查是否使用支持的格式（Markdown/YAML）
2. 确认任务标记符合规范
3. 提供示例格式供参考

7.2 循环依赖

症状：拓扑排序失败

解决：

1. 识别循环涉及的任务
2. 建议拆分任务或调整依赖
3. 支持用户手动打破循环

7.3 文件冲突

症状：多个任务修改同一文件且无法确定顺序

解决：

1. 检测同文件修改的任务
2. 建议添加显式依赖
3. 串行执行冲突任务

7.4 置信度过低

症状：整体置信度 < 40

可能原因：

• 任务描述不清晰
• 目标文件不存在
• 依赖关系复杂或有循环

解决：

1. 报告具体的低置信度任务
2. 列出影响置信度的因素
3. 建议改进措施

---

8. 输出格式规范

8.1 init_ctx 格式

{
  "config": {
    "test_command": "make test",
    "lint_command": "make lint",
    "typecheck_command": "make typecheck",
    "batch_size": 3,
    "docs": {
      "bugfix_dir": "docs/bugfix",
      "best_practices_dir": "docs/best-practices"
    }
  },
  "plan_info": {
    "source": "file",
    "path": "docs/plans/feature-auth.md",
    "title": "用户认证系统实现",
    "format": "markdown",
    "total_tasks": 5
  },
  "tasks": [...],
  "project_info": {
    "plugin_root": "/path/to/project",
    "git": {
      "branch": "feature/auth",
      "modified_files": []
    },
    "detected_stack": "mixed"
  }
}

8.2 验证结果格式

{
  "validation_results": [...],
  "execution_order": ["T-001", "T-002", "T-003"],
  "batches": [
    {
      "batch_id": 1,
      "tasks": ["T-001", "T-002"],
      "can_parallel": true
    }
  ],
  "overall_confidence": 85,
  "recommendation": "proceed"
}

8.3 执行报告格式

{
  "execution_results": [
    {
      "task_id": "T-001",
      "status": "completed",
      "tdd_cycles": 1,
      "changes": [...],
      "duration_seconds": 120
    }
  ],
  "summary": {
    "total": 5,
    "completed": 4,
    "skipped": 1,
    "failed": 0
  },
  "review_results": {...},
  "knowledge_extracted": [...]
}