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

# submitPlanTool

這是一個不限定 Agent 的內建 Tool，用來提交實作計畫供使用者審閱。Agent 會將計畫寫入 Markdown 檔案，再把檔案路徑傳給此 Tool。Tool 會暫停執行，直到使用者核准或拒絕計畫。

此 Tool 透過原生的 [Tool 暫停](https://mastra.zisheng.pro/zh-TW/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'）。

## 暫停 payload

`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/zh-TW/docs/harness/agent-controller) 中使用時，核准計畫會從目前模式切換至 `transitionsTo` 設定的模式。如果未設定 `transitionsTo`，controller 會切換到解析後的預設模式。詳情請參閱[模式](https://mastra.zisheng.pro/zh-TW/docs/harness/agent-controller)。