尧图网页设计 
DeepBot外部API接口完全参考message/command两大端点的调用细节与避坑指南【免费下载链接】deepbotDeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.项目地址: https://gitcode.com/gh_mirrors/de/deepbotDeepBot 外部 API是 DeepBot 这个系统级 AI 助手为自动化程序与 AI Agent 提供的两大 HTTP 端点POST /api/external/message发送消息并同步等待 AI 完整回复和POST /api/external/command发送系统指令并等待执行结果。无需 WebSocket一次请求拿回完整答案配合X-Secret请求头即可完成认证。本文基于官方文档 docs/external-api.md 与路由源码 src/server/routes/external.ts带你把DeepBot 外部API接口的调用细节一次讲透并整理出 6 个最常见的踩坑点。一、为什么需要 DeepBot 外部 API 接口DeepBot 的 Web 服务入口在 src/server/index.ts默认同时提供 HTTP API 与 WebSocket。如果你想在自己的脚本、CI 任务、AI Agent 或飞书自动化流程里问一句话、拿回一个完整答案WebSocket 的流式模型过于复杂——外部 API 把流式过程封装成了同步阻塞接口你发出请求它阻塞直到 AI 回复完成最长 5 分钟然后一次性返回完整文本。两大端点定位不同端点用途Tab 不存在时POST /api/external/message发送普通消息支持附件✅ 自动创建同名 TabPOST /api/external/command发送[SYSTEM]前缀的系统指令❌ 返回 404路由挂载位置见 src/server/index.ts整个/api/external前缀下的请求统一走X-Secret认证与前端使用的 JWT Token 认证相互独立。二、前置准备服务端口与 X-Secret 认证配置1. 找到服务地址基础地址为http://host:端口。端口由PORT环境变量控制src/server/index.ts 中默认值为3008官方文档示例中使用 3000以你实际启动日志服务地址为准。2. 配置 X-Secret 请求头外部接口的认证方式非常直接请求头X-Secret的值 服务端环境变量JWT_SECRET的值。认证逻辑实现在 src/server/routes/external.ts 的中间件里校验失败会立即返回 401/403 并拒绝执行curl -X POST http://localhost:3008/api/external/message \ -H Content-Type: application/json \ -H X-Secret: your-jwt-secret \ -d {tab:Agent1,content:你好}⚠️ 注意JWT_SECRET未设置时代码会回退到默认值见 src/server/middleware/auth.ts生产环境请务必显式配置自己的密钥。三、message 信息接口发送消息并同步等待 AI 回复请求体示例字段说明来自 docs/external-api.md{ tab: Agent1, content: 请分析这张图片, timeout: 300000, fast: false, attachments: [ { name: photo.jpg, data: base64内容..., type: image/jpeg } ] }关键参数速览tab必填目标 Tab 名称。匹配规则是去除所有空格后比较即Agent1能匹配名为Agent 1的 TabTab 不存在时自动创建。content/attachments二者至少提供一个。附件的data为 base64 编码不带data:xxx;base64,前缀type省略时按扩展名自动推断推断表见 src/server/routes/external.ts。fast可选传true时该 Tab 进入 Fast 模式——不加载 AGENT.md、工具描述与 Skillstoken 消耗大幅下降适合简单问答这是 Tab 级别的持久状态需要显式传fast: false才会恢复。timeout可选等待超时毫秒默认 3000005 分钟。成功响应{ success: true, tab: Agent 1, tabCreated: true, reply: AI 的完整回复文本, messageId: msg_abc123, totalDuration: 3200, modelId: gpt-4o }reply是 AI 回复的完整文本tabCreated: true表示该 Tab 是本次请求自动新建的。四、command 指令接口让 Agent 执行系统级任务指令接口与消息接口的核心差异有两点实现见 src/server/routes/external.ts自动加上[SYSTEM]前缀Agent 将其视为系统级任务可调用工具、执行命令例如检查磁盘空间并生成报告。Tab 必须已存在不会自动创建找不到时返回 404 与错误信息未找到名为 xxx 的 Tab。请求体与响应结构和消息接口几乎一致只是content换成command回复字段为result{ tab: Agent1, command: 列出工作目录文件, timeout: 300000 }{ success: true, tab: Agent 1, result: Agent 执行完毕后的完整输出文本, messageId: msg_def456, totalDuration: 5600, modelId: gpt-4o }典型用法用message接口做问答用command接口做定时巡检、批量任务等自动化操作。五、DeepBot 外部 API 调用避坑指南6 个高频错误坑 1HTTP 客户端超时小于服务端 timeout这是第一大坑。接口默认阻塞等待 5 分钟如果你的 HTTP 客户端超时设为 30 秒会先于服务端断开。客户端超时必须大于请求体中的timeout如 body 传 300000客户端设 310 秒以上。坑 2Tab 名称里的空格匹配时双方名称都会去除所有空格再比较。Agent1可匹配Agent 1但不会匹配Agent One——别指望模糊匹配。坑 3误用 command 接口创建 Tab自动创建 Tab 只有message接口具备。用command打一个不存在的 Tab 会得到 404需要先确保目标 Tab 已存在可在应用界面创建或先用一次 message 请求。⏳坑 4把并发当并行同一 Tab 的并发请求会排队串行处理不是并行。想提速请拆到不同 Tab而不是对同一 Tab 连发请求。坑 5fast 模式的粘滞效果fast: true会让 Tab 持久进入 Fast 模式前端 Tab 颜色会变化后续不带fast的请求不会自动恢复。如果你发现 Tab 突然变笨、不再调用工具多半是之前的请求把模式切成了 Fast补发一次fast: false即可。坑 6附件 base64 前缀与体积data字段是纯 base64 内容不要带data:image/jpeg;base64,前缀服务端会自动拼接见 src/server/routes/external.ts。另外服务端 JSON 解析上限为 700MBsrc/server/index.ts图片单张约 5MB、文件约 500MB 以内为宜。错误码速查HTTP 状态码error 内容原因401缺少 X-Secret 请求头未携带认证头403Secret 无效X-Secret值与JWT_SECRET不一致400缺少 tab / content 参数请求体缺字段404未找到名为 xxx 的 Tab仅 command 接口触发500等待回复超时300秒AI 未在超时内完成500Agent 执行出错Agent 运行时异常六、小结与延伸阅读掌握DeepBot 外部API接口的两大端点其实只需记住三件事message发消息可自动建 Tab、可带附件、command发系统指令Tab 必须存在、客户端超时永远要比 body 里的 timeout 大。加上X-Secret认证与fast模式的持久性这两个细节基本可以覆盖绝大多数集成场景。延伸阅读均为仓库内路径官方接口文档含 curl / Python / Node.js 完整示例docs/external-api.md外部路由实现认证、附件处理、等待回复机制src/server/routes/external.tsWeb 服务入口与端口配置src/server/index.ts飞书机器人配置指南连接器场景docs/飞书机器人配置指南.md【免费下载链接】deepbotDeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.项目地址: https://gitcode.com/gh_mirrors/de/deepbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DeepBot外部API接口完全参考：message/command两大端点的调用细节与避坑指南
DeepBot外部API接口完全参考message/command两大端点的调用细节与避坑指南【免费下载链接】deepbotDeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.项目地址: https://gitcode.com/gh_mirrors/de/deepbotDeepBot 外部 API是 DeepBot 这个系统级 AI 助手为自动化程序与 AI Agent 提供的两大 HTTP 端点POST /api/external/message发送消息并同步等待 AI 完整回复和POST /api/external/command发送系统指令并等待执行结果。无需 WebSocket一次请求拿回完整答案配合X-Secret请求头即可完成认证。本文基于官方文档 docs/external-api.md 与路由源码 src/server/routes/external.ts带你把DeepBot 外部API接口的调用细节一次讲透并整理出 6 个最常见的踩坑点。一、为什么需要 DeepBot 外部 API 接口DeepBot 的 Web 服务入口在 src/server/index.ts默认同时提供 HTTP API 与 WebSocket。如果你想在自己的脚本、CI 任务、AI Agent 或飞书自动化流程里问一句话、拿回一个完整答案WebSocket 的流式模型过于复杂——外部 API 把流式过程封装成了同步阻塞接口你发出请求它阻塞直到 AI 回复完成最长 5 分钟然后一次性返回完整文本。两大端点定位不同端点用途Tab 不存在时POST /api/external/message发送普通消息支持附件✅ 自动创建同名 TabPOST /api/external/command发送[SYSTEM]前缀的系统指令❌ 返回 404路由挂载位置见 src/server/index.ts整个/api/external前缀下的请求统一走X-Secret认证与前端使用的 JWT Token 认证相互独立。二、前置准备服务端口与 X-Secret 认证配置1. 找到服务地址基础地址为http://host:端口。端口由PORT环境变量控制src/server/index.ts 中默认值为3008官方文档示例中使用 3000以你实际启动日志服务地址为准。2. 配置 X-Secret 请求头外部接口的认证方式非常直接请求头X-Secret的值 服务端环境变量JWT_SECRET的值。认证逻辑实现在 src/server/routes/external.ts 的中间件里校验失败会立即返回 401/403 并拒绝执行curl -X POST http://localhost:3008/api/external/message \ -H Content-Type: application/json \ -H X-Secret: your-jwt-secret \ -d {tab:Agent1,content:你好}⚠️ 注意JWT_SECRET未设置时代码会回退到默认值见 src/server/middleware/auth.ts生产环境请务必显式配置自己的密钥。三、message 信息接口发送消息并同步等待 AI 回复请求体示例字段说明来自 docs/external-api.md{ tab: Agent1, content: 请分析这张图片, timeout: 300000, fast: false, attachments: [ { name: photo.jpg, data: base64内容..., type: image/jpeg } ] }关键参数速览tab必填目标 Tab 名称。匹配规则是去除所有空格后比较即Agent1能匹配名为Agent 1的 TabTab 不存在时自动创建。content/attachments二者至少提供一个。附件的data为 base64 编码不带data:xxx;base64,前缀type省略时按扩展名自动推断推断表见 src/server/routes/external.ts。fast可选传true时该 Tab 进入 Fast 模式——不加载 AGENT.md、工具描述与 Skillstoken 消耗大幅下降适合简单问答这是 Tab 级别的持久状态需要显式传fast: false才会恢复。timeout可选等待超时毫秒默认 3000005 分钟。成功响应{ success: true, tab: Agent 1, tabCreated: true, reply: AI 的完整回复文本, messageId: msg_abc123, totalDuration: 3200, modelId: gpt-4o }reply是 AI 回复的完整文本tabCreated: true表示该 Tab 是本次请求自动新建的。四、command 指令接口让 Agent 执行系统级任务指令接口与消息接口的核心差异有两点实现见 src/server/routes/external.ts自动加上[SYSTEM]前缀Agent 将其视为系统级任务可调用工具、执行命令例如检查磁盘空间并生成报告。Tab 必须已存在不会自动创建找不到时返回 404 与错误信息未找到名为 xxx 的 Tab。请求体与响应结构和消息接口几乎一致只是content换成command回复字段为result{ tab: Agent1, command: 列出工作目录文件, timeout: 300000 }{ success: true, tab: Agent 1, result: Agent 执行完毕后的完整输出文本, messageId: msg_def456, totalDuration: 5600, modelId: gpt-4o }典型用法用message接口做问答用command接口做定时巡检、批量任务等自动化操作。五、DeepBot 外部 API 调用避坑指南6 个高频错误坑 1HTTP 客户端超时小于服务端 timeout这是第一大坑。接口默认阻塞等待 5 分钟如果你的 HTTP 客户端超时设为 30 秒会先于服务端断开。客户端超时必须大于请求体中的timeout如 body 传 300000客户端设 310 秒以上。坑 2Tab 名称里的空格匹配时双方名称都会去除所有空格再比较。Agent1可匹配Agent 1但不会匹配Agent One——别指望模糊匹配。坑 3误用 command 接口创建 Tab自动创建 Tab 只有message接口具备。用command打一个不存在的 Tab 会得到 404需要先确保目标 Tab 已存在可在应用界面创建或先用一次 message 请求。⏳坑 4把并发当并行同一 Tab 的并发请求会排队串行处理不是并行。想提速请拆到不同 Tab而不是对同一 Tab 连发请求。坑 5fast 模式的粘滞效果fast: true会让 Tab 持久进入 Fast 模式前端 Tab 颜色会变化后续不带fast的请求不会自动恢复。如果你发现 Tab 突然变笨、不再调用工具多半是之前的请求把模式切成了 Fast补发一次fast: false即可。坑 6附件 base64 前缀与体积data字段是纯 base64 内容不要带data:image/jpeg;base64,前缀服务端会自动拼接见 src/server/routes/external.ts。另外服务端 JSON 解析上限为 700MBsrc/server/index.ts图片单张约 5MB、文件约 500MB 以内为宜。错误码速查HTTP 状态码error 内容原因401缺少 X-Secret 请求头未携带认证头403Secret 无效X-Secret值与JWT_SECRET不一致400缺少 tab / content 参数请求体缺字段404未找到名为 xxx 的 Tab仅 command 接口触发500等待回复超时300秒AI 未在超时内完成500Agent 执行出错Agent 运行时异常六、小结与延伸阅读掌握DeepBot 外部API接口的两大端点其实只需记住三件事message发消息可自动建 Tab、可带附件、command发系统指令Tab 必须存在、客户端超时永远要比 body 里的 timeout 大。加上X-Secret认证与fast模式的持久性这两个细节基本可以覆盖绝大多数集成场景。延伸阅读均为仓库内路径官方接口文档含 curl / Python / Node.js 完整示例docs/external-api.md外部路由实现认证、附件处理、等待回复机制src/server/routes/external.tsWeb 服务入口与端口配置src/server/index.ts飞书机器人配置指南连接器场景docs/飞书机器人配置指南.md【免费下载链接】deepbotDeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.项目地址: https://gitcode.com/gh_mirrors/de/deepbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考