Plan Parser 与 Prompt Builder

这是「GSD 全景代码解析」专题的第 40 篇。

一、Plan Parser 核心职责

PlanParser 负责将 plan.json 转换为运行时数据结构：

interface ParsedPlan {
  title: string;
  description: string;
  tasks: ParsedTask[];
  globals: Record<string, any>;
  metadata: PlanMetadata;
}

interface ParsedTask {
  id: string;
  name: string;
  agent: string;
  prompt: string;          // 原始模板
  promptResolved: string;  // 解析后
  dependencies: string[];
  outputs: string[];
  condition?: string;
}

二、Prompt Builder 工作流程

graph LR
    A[plan.json] --> B[PlanParser]
    B --> C[解析任务结构]
    C --> D[加载模板]
    D --> E[注入变量]
    E --> F[构建最终 Prompt]
    F --> G[传递给 Agent]

2.1 模板语法

// 变量插值
${task.name}
${globals.projectTitle}

// 条件渲染
{{#if task.condition}}
  执行条件任务
{{/if}}

// 循环
{{#each task.dependencies}}
  - {{this}}
{{/each}}

三、动态 Prompt 构建

class PromptBuilder {
  build(task: ParsedTask, context: BuildContext): string {
    // 1. 加载基础模板
    let prompt = this.loadTemplate(task.agent);
    
    // 2. 注入系统上下文
    prompt = this.injectSystemContext(prompt, context);
    
    // 3. 注入任务特定变量
    prompt = this.injectTaskVars(prompt, task);
    
    // 4. 注入依赖输出
    prompt = this.injectDependencyOutputs(prompt, task, context);
    
    return prompt;
  }
}

四、上下文注入策略

注入阶段	内容	优先级
系统上下文	PROJECT.md、REQUIREMENTS.md	最高
全局变量	globals 对象	高
任务变量	task 自身属性	中
依赖输出	前置任务结果	中
运行时状态	当前执行进度	低

五、错误处理

class PlanValidationError extends Error {
  constructor(
    message: string,
    public taskId: string,
    public field: string
  ) {
    super(message);
  }
}

// 常见验证错误
- MISSING_REQUIRED_FIELD
- INVALID_AGENT_REFERENCE
- CIRCULAR_DEPENDENCY
- TEMPLATE_SYNTAX_ERROR

---

下一篇预告： 第 41 篇《Context Engine 与截断策略》