> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# submitPlanTool

这是一个内置且与 Agent 无关的 Tool，用于提交实施计划供用户审查。Agent 将计划写入 Markdown 文件，并把文件路径传给此 Tool。该 Tool 会暂停运行，直至用户批准或拒绝计划。

该 Tool 通过原生的 [Tool 暂停](https://mastra.zisheng.pro/docs/agents/agent-approval)机制实现暂停：它会调用 `suspend({ path })`，使 Agent 发出 `tool-call-suspended` 事件。宿主读取计划文件并将其呈现给用户，然后根据批准或拒绝结果恢复运行。

在 Agent 运行之外执行时（没有可用的 `suspend`），该 Tool 会返回一个包含文件路径的易读回退字符串。

## 使用示例

将 `submitPlanTool` 添加到 Agent 的 Tool 集：

```typescript
import { Agent } from '@mastra/core/agent'
import { submitPlanTool } from '@mastra/core/tools'

const agent = new Agent({
  id: 'planner',
  name: 'Planner',
  instructions: 'Write a plan to a file before starting work, then submit it for approval.',
  model,
  tools: { submitPlanTool },
})
```

处理暂停并恢复运行：

```typescript
import fs from 'node:fs'

const stream = await agent.stream('Refactor the auth module')

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tool-call-suspended' && chunk.payload.toolName === 'submit_plan') {
    const { path } = chunk.payload.suspendPayload
    const plan = fs.readFileSync(path, 'utf-8')
    console.log(plan)

    // Approve:
    const resumed = await agent.resumeStream({ action: 'approved' }, { runId: stream.runId })
    for await (const c of resumed.textStream) process.stdout.write(c)
  }
}
```

要拒绝计划并提供反馈：

```typescript
await agent.resumeStream(
  { action: 'rejected', feedback: 'Add error handling steps' },
  { runId: stream.runId },
)
```

## 输入 Schema

模型调用此 Tool 时使用以下参数：

**path** (`string`): 磁盘上的计划 Markdown 文件路径（例如 '.mastracode/plans/add-dark-mode.md'）。

## 暂停载荷

`tool-call-suspended` 事件携带一个 `suspendPayload`：

**path** (`string`): Agent 写入的计划文件路径。

**title** (`string`): 计划标题，由宿主读取文件后填充。

**plan** (`string`): 计划正文，由宿主读取文件后填充。

## 恢复数据

向 `agent.resumeStream()` 传入一个对象：

**action** (`'approved' | 'rejected'`): 用户批准还是拒绝了计划。

**feedback** (`string`): 计划被拒绝时的修改指示。该内容会提供给模型，使其能够修改并重新提交。

**path** (`string`): 计划文件路径，回传该值以便重放历史记录。

**title** (`string`): 计划标题，回传该值以便重放历史记录。

**plan** (`string`): 计划正文，回传该值以便重放历史记录。

## 审批行为

- **已批准：** Tool 向模型返回 `"Plan approved. Proceed with implementation following the approved plan."`。
- **拒绝并提供反馈：** Tool 返回反馈，并要求模型修改计划后再次提交。
- **拒绝但未提供反馈：** Tool 会告诉模型等待用户的下一条消息，然后再修改计划。

在 [AgentController](https://mastra.zisheng.pro/docs/harness/agent-controller) 中使用时，计划获批会从当前模式切换到 `transitionsTo` 配置的模式。未配置 `transitionsTo` 时，控制器会切换到解析出的默认模式。详情请参阅[模式](https://mastra.zisheng.pro/docs/harness/agent-controller)。