消息类交互与纯文本生成行为不一致，是因混淆message api（/v1/chat/completions，维护会话上下文、角色语义、状态感知）与text completions api（/v1/completions，无状态单次补全、仅接受prompt字符串）的设计边界所致。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您在集成 Clawdbot 时发现消息类交互与纯文本生成行为表现不一致，可能是由于混淆了 Message API 与 Text Completions API 的设计边界。以下是二者差异的详细说明：
一、核心定位与语义目标不同
Message API 是面向多轮对话场景构建的接口，它隐式维护会话上下文、角色标识（如 user / assistant / system）及历史消息链，并支持流式响应、工具调用（function calling）和状态感知的响应生成。Text Completions API 则是无状态的单次补全接口，仅接收原始提示文本（prompt），输出对应补全内容，不携带角色语义、不保留历史、不参与会话编排。
1、Message API 的请求体中必须包含 messages 数组，每个元素需指定 role 和 content 字段；
2、Text Completions API 的请求体中仅接受 prompt 字符串字段，不允许出现 messages 或 role 等结构化会话字段；
3、Clawdbot 在接入层会根据路径自动路由：/v1/chat/completions 走 Message 流程，/v1/completions 走 Text 补全流程。
二、底层适配逻辑与模型输入构造方式不同
Message API 在编排层会对 messages 数组执行格式标准化处理，注入系统提示词（来自 SOUL.md、AGENTS.md 等）、拼接对话历史、应用模板（如 Qwen3 的 ChatML 格式），再交由 vLLM 执行推理；Text Completions API 则跳过所有会话结构解析，直接将 prompt 原样送入 tokenizer，不做角色标记插入或历史截断控制。
1、当使用 Qwen3:32B 模型时，Message API 输出的 input_ids 会包含 user 等特殊分隔符；
2、Text Completions API 对同一段文本调用，生成的 input_ids 中 完全不包含任何角色标记或对话结构符号；
3、若在 Message API 请求中传入非数组类型的 prompt 字段，Clawdbot 网关将返回 400 Bad Request 并提示“messages is required”。
三、响应结构与前端消费契约不同
Message API 响应遵循 OpenAI 兼容格式，固定返回 choices 数组，每个 choice 包含 message 对象（含 role 和 content），并可选返回 usage、finish_reason 等字段；Text Completions API 响应则返回 completion 字符串字段，不嵌套 message 结构，也不提供 role 信息，其 JSON schema 更接近传统语言模型的 raw output。
1、Message API 成功响应中必含 choices[0].message.content 字段，供前端 SDK 直接提取回复正文；
2、Text Completions API 成功响应中只含 completion 字符串，无 choices 或 message 层级嵌套；
3、若前端组件按 OpenAI 标准解析 Message API 响应，却误将 Text Completions API 响应传入同一解析函数，将触发 TypeError: Cannot read property 'content' of undefined。
四、权限控制与会话生命周期管理不同
Message API 请求在编排层被绑定至具体会话 ID（session_id），支持跨请求的状态延续、记忆注入（MEMORY.md）、心跳检查（HEARTBEAT.md）及插件上下文隔离；Text Completions API 请求被视为瞬时计算任务，不分配 session_id，不读取任何工作区 Markdown 文件，也不触发工具调度或记忆检索流程。
1、调用 Message API 时，Clawdbot 会自动从当前工作区加载 USER.md 和 MEMORY.md 内容作为上下文补充；
2、Text Completions API 完全忽略工作区目录结构，不会读取任何 .md 配置文件；
3、若请求携带 session_id 参数，Message API 将尝试恢复该会话状态，而 Text Completions API 会直接忽略该参数。
五、错误处理与调试线索不同
Message API 在失败时会返回结构化 error 对象，包含 code（如 invalid_request_error）、param（指出哪个字段非法）及 message（人类可读描述），便于前端快速定位协议误用；Text Completions API 的错误响应更精简，通常仅返回 message 字符串与 HTTP 状态码，缺乏字段级诊断信息。
1、当向 Message API 发送缺失 messages 的请求时，响应 body 中 error.param 值为 "messages"；
2、当向 Text Completions API 发送含 messages 字段的请求时，响应 body 中 error.message 将明确提示 "Unexpected field: messages"；
3、Clawdbot Dashboard 的 Logs 页面中，两类请求分别标记为 "chat" 类型 与 "completion" 类型，可用于区分排查。
