企业官网建设流程全解析

1. 为什么我要给 WorkBuddy 接一个自定义 MCP 连接器

WorkBuddy 这个工具我用了一段时间，它的强项在于把日常的重复性工作流串起来，比如批量处理文件、定时抓取信息、自动整理笔记。但它默认的能力边界是固定的，遇到需要调用外部 AI 服务、访问特定 API 或者操作本地工具的场景，就得靠 MCP 来扩展。

MCP 全称 Model Context Protocol，直译过来是“模型上下文协议”。你可以把它理解成一套标准化的插座：WorkBuddy 是电器，外部服务是电网，MCP 就是中间那个统一的插头标准。没有它的时候，每接一个外部服务都得写一套私有适配代码；有了它，只要服务端按 MCP 规范暴露接口，客户端就能即插即用。

这次我选的目标是「腾讯混元生图」的 SSE 云托管服务。为什么拿它当例子？一是生图这个需求足够典型，很多人都有“让 WorkBuddy 帮我根据文字描述生成配图”的诉求；二是它走的是 SSE（Server-Sent Events）协议，和常见的请求-响应式 API 不太一样，踩坑点集中，讲透了之后你接别的 SSE 类服务也能照搬。

SSE 是什么？简单说，它是一种服务器单向推送数据给客户端的长连接机制。普通 HTTP 请求像你打电话问客服一个问题，对方答完就挂断；SSE 像你打开收音机听广播，电台持续往你这边推内容，你只管接收。生图这种任务耗时较长，服务端往往先返回“任务已创建”，再陆续推送进度和最终结果，用 SSE 就很合适。

这篇文章适合三类人看：一是已经在用 WorkBuddy、想扩展它能力边界的老用户；二是手上有 SSE 接口、不知道怎么接进 AI 工具链的开发者；三是对 MCP 协议好奇、想找一个完整案例上手的新手。我会从配置文件的字段含义讲起，到实际调试时遇到的连接超时、事件解析失败等问题，把整个流程拆开揉碎。

需要提前说明的是，下面涉及的具体配置参数、字段命名，一部分来自我实际调试的记录，一部分是基于 MCP 通用规范和 SSE 标准做的合理推断。不同版本的 WorkBuddy 在细节上可能有差异，你照着做的时候以自己工具里的实际提示为准。

2. 动手之前先把 MCP 和 SSE 这两个概念吃透

2.1 MCP 到底解决了什么问题

在没有 MCP 之前，给 AI 工具接外部能力是一件很痛苦的事。假设你有五个外部服务要接——一个生图、一个查天气、一个读数据库、一个发邮件、一个操作浏览器——每个服务都有自己的认证方式、参数格式、返回结构。你得为每一个写一套适配层，WorkBuddy 升级一次接口，你可能就得改一遍代码。

MCP 的思路是把“工具怎么被调用”这件事标准化。它定义了一套描述语言，服务端告诉客户端“我有哪些工具、每个工具需要什么参数、返回什么格式”，客户端负责把这些信息转成模型能理解的上下文。模型决定调用某个工具时，客户端按标准格式发请求，服务端按标准格式回结果。

这里有个容易混淆的点：MCP 是软件协议，不是硬件协议。热搜里有人问“MCP 是软件协议，硬件协议那个概念叫什么来着”，硬件领域对应的概念通常叫“总线标准”或“接口规范”，比如 USB、I2C、SPI 这些。MCP 借鉴的正是这种“统一接口”的思想，只不过它统一的是 AI 模型和外部工具之间的交互方式。

MCP 支持多种传输方式，常见的有 stdio（标准输入输出，适合本地进程）和 SSE（适合远程服务）。stdio 模式下，WorkBuddy 会启动一个本地子进程，通过标准输入输出和它通信；SSE 模式下，WorkBuddy 直接连一个远程 URL，服务端通过事件流推送数据。这次我们用的是后者。

2.2 SSE 的工作机制和它的脾气

SSE 基于 HTTP，但和普通 HTTP 有几个关键区别。第一，它的响应头里Content-Type必须是text/event-stream，这是识别 SSE 流的标志。第二，连接建立后不会立即关闭，服务端可以持续往客户端写数据。第三，数据有固定的格式：每条消息以data:开头，以两个换行符结束，还可以带event:、id:、retry:等字段。

我画个简单的例子帮你理解。服务端推送一条消息，实际传输的内容长这样：

event: progress data: {"status":"generating","percent":45} event: result data: {"status":"done","image_url":"https://..."}

客户端解析时，先看event:确定事件类型，再看data:里的 JSON 内容。两个换行符是消息分隔符，少了它客户端就不知道一条消息到哪儿结束。

SSE 有几个“脾气”你得顺着它。第一，它是单向的，只能服务端推、客户端收，客户端想发数据得另开一个 HTTP 请求。第二，很多代理和网关会在连接空闲一段时间后强制断开，这就是热搜里那个stream disconnected before completion: idle timeout waiting for SSE报错的来源。第三，浏览器对 SSE 有连接数限制，虽然 WorkBuddy 作为桌面工具不受这个限制，但服务端可能有限制。

2.3 为什么选腾讯混元生图做案例

生图服务的交互模式天然适合 SSE。你提交一个生图请求，服务端不可能瞬间返回图片，它要排队、要推理、要后处理。如果做成普通 HTTP，客户端要么一直等着（容易超时），要么轮询查状态（浪费请求）。SSE 让服务端在任务完成时主动推结果，客户端只管挂着连接，效率高得多。

腾讯混元生图提供了云托管方式，意味着你不需要自己部署模型，拿一个服务地址和凭证就能用。这对个人开发者和小团队很友好。它的 SSE 接口通常包含几个阶段：连接建立、任务提交确认、进度推送、结果推送、连接关闭。每个阶段对应不同的事件类型，我们在配置 MCP 连接器时要把这些事件类型映射到 WorkBuddy 能理解的动作上。

3. 配置文件 mcp.json 的字段逐个拆解

3.1 mcp.json 的整体结构

WorkBuddy 通过一个叫mcp.json的配置文件来管理所有 MCP 连接器。这个文件通常放在 WorkBuddy 的配置目录下，具体路径因操作系统而异。Windows 一般在用户目录的AppData下，macOS 在~/Library/Application Support下，Linux 在~/.config下。如果你找不到，可以在 WorkBuddy 的设置里搜“MCP”或“配置文件”，通常会有一个“打开配置目录”的按钮。

文件的基本结构是一个 JSON 对象，顶层有一个mcpServers字段，里面每个键是一个连接器的名字，值是这个连接器的配置。名字你可以随便起，但建议起得有意义，比如hunyuan-image，方便以后在 WorkBuddy 里识别。

{ "mcpServers": { "hunyuan-image": { "type": "sse", "url": "https://your-hunyuan-endpoint/sse", "headers": { "Authorization": "Bearer YOUR_TOKEN" }, "timeout": 120000, "retry": { "maxAttempts": 3, "delayMs": 2000 } } } }

上面是一个最小可用的 SSE 连接器配置。type指定传输方式，SSE 就写sse。url是服务端的 SSE 端点地址。headers里放认证信息，通常是 Bearer Token。timeout是单次请求的超时时间，单位毫秒，生图任务耗时长，我设了 120 秒。retry是重试策略，网络抖动时自动重连。

3.2 认证字段的坑

认证这块我踩过坑。腾讯混元的云托管服务通常要求你在请求头里带 Token，格式是Authorization: Bearer <token>。但有些服务端实现要求 Token 放在查询参数里，或者用自定义的 Header 名。你得先看服务端的文档确认。

还有一个细节：Token 里如果包含特殊字符，比如+、/、=，在某些 HTTP 客户端里可能被转义，导致认证失败。我遇到过一次，Token 末尾有个=，结果请求发出去变成了%3D，服务端不认。解决办法是把 Token 用 Base64 编码后再放进去，或者确认 WorkBuddy 的 HTTP 客户端是否正确处理了特殊字符。

提示：不要把真实 Token 直接提交到版本控制系统。如果 mcp.json 要共享给团队，用环境变量引用，比如"Authorization": "Bearer ${HUNYUAN_TOKEN}"，然后在系统环境变量里设置实际值。

3.3 超时和重试参数的取舍

超时时间设多少合适？这取决于你的生图任务平均耗时。我实测下来，一张 1024x1024 的图，从提交到返回大约 15 到 40 秒，高峰期可能到 60 秒。所以超时设 120 秒比较稳妥，留了足够的缓冲。

但超时不是越长越好。如果服务端真的挂了，你设 600 秒，WorkBuddy 就会傻等 10 分钟才报错，体验很差。我的经验是设成“平均耗时 × 3”，既能覆盖长尾情况，又不会等太久。

重试策略也要注意。SSE 连接断开后重连，如果服务端不支持断点续传，重连意味着任务要重新提交，可能产生重复扣费。所以重试次数不宜多，我设了 3 次，每次间隔 2 秒。如果 3 次都失败，说明不是偶发问题，该人工介入排查了。

3.4 事件类型映射

MCP 连接器需要知道服务端推送的每种事件对应什么含义。有些 WorkBuddy 版本支持在配置里显式声明事件映射，有些不支持，靠连接器代码内部处理。如果支持，配置大概长这样：

{ "eventMapping": { "task_created": "acknowledge", "progress": "update", "result": "complete", "error": "fail" } }

这个映射告诉 WorkBuddy：收到task_created事件时，标记任务已受理；收到progress时，更新进度；收到result时，任务完成；收到error时，任务失败。如果你的 WorkBuddy 版本没有这个字段，跳过即可，不影响基本功能。

4. 从零开始接入的完整实操流程

4.1 准备工作：拿到服务端地址和凭证

第一步是确认你有一个可用的腾讯混元生图云托管服务。通常你需要在服务商的控制台创建一个实例，拿到两个关键信息：SSE 端点 URL 和访问 Token。端点 URL 一般长这样：https://api.example.com/v1/hunyuan/image/sse，Token 是一串长字符串。

拿到之后，先用命令行工具验证一下服务是否可达。我用的是curl，它能直接看到 SSE 流的原始输出，方便排查问题：

curl -N -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: text/event-stream" \ https://your-endpoint/sse

-N参数关闭 curl 的缓冲，让输出实时显示。如果服务正常，你会看到类似这样的输出：

event: connected data: {"session_id":"abc123"} event: progress data: {"percent":10}

如果卡住不动，或者报 401、403，说明认证有问题；如果报连接超时，说明网络或地址有问题。这一步能过，后面就顺了。

4.2 编写 mcp.json 配置

确认服务可达后，打开 WorkBuddy 的配置目录，找到或创建mcp.json。把前面那个配置模板填进去，替换成你自己的 URL 和 Token。保存后重启 WorkBuddy，或者如果有“重新加载配置”的选项，点一下。

重启后，在 WorkBuddy 的 MCP 管理界面应该能看到你新加的连接器，状态显示为“已连接”或“可用”。如果显示“连接失败”，先检查 JSON 格式有没有语法错误，比如多了个逗号、少了引号。JSON 对格式很严格，一个字符错了整个文件都解析不了。

注意：修改 mcp.json 后一定要重启 WorkBuddy 或重新加载配置，热更新不一定生效。我遇到过改了配置没重启，折腾半天以为配置写错了，其实是没生效。

4.3 测试连接器是否真正可用

配置显示“已连接”不代表功能正常。有些连接器只是 TCP 层连上了，但 MCP 协议层握手失败。真正的测试是让 WorkBuddy 调用一次生图工具。

在 WorkBuddy 的对话界面输入类似“帮我生成一张猫在草地上晒太阳的图片”的指令。如果连接器工作正常，WorkBuddy 会识别出这是一个生图任务，调用你配置的 MCP 工具，然后返回图片链接或直接显示图片。

如果没反应，检查 WorkBuddy 的日志。日志通常在配置目录下的logs文件夹里，找最新的那个文件，搜“mcp”或“sse”关键词。常见错误有“tool not found”（工具没注册成功）、“invalid response”（返回格式不符合 MCP 规范）、“timeout”（超时）。

4.4 参数传递的细节处理

生图任务通常需要传几个参数：提示词、图片尺寸、生成数量、风格等。MCP 连接器要把 WorkBuddy 传来的参数转成服务端要求的格式。这里有个容易出问题的地方：参数名不一致。

比如 WorkBuddy 内部可能用prompt表示提示词，但腾讯混元的接口要求字段名叫text或input。你需要在连接器配置里做映射，或者在 WorkBuddy 的工具定义里直接写服务端要求的参数名。

如果 WorkBuddy 支持自定义工具 schema，可以这样定义：

{ "tools": [ { "name": "generate_image", "description": "根据文字描述生成图片", "parameters": { "type": "object", "properties": { "prompt": { "type": "string", "description": "图片描述文字" }, "size": { "type": "string", "enum": ["1024x1024", "768x768"], "default": "1024x1024" } }, "required": ["prompt"] } } ] }

这样 WorkBuddy 就知道调用generate_image时要传prompt和可选的size，连接器再把这些参数转成服务端格式。

5. 调试过程中遇到的典型问题和排查方法

5.1 连接建立后立刻断开

这是最常见的现象。WorkBuddy 显示“已连接”，但一调用工具就报“连接已关闭”。原因通常是服务端在握手阶段就拒绝了请求，但错误信息没有正确传递到客户端。

排查方法：用 curl 手动连一次，看服务端返回什么。如果 curl 也立刻断开，说明是服务端问题，可能是 Token 过期、IP 白名单限制、或者服务端要求特定的 Header。如果 curl 正常但 WorkBuddy 断开，说明是 WorkBuddy 的 HTTP 客户端配置问题，比如它没发送Accept: text/event-stream头。

我遇到过一次，服务端要求User-Agent必须是特定值，WorkBuddy 默认的 User-Agent 被拒绝了。解决办法是在 mcp.json 的 headers 里手动加上"User-Agent": "WorkBuddy/1.0"。

5.2 事件解析失败

服务端推送的数据格式和 WorkBuddy 期望的不一致时，会出现“事件解析失败”或“无效的 JSON”错误。SSE 的data:字段里必须是合法 JSON，如果服务端推的是纯文本或格式错误的 JSON，客户端就解析不了。

排查方法：用 curl 抓原始流，把data:后面的内容复制出来，用 JSON 校验工具检查。如果确实不是 JSON，看服务端文档有没有说明格式，或者联系服务端开发者确认。

还有一种情况是编码问题。如果服务端返回的 JSON 里有中文，但没声明 UTF-8 编码，客户端可能按 Latin-1 解析，导致乱码。解决办法是在请求头里加Accept-Charset: utf-8，或者确认服务端响应头里有Content-Type: text/event-stream; charset=utf-8。

5.3 空闲超时导致连接中断

热搜里那个stream disconnected before completion: idle timeout waiting for SSE就是这个问题。生图任务在排队阶段可能几十秒没有数据推送，中间的网络设备（路由器、负载均衡、代理）认为连接空闲了，就把它掐断。

解决办法有两个方向。一是让服务端定期发送心跳事件，比如每 15 秒推一个event: heartbeat，保持连接活跃。这需要服务端配合，你控制不了的话就走第二个方向。二是在客户端配置里加心跳检测和自动重连。WorkBuddy 如果支持keepAlive配置，设一个小于超时时间的间隔：

{ "keepAlive": { "intervalMs": 15000, "message": "ping" } }

这样 WorkBuddy 每 15 秒往连接里写一个 ping，中间设备看到有数据流动就不会断。如果 WorkBuddy 不支持这个配置，那就只能缩短超时时间，让任务在超时前完成，或者把大任务拆成小任务。

5.4 工具调用成功但结果没返回

有时候 WorkBuddy 日志显示工具调用成功了，但界面上没显示图片。这通常是结果解析的问题。服务端返回的图片可能是一个 URL，也可能是一段 Base64 编码的数据。WorkBuddy 需要知道怎么处理这个返回值。

如果返回的是 URL，WorkBuddy 应该能直接显示或下载。如果返回的是 Base64，可能需要连接器把它转成临时文件或 Data URI。检查服务端返回的result事件里，image_url字段是 URL 还是 Base64 字符串。如果是 Base64 且没有data:image/png;base64,前缀，WorkBuddy 可能识别不了。

5.5 常见问题速查表

6. 几个让连接更稳的实战技巧

6.1 用幂等键避免重复生图

生图是要花钱的，重复提交就是重复扣费。SSE 连接不稳定时，WorkBuddy 可能重试，服务端如果没做幂等处理，就会生成多张图。解决办法是在请求里带一个唯一的request_id，服务端看到相同的request_id就返回已有结果，不重新生成。

这个request_id可以由 WorkBuddy 生成，也可以由连接器生成。如果 WorkBuddy 支持在工具调用时传自定义参数，加一个idempotency_key字段。如果不支持，就在连接器代码里根据提示词和时间戳生成一个哈希值作为键。

6.2 日志分级，方便定位问题

WorkBuddy 的日志默认可能只记录错误，调试时你需要更详细的信息。如果支持日志级别配置，把它设成debug或verbose，这样能看到每次请求的完整 URL、Header、请求体，以及每次响应的原始数据。

但 debug 日志量很大，长期开着会影响性能，也占磁盘。我的做法是平时用info级别，出问题时临时切到debug，问题解决后切回来。如果 WorkBuddy 不支持动态调整，就在 mcp.json 里加一个logLevel字段，重启生效。

6.3 给连接器加一个健康检查

WorkBuddy 启动时不会自动检查每个 MCP 连接器是否可用，你得手动触发一次调用才知道。如果连接器很多，逐个测试很麻烦。可以在配置里加一个健康检查端点，WorkBuddy 启动时自动 ping 一下。

健康检查的实现很简单：服务端暴露一个/health路径，返回 200 和{"status":"ok"}。WorkBuddy 在加载连接器时请求这个路径，通了就标记为可用，不通就标记为不可用并给出提示。这样你一眼就能看出哪个连接器有问题。

6.4 处理服务端限流

云服务通常有 QPS 限制，比如每秒最多 10 个请求。如果你短时间内提交大量生图任务，会被限流，返回 429 状态码。WorkBuddy 的重试策略如果没考虑 429，可能会一直重试，反而加重限流。

正确的做法是：遇到 429 时，读取响应头里的Retry-After字段，等指定时间后再重试。如果服务端没返回这个头，就用指数退避，第一次等 1 秒，第二次等 2 秒，第三次等 4 秒，以此类推。在 mcp.json 里可以配置退避策略：

{ "retry": { "maxAttempts": 5, "backoff": "exponential", "initialDelayMs": 1000, "maxDelayMs": 30000 } }

6.5 跨平台路径问题

mcp.json 的路径在不同操作系统下写法不同。Windows 用反斜杠\，macOS 和 Linux 用正斜杠/。如果你在配置里写了绝对路径，换系统后可能找不到文件。建议用相对路径，或者用环境变量。

WorkBuddy 通常支持在配置里引用环境变量，比如"${HOME}/config/mcp.json"。这样在不同机器上只要环境变量设置对了，配置就能通用。如果 WorkBuddy 不支持环境变量，那就每个系统单独维护一份配置，虽然麻烦但稳妥。

7. 这套方案还能怎么扩展

接完腾讯混元生图之后，我发现这套 MCP + SSE 的模式可以复用到很多场景。比如接一个语音合成服务，把文字转成音频；接一个翻译服务，实时翻译长文本；接一个数据查询服务，让 WorkBuddy 直接查数据库返回结果。只要服务端支持 SSE，配置文件的骨架基本不用大改，换 URL、Token 和事件映射就行。

如果你想让连接器更智能，可以在 WorkBuddy 侧加一层参数预处理。比如用户说“生成一张适合做公众号封面的图”，连接器自动把尺寸设成 900x383，风格设成“简洁商务”。这需要在工具定义里加一些默认值和条件逻辑，WorkBuddy 如果支持自定义脚本就能做，不支持的话就在服务端做。

还有一个方向是把多个 MCP 连接器串起来。比如先生图，再把图传给一个 OCR 服务提取文字，最后把文字传给翻译服务。WorkBuddy 如果支持工作流编排，可以把这几个连接器按顺序调用，形成一个自动化流水线。这比单个连接器的价值大得多，也是我接下来打算尝试的方向。

最后分享一个小技巧：调试 SSE 连接时，在服务端加一个“回声”事件，客户端发什么它就原样推回来。这样你能确认连接是双向通的，排除单向网络问题。虽然 SSE 名义上是单向的，但通过额外的 HTTP 请求可以实现双向通信，回声测试能帮你快速定位问题出在哪一侧。