一个员工提出需求："能不能给我配个专属智能客服？"这个看似随口一问的需求，牵出了WorkMate架构里最有扩展性的一块拼图——对外开放接口（Open API）。本文拆解它的设计思路、协议细节与落地场景，相关技术文档与技能包均已在开源项目中公开。

一、一个"随口一提"的需求，为什么必须安排

WorkMate为每位员工配备一个工作伴侣：它装在员工自己的Windows电脑上，权限与员工本人完全一致，能操作微信、同花顺、浏览器，能读写文件、跑脚本、调MCP工具，能按技能包完成报价、写报告、审合同。用久了，员工对它的信任会自然生长——于是新的期待就来了：

"既然它这么能干，能不能让它去当我的智能客服？客户在外网提问，它来回答。"

这个需求听起来轻巧，拆开看却一点都不简单。它的本质是：把一台部署在内网、绑定个人身份、需要人工监督的桌面智能体，安全地延伸到公网，变成一台7×24小时在线的对外服务节点。具体要满足三个硬条件：

第一，要有一个外网能访问的地址。桌面端跑在员工本机，没有公网IP、没有域名、不监听外部端口——客户从互联网根本"看不见"它。要么给它做端口映射，要么在中间加一层能被外网访问的入口。

第二，要能实时监控到回复结果。智能客服不是"发出去就不管"的邮件，客户要看到逐字蹦出来的回答，运营要看到它调用了哪些工具、思考到哪一步、有没有卡在某个环节。这就要求服务端能主动把执行过程推给调用方，而不是让调用方傻等一个最终结果。

第三，使用起来要简单，最好能直接配置。提需求的员工是业务岗，不是运维岗。如果方案要求他配Nginx、开防火墙、写鉴权中间件、维护长连接重连逻辑，这个需求在第一周就会烂尾。

三个条件摆出来，问题的性质就清楚了：这不是"加个接口"的小事，而是要在"个人桌面智能体"和"外部调用方"之间，架一条安全、实时、双向的通道。

二、常规方案为什么都别扭

在动手之前，我们先把市面上常见的三条路走了一遍，看看它们各自卡在哪里。

方案一：自建后端服务 + 轮询取结果。最直觉的做法——写一个Web服务，接收外部请求，转发给AI，再把结果返回。问题在于：桌面端智能体的执行是长过程（一次报告生成可能跑十几分钟，中间还有人工确认环节），HTTP的"请求—响应"模型撑不住这种时长；退一步用轮询，调用方每隔几秒问一次"好了吗"，延迟高、请求量大，而且中间过程全丢了——你只能拿到最终答案，看不到它怎么想的、调了什么工具、在哪一步停下来等人确认。对一个要监控质量的客服场景来说，这等于把黑箱换了个位置摆。

方案二：直接用云厂商的对话机器人平台。这条路省事，但代价是能力被平台框死。云机器人擅长FAQ问答、意图识别、多轮填槽，可它接不上你的私有数据、调不了你本机的同花顺、读不了你内网的知识库、更不会操作微信发文件。你想要的是"把已经能干活的WorkMate开放出去"，而不是"再养一个只会聊天的机器人"——能力半径完全不是一回事。

方案三：RPA + 开放API拼接。用RPA模拟人操作界面，再包一层API对外暴露。听起来两全其美，实际是把复杂度翻倍：RPA的稳定性本就依赖界面不变，再叠加网络暴露、鉴权、并发、断线重连，维护成本高得吓人；而且"人工确认"这类交互几乎无法透传——AI停下来问"要不要继续生成详细版"，外部调用方根本收不到这个提问，任务就永久卡住了。

三条路走下来，结论很清晰：常规方案要么丢过程、要么丢能力、要么丢稳定性。真正的解法必须同时满足四件事——长连接实时推送、完整事件透传（含思考与工具调用）、可交互可中断、以及极简的接入方式。

三、WorkMate的答案：对外开放接口

3.0 先用一个类比讲清楚它在干什么

想象你在一栋写字楼里办公，你的工位（桌面端）里有电脑、有资料柜、有你本人的门禁卡。现在外面有客户想找你办事，但他进不了这栋楼——这就是桌面端的处境：能力很强，但外面够不着。

WorkMate的做法不是把工位搬到楼外，而是在一楼开一个前台窗口：

• 客户到窗口，报上你的姓名和工牌号（用户名+密码），前台核实无误后，给他接一条专线电话（WebSocket长连接）；
• 客户在电话里说需求（task_start），前台把话转给楼上你的工位，由你的电脑真实执行——用的是你的权限、你的资料柜、你的工具，一点不多、一点不少；
• 执行过程中，工位会实时向电话里播报：它在查什么资料、调了什么工具、写到哪一步了（delta/think事件）；
• 如果它需要你拍板（比如"要不要发正式报价"），它会停下来问，客户在电话里回答后，它接着干（hitl_wait/task_resume）；
• 客户随时可以挂电话，一挂断，楼上正在干的活立即停手，不会留下没人认领的半成品。

这个"前台窗口+专线电话"，就是对外开放接口（Open API）。它没有新建一套系统，只是给已有的桌面端开了一扇受控的窗——能力原样开放，过程完全透明，边界严格可控。

3.1 最重要的一句话：它调用的，是员工自己的WorkMate

上面那个类比里，有一个细节值得单独拎出来讲——客户在电话里提的需求，最终是由"楼上你自己的工位"完成的，不是由某个新系统、也不是由某个公共机器人完成的。

这句话的分量在哪里？我们把它拆开看：

第一，它调用的是"员工本人"的桌面端，不是一台公共服务器。任务在员工自己的电脑上跑，用的是员工自己的账号身份、自己的权限范围、自己的登录状态。这意味着：员工平时能做的事，对外接口就能做；员工平时不能做的事，对外接口同样做不了。权限边界不需要重新设计，因为它天然就是同一套。

第二，它继承的是桌面端"完整的"能力，而不是一个阉割版。这一点是整套方案真正的价值所在。一个已经用了一段时间的WorkMate桌面端，身上积累了什么？

• 工具（MCP）：能查行情、能读写文件、能跑脚本、能发消息、能操作本机软件（微信、同花顺、浏览器……）；
• 技能（Skills）：报价、写报告、审合同、做数据提取、生成风险报告……这些是公司把管理规范和业务流程沉淀下来的"标准动作"；
• 知识库：企业知识库、个人知识库、历史文档，都是它回答问题的依据；
• 记忆：三层记忆让它记得员工说过什么、习惯怎么做、公司业务是什么；
• 人机协同机制：遇到拿不准的事会停下来问人，关键操作必须确认。

这些东西不需要为"智能客服"重新开发一遍。对外开放接口做的事情，只是把"员工在电脑前敲字"换成了"客户从外网发消息"——输入的口子变了，干活的人和干活的能力一点没变。

第三，这才是"快速实现智能客服"的真正原因。换个角度看这件事：如果没有开放接口，要做一个智能客服，你得从零搭一套系统——接大模型、写提示词、接知识库、接业务系统、做权限、做审计、做人工兜底……每一项都是工作量。而有了开放接口，你要做的是：把已经能干活的桌面端，接一根线接到外面去。

具体到"智能客服"这个场景，能力是这样"白捡"来的：

智能客服需要什么	桌面端已经有什么	需要新开发什么
能回答业务问题	知识库 + 三层记忆	无
能查实时数据	MCP工具（行情、库存、订单……）	无
能按公司规范回复	技能包（报价、报告、风控……）	无
能处理文件	附件下载 + 文档解析能力	无
关键操作有人把关	HITL人机协同机制	无
操作可追溯	全链路审计日志	无
能被外网访问	—	开放接口（已提供）
能实时看到过程	—	开放接口（已提供）

表格最后两行是唯一需要"新增"的部分，而它们恰好就是对外开放接口已经解决的事。换句话说：智能客服的"业务能力"是现成的，开放接口只负责解决"怎么把能力递出去"。

第四，这也解释了为什么它比"重新做一个客服机器人"更划算。新做一个机器人，它不懂你的业务术语、不知道你的报价规则、读不到你的历史文档、调不了你的内部系统——你得把这些从零教它一遍，而且教完还是两套东西，各维护各的。而基于桌面端扩展出来的智能客服，和员工本人在用的是同一套大脑：今天员工教会了WorkMate一个新的报价规则，明天客服就自动会了；公司更新了知识库，客服的回答同步更新。一份能力，两处使用，零额外维护。

所以，理解对外开放接口，关键不是记住它用了WebSocket、有几个字段——而是要看到：它把员工桌面端的能力，原封不动地扩展到了企业需要的任何一个出口上。智能客服只是第一个出口，后面还有无数个。

3.2 两个端点：一个换门票，一个打电话

整套接口只暴露两个地址，分工极其简单：

用途	协议	地址	打个比方
换取token	HTTP POST	/api/open/auth/token	到前台换一张临时通行证
长连接	WebSocket	/api/open/ws	接通那部专线电话

什么是WebSocket？ 你可以把它理解成"电话"，而普通的HTTP请求是"寄信"。寄信只能一问一答，寄出去就得等回信；电话则不同——双方可以随时说话，不用等对方先挂断。这正是智能客服需要的：客户提问后，AI的回答要一个字一个字蹦出来，中途还要能插话、能叫停，寄信模式做不到。

鉴权（也就是验明身份）有两种方式：

• 方式一（推荐，最简单）：电话接通后，第一句话就报上用户名和密码。注意有个时间限制——60秒内必须报，否则前台直接挂断。
• 方式二：如果调用方不方便在第一句就说密码（比如浏览器环境、或者公司网关统一管鉴权），可以先用HTTP接口换一张wm1.*格式的临时通行证（token），再拿这张证去接通电话。

验证通过后，前台会回一句auth_ok，里面有个desktop_online字段——它告诉你"楼上的人今天在不在工位"。如果不在（桌面端没登录），你发起任务时会收到一个明确的desktop_offline错误，而不是让请求石沉大海、白等一场。

3.3 发起任务：一个字段就能跑起来

身份验证通过后，发一条消息就能开工：

{
  "action": "task_start",
  "user_input": "帮我查一下今天PP2605的价格并分析走势",
  "skills_names": [],
  "mcp_tool_names": [],
  "knowledge_file_ids": [],
  "attachment_urls": []
}

必填的只有`user_input`（任务内容）一个字段，其余全是可选项：想让它用某个技能包就填skills_names，想限定它能用哪些工具就填mcp_tool_names，想让它读知识库文件就填knowledge_file_ids，想传附件就填attachment_urls。什么都不填也能跑。

这里有个对客服场景特别重要的设计——会话续接：

• 不传`thread_id`：每次都是新建对话，等价于你在桌面端点了"新建对话"再发消息；
• 传入`thread_id`：在同一个对话里接着聊，前面的上下文全部保留。

为什么重要？因为客户不可能一句话把需求说清楚。第一句问"PP2605多少钱"，第二句追问"那和上周比呢"——如果没有会话续接，AI每次都是失忆状态，第二句就答不上来。`thread_id`就是那个"对话窗口的门牌号"，记住它，多轮对话才连贯。

3.4 事件流：把"黑箱"变成"玻璃箱"

这是整套接口最有价值的部分。任务下发后，服务端会持续推送事件（就像电话里不断有播报），调用方看到的不只是最终答案，而是全过程：

事件类型	含义	客户/运营看到什么
queued / queue_heartbeat	进入排队、排队心跳	"前面还有2个任务，请稍候"
executing / status	开始执行、阶段状态	"正在解析附件……"
`delta`	回复文本的增量片段	字一个字往外蹦的打字机效果
`think`	思考过程与工具调用细节	"正在查询同花顺行情……"
reference_parsed	知识库/附件解析结果	"已读取《9月行情周报》"
`hitl_wait`	需要人拍板的交互请求	弹出一张确认卡片
done / error / cancelled	终态：完成、出错、被取消	任务收尾

三个关键事件，各自解决一个问题：

• `delta`解决"等待焦虑"：客户不用盯着转圈圈，回答像真人打字一样逐字出现；
• `think`解决"信任问题"：运营能看到AI查了什么数据、调了什么工具、得出了什么中间结论——出了问题能查，答得对不对能验；
• `hitl_wait`解决"责任问题"：这是WorkMate最核心的"人机协同"能力被完整搬到了外部。当AI遇到需要确认的关键操作（比如发送正式报价、修改合同条款），它会停下来，把问题、选项一起推给外部系统；外部渲染出一张确认卡片，用户点选后，通过task_resume把答复回传（resume_command里写明是确认、输入还是多选），任务继续往下跑。

这意味着：外部调用方不只是"看客"，而是能参与决策的"副驾驶"。AI不会绕过人自作主张，关键节点始终有人把关——这正是企业敢把AI放到对外场景的前提。

3.5 停止与断开：收尾干净，不留烂摊子

对外服务最怕"任务跑飞了没人管"。这套接口把三种收尾情况都定义清楚了：

• 主动停止：发一条task_stop。如果任务还在排队，就取消排队；如果正在执行，就触发停止（约5秒内中断）；如果正卡在等人确认的环节，就以"拒绝"的方式终止任务。
• 主动断开：直接关掉连接。该连接上所有没结束的任务（排队中/执行中/等待确认中）全部自动取消，桌面端不会留下"僵尸任务"。
• 桌面端掉线：如果执行过程中员工的电脑关机或断网，服务端会等15秒确认没有重连，然后推送desktop_lost错误并结束通道。

这背后是一条清晰的设计原则：通道是连接级的、纯内存态——断线即取消，重连需重新发起。为什么要这样设计？因为它避免了最难排查的一类故障："任务在后台偷偷跑完了，调用方却毫不知情"。宁可明确失败，也不要状态不一致。

同时要说明一点：员工自己在桌面端发起的任务，不走这条链路，所以它们"重启后可恢复"的行为完全不受影响。两套逻辑彼此独立、互不干扰。

四、技术小白怎么办？交给技能包

到这里，技术方案已经完整了。但还有一个现实问题：提需求的员工是业务岗，他看不懂WebSocket协议，也不该看懂。难道要他去读技术文档、写Python脚本吗？

不需要。我们提供了open-api-assistant技能——让WorkMate自己来调WorkMate的开放接口。

这个技能包内置了一个可直接运行的Python命令行客户端，三条命令就能跑通一次远程问答，最贴心的是浏览器演示页：技能包里有一个零依赖的单文件HTML（open_api_chat_demo.html），双击打开就能体验完整交互——连接、发任务、看流式回复、看思考时间线、点HITL卡片、主动停止、多轮续接。它既是体验入口，也是第三方前端对接的完整参考实现。

换句话说，从"我想做个智能客服"到"跑起来"，中间不需要工程师介入：业务人员描述需求，WorkMate读取技能包，自动完成对接与验证。

4.1 文档与技能包在哪里下载

上面提到的全部内容——对外开放接口的完整技术文档、open-api-assistant技能包（含命令行客户端、Python库封装、零依赖浏览器演示页），以及WorkMate的Harness核心框架、供应链基础Skills模板、MCP SDK，都可以在开源项目中直接获取：

https://github.com/richsupply/workmate

仓库里与本文直接相关的内容包括：

• 技术文档：对外开放接口的设计方案与技术文档（协议细节、字段说明、错误码、生命周期语义、各语言调用案例），即本文第三章所依据的权威来源；
• 技能包：open-api-assistant技能，内含SKILL.md（使用说明与工作流）、scripts/open_api_client.py（可直接运行的命令行客户端与库封装）、references/open_api_guide.md（协议速查表）、examples/open_api_chat_demo.html（浏览器演示页）；
• 框架与模板：Harness核心框架、10个供应链基础Skills模板、MCP SDK。

拿到之后，你既可以照着文档自己实现一套调用端，也可以直接把技能包挂到WorkMate里让AI代劳——文档给愿意动手的人，技能给只想用的人，两条路都通。

五、总结与延展：一扇窗能通向多少房间

回顾整条链路，WorkMate对外开放接口的价值可以浓缩成三句话：它把桌面智能体的能力原样开放（权限、技能、知识库、工具全继承）；它把执行过程完整透明（思考、工具、流式文本、人工确认全透传）；它把接入成本压到最低（首帧鉴权、单字段发起、技能包代劳）。

而这扇窗能通向的房间，远不止"智能客服"一间：

场景一：企业自有系统的AI化改造。ERP、OA、CRM不必推倒重来——在这些系统里嵌一个对话框，后端调开放接口转发给对应员工的桌面端，老系统就"原地升级"出了AI能力。业务员在熟悉的界面里提问，背后是完整的智能体在工作。

场景二：客户门户与小程序。把开放接口作为后端，前台做成网页版或小程序版"AI分析师"。客户登录后提问，后台按客户归属路由到对应分析师的桌面端——每个客户都有一位专属分析师，而分析师本人不需要加班。

场景三：批量任务调度。开放接口支持一条连接先后发起多个任务（各自独立channel_id），天然适合批量场景：夜间批量生成一百份客户定制报告、批量跑数据核查、批量做舆情扫描，第二天上班直接收结果。

场景四：跨组织协同。当上下游企业都部署了WorkMate，双方的开放接口可以安全对接——采购方的系统发起询价，供应方的桌面端自动响应，hitl_wait机制保证关键承诺仍由人确认。这是"企业级Agent互联网"的雏形。

再往远看一层，这套接口还藏着三个更有想象力的延伸：

其一，Agent-to-Agent的直接对话。当前是"系统调Agent"，未来可以演进为"Agent调Agent"。你的桌面端遇到超出能力边界的问题时，可以主动通过开放接口向同事的桌面端发起协作请求——智能体之间自己组队，人只负责设定边界和验收结果。

其二，能力市场化的技术底座。当开放接口成为标准，每位员工（或每个部门）的桌面端都可以被看作一个"能力节点"。谁的报告写得好、谁的报价响应快，都可以被量化、被调用、被复用。组织内部第一次有了"能力可计量"的基础设施。

其三，从"接口"到"协议"的跃迁。今天我们定义的是WorkMate自己的task_start、task_event、hitl_wait；如果这套语义被更多厂商采纳，它就有机会成为企业级Agent互联的通用语言——就像HTTP定义了网页、SMTP定义了邮件。到那时，开放接口不再是一个功能，而是产业智能体网络的接入标准。

一扇窗，通向的是一整片建筑群。而这一切的起点，只是某位员工那句"能不能给我配个专属智能客服"——好的架构，就是让每个朴素的需求都能找到一条干净的实现路径。