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

# submitPlanTool

這是一個與 Agent 無關的內置 Tool，可提交實作計劃供用戶審閱。Agent 會將計劃寫入 markdown 檔案，並把檔案路徑傳給此 Tool。此 Tool 會暫停執行，直至用戶核准或拒絕計劃。

此 Tool 透過原生的 [Tool 暫停](https://mastra.zisheng.pro/zh-HK/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 },
)
```

## 輸入結構

模型會使用以下參數呼叫此 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/zh-HK/docs/harness/agent-controller) 內使用時，計劃獲核准後，會由目前模式切換至 `transitionsTo` 設定的模式。如果未設定 `transitionsTo`，控制器會切換至其解析後的預設模式。詳情請參閱[模式](https://mastra.zisheng.pro/zh-HK/docs/harness/agent-controller)。