# Prompt 接纳、队列与终态

> 用 promptId 区分已接纳、取消请求、执行结束和恢复出的历史结果。

- 网址：https://funcoding.ai/agents/qwen-code/runtime/prompt-outcomes/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Qwen Code 官方文档：Session Lifecycle and Identity](https://github.com/QwenLM/qwen-code/blob/main/docs/developers/daemon/08-session-lifecycle.md)、[Qwen Code 官方文档：Typed Event Schema](https://github.com/QwenLM/qwen-code/blob/main/docs/developers/daemon/09-event-schema.md)、[Qwen Code 官方文档：Serve Protocol Reference](https://github.com/QwenLM/qwen-code/blob/main/docs/developers/qwen-serve-protocol.md)

---
当前非阻塞 prompt 协议将接纳与执行分开。POST /session/:id/prompt 返回 202 和 promptId、lastEventId，表示已进入 daemon 管理，不表示 agent 已完成。

## 关联结果

订阅该 session SSE，并按 promptId 匹配 turn_complete 或 turn_error。DaemonSessionClient 在有活动事件订阅时可自动使用非阻塞路径并等待对应终态；直接 REST 客户端需要自己完成关联。

turn_complete 的 stopReason 是开放字符串。当前可见 end_turn、max_tokens、max_turn_requests、refusal、cancelled，但客户端不应只允许固定枚举。

cancelled 也可能来自尚未运行的 queued prompt 被移除、调用方断开或 teardown，不能证明 agent 实际执行过。daemon 内部期限或关闭失败通过 turn_error 表示，code 是可选字段；child 崩溃场景可能只有 message。

## Queue 事件不是 turn terminal

| 事件 | 表示什么 |
| --- | --- |
| pending_prompt_added | prompt 真正排在 active turn 后面等待；idle session 的第一条不发此事件 |
| pending_prompt_started | 该项被提升开始运行；开始前移除则可能没有此事件 |
| pending_prompt_completed | queue view 的记录结算，state 为 completed 或 removed |
| prompt_cancelled | 已请求取消，尚不等于取消正式完成 |

pending_prompt_completed 的 completed 包含运行后失败的情形，具体错误仍由 turn_error 给出。它不能用来显示“任务成功”。

## 重启后的终态证据

重启恢复的旧 turn 不重新广播 SSE。load 响应可在 promptTerminals[] 给出 completed/reconstructed_from_transcript 或 interrupted/daemon_lost；后者没有 stopReason，应按 terminal 分类。

没有 ledger 证据时，整个 promptTerminals 字段可缺失。缺失不是成功，也不证明可安全重新执行同一 prompt。

## 期限与之后的查询

prompt_absolute_deadline 支持时，deadlineMs 可以缩短服务端期限。到期通过关联 turn_error 的 prompt_deadline_exceeded 释放调用方，但不强杀 agent。

agent 之后若真正结束，turn-status 查询可能反映已结算的 transcript 结果。不要把最早收到的 deadline 当作永远不可更新的执行结局，也不要因此无条件重试会产生副作用的工作。

## 独立辅助接口

recap 返回尽力生成的一行摘要，null 可表示历史不足或临时模型失败。btw 是单轮、无工具的上下文旁问；generate 则不读取对话历史、不记录 turn、不暴露工具，以请求独立 SSE 返回 started/thinking/delta/done/error。

shell 直接在 daemon 主机执行并把命令结果加入历史，不经过模型生成命令；它没有路径 sandbox。rewind 只回退对话与可跟踪文件，不能撤销 Shell、Git、脚本或人工操作，且文件恢复失败时对话可能已经回退。

这些端点各有 capability 和权限要求，不能仅因 session live 就假定全部开放。基础会话 API 见[会话生命周期](https://funcoding.ai/agents/qwen-code/runtime/session-lifecycle/)。