Chat API

POST /api/chat

聊天页发起执行任务的入口。

鉴权要求

默认属于受保护接口。开发时如果服务使用了 --disable-auth，可以匿名调用，但这不代表真实部署的默认行为。

请求体

{
  "prompt": "打开 google.com 搜索 AI",
  "execute": true,
  "session_id": "optional-session-id",
  "current_url": "https://example.com",
  "constraints": ["不要登录", "只读页面"],
  "llm_provider": "openai",
  "llm_model": "gpt-4o",
  "profile_id": "optional-profile-id",
  "profile_label": "optional-profile-label"
}

常见可选字段

• capture_context
• context_timeout_secs
• context_screenshot
• llm_api_base
• llm_temperature
• llm_api_key
• llm_backup_api_key
• llm_max_output_tokens

执行路径返回结构

当 execute=true 且请求进入真实任务执行链路时，前端最依赖下面这组字段：

{
  "success": true,
  "session_id": "session-uuid",
  "task_id": "task-uuid",
  "plan": {},
  "flow": {},
  "stdout": "",
  "stderr": null
}

轻量回复路径

如果请求没有进入真实执行链路，例如：

• execute=false
• 命中了后端的 lightweight reply

返回里可能只有：

• success
• stdout
• stderr

这类响应里 task_id 和 session_id 都可能为空，不应被前端当成运行态绑定失败。

常见失败路径

失败时通常会保留统一外壳：

{
  "success": false,
  "stderr": "error message"
}

其中：

• task_id 可能为空
• session_id 可能为空，也可能保留已识别到的 session
• stdout 通常为空字符串

常见错误

状态码	场景
400	prompt 为空、超过长度限制、provider 不合法
401	需要鉴权但未登录
429	chat 接口命中限流
500	后端执行链路内部错误

联调建议

• 要验证右侧运行态，务必确保请求走的是“真实执行路径”，不要只测 execute=false。
• 如果接口返回 success=true 但没有 task_id，先判断是不是命中了 lightweight reply。
• 对聊天页来说，session_id 和 task_id 的关系要和 /api/sessions/:id、/api/tasks/:id/status 一起联调，不要单独看这一条接口。

约束

• 新前端只在“真实执行路径”上依赖 session_id 和 task_id 同时存在
• 如果后端调整字段形状，必须同步更新运行态控制器
• 对执行路径来说，task_id 缺失会直接影响右侧步骤和画面绑定