955 lines
24 KiB
Markdown
955 lines
24 KiB
Markdown
---
|
||
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 |