---
description: "需求规划拆解：将复杂需求转化为结构化任务树，生成执行计划"
---

# /runtime.plan - 需求规划与任务拆解

## 核心目标

**我们不是执行者，我们是规划者**。

当面对复杂需求时，我们像经验丰富的架构师一样：
1. **理解需求本质** - 用户真正想要的是什么？
2. **功能分解** - 将大问题拆解为小任务
3. **识别依赖** - 哪些必须先做，哪些可以并行？
4. **估算工时** - 需要多少时间？风险在哪里？
5. **生成执行路径** - 最优的实施顺序

```
用户需求 → 需求分析 → 功能拆解 → 依赖识别 → 任务树 → 执行计划
                                                              ↓
                                                    /runtime.iterate
```

---

## 何时使用 /runtime.plan

### 必须使用场景
- ✅ **用户需求模糊**："我想加个电商功能" → 需要拆解为具体任务
- ✅ **技术方案不确定**：需要分析多种实现路径
- ✅ **项目范围大**：功能复杂，需要系统性规划
- ✅ **团队协作**：需要清晰的任务分配和依赖关系
- ✅ **估算和排期**：需要工作量估算和时间线

### 使用流程

```bash
用户: "实现用户认证系统（注册、登录、密码重置、JWT）"

AI:
/runtime.plan "用户认证系统"
  ↓ 自动执行...

[阶段1: 需求分析]
- 识别需求类型: 新功能开发
- 提取约束: JWT有效期7天、并发1000
- 分析技术栈: Express + PostgreSQL
- 识别范围: API、DB、安全、邮件

[阶段2: 功能拆解]
- 功能点: 注册、登录、密码重置、JWT管理、登出
- 任务数: 17个任务
- 分层: 基础设施 → 服务层 → API → 安全 → 测试

[阶段3: 依赖分析]
- 构建依赖图
- 计算关键路径
- 识别可并行任务

[阶段4: 估算与风险]
- 总工时: 17.75小时
- 关键路径: 9小时
- 风险: 密码重置流程复杂

[输出: 交付给用户]
- 可视化任务树 (ASCII/MD格式)
- JSON格式的机器可读计划
- 甘特图时间线
- 风险评估报告

# 然后进入迭代执行
/runtime.iterate --plan=plan-2025xx.json
  ↓ 自动执行...
```

---

## 规划过程详解

### 阶段1: 需求分析 (Understanding)

#### 1.1 需求类型识别

```python
def identify_requirement_type(text: str) -> RequirementType:
    """识别需求类型"""
    if any(word in text for word in ["添加", "实现", "开发", "新功能"]):
        return RequirementType.NEW_FEATURE

    if any(word in text for word in ["修复", "bug", "错误", "问题"]):
        return RequirementType.BUG_FIX

    if any(word in text for word in ["重构", "优化", "改进", "清理"]):
        return RequirementType.REFACTORING

    if any(word in text for word in ["学习", "理解", "调研", "研究"]):
        return RequirementType.RESEARCH

    return RequirementType.UNKNOWN
```

#### 1.2 约束提取

从需求中提取隐含约束：

```python
def extract_constraints(demand: str) -> Constraints:
    """提取约束条件"""

    constraints = {
        "time": None,      # 时间约束
        "budget": None,    # 资源约束
        "tech_stack": [],  # 技术栈约束
        "performance": {}, # 性能约束
        "security": {},    # 安全约束
    }

    # 性能约束
    if "并发" in demand:
        # "支持并发1000用户"
        match = re.search(r"并发(\d+)", demand)
        if match:
            constraints["performance"]["concurrency"] = int(match.group(1))

    # 时间约束
    if "JWT" in demand and "天" in demand:
        # "JWT有效期7天"
        match = re.search(r"有效期(\d+)天", demand)
        if match:
            constraints["security"]["tokenExpiry"] = int(match.group(1))

    # 安全约束
    if "加密" in demand:
        constraints["security"]["encryption"] = True

    return constraints
```

#### 1.3 知识缺口识别

```python
def identify_knowledge_gaps(demand: str, context: Memory) -> List[str]:
    """
    识别规划需要但当前缺乏的知识
    """
    gaps = []

    # 检查技术栈
    if "JWT" in demand and not context.has_pattern("jwt"):
        gaps.append("JWT实现模式")

    if "密码" in demand and not context.has_pattern("bcrypt"):
        gaps.append("密码哈希模式")

    # 检查架构
    if "认证" in demand and not context.has_pattern("auth"):
        gaps.append("认证架构模式")

    # 检查项目上下文
    if not context.has_key("tech_stack"):
        gaps.append("项目技术栈")

    return gaps
```

---

### 阶段2: 功能分解 (Decomposition)

#### 2.1 洋葱模型分解法

```
                [用户可见功能]
                      ↑
            ╔═════════════════════╗
            ║   API层 (REST/GraphQL) ║
            ╚═══════════╦═══════════╝
                        ↓
            ╔═════════════════════╗
            ║  服务层 (业务逻辑)    ║
            ╚═══════════╦═══════════╝
                        ↓
            ╔═════════════════════╗
            ║  数据层 (DB/Cache)   ║
            ╚═══════════╦═══════════╝
                        ↓
            ╔═════════════════════╗
            ║  基础设施 (安全/监控) ║
            ╚═════════════════════╝
```

**分解规则**:
- 每一层都可以独立分解
- 上层依赖下层
- 同层任务尽量解耦

#### 2.2 认证系统分解示例

```python
# 顶层: 用户故事
stories = [
    "作为新用户，我可以注册账号",
    "作为用户，我可以登录系统",
    "作为忘记密码的用户，我可以重置密码",
    "作为登录用户，我可以安全退出"
]

# 第二层: 功能点
features = {
    "注册": {
        "输入": ["email", "password"],
        "验证": ["邮箱格式", "密码强度", "邮箱唯一性"],
        "副作用": ["密码哈希", "生成验证Token", "发送邮件"]
    },
    "登录": {
        "输入": ["email", "password"],
        "验证": ["账号存在", "密码匹配", "账号已验证"],
        "输出": ["JWT Token", "Refresh Token"]
    }
}

# 第三层: 技术任务
tasks = {
    "注册": [
        "创建User表",
        "实现密码bcrypt哈希",
        "实现邮箱验证逻辑",
        "实现Register API",
        "集成邮件服务",
        "写单元测试"
    ]
}
```

#### 2.3 MECE原则（Mutually Exclusive, Collectively Exhaustive）

```markdown
# 好的分解（符合MECE）

✅ 认证系统
├─ 注册（独立功能）
├─ 登录（独立功能）
├─ 密码重置（独立功能）
└─ Token管理（独立功能）

# 坏的分解（不符合MECE）

❌ 认证系统
├─ 注册（独立）
├─ 登录（独立）
├─ 发送邮件（重复：注册和密码重置都发送邮件）  ← 不互斥
└─ ...（缺少Token刷新、登出） ← 不穷尽
```

---

### 阶段3: 依赖关系分析

#### 3.1 依赖类型

```python
class DependencyType(Enum):
    # 必须先完成A，才能开始B
    SEQUENTIAL = "sequential"  # 串行

    # A和B可以同时进行
    PARALLEL = "parallel"      # 并行

    # A完成后，B才能开始，但C不需要A
    PARTIAL = "partial"        # 部分依赖

    # A和B互相依赖（需要重构设计）
    CIRCULAR = "circular"      # 循环依赖（坏味道）
```

#### 3.2 构建依赖图

```python
def build_dependency_graph(tasks: List[Task]) -> nx.DiGraph:
    """
    构建任务依赖关系图
    """
    G = nx.DiGraph()

    # 添加节点
    for task in tasks:
        G.add_node(task.id,
                  name=task.name,
                  effort=task.effort,
                  priority=task.priority,
                  risk=task.risk_level)

    # 添加边（依赖关系）
    for task in tasks:
        for dep_id in task.dependencies:
            G.add_edge(dep_id, task.id, type="depends_on")

    return G
```

#### 3.3 识别关键路径

```python
def find_critical_path(G: nx.DiGraph) -> List[str]:
    """
    计算关键路径（最长工时路径）
    """
    # 计算每个节点到终点的最长路径
    critical_path = nx.dag_longest_path(G, weight="effort")

    return critical_path
```

**认证系统关键路径示例**: `User表 → Token表 → Token服务 → Login API → 集成测试`

**总工时**: 9小时（最短可能完成时间）

---

### 阶段4: 任务树生成

#### 4.1 可视化任务树 (ASCII)

```python
def generate_ascii_tree(tasks: List[Task]) -> str:
    """
    生成ASCII格式的任务树
    """
    lines = []
    lines.append("实现用户认证系统 (目标)")
    lines.append("│")

    # 按层级分组
    layers = {
        "基础设施": ["①", "②", "③"],
        "服务层": ["④", "⑤", "⑥"],
        "API层": ["⑦", "⑧", "⑨", "⑩", "⑪"],
        "安全层": ["⑫", "⑬", "⑭"],
        "测试": ["⑮", "⑯", "⑰"]
    }

    for i, (layer_name, task_ids) in enumerate(layers.items()):
        lines.append(f"├─ {layer_name}")

        for j, task_id in enumerate(task_ids):
            task = get_task(task_id)
            prefix = "└─" if j == len(task_ids) - 1 else "├─"
            lines.append(f"│   {prefix} {task_id}: {task.name} ({task.effort}h)")

    return "\n".join(lines)
```

**输出示例**: `.ai-runtime/commands/runtime.plan.md`中包含完整示例

#### 4.2 JSON格式的任务树

```json
{
  "project": "用户认证系统",
  "total_tasks": 17,
  "total_effort": "17.75h",
  "critical_path": ["①","②","⑤","⑧","⑮","⑯"],
  "critical_path_effort": "9h",
  "tasks": [
    {
      "id": "①",
      "name": "创建User表",
      "layer": "基础设施",
      "effort": 0.5,
      "priority": "P0",
      "dependencies": [],
      "risk": "low",
      "acceptance_criteria": [
        "表结构符合User模型",
        "已添加email唯一索引",
        "created_at自动填充"
      ]
    },
    {
      "id": "②",
      "name": "创建Token表",
      "layer": "基础设施",
      "effort": 0.5,
      "priority": "P0",
      "dependencies": ["①"],
      "risk": "low"
    }
  ],
  "phases": [
    {
      "phase": 1,
      "name": "基础设施",
      "tasks": ["①","②","③"],
      "parallelizable": true
    },
    {
      "phase": 2,
      "name": "服务层",
      "tasks": ["④","⑤","⑥"]
    }
  ]
}
```

#### 4.3 甘特图生成

```python
def generate_gantt(tasks: List[Task]) -> str:
    """
    生成简单的甘特图（Markdown格式）
    """
    lines = []
    lines.append("```gantt")
    lines.append("title 认证系统实施计划")
    lines.append("dateFormat  YYYY-MM-DD")
    lines.append("")

    # 按阶段分组
    for phase in ["基础设施", "服务层", "API层", "安全层", "测试"]:
        phase_tasks = [t for t in tasks if t.layer == phase]
        if phase_tasks:
            lines.append(f"section {phase}")
            for task in phase_tasks:
                start = task.start_date.strftime('%Y-%m-%d')
                end = task.end_date.strftime('%Y-%m-%d')
                lines.append(f"{task.name} :a{task.id}, {start}, {end}")

    lines.append("```")

    return "\n".join(lines)
```

---

### 阶段5: 风险评估

#### 5.1 识别风险

```python
def identify_risks(tasks: List[Task]) -> List[Risk]:
    """
    基于任务特征识别风险
    """
    risks = []

    for task in tasks:
        # 复杂度过高风险
        if task.effort > 4:
            risks.append(Risk(
                task=task.id,
                level="medium",
                category="complexity",
                description="任务过大，可能隐藏未知问题",
                mitigation="进一步分解成子任务"
            ))

        # 依赖过多风险
        if len(task.dependencies) > 3:
            risks.append(Risk(
                task=task.id,
                level="high",
                category="dependency",
                description="强依赖多个任务，成为阻塞点",
                mitigation="尽早开始，或与下游任务同步进行"
            ))

        # 新知识风险
        if task.confidence < 0.6:
            risks.append(Risk(
                task=task.id,
                level="high",
                category="knowledge",
                description="不熟悉的技术/模式，容易出错",
                mitigation="先进行小的Spike，或请求专家帮助"
            ))

    return risks
```

#### 5.2 风险矩阵

```markdown
## 风险评估矩阵

| 任务 | 风险类型 | 可能性 | 影响 | 等级 | 应对策略 |
|------|---------|--------|------|------|---------|
| 密码重置流程 | 复杂度 | 中 | 高 | 🔴 高 | 进一步分解，先做Spike |
| Token刷新 | 知识缺口 | 高 | 中 | 🟡 中 | 查阅资料，咨询专家 |
| Email服务 | 外部依赖 | 低 | 中 | 🟢 低 | 设计降级方案 |
```

---

## 命令定义

### 语法

```bash
/runtime.plan "[需求描述]" \
  --strategy=[full|mvp|risk-driven] \
  --estimate=[true|false] \
  --detail=[high|medium|low] \
  --output=[json|md|both]
```

### 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `strategy` | 规划策略<br>- `full`: 完整规划所有细节<br>- `mvp`: 只规划MVP核心功能<br>- `risk-driven`: 优先规划高风险部分 | `full` |
| `estimate` | 是否包含工时估算 | `true` |
| `detail` | 任务详细程度 | `medium` |
| `output` | 输出格式 | `both` |

### 使用示例

#### 示例1: 完整规划

```bash
/runtime.plan "实现用户认证系统，包括注册、登录、密码重置、JWT管理，使用bcrypt加密，JWT有效期7天"
```

**输出**:

**console**:
```
📋 需求规划: 用户认证系统
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

需求类型: 新功能开发
技术栈: Node.js + Express + PostgreSQL + JWT
约束: JWT有效期7天，bcrypt加密

[功能拆解]
├─ 注册
├─ 登录
├─ 密码重置
└─ JWT管理

[任务统计]
总任务数: 17个
总工时: 17.75小时
关键路径: 9小时

[风险]
⚠️  密码重置流程复杂度高（建议Spike）
⚠️  Token刷新机制不熟悉（建议先调研）

输出文件:
✓ cognition/plans/plan-20251114-1045.json
✓ cognition/plans/plan-20251114-1045.md
✓ cognition/graphs/task-tree-20251114-1045.svg
```

**JSON输出**: `cognition/plans/plan-20251114-1045.json`
```json
{
  "project": "用户认证系统",
  "requirement": "实现用户认证系统，包括注册...",
  "total_tasks": 17,
  "total_effort": "17.75h",
  "critical_path": ["①","②","⑤","⑧","⑮","⑯"],
  "tasks": [...],
  "risks": [...]
}
```

**Markdown输出**: `cognition/plans/plan-20251114-1045.md`
```markdown
# 用户认证系统 - 实施计划

## 需求概述
实现用户认证系统...

## 任务树

### 阶段1: 基础设施
- ① 创建User表 (0.5h) - P0
- ② 创建Token表 (0.5h) - P0 - 依赖:①
- ③ 配置JWT (0.25h) - P0

...

## 甘特图
```gantt
...
```

## 风险评估
...
```

#### 示例2: MVP规划

```bash
/runtime.plan "构建图片分享社交平台" --strategy=mvp
```

**特点**:
- 只规划核心功能（上传图片、浏览、点赞、评论）
- 非核心功能（滤镜、故事、推荐算法）推迟到后续迭代
- 快速交付可演示版本

#### 示例3: 风险驱动规划

```bash
/runtime.plan "实现微服务架构的电商平台" --strategy=risk-driven
```

**特点**:
- 优先识别高风险任务（服务拆分、数据一致性、分布式事务）
- 建议先Spike，降低不确定性
- 生成风险评估报告

---

## 规划策略

### 策略1: Full（完整规划）

```
适用: 项目需求明确，技术方案清晰，有足够时间

特点:
- 规划所有细节
- 包括测试、文档、监控
- 精确到小时的估算

输出: 完整项目计划（类似PRD + 技术方案）
```

### 策略2: MVP（最小可行产品）

```
适用: 需求探索期，需要快速验证，时间紧张

特点:
- 只规划核心价值功能
- 砍掉所有"锦上添花"的功能
- 估算粗略（只到天）

输出: MVP功能清单 + 最小任务集
```

**示例**: 社交应用MVP
- ✅ 用户注册/登录
- ✅ 发帖
- ✅ 浏览帖子
- ✅ 点赞

**推迟到迭代2**:
- ❌ 评论回复
- ❌ 私信
- ❌ 推荐算法
- ❌ 图片滤镜

### 策略3: Risk-Driven（风险驱动规划）

```
适用: 技术不确定性强，有高风险模块

特点:
- 优先分析高风险任务
- 建议先做技术调研（Spike）
- 生成风险缓解计划

输出: 风险矩阵 + 应对策略 + 调整后任务树
```

**示例**: 微服务架构

高风险任务:
1. 服务拆分策略 → 先做Spike
2. 分布式事务 → 调研Saga模式
3. 数据一致性 → 评估最终一致性影响

低风险任务（可以推迟）:
- API网关 → 成熟技术，直接使用
- 服务发现 → Consul/Nacos直接使用
- 配置中心 → Apollo/Nacos直接使用

---

## 任务规格模板

每个任务使用统一模板：

```markdown
## Task {ID}: {任务名称}

**ID**: TASK-{ID}
**类型**: [feature|bug|refactor|doc|test]
**优先级**: [P0|P1|P2]
**预计工时**: X小时
**置信度**: 0.X (0-1)
**依赖**: [依赖的任务ID列表]

### 目标
[清晰描述任务的目标]

### 验收标准（DoD）
- [ ] 代码实现完成
- [ ] 单元测试覆盖率 > 80%
- [ ] 手动测试通过
- [ ] 代码审查通过
- [ ] 文档更新
- [ ] 无回归错误

### 实现大纲
1. [步骤1]
2. [步骤2]
3. [步骤3]

### 潜在风险
- ⚠️ [风险1]
- ⚠️ [风险2]

### 如果卡住（Escalation）
- [求助谁/查阅什么]

### 相关文件
- [文件路径]
```

---

## 与 /runtime.learn 的区别

| 维度 | `/runtime.learn` | `/runtime.plan` | 为什么分开？ |
|------|-----------------|----------------|------------|
| **目标** | 理解未知问题 | 规划已知需求 | 认知阶段不同 |
| **输入** | 问题（需要探索） | 需求（相对明确） | 前提条件不同 |
| **核心** | 知识缺口识别 | 功能拆解与依赖分析 | 方法论不同 |
| **输出** | 学习报告 + 新知识 | 任务树 + 执行计划 | 产物不同 |
| **下一步** | 通常接 /runtime.plan | 接 /runtime.iterate | 工作流分工 |

**典型工作流**:
```
情况A: 完全未知的问题
/runtime.learn "为什么服务会崩溃？"
  ↓ 理解后，发现问题: "需要添加限流"
/runtime.plan "实现限流功能"  # 生成实施计划
  ↓
/runtime.iterate --plan=plan-xx.json  # 执行计划

情况B: 明确的需求
/runtime.plan "实现用户认证系统"  # 直接规划
  ↓
/runtime.iterate --plan=plan-xx.json  # 执行计划
```

---

## 工具与脚本

### 辅助脚本: task-analyzer.py

```python
#!/usr/bin/env python3
"""
任务分析器 - 从需求文本提取结构化信息
"""

import re
import json

class TaskAnalyzer:
    def __init__(self):
        self.patterns = {
            "action": r"(实现|添加|修改|删除|重构|修复)",
            "object": r"(用户|认证|JWT|密码|邮件|Token|API)",
            "constraint": r"\[(.*?)\]",
            "time": r"(\d+天|\d+小时|\d+h)"
        }

    def analyze(self, requirement_text):
        """分析需求文本"""
        result = {
            "actions": [],
            "objects": [],
            "constraints": [],
            "time_keywords": []
        }

        for key, pattern in self.patterns.items():
            matches = re.findall(pattern, requirement_text)
            result[f"{key}s"] = matches

        return result

    def suggest_tasks(self, analysis):
        """基于分析建议任务"""
        tasks = []

        # 如果发现"认证"和"用户"
        if "认证" in analysis["objects"] and "用户" in analysis["objects"]:
            tasks.extend([
                "创建User表",
                "实现密码哈希",
                "实现注册API",
                "实现登录API"
            ])

        # 如果发现"JWT"
        if "JWT" in analysis["objects"]:
            tasks.extend([
                "配置JWT",
                "实现Token生成",
                "实现Token验证",
                "实现Token刷新"
            ])

        return list(set(tasks))

# 使用示例
analyzer = TaskAnalyzer()
result = analyzer.analyze("实现用户认证系统，包括JWT和bcrypt加密")
print(json.dumps(result, indent=2, ensure_ascii=False))
```

---

## 最佳实践

### 实践1: 规划前先用Learn（如果不确定）

```bash
# 不确定现有架构
❌ /runtime.plan "实现新功能X"  # 可能规划不切实际

# 先学习，再规划
✅ /runtime.learn "理解现有架构" → 置信度>0.8
✅ /runtime.plan "实现新功能X"
```

### 实践2: 用小需求练习

```bash
# 复杂需求（不建议首次尝试）
❌ /runtime.plan "重构整个微服务架构"

# 从小需求开始
✅ /runtime.plan "添加密码重置功能"  # 3-5个任务
✅ /runtime.plan "实现用户注册"      # 2-3个任务
```

### 实践3: 定期重新规划

```python
# 需求变更时
if requirement_changed:
    # 不是继续执行旧计划
    old_plan = load_old_plan()

    # 而是重新规划
    new_plan = runtime.plan(new_requirement)

    # 比较差异
    diff = compare_plans(old_plan, new_plan)

    # 适应新计划
    runtime.iterate(plan=new_plan)
```

### 实践4: 保存并复用模式

```bash
# 规划完成后
/runtime.plan "实现OAuth2.0认证"

# 固化成功模式
/runtime.remember "OAuth2.0认证的任务树模板"

# 下次类似需求
/runtime.plan "实现SAML认证"
  → AI从记忆中提取OAuth2.0模式作为参考
  → 生成类似结构的任务树
```

---

## 输出规范

### JSON Schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "version": {"type": "string"},
    "project": {"type": "string"},
    "requirement": {"type": "string"},
    "created_at": {"type": "string"},
    "total_tasks": {"type": "integer"},
    "total_effort": {"type": "string"},
    "critical_path": {
      "type": "array",
      "items": {"type": "string"}
    },
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "layer": {"type": "string"},
          "effort": {"type": "number"},
          "priority": {"type": "string"},
          "dependencies": {
            "type": "array",
            "items": {"type": "string"}
          },
          "acceptance_criteria": {
            "type": "array",
            "items": {"type": "string"}
          }
        }
      }
    },
    "risks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "task": {"type": "string"},
          "level": {"type": "string"},
          "category": {"type": "string"},
          "description": {"type": "string"},
          "mitigation": {"type": "string"}
        }
      }
    }
  }
}
```

---

## 宪法遵循

**遵循原则**:
- ✓ 1.2 类脑思维: 将需求拆解为可管理的模块
- ✓ 2.1 代码即知识: 任务树是代码结构的心智模型
- ✓ 4.4 规划透明: 规划过程清晰可见（新增）
- ✓ 1.3 谦逊与不确定: 明确标注置信度和风险
- ✓ 2.2 渐进式实施: 支持MVP和风险驱动策略

---

**命令定义**: `.ai-runtime/commands/runtime.plan.md`
**脚本**: `.ai-runtime/scripts/task-analyzer.py` (辅助分析)
**输出**: `cognition/plans/plan-{timestamp}.{json|md}`
**版本**: 1.0.0