自进化 agent：核心模块一任务规划器 Planner

Planner 是 Agent 的第一层"大脑"。

它负责把用户一句模糊需求，变成一组可以执行的步骤。

1. Planner 解决什么问题？

用户说：

复制代码

帮我分析一下这个项目

这句话太模糊。

普通 AI 可能直接回答一堆泛泛建议。

Planner 要先把它变成：

复制代码

1. 读取 README
2. 分析目录结构
3. 识别技术栈
4. 检查核心模块
5. 分析安全风险
6. 分析可维护性
7. 输出报告

也就是说，Planner 的核心作用是：

复制代码

把目标变成步骤
把步骤变成工具调用计划

2. Planner 的输入和输出

输入

复制代码

type PlannerInput = {
  userId: string
  task: string
  memories?: Memory[]
  availableTools: ToolDefinition[]
}

输出

复制代码

type Plan = {
  goal: string
  steps: PlanStep[]
}

type PlanStep = {
  id: string
  title: string
  description: string
  tool?: string
  expectedOutput: string
  riskLevel: "low" | "medium" | "high"
}

示例：

复制代码

{
  "goal": "分析项目代码质量",
  "steps": [
    {
      "id": "step_1",
      "title": "读取项目说明",
      "description": "读取 README 和 package 配置，理解项目定位与技术栈",
      "tool": "read_file",
      "expectedOutput": "项目基本信息",
      "riskLevel": "low"
    },
    {
      "id": "step_2",
      "title": "分析目录结构",
      "description": "扫描项目目录，识别模块边界和代码组织方式",
      "tool": "list_files",
      "expectedOutput": "目录结构分析",
      "riskLevel": "low"
    }
  ]
}

3. Planner 不应该做什么？

Planner 只负责规划，不负责执行。

不要让 Planner：

复制代码

直接读文件
直接跑命令
直接修改代码
直接调用危险工具
直接输出最终答案

它只应该输出：

复制代码

接下来要做什么
为什么要做
需要用哪个工具
风险等级是什么

这样系统才可控。

4. Planner 的核心 Prompt

可以这样写：

复制代码

你是一个任务规划器 Planner。

你的职责是把用户目标拆解成可执行步骤。

要求：
1. 不执行任务，只生成计划。
2. 每一步必须清晰、可验证。
3. 优先使用低风险工具。
4. 高风险操作必须标记 riskLevel = "high"。
5. 如果任务信息不足，先生成最合理的保守计划。
6. 输出严格 JSON。

输出格式：

复制代码

{
  "goal": "用户目标",
  "steps": [
    {
      "id": "step_1",
      "title": "步骤标题",
      "description": "步骤说明",
      "tool": "工具名称或 null",
      "expectedOutput": "期望产物",
      "riskLevel": "low | medium | high"
    }
  ]
}

5. Planner 如何使用记忆？

Planner 在规划前，应该先读取相关记忆。

例如用户长期偏好：

复制代码

用户喜欢先看整体架构，再看细节。
用户不喜欢一上来就给代码。
用户重视安全和可维护性。

那么 Planner 应该生成这样的计划：

复制代码

1. 先分析整体架构
2. 再分析模块边界
3. 再分析安全风险
4. 再分析可维护性
5. 最后给代码级建议

记忆会影响规划顺序。

6. Planner 如何选择工具？

每个工具都要有定义。

复制代码

type ToolDefinition = {
  name: string
  description: string
  inputSchema: unknown
  riskLevel: "low" | "medium" | "high"
}

示例：

复制代码

const tools = [
  {
    name: "read_file",
    description: "读取指定文件内容",
    riskLevel: "low"
  },
  {
    name: "write_file",
    description: "写入或覆盖文件",
    riskLevel: "high"
  },
  {
    name: "run_command",
    description: "执行 shell 命令",
    riskLevel: "high"
  }
]

Planner 只能从可用工具中选择。

不要让它编造工具。

7. Planner 的风险控制

规划阶段就要标记风险。

低风险：

复制代码

读取文件
搜索资料
分析文本
生成报告

中风险：

复制代码

创建文件
修改草稿
调用外部 API

高风险：

复制代码

删除文件
覆盖代码
执行 shell
提交 git
发送邮件
支付操作

高风险步骤必须进入人工确认。

复制代码

if (step.riskLevel === "high") {
  await requestUserApproval(step)
}

8. Planner 的最小实现流程

复制代码

async function createPlan(input: PlannerInput): Promise<Plan> {
  const prompt = buildPlannerPrompt({
    task: input.task,
    memories: input.memories,
    tools: input.availableTools
  })

  const plan = await callLLM(prompt)

  return validatePlan(plan, input.availableTools)
}

关键点：

复制代码

1. 构建 Prompt
2. 注入用户任务
3. 注入相关记忆
4. 注入可用工具
5. 调用 LLM
6. 校验输出
7. 返回计划

9. Planner 输出必须校验

不能完全相信 LLM。

必须检查：

复制代码

是不是合法 JSON
steps 是否为空
tool 是否存在
riskLevel 是否合法
是否包含危险步骤

示例：

复制代码

function validatePlan(plan: Plan, tools: ToolDefinition[]) {
  const toolNames = new Set(tools.map(t => t.name))

  for (const step of plan.steps) {
    if (step.tool && !toolNames.has(step.tool)) {
      throw new Error(`Unknown tool: ${step.tool}`)
    }

    if (!["low", "medium", "high"].includes(step.riskLevel)) {
      throw new Error(`Invalid risk level: ${step.riskLevel}`)
    }
  }

  return plan
}

10. Planner 的进化点

Planner 本身也可以进化。

例如一开始规划是：

复制代码

搜索资料 → 生成答案

后来发现质量不稳定。

经过反思后，策略变成：

复制代码

搜索资料 → 交叉验证 → 总结共识 → 输出答案

Planner 进化的不是模型，而是：

复制代码

任务模板
步骤顺序
工具选择规则
风险策略
用户偏好

本章总结

Planner 的核心职责是：

复制代码

把用户目标变成可执行、可验证、可控的步骤。

它不负责执行，只负责规划。

一个好的 Planner 必须做到：

复制代码

目标清晰
步骤明确
工具合法
风险可控
可被校验
可被复用

本章验收标准

Planner 合格的标准：

复制代码

能把模糊目标拆成可执行步骤
能标记工具和风险
能输出结构化计划
能被校验和复用

关键设计决策

Planner 只负责规划：

复制代码

不直接执行工具
不私自越权
计划必须结构化
高风险步骤必须显式标记