1. 项目概述携程问道与Workbuddy的融合最近在折腾一个挺有意思的项目把携程的“问道”AI助手能力集成到了Workbuddy这个协作工具里。简单来说就是让你能在Workbuddy的聊天窗口里直接调用携程问道的智能问答、行程规划、酒店推荐这些功能不用再切来切去。这玩意儿听起来像是简单的API对接但真做起来从环境配置、接口鉴权到错误处理每一步都有不少细节。特别是最近Workbuddy更新了它的技能Skill开发框架文档又比较零散踩了不少坑。这篇文章我就把从零开始把一个外部AI服务以携程问道为例接入Workbuddy的全过程包括核心原理、实操代码和避坑指南给你掰开揉碎了讲清楚。无论你是想给自己的团队做个内部工具还是想了解现代SaaS平台如何扩展第三方能力这篇都能给你一个完整的参考。2. 核心概念与前置准备在动手写代码之前我们必须把几个关键角色和它们之间的关系理清楚。这就像搭积木你得先知道每块积木是干什么的才能拼出想要的样子。2.1 角色定义携程问道、Workbuddy与你的技能首先这里涉及三个核心部分携程问道这是能力提供方。它本质上是一个提供旅游领域智能服务的API集合。比如你给它一段自然语言“帮我查一下下周北京飞上海的机票”它能理解你的意图并返回结构化的航班信息。对我们开发者而言它就是一个标准的HTTP API服务通常需要API Key进行鉴权。Workbuddy这是能力承载和交互的平台。它是一个集成了聊天、任务、文档的协作工具。Workbuddy允许开发者创建“技能”Skill这些技能可以像机器人一样在特定的聊天群组或私聊中被触发执行预设的任务。你的技能Skill这是你将要开发的桥梁。它是一段部署在你自己服务器或云函数上的后端代码。当用户在Workbuddy里你的技能并发送指令时Workbuddy会将这个指令转发给你的技能服务器。你的技能服务器收到后去调用携程问道的API拿到结果再格式化返回给Workbuddy最后由Workbuddy展示给用户。所以数据流是这样的用户 技能 - Workbuddy - 你的技能服务器 - 携程问道API - 你的技能服务器 - Workbuddy - 用户。2.2 环境与工具准备工欲善其事必先利其器。以下是开始前必须准备好的东西Node.js 环境Workbuddy的技能开发SDK对Node.js支持最友好这也是社区最常用的选择。强烈建议使用LTS版本比如18.x或20.x。避免使用过于前沿的版本如热词中提到的v24.19.0未发布的问题以免遇到不兼容的依赖。安装检查打开终端运行node -v和npm -v确认版本号。安装指引如果未安装去Node.js官网下载LTS安装包。Windows用户注意如果之前安装过且出现问题可以彻底卸载后重装并确保安装时勾选了“添加到PATH”选项。代码编辑器VS Code、WebStorm等任选用着顺手就行。携程问道API权限你需要联系携程相关的开放平台或商务申请成为开发者获取到关键的API Key有时也叫App Key/Secret和API的基地址Base URL。没有这个一切无从谈起。Workbuddy开发者账号登录你的Workbuddy通常可以在“设置”-“集成”或“开发者中心”找到创建技能Create Skill的入口。创建技能后你会获得一个重要的凭证Skill Token或Verification Token用于验证来自Workbuddy的请求是否合法。公网可访问的服务器/地址你的技能代码需要部署在一个能被Workbuddy服务器访问到的地方。开发初期我强烈推荐使用内网穿透工具比如ngrok或localtunnel。它们能把你的本地localhost:3000映射成一个临时的公网HTTPS地址方便调试。例如安装ngrok后运行ngrok http 3000你会得到一个类似https://abcd.ngrok.io的地址这就是你临时的技能服务器地址。注意Workbuddy出于安全考虑只支持HTTPS的回调地址。所以无论是ngrok提供的临时地址还是你最终部署的服务器都必须支持HTTPS。本地开发用ngrok是最省事的方案。3. 技能服务端核心实现这一部分是整个项目的骨架。我们将创建一个简单的Express.js服务器来处理Workbuddy发来的请求并调用携程问道API。3.1 项目初始化与依赖安装首先创建一个新的项目目录并初始化。mkdir ctrip-workbuddy-skill cd ctrip-workbuddy-skill npm init -y接着安装我们需要的核心依赖。npm install express axios body-parser dotenv npm install -D nodemonexpress: Node.js最流行的Web框架用于快速搭建服务器。axios: 用于发起HTTP请求调用携程问道API。比原生的http模块更好用支持Promise。body-parser: 中间件用于解析Workbuddy POST过来的JSON数据。dotenv: 管理环境变量把敏感的API Key等配置从代码中分离。nodemon: 开发工具监听文件变化自动重启服务器提升开发效率。在package.json中添加一个启动脚本scripts: { start: node index.js, dev: nodemon index.js }3.2 核心服务器代码解析创建项目的主文件index.js我们来一步步构建它。// index.js require(dotenv).config(); // 加载.env文件中的环境变量 const express require(express); const bodyParser require(body-parser); const axios require(axios); const app express(); const PORT process.env.PORT || 3000; // 中间件解析JSON格式的请求体 app.use(bodyParser.json()); // 从环境变量读取配置 const WORKBUDDY_VERIFICATION_TOKEN process.env.WORKBUDDY_VERIFICATION_TOKEN; const CTRIP_API_KEY process.env.CTRIP_API_KEY; const CTRIP_API_BASE process.env.CTRIP_API_BASE || https://openapi.ctrip.com; // 验证Workbuddy请求的中间件 const verifyWorkbuddyRequest (req, res, next) { const token req.headers[x-workbuddy-token]; // Workbuddy实际可能用不同的头需查阅最新文档 if (token ! WORKBUDDY_VERIFICATION_TOKEN) { console.warn(验证失败收到的Token:, token); return res.status(403).json({ error: Forbidden: Invalid token }); } next(); }; // Workbuddy技能配置的端点用于技能启用时验证 app.get(/skill, (req, res) { // 有些平台需要这个端点返回技能的基本信息或者用于健康检查 res.json({ status: ok, message: Ctrip WenDao Skill is running. }); }); // 核心处理用户消息的端点 app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { console.log(收到Workbuddy消息:, JSON.stringify(req.body, null, 2)); const userMessage req.body.text; // 用户输入的原始文本 const userId req.body.user_id; const channelId req.body.channel_id; if (!userMessage) { return res.json({ text: 您好我收到了空消息。请告诉我您想查询什么 }); } try { // 1. 调用携程问道API const ctripResponse await axios.post( ${CTRIP_API_BASE}/ai/wendao/chat, // 假设的接口路径实际需替换 { query: userMessage, session_id: ${userId}-${channelId}, // 用用户和频道ID构造会话保持上下文 // 其他可能的参数如城市、时间等可以从userMessage中解析后传入 }, { headers: { Authorization: Bearer ${CTRIP_API_KEY}, Content-Type: application/json, }, timeout: 10000, // 设置10秒超时避免长时间等待 } ); // 2. 处理携程API的返回结果 const aiReply ctripResponse.data.reply; // 根据实际API响应结构调整 const formattedReply 【携程问道】\n${aiReply}\n\n---\n*以上信息由携程问道提供请以实时查询为准。*; // 3. 返回格式化的消息给Workbuddy res.json({ text: formattedReply, // Workbuddy可能支持更丰富的消息格式如Markdown、附件等 // response_type: in_channel // 如果想让消息对频道所有人可见 }); } catch (error) { console.error(处理请求时出错:, error); let errorMessage 抱歉查询服务暂时不可用请稍后再试。; // 针对特定错误进行友好提示 if (error.code ECONNRESET) { errorMessage 网络连接不稳定请求超时了。; } else if (error.response) { // 携程API返回了错误状态码 console.error(API错误详情:, error.response.status, error.response.data); if (error.response.status 400) { // 重点处理热词中提到的400错误 const errorData error.response.data; if (errorData.error errorData.error.includes(maximum context length)) { errorMessage 您的问题或历史对话内容太长了超出了AI的处理限制。请尝试简化您的问题或开启一个新对话。; } else if (errorData.error errorData.error.includes(type must be in)) { errorMessage 请求参数配置有误请联系技能管理员检查。; } } else if (error.response.status 401 || error.response.status 403) { errorMessage 服务授权失败请确认API密钥是否有效。; } else if (error.response.status 429) { errorMessage 请求过于频繁请稍等一分钟再试。; } } else if (error.request) { // 请求发出了但没有收到响应 errorMessage 无法连接到旅行查询服务请检查网络。; } res.json({ text: 【出错啦】\n${errorMessage} }); } }); // 启动服务器 app.listen(PORT, () { console.log(技能服务器运行在 http://localhost:${PORT}); console.log(请确保Workbuddy配置的回调地址是: https://你的公网地址/skill/message); });3.3 环境变量配置在项目根目录创建.env文件存放你的敏感信息。切记将这个文件添加到.gitignore中不要提交到代码仓库。# .env PORT3000 WORKBUDDY_VERIFICATION_TOKENyour_workbuddy_skill_token_here CTRIP_API_KEYyour_ctrip_openapi_key_here CTRIP_API_BASEhttps://openapi.ctrip.com3.4 本地运行与测试在终端运行npm run dev启动开发服务器。在另一个终端运行ngrok http 3000获取你的公网HTTPS地址例如https://abc123.ngrok.io。使用curl或Postman模拟Workbuddy的请求测试你的技能curl -X POST https://abc123.ngrok.io/skill/message \ -H Content-Type: application/json \ -H x-workbuddy-token: your_workbuddy_skill_token_here \ -d {text: 上海外滩附近有什么推荐的高分酒店, user_id: test_user, channel_id: test_channel}你应该能收到一个格式化的回复。4. Workbuddy技能配置与上线代码写好了服务器跑起来了现在需要告诉Workbuddy这个技能的存在。4.1 在Workbuddy控制台创建技能登录Workbuddy进入“开发者中心”或“技能管理”。点击“创建新技能”。填写技能基本信息技能名称携程旅行助手描述基于携程问道AI提供机票、酒店、行程问答服务。回调URL填写你的ngrok地址加上端点例如https://abc123.ngrok.io/skill/message。这是最关键的一步。验证Token这里填写你在.env里设置的WORKBUDDY_VERIFICATION_TOKEN。Workbuddy会在每次请求的Header中带上这个Token你的代码用它来验证请求来源。权限/Scope根据技能需要勾选“接收消息”、“发送消息”等权限。保存后Workbuddy可能会尝试访问你设置的“回调URL”进行一次握手验证确保你的服务器能正常响应。确保你的本地服务器和ngrok都在运行。4.2 在聊天中使用技能技能创建成功后你通常需要将它安装或添加到某个工作区或频道。在目标频道中输入携程旅行助手 帮我规划一个周末的杭州美食之旅。Workbuddy会将这条消息转发给你的服务器你的服务器处理完后结果会以技能的身份在频道中回复。5. 高级功能与优化实践基础功能跑通后我们可以考虑让它变得更智能、更健壮。5.1 实现对话上下文管理上面的示例中我们简单地将userId和channelId组合作为会话ID。但对于多轮对话这还不够。我们需要在服务器端临时存储对话历史。// 简单的内存存储生产环境需用Redis或数据库 const conversationHistory new Map(); app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { const userMessage req.body.text; const sessionKey ${req.body.user_id}-${req.body.channel_id}; // 获取历史记录只保留最近N轮 let history conversationHistory.get(sessionKey) || []; history.push({ role: user, content: userMessage }); if (history.length 10) { // 控制上下文长度防止触发token超限错误 history history.slice(-6); // 只保留最近3轮对话假设每轮一问一答 } try { const ctripResponse await axios.post(${CTRIP_API_BASE}/chat, { query: userMessage, session_id: sessionKey, history: history, // 将历史记录传给API }, { headers }); const aiReply ctripResponse.data.reply; history.push({ role: assistant, content: aiReply }); conversationHistory.set(sessionKey, history); res.json({ text: formatReply(aiReply) }); } catch (error) { // ... 错误处理 } });5.2 指令解析与多技能路由用户可能不仅想查旅游信息。我们可以解析指令将不同任务路由到不同的处理逻辑甚至调用其他API。// 简单的指令解析 function parseCommand(text) { if (text.includes(机票) || text.includes(航班)) { return flight; } else if (text.includes(酒店)) { return hotel; } else if (text.includes(天气)) { return weather; // 可能需要调用其他天气API } else { return general; // 默认用携程问道通用问答 } } app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { const command parseCommand(req.body.text); switch(command) { case flight: // 调用专门的航班查询函数可能使用不同的API端点 result await queryFlight(req.body.text); break; case weather: // 调用第三方天气API result await queryWeather(req.body.text); break; case general: default: result await queryCtripWenDao(req.body.text, req.body); break; } res.json(result); });5.3 异步处理与延迟响应有些查询比如复杂的行程规划可能耗时超过Workbuddy的请求超时限制通常3-5秒。这时需要使用“延迟响应”模式。立即返回一个“正在处理”的临时消息。在后台异步调用携程API。API调用完成后使用Workbuddy提供的“响应URL”通常在请求体中或Webhook将最终结果发送回去。app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { // 立即响应告诉Workbuddy已收到 res.json({ text: 正在为您查询请稍候... }); const responseUrl req.body.response_url; // Workbuddy可能提供此字段用于延迟发送 // 异步处理 processQueryAsync(userMessage, responseUrl).catch(console.error); }); async function processQueryAsync(message, responseUrl) { try { const result await longRunningCtripQuery(message); // 使用axios向responseUrl发送POST请求更新消息 await axios.post(responseUrl, { text: 查询完成${result}, replace_original: true // 替换掉“正在处理”那条消息 }); } catch (error) { await axios.post(responseUrl, { text: 查询失败${error.message} }); } }6. 部署、监控与问题排查6.1 生产环境部署本地开发测试完成后你需要将代码部署到稳定的云服务器或Serverless平台。传统服务器你可以购买一台云服务器如阿里云ECS、腾讯云CVM安装Node.js环境使用pm2等进程管理工具来守护你的应用。npm install -g pm2 pm2 start index.js --name ctrip-skill pm2 save pm2 startupServerless函数更推荐的方式。利用云厂商的Serverless函数如阿里云函数计算、腾讯云SCF、Vercel、Netlify Functions无需管理服务器按量计费自动扩缩容。你需要将代码稍作改造以适应函数入口格式。部署后将Workbuddy技能配置中的“回调URL”更新为你的生产环境地址并确保WORKBUDDY_VERIFICATION_TOKEN和CTRIP_API_KEY等环境变量在部署平台中正确设置。6.2 日志记录与监控清晰的日志是排查问题的生命线。不要只用console.log。结构化日志使用winston或pino库将日志输出到文件并包含时间戳、请求ID、错误堆栈等信息。关键点打日志在收到请求、调用API前、收到API响应、发生错误时都记录相关信息注意脱敏不要记录完整的API Key。应用性能监控APM如果服务重要可以考虑接入简单的监控比如用prom-client暴露指标或用云厂商的APM服务监控接口响应时间和错误率。6.3 常见问题排查实录以下是我在开发和运维过程中遇到的一些典型问题及解决方法问题现象可能原因排查步骤与解决方案Workbuddy提示“技能未响应”或“配置错误”1. 回调URL无法访问服务器宕机、端口未开。2. 网络策略阻止防火墙、安全组。3. 验证Token不匹配。1. 在服务器上curl http://localhost:PORT/skill检查服务是否存活。2. 用telnet或在线端口检测工具检查公网IP:PORT是否通畅。3.仔细核对Workbuddy控制台填写的Token和代码中WORKBUDDY_VERIFICATION_TOKEN的值是否完全一致包括首尾空格。技能收到请求但调用携程API失败返回400错误1. 请求参数格式错误如热词中的‘type’ must be in...。2. 请求体过大触发maximum context length错误。1.仔细阅读携程API官方文档对照检查每个必填参数、枚举值。将请求体和错误响应完整打印到日志中比对。2. 优化代码限制用户输入和历史对话的长度。在调用API前先估算token数可粗略按中文字符数*2计算如果过长则提示用户简化问题或清空历史。调用API超时Timeout或连接重置ECONNRESET1. 网络不稳定。2. 携程API服务端处理慢或异常。3. 服务器到API端的网络链路问题。1. 在代码中增加重试机制如使用axios-retry库。2. 适当增加timeout配置如15秒。3. 在服务器上直接curl携程API测试网络连通性和延迟。如果是云函数检查是否配置了正确的网络VPC。技能响应慢用户等待时间长1. 自身服务器性能瓶颈。2. 携程API响应慢。3. 同步处理耗时操作。1. 使用异步响应模式见5.3节先给用户反馈。2. 为你的技能服务器或函数配置更高的计算资源。3. 考虑缓存一些常见查询结果如城市热门酒店列表减少对API的调用。日志中看到401/403错误API密钥失效、过期或没有请求该接口的权限。1. 登录携程开放平台确认API Key状态是否正常。2. 检查请求头中的Authorization格式是否正确如Bearer后是否有空格。3. 确认该API Key是否有调用目标接口的权限。一个关键的实操心得在开发阶段务必把console.log(req.body, req.headers)打开你会清晰地看到Workbuddy到底给你发送了什么数据。很多配置错误都是因为想当然地认为数据格式而实际格式有差异。同样在调用携程API时也要把请求体和响应体注意脱敏打印出来这是定位API调用问题最快的方法。7. 安全与性能考量7.1 安全加固Token保密WORKBUDDY_VERIFICATION_TOKEN和CTRIP_API_KEY是最高机密必须使用环境变量管理绝对不要写入代码或提交到Git。输入验证与清理对用户输入的text进行基本的清理防止注入攻击。虽然这里是文本对话但良好的习惯很重要。HTTPS强制生产环境必须使用HTTPS。无论是你的技能服务器还是与Workbuddy、携程API的通信都应使用TLS加密。速率限制在你的技能服务器入口添加速率限制如express-rate-limit防止被恶意用户刷API导致你的携程API Key被限流或产生高额费用。7.2 性能优化连接池使用axios时可以考虑配置httpAgent和httpsAgent来复用到携程API的HTTP连接减少TCP握手开销。缓存策略对于非实时性要求极高的数据如城市信息、景点列表可以在你的服务器内存或Redis中设置短期缓存如5分钟显著减少API调用次数和响应时间。代码优化避免在请求处理中进行复杂的同步计算或阻塞I/O操作。使用异步编程模式让Node.js的事件循环保持高效。整个项目从构思到上线最耗时的部分往往不是写核心逻辑而是调试网络、权限和各个平台之间微妙的参数差异。尤其是在处理像“maximum context length”这类上游API的限制时需要在你的代码中提前做好防御性设计给用户清晰的引导而不是抛出一段机器错误码。把技能做得稳定、友好比单纯实现功能要重要得多。当你看到团队成员在Workbuddy里自然地你的技能并快速得到想要的旅行建议时那种感觉还是挺棒的。
从零到一：将携程问道AI集成到Workbuddy的实战指南
1. 项目概述携程问道与Workbuddy的融合最近在折腾一个挺有意思的项目把携程的“问道”AI助手能力集成到了Workbuddy这个协作工具里。简单来说就是让你能在Workbuddy的聊天窗口里直接调用携程问道的智能问答、行程规划、酒店推荐这些功能不用再切来切去。这玩意儿听起来像是简单的API对接但真做起来从环境配置、接口鉴权到错误处理每一步都有不少细节。特别是最近Workbuddy更新了它的技能Skill开发框架文档又比较零散踩了不少坑。这篇文章我就把从零开始把一个外部AI服务以携程问道为例接入Workbuddy的全过程包括核心原理、实操代码和避坑指南给你掰开揉碎了讲清楚。无论你是想给自己的团队做个内部工具还是想了解现代SaaS平台如何扩展第三方能力这篇都能给你一个完整的参考。2. 核心概念与前置准备在动手写代码之前我们必须把几个关键角色和它们之间的关系理清楚。这就像搭积木你得先知道每块积木是干什么的才能拼出想要的样子。2.1 角色定义携程问道、Workbuddy与你的技能首先这里涉及三个核心部分携程问道这是能力提供方。它本质上是一个提供旅游领域智能服务的API集合。比如你给它一段自然语言“帮我查一下下周北京飞上海的机票”它能理解你的意图并返回结构化的航班信息。对我们开发者而言它就是一个标准的HTTP API服务通常需要API Key进行鉴权。Workbuddy这是能力承载和交互的平台。它是一个集成了聊天、任务、文档的协作工具。Workbuddy允许开发者创建“技能”Skill这些技能可以像机器人一样在特定的聊天群组或私聊中被触发执行预设的任务。你的技能Skill这是你将要开发的桥梁。它是一段部署在你自己服务器或云函数上的后端代码。当用户在Workbuddy里你的技能并发送指令时Workbuddy会将这个指令转发给你的技能服务器。你的技能服务器收到后去调用携程问道的API拿到结果再格式化返回给Workbuddy最后由Workbuddy展示给用户。所以数据流是这样的用户 技能 - Workbuddy - 你的技能服务器 - 携程问道API - 你的技能服务器 - Workbuddy - 用户。2.2 环境与工具准备工欲善其事必先利其器。以下是开始前必须准备好的东西Node.js 环境Workbuddy的技能开发SDK对Node.js支持最友好这也是社区最常用的选择。强烈建议使用LTS版本比如18.x或20.x。避免使用过于前沿的版本如热词中提到的v24.19.0未发布的问题以免遇到不兼容的依赖。安装检查打开终端运行node -v和npm -v确认版本号。安装指引如果未安装去Node.js官网下载LTS安装包。Windows用户注意如果之前安装过且出现问题可以彻底卸载后重装并确保安装时勾选了“添加到PATH”选项。代码编辑器VS Code、WebStorm等任选用着顺手就行。携程问道API权限你需要联系携程相关的开放平台或商务申请成为开发者获取到关键的API Key有时也叫App Key/Secret和API的基地址Base URL。没有这个一切无从谈起。Workbuddy开发者账号登录你的Workbuddy通常可以在“设置”-“集成”或“开发者中心”找到创建技能Create Skill的入口。创建技能后你会获得一个重要的凭证Skill Token或Verification Token用于验证来自Workbuddy的请求是否合法。公网可访问的服务器/地址你的技能代码需要部署在一个能被Workbuddy服务器访问到的地方。开发初期我强烈推荐使用内网穿透工具比如ngrok或localtunnel。它们能把你的本地localhost:3000映射成一个临时的公网HTTPS地址方便调试。例如安装ngrok后运行ngrok http 3000你会得到一个类似https://abcd.ngrok.io的地址这就是你临时的技能服务器地址。注意Workbuddy出于安全考虑只支持HTTPS的回调地址。所以无论是ngrok提供的临时地址还是你最终部署的服务器都必须支持HTTPS。本地开发用ngrok是最省事的方案。3. 技能服务端核心实现这一部分是整个项目的骨架。我们将创建一个简单的Express.js服务器来处理Workbuddy发来的请求并调用携程问道API。3.1 项目初始化与依赖安装首先创建一个新的项目目录并初始化。mkdir ctrip-workbuddy-skill cd ctrip-workbuddy-skill npm init -y接着安装我们需要的核心依赖。npm install express axios body-parser dotenv npm install -D nodemonexpress: Node.js最流行的Web框架用于快速搭建服务器。axios: 用于发起HTTP请求调用携程问道API。比原生的http模块更好用支持Promise。body-parser: 中间件用于解析Workbuddy POST过来的JSON数据。dotenv: 管理环境变量把敏感的API Key等配置从代码中分离。nodemon: 开发工具监听文件变化自动重启服务器提升开发效率。在package.json中添加一个启动脚本scripts: { start: node index.js, dev: nodemon index.js }3.2 核心服务器代码解析创建项目的主文件index.js我们来一步步构建它。// index.js require(dotenv).config(); // 加载.env文件中的环境变量 const express require(express); const bodyParser require(body-parser); const axios require(axios); const app express(); const PORT process.env.PORT || 3000; // 中间件解析JSON格式的请求体 app.use(bodyParser.json()); // 从环境变量读取配置 const WORKBUDDY_VERIFICATION_TOKEN process.env.WORKBUDDY_VERIFICATION_TOKEN; const CTRIP_API_KEY process.env.CTRIP_API_KEY; const CTRIP_API_BASE process.env.CTRIP_API_BASE || https://openapi.ctrip.com; // 验证Workbuddy请求的中间件 const verifyWorkbuddyRequest (req, res, next) { const token req.headers[x-workbuddy-token]; // Workbuddy实际可能用不同的头需查阅最新文档 if (token ! WORKBUDDY_VERIFICATION_TOKEN) { console.warn(验证失败收到的Token:, token); return res.status(403).json({ error: Forbidden: Invalid token }); } next(); }; // Workbuddy技能配置的端点用于技能启用时验证 app.get(/skill, (req, res) { // 有些平台需要这个端点返回技能的基本信息或者用于健康检查 res.json({ status: ok, message: Ctrip WenDao Skill is running. }); }); // 核心处理用户消息的端点 app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { console.log(收到Workbuddy消息:, JSON.stringify(req.body, null, 2)); const userMessage req.body.text; // 用户输入的原始文本 const userId req.body.user_id; const channelId req.body.channel_id; if (!userMessage) { return res.json({ text: 您好我收到了空消息。请告诉我您想查询什么 }); } try { // 1. 调用携程问道API const ctripResponse await axios.post( ${CTRIP_API_BASE}/ai/wendao/chat, // 假设的接口路径实际需替换 { query: userMessage, session_id: ${userId}-${channelId}, // 用用户和频道ID构造会话保持上下文 // 其他可能的参数如城市、时间等可以从userMessage中解析后传入 }, { headers: { Authorization: Bearer ${CTRIP_API_KEY}, Content-Type: application/json, }, timeout: 10000, // 设置10秒超时避免长时间等待 } ); // 2. 处理携程API的返回结果 const aiReply ctripResponse.data.reply; // 根据实际API响应结构调整 const formattedReply 【携程问道】\n${aiReply}\n\n---\n*以上信息由携程问道提供请以实时查询为准。*; // 3. 返回格式化的消息给Workbuddy res.json({ text: formattedReply, // Workbuddy可能支持更丰富的消息格式如Markdown、附件等 // response_type: in_channel // 如果想让消息对频道所有人可见 }); } catch (error) { console.error(处理请求时出错:, error); let errorMessage 抱歉查询服务暂时不可用请稍后再试。; // 针对特定错误进行友好提示 if (error.code ECONNRESET) { errorMessage 网络连接不稳定请求超时了。; } else if (error.response) { // 携程API返回了错误状态码 console.error(API错误详情:, error.response.status, error.response.data); if (error.response.status 400) { // 重点处理热词中提到的400错误 const errorData error.response.data; if (errorData.error errorData.error.includes(maximum context length)) { errorMessage 您的问题或历史对话内容太长了超出了AI的处理限制。请尝试简化您的问题或开启一个新对话。; } else if (errorData.error errorData.error.includes(type must be in)) { errorMessage 请求参数配置有误请联系技能管理员检查。; } } else if (error.response.status 401 || error.response.status 403) { errorMessage 服务授权失败请确认API密钥是否有效。; } else if (error.response.status 429) { errorMessage 请求过于频繁请稍等一分钟再试。; } } else if (error.request) { // 请求发出了但没有收到响应 errorMessage 无法连接到旅行查询服务请检查网络。; } res.json({ text: 【出错啦】\n${errorMessage} }); } }); // 启动服务器 app.listen(PORT, () { console.log(技能服务器运行在 http://localhost:${PORT}); console.log(请确保Workbuddy配置的回调地址是: https://你的公网地址/skill/message); });3.3 环境变量配置在项目根目录创建.env文件存放你的敏感信息。切记将这个文件添加到.gitignore中不要提交到代码仓库。# .env PORT3000 WORKBUDDY_VERIFICATION_TOKENyour_workbuddy_skill_token_here CTRIP_API_KEYyour_ctrip_openapi_key_here CTRIP_API_BASEhttps://openapi.ctrip.com3.4 本地运行与测试在终端运行npm run dev启动开发服务器。在另一个终端运行ngrok http 3000获取你的公网HTTPS地址例如https://abc123.ngrok.io。使用curl或Postman模拟Workbuddy的请求测试你的技能curl -X POST https://abc123.ngrok.io/skill/message \ -H Content-Type: application/json \ -H x-workbuddy-token: your_workbuddy_skill_token_here \ -d {text: 上海外滩附近有什么推荐的高分酒店, user_id: test_user, channel_id: test_channel}你应该能收到一个格式化的回复。4. Workbuddy技能配置与上线代码写好了服务器跑起来了现在需要告诉Workbuddy这个技能的存在。4.1 在Workbuddy控制台创建技能登录Workbuddy进入“开发者中心”或“技能管理”。点击“创建新技能”。填写技能基本信息技能名称携程旅行助手描述基于携程问道AI提供机票、酒店、行程问答服务。回调URL填写你的ngrok地址加上端点例如https://abc123.ngrok.io/skill/message。这是最关键的一步。验证Token这里填写你在.env里设置的WORKBUDDY_VERIFICATION_TOKEN。Workbuddy会在每次请求的Header中带上这个Token你的代码用它来验证请求来源。权限/Scope根据技能需要勾选“接收消息”、“发送消息”等权限。保存后Workbuddy可能会尝试访问你设置的“回调URL”进行一次握手验证确保你的服务器能正常响应。确保你的本地服务器和ngrok都在运行。4.2 在聊天中使用技能技能创建成功后你通常需要将它安装或添加到某个工作区或频道。在目标频道中输入携程旅行助手 帮我规划一个周末的杭州美食之旅。Workbuddy会将这条消息转发给你的服务器你的服务器处理完后结果会以技能的身份在频道中回复。5. 高级功能与优化实践基础功能跑通后我们可以考虑让它变得更智能、更健壮。5.1 实现对话上下文管理上面的示例中我们简单地将userId和channelId组合作为会话ID。但对于多轮对话这还不够。我们需要在服务器端临时存储对话历史。// 简单的内存存储生产环境需用Redis或数据库 const conversationHistory new Map(); app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { const userMessage req.body.text; const sessionKey ${req.body.user_id}-${req.body.channel_id}; // 获取历史记录只保留最近N轮 let history conversationHistory.get(sessionKey) || []; history.push({ role: user, content: userMessage }); if (history.length 10) { // 控制上下文长度防止触发token超限错误 history history.slice(-6); // 只保留最近3轮对话假设每轮一问一答 } try { const ctripResponse await axios.post(${CTRIP_API_BASE}/chat, { query: userMessage, session_id: sessionKey, history: history, // 将历史记录传给API }, { headers }); const aiReply ctripResponse.data.reply; history.push({ role: assistant, content: aiReply }); conversationHistory.set(sessionKey, history); res.json({ text: formatReply(aiReply) }); } catch (error) { // ... 错误处理 } });5.2 指令解析与多技能路由用户可能不仅想查旅游信息。我们可以解析指令将不同任务路由到不同的处理逻辑甚至调用其他API。// 简单的指令解析 function parseCommand(text) { if (text.includes(机票) || text.includes(航班)) { return flight; } else if (text.includes(酒店)) { return hotel; } else if (text.includes(天气)) { return weather; // 可能需要调用其他天气API } else { return general; // 默认用携程问道通用问答 } } app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { const command parseCommand(req.body.text); switch(command) { case flight: // 调用专门的航班查询函数可能使用不同的API端点 result await queryFlight(req.body.text); break; case weather: // 调用第三方天气API result await queryWeather(req.body.text); break; case general: default: result await queryCtripWenDao(req.body.text, req.body); break; } res.json(result); });5.3 异步处理与延迟响应有些查询比如复杂的行程规划可能耗时超过Workbuddy的请求超时限制通常3-5秒。这时需要使用“延迟响应”模式。立即返回一个“正在处理”的临时消息。在后台异步调用携程API。API调用完成后使用Workbuddy提供的“响应URL”通常在请求体中或Webhook将最终结果发送回去。app.post(/skill/message, verifyWorkbuddyRequest, async (req, res) { // 立即响应告诉Workbuddy已收到 res.json({ text: 正在为您查询请稍候... }); const responseUrl req.body.response_url; // Workbuddy可能提供此字段用于延迟发送 // 异步处理 processQueryAsync(userMessage, responseUrl).catch(console.error); }); async function processQueryAsync(message, responseUrl) { try { const result await longRunningCtripQuery(message); // 使用axios向responseUrl发送POST请求更新消息 await axios.post(responseUrl, { text: 查询完成${result}, replace_original: true // 替换掉“正在处理”那条消息 }); } catch (error) { await axios.post(responseUrl, { text: 查询失败${error.message} }); } }6. 部署、监控与问题排查6.1 生产环境部署本地开发测试完成后你需要将代码部署到稳定的云服务器或Serverless平台。传统服务器你可以购买一台云服务器如阿里云ECS、腾讯云CVM安装Node.js环境使用pm2等进程管理工具来守护你的应用。npm install -g pm2 pm2 start index.js --name ctrip-skill pm2 save pm2 startupServerless函数更推荐的方式。利用云厂商的Serverless函数如阿里云函数计算、腾讯云SCF、Vercel、Netlify Functions无需管理服务器按量计费自动扩缩容。你需要将代码稍作改造以适应函数入口格式。部署后将Workbuddy技能配置中的“回调URL”更新为你的生产环境地址并确保WORKBUDDY_VERIFICATION_TOKEN和CTRIP_API_KEY等环境变量在部署平台中正确设置。6.2 日志记录与监控清晰的日志是排查问题的生命线。不要只用console.log。结构化日志使用winston或pino库将日志输出到文件并包含时间戳、请求ID、错误堆栈等信息。关键点打日志在收到请求、调用API前、收到API响应、发生错误时都记录相关信息注意脱敏不要记录完整的API Key。应用性能监控APM如果服务重要可以考虑接入简单的监控比如用prom-client暴露指标或用云厂商的APM服务监控接口响应时间和错误率。6.3 常见问题排查实录以下是我在开发和运维过程中遇到的一些典型问题及解决方法问题现象可能原因排查步骤与解决方案Workbuddy提示“技能未响应”或“配置错误”1. 回调URL无法访问服务器宕机、端口未开。2. 网络策略阻止防火墙、安全组。3. 验证Token不匹配。1. 在服务器上curl http://localhost:PORT/skill检查服务是否存活。2. 用telnet或在线端口检测工具检查公网IP:PORT是否通畅。3.仔细核对Workbuddy控制台填写的Token和代码中WORKBUDDY_VERIFICATION_TOKEN的值是否完全一致包括首尾空格。技能收到请求但调用携程API失败返回400错误1. 请求参数格式错误如热词中的‘type’ must be in...。2. 请求体过大触发maximum context length错误。1.仔细阅读携程API官方文档对照检查每个必填参数、枚举值。将请求体和错误响应完整打印到日志中比对。2. 优化代码限制用户输入和历史对话的长度。在调用API前先估算token数可粗略按中文字符数*2计算如果过长则提示用户简化问题或清空历史。调用API超时Timeout或连接重置ECONNRESET1. 网络不稳定。2. 携程API服务端处理慢或异常。3. 服务器到API端的网络链路问题。1. 在代码中增加重试机制如使用axios-retry库。2. 适当增加timeout配置如15秒。3. 在服务器上直接curl携程API测试网络连通性和延迟。如果是云函数检查是否配置了正确的网络VPC。技能响应慢用户等待时间长1. 自身服务器性能瓶颈。2. 携程API响应慢。3. 同步处理耗时操作。1. 使用异步响应模式见5.3节先给用户反馈。2. 为你的技能服务器或函数配置更高的计算资源。3. 考虑缓存一些常见查询结果如城市热门酒店列表减少对API的调用。日志中看到401/403错误API密钥失效、过期或没有请求该接口的权限。1. 登录携程开放平台确认API Key状态是否正常。2. 检查请求头中的Authorization格式是否正确如Bearer后是否有空格。3. 确认该API Key是否有调用目标接口的权限。一个关键的实操心得在开发阶段务必把console.log(req.body, req.headers)打开你会清晰地看到Workbuddy到底给你发送了什么数据。很多配置错误都是因为想当然地认为数据格式而实际格式有差异。同样在调用携程API时也要把请求体和响应体注意脱敏打印出来这是定位API调用问题最快的方法。7. 安全与性能考量7.1 安全加固Token保密WORKBUDDY_VERIFICATION_TOKEN和CTRIP_API_KEY是最高机密必须使用环境变量管理绝对不要写入代码或提交到Git。输入验证与清理对用户输入的text进行基本的清理防止注入攻击。虽然这里是文本对话但良好的习惯很重要。HTTPS强制生产环境必须使用HTTPS。无论是你的技能服务器还是与Workbuddy、携程API的通信都应使用TLS加密。速率限制在你的技能服务器入口添加速率限制如express-rate-limit防止被恶意用户刷API导致你的携程API Key被限流或产生高额费用。7.2 性能优化连接池使用axios时可以考虑配置httpAgent和httpsAgent来复用到携程API的HTTP连接减少TCP握手开销。缓存策略对于非实时性要求极高的数据如城市信息、景点列表可以在你的服务器内存或Redis中设置短期缓存如5分钟显著减少API调用次数和响应时间。代码优化避免在请求处理中进行复杂的同步计算或阻塞I/O操作。使用异步编程模式让Node.js的事件循环保持高效。整个项目从构思到上线最耗时的部分往往不是写核心逻辑而是调试网络、权限和各个平台之间微妙的参数差异。尤其是在处理像“maximum context length”这类上游API的限制时需要在你的代码中提前做好防御性设计给用户清晰的引导而不是抛出一段机器错误码。把技能做得稳定、友好比单纯实现功能要重要得多。当你看到团队成员在Workbuddy里自然地你的技能并快速得到想要的旅行建议时那种感觉还是挺棒的。