企业官网建设流程全解析

我最近把一个想法从零做到了能稳定跑的状态，整个过程里写代码的时间其实不算多，真正花时间的是把平台上几个抽象概念搞清楚，以及一遍遍打磨，让 Agent 的回复不那么“AI味”。

这个想法很简单：我有个独立站，每天都会收到大量重复咨询，比如“我的订单到哪里了”“怎么退款”“发票怎么开”。以前我靠复制粘贴话术硬扛，后来实在扛不住，决定把这些重复劳动交给一个 Agent 应用。最后我在 WorkBuddy 开放平台上，用“个人开发者”身份，从注册账号到发布上线，完整做了一个叫 OrderHelper 的订单咨询 Agent。用户问题进来，它先判断意图，再决定是直接回复、查询订单、还是转给人工，整个过程可以通过开放平台 API 暴露给我自己的网站使用。

这篇文章就是那次接入的完整记录，适合两类人看：一是想接入 WorkBuddy 开放平台但还没动手的个人开发者；二是正准备做 Agent 应用、但对“Agent、Skill、Workflow 到底怎么配合”还没形成画面感的朋友。我会尽量把每一步为什么这么做也讲清楚，方便你直接照着推演到自己的场景里。

1. 为什么个人开发者应该关注 WorkBuddy 开放平台

1.1 个人开发者做 Agent 的三条路线对比

在决定用 WorkBuddy 开放平台之前，我把目前的路线大致对比了一遍。作为一个独立开发者，没有团队也没有运维时间，选择路线的标准很朴素：能不能在最短时间内把业务逻辑跑通，并且后续维护成本可控。

第一条路线是自己基于开源框架搭一套 Agent 服务。比如用 LangChain 这类工具自己组织模型调用、工具调用、记忆管理，再自己部署模型网关和任务队列。好处是可控性极强，什么都能改，代价是模型调用、会话管理、工具注册、错误重试、日志监控这些都要自己写一遍。一个人做完这些，少说一两周，多则个把月，而且上线之后还得长期维护。这个成本对大部分个人开发者来说并不低。

第二条路线是用低代码平台直接配置一个聊天机器人。上手很快，界面里拖拖拽拽就能出来一个能对话的东西。但这类方案的问题在于：如果你打算把 Agent 能力嵌进自己的网站或业务系统，往往只能依赖平台方提供的固定组件，扩展空间比较有限。尤其遇到需要自定义工具调用、自定义接口返回格式的业务，会非常别扭。

第三条路线就是 WorkBuddy 开放平台这类“开放平台式接入”。平台把模型调用、会话管理、工具调用、发布出口都封装好了，开发者把重点放在业务定义上：先创建一个 Agent，给它写好人设和规则，再挂上需要的 Skill，最后通过开放平台 API 对外提供服务。对比下来，这条路线的启动成本低，发布能力也完整。我最终选它，核心原因就是我可以把精力放在业务逻辑和话术打磨上，而不是去处理基础设施。

三条路线的差异我简单整理了一张表：

1.2 必须先搞懂三个概念：Agent、Skill、Workflow

首次接触 WorkBuddy 开放平台时，文档里出现频率最高的词就是 Agent、Skill 和 Workflow。这三个概念如果不先厘清，后面配置起来会非常混乱。我用一个比较生活化的方式理解它们：Agent 相当于你雇的一个员工，Skill 是员工手里的工具和作业标准，Workflow 则是员工处理复杂任务时的标准作业流程。

Agent 是面向用户的核心入口，它承担角色设定、模型选择、上下文记忆管理。你告诉它“你是订单咨询助理”，并给它一套行为规则，它就会按照这套规则来理解用户输入并组织回复。Agent 本身可以不依赖任何 Skill 工作，只做问答也行，但那样它就只能“动嘴”，不能“动手”。

Skill 是可复用的能力模块，本质上是传统开发里的一个函数或插件。比如我要做一个订单查询功能，就把“输入订单号，调用订单系统接口，返回订单状态”封装成一个 Skill。Agent 在对话中判断用户需要查询订单时，就会自动调用这个 Skill，再把 Skill 返回的结果整理成自然语言回复。Skill 做得好不好，直接决定了 Agent 在需要落地动作时的可靠程度。

Workflow 则是把多个 Skill 按顺序编排成一条流水线。如果业务逻辑是固定的，比如“先查订单状态，如果已发货则查询物流轨迹，再生成回复”，就可以用 Workflow 把这两个 Skill 串起来。Workflow 适合流程稳定、分支明确的场景；如果场景比较发散，比如用户可能问订单、可能问退款、可能问发票，那更适合让 Agent 自己判断调用哪个 Skill，而不是硬编码流程。

顺带提一句，WorkBuddy 有面向不同行业的版本封装，比如金融版这类行业版本会预置一些通用 Skill 和模板。作为个人开发者，起步阶段直接用通用标准版就够了，等业务场景成熟后再考虑是否需要行业版能力。

2. 接入前的准备工作：账号、凭证与基础环境

2.1 注册开发者账号与实名认证

接入 WorkBuddy 开放平台的第一步，是注册开发者账号并完成实名认证。这个流程和大多数平台一致，但我个人建议在申请时就确认清楚主体类型：个人开发者选“个人主体”，企业开发者选“企业主体”。个人主体的认证流程通常快一些，一般是提交身份信息后等待平台审核，快则几小时，慢则一个工作日。

很多开发者容易忽略的一点是：实名认证信息会和你后续创建的应用绑定，尤其是涉及发布上线、创建正式 API 授权时，主体信息一旦填错会导致审核不通过。我第一次提交时就是没注意身份信息里的姓名填成了昵称，结果被打回一次，白白等了一晚上。所以注册阶段务必仔细核对姓名与证件信息。

完成认证后，进入开发者控制台。控制台首页一般会展示“应用管理”“凭证管理”“数据看板”“日志查询”等入口。对于刚接入的人，主要关注“应用管理”和“凭证管理”两个模块就够了，其他模块等应用上线后再看。

2.2 创建应用并获取 API 凭证

在“应用管理”里新建一个应用，应用类型选择“开放平台接入”，然后填写应用名称、应用简介、回调地址。

回调地址需要注意：如果你的 Agent 应用需要异步通知（比如用户提交了一个耗时操作，平台处理完成后回调你的服务器），这里填写的 URL 必须是公网可访问的 HTTPS 地址。个人开发者如果没有现成的服务器，可以先暂时填一个占位地址，等真正需要回调时再改。

应用创建完成后，进入“凭证管理”模块，可以看到几个核心凭证：

• App ID：应用的唯一标识，类似用户名，可以暴露在前端。
• App Secret：应用密钥，用来签名请求，绝对不能泄漏到前端或公开仓库。
• API Key：调用开放平台接口时使用的认证凭证，可以按需创建和撤销。

这里有个我踩过的坑：刚开始图方便，我把 App Secret 写在了前端代码的配置里，结果调试时浏览器控制台直接就能看到整个密钥。开放平台的很多接口校验是基于 App Secret 做签名，泄漏之后等于任何人都能冒充我的应用调用接口。所以个人开发者也必须养成“密钥只在服务端存放”的习惯，前端只放 App ID，所有带敏感凭证的请求都通过自己的后端转发。

权限配置方面，开发者在控制台按需申请接口权限。我的做法是最小权限原则：只申请了 Agent 对话、Skill 管理、日志查询这三项，用不到的权限一律不开。权限开少了之后可以随时补，但开多了一旦密钥泄漏，攻击者能做的事就更多。

2.3 理解 Agent 配置中的关键参数

拿到凭证后，先别急着写代码。我强烈建议先花半小时在控制台里创建一个测试 Agent，把所有配置项都点一遍，理解每个参数的含义。这里面有几个参数对最终效果影响很大。

第一是模型选择。WorkBuddy 开放平台通常会提供一组默认模型供选择，不同模型在指令遵循能力、中文理解能力、响应速度、成本上差异明显。任务型 Agent（比如订单咨询）不需要太强的创作能力，选一个稳定、便宜、指令遵循好的模型即可；如果你的场景需要大量开放式的文案创作，再考虑更强的模型。

第二是温度参数。温度控制生成内容的随机性，取值范围一般是 0 到 1。我在订单咨询场景里把温度设为 0.2 左右。任务型对话要的是确定性和一致性，如果温度过高，Agent 会对同一个问题给出各种风格完全不同的回答，用户会觉得很不稳定。创意写作场景才需要把温度调高到 0.7 以上。

第三是最大 Token（回复长度）。这个参数限制单次回复的最大字符数。个人开发者很容易忽略它，导致 Agent 有时候长篇大论讲一堆用户已经知道的事。对话式客服场景应该把单次回复控制得尽量短，我的 OrderHelper 单次回复最大 token 设置为 500 左右，足够覆盖大多数订单问题的回答，又不会显得啰嗦。

第四是上下文轮数。这个参数决定 Agent 在多少轮对话内保持记忆。订单咨询这类任务，用户通常会在几轮内把问题说清楚，保留 10 到 20 轮上下文够用了。上下文保留越长，准确率不一定越高，因为超长上下文会稀释重要信息，还会明显增加 token 成本。

3. 从零到一：创建你的第一个 Agent 应用

3.1 先定义输入与输出，再开始配置

很多人在创建 Agent 时容易犯一个错误：一上来就写人设，写了一大段“你是一个温柔的客服”，然后把 Agent 挂上线，结果面对真实用户时输出结构完全不可控。

我的做法是倒过来，先定义清楚输入输出。以 OrderHelper 为例，我先列了一个最小功能矩阵：

把这张表画出来之后，Agent 的人设、Skill 的边界、兜底策略都清晰了。这个步骤花不了多少时间，但能省掉后面大量调参时间。你会发现很多配置，本质上是在把这张表翻译成平台能理解的语言。

3.2 在控制台创建 Agent 并配置基础信息

打开 WorkBuddy 开发者控制台，进入“Agent 管理”，新建一个 Agent。

填写基础信息：名称填“订单咨询助手”，描述填“处理独立站用户的订单状态、物流、退款、发票相关咨询”。描述字段别小看，平台的模型调度会参考这个描述来理解 Agent 的职责，写得太随意会导致模型对场景理解偏差。

接下来是配置人设。我把人设分成了四块：

• 角色：你是一个电商订单助理，服务于独立站用户。
• 行为准则：回答必须基于订单系统返回的真实数据；不得虚构订单状态；用户情绪激烈时优先安抚并转人工。
• 输出要求：在需要输出结构化信息时，必须使用 JSON 格式，包含意图、回复内容、是否需要转人工。
• 兜底规则：当用户问题不在处理范围内，引导用户描述订单号或具体问题。

这里我建议把最重要的约束放在人设开头几句。模型对 prompt 开头的注意力通常高于中间，所以“不得虚构订单状态”这种硬规则，一定要往前放，不要埋在一大段人设的末尾。

完成基础配置后，可以在控制台里直接发起对话测试。不过此时还没有挂任何 Skill，Agent 只能做纯文本问答。这一步的目标是先确认人设是否生效、回复语气是否符合预期，先不要急着加工具。

3.3 编写第一个 Skill：订单查询

Agent 配置完之后，核心工作就是写 Skill。我第一个选择实现的是 query_order，也就是订单查询。这个 Skill 的职责是：接收用户问题中提取出的订单号，调用订单系统接口，返回订单当前状态。

在 WorkBuddy 开放平台里创建 Skill 时，需要填写几个关键信息：

• Skill 名称：一句话说明这个技能是什么。
• Skill 描述：说明何时调用、调用条件、需要哪些信息。这个描述会直接影响模型的工具调用决策，必须写得非常明确。比如我写的是：当用户询问订单状态、物流进度、预计到货时间时调用；如果用户未提供订单号，需要先向用户索要订单号；调用前把订单号整理成字符串格式。
• 输入参数：定义调用时需要的参数列表。我定义了一个必填参数 order_id，类型为 string，描述为“用户提供的订单号，一般是数字序列”。

这里有一个非常关键的细节：Skill 的输入参数描述，不是写给程序看的，是写给模型看的。模型在对话过程中要根据这些描述来决定传什么参数进来。如果描述含糊，比如只写“订单号”三个字，模型在抽取订单号时可能把用户提到的其他数字也当成订单号传进来，导致查询失败。后来我把描述改成“用户消息中与订单相关的数字编号，通常格式为 8 位以上数字”，准确率明显提升。

Skill 的执行逻辑，我写了一个简单的 Python 函数示意：

def query_order(skill_input: dict): order_id = skill_input.get("order_id") # 这里是模拟调用订单系统接口 # 真实场景中替换为你的业务 API 请求 order_status_map = { "20240312001": {"status": "shipped", "logistics": "已到达转运仓", "eta": "2024-03-15"}, "20240312002": {"status": "pending", "logistics": "等待付款确认", "eta": None}, } order_info = order_status_map.get(order_id) if not order_info: return {"found": False, "message": "未查询到该订单，请核对订单号"} return {"found": True, **order_info}

重点不在代码本身，而在返回结构。Skill 返回的数据一定是结构化 JSON，而不是一段写好的文案。这样 Agent 拿到数据后可以结合上下文重新组织语言，回复会更自然。如果 Skill 返回的是一句“您的订单已发货”，那 Agent 就失去了二次加工的余地。

3.4 把 Agent 和 Skill 连接起来

Skill 创建完成后，回到 Agent 编辑页，在“已绑定技能”里选择 query_order，保存并发布到测试环境。

这里我会做一个专门的调试用例集，而不是随机问问题。我的用例集包括以下几条：

• 正常查单：“我的订单 20240312001 到哪里了？”期望输出：查到物流状态和预计时间。
• 缺少参数：“帮我查一下订单。”期望输出：Agent 主动索要订单号，而不是瞎猜一个。
• 参数模糊：“我买的东西发货了吗？”期望输出：Agent 继续追问订单号。
• 不相关问题：“今天天气怎么样？”期望输出：回到业务主题，不调用 Skill。
• 订单不存在：“订单 999999 在哪里？”期望输出：明确提示未找到，并建议核对订单号。

测试时我尤其关注第二条和第三条。模型在缺少参数时，最常见的错误是自己编造一个订单号去查，结果返回“订单不存在”，用户看到的就是一句冷冰冰的失败提示。解决办法是在 Skill 描述里明确写“如果用户没有提供订单号，先向用户索要，不要尝试猜测或编造订单号”，同时在 Agent 人设的兜底规则里也提一句，双重约束后才稳定下来。

调试面板里还有一个非常实用的功能——查看每次工具调用的入参和出参。如果某次对话，Agent 明明应该查单但没查，你就可以回看模型到底有没有触发工具调用、触发时传了什么参数。这比自己通过对话黑盒猜原因高效太多。

3.5 模棱两可场景的处理与兜底

测试一段后，另一个常见问题是：用户表达含糊，模型不知道该不该调用工具。比如“那个 12 号的单子发货了吗”这句话里，“12 号”既可能是订单号的一部分，也可能是下单日期。模型的处理就会不稳定。

针对这类问题，我的做法是把 Skill 的输入参数里加一个可选的 email 或手机号字段，让模型在订单号不明确时继续追问用户，把信息补全。同时在 Agent 人设里加了一条规则：如果在一次对话中无法确认必要参数，不要强行调用工具，先用自己的话向用户确认。

Agent 应用里所谓的“智能”，很多时候并不是模型有多聪明，而是我们在边界场景里把规则写清楚了。模型能做的是在规则内灵活执行，但规则本身必须由开发者一点点补齐。

4. 发布上线与外部系统接入

4.1 从测试环境发布到正式环境

当测试用例集全部通过后，就可以准备发布了。WorkBuddy 开放平台的发布机制通常分为两步：把 Agent 发布到测试环境，再把测试环境的版本申请上线到正式环境。

正式环境的上线会经历一次审核，审核主要看应用场景是否清晰、是否涉及敏感行业、Prompt 是否有诱导性内容等。个人开发者第一次申请时，建议在应用简介里把使用场景写清楚。比如我写的是“用于自己独立站的订单咨询自动回复”，审核很快就通过了。

发布到正式环境后，控制台会生成一个正式环境的 API Endpoint。注意测试环境和正式环境的 Endpoint 是分开的，密钥也建议分开管理，避免在测试阶段误调用正式接口，浪费额度。

4.2 从自己的网站调用 Agent API

在 WorkBuddy 开放平台中，Agent 应用对外提供对话类接口。个人开发者接入时，一般会写一个小后端，把来自自己网站的前端请求转发给开放平台。这样做的好处是：API Key、App Secret 只保存在后端，前端不接触任何敏感凭证。

调用流程通常是先做签名认证，再发起对话请求。签名逻辑大部分平台类似：把 App ID、时间戳、请求体拼接后用 App Secret 做 HMAC 签名，放到请求头里。具体公式以你拿到的文档为准，我在这里给一个示意：

import hashlib import hmac import json import time import requests base_url = "https://api.workbuddy.example.com/v1" app_id = "your_app_id" app_secret = "your_app_secret" timestamp = str(int(time.time())) payload = { "agent_id": "ag_xxxxxxxx", "session_id": "sess_001", "user_id": "user_123", "query": "我的订单 20240312001 到哪里了？", } body = json.dumps(payload, ensure_ascii=False) # 签名计算，具体拼接规则以文档为准 sign_str = f"{app_id}{timestamp}{body}" sign = hmac.new(app_secret.encode(), sign_str.encode(), hashlib.sha256).hexdigest() headers = { "Content-Type": "application/json", "X-App-Id": app_id, "X-Timestamp": timestamp, "X-Sign": sign, } resp = requests.post(f"{base_url}/agent/chat", headers=headers, data=body) print(resp.json())

这里有个个人开发者常忽略的地方：用户身份隔离。一个开放平台 Agent 往往会被多个用户调用，平台一般提供 session_id 或 user_id 来区分不同用户。我的经验是 session_id 按用户维度创建，同一个用户的多轮对话保持同一个 session_id，这样 Agent 才能连续理解上下文。如果每个请求都用随机 session_id，用户前面说过的订单号，后面再提一句“刚才那个订单”，Agent 就完全听不懂了。

4.3 超时与异步处理的取舍

对话类接口通常设计为同步返回，适合大多数问答场景。但如果你在 Skill 里接了很慢的外部服务，比如订单系统平均响应时间超过 2 秒，同步接口的体验就会很糟糕。平台一般会提供异步任务模式：提交请求后立即返回一个 task_id，处理完成后通过回调地址通知你结果。

我的建议是：初期宁可用同步接口加上超时重试，也不要一上来就搞异步回调。异步模式虽然用户体验更好，但回调地址、任务状态查询、超时补偿这些逻辑都要额外处理，对个人开发者来说开发量不小。等调用量和外部接口延迟确实成为问题时，再升级异步方案不迟。

另外，调用时一定要做好超时控制。我在代码里把连接超时设为 3 秒，读取超时设为 15 秒。如果平台响应超时，先查服务端日志确认任务是否处理完成，再决定是否重试，避免同一个请求被重复提交两次，导致用户看到两条回复。

4.4 发布后的数据观察

Agent 应用跑起来之后，我每天会花几分钟看一下控制台里的数据：调用量、平均延迟、失败率、token 消耗。数据看板的价值不只是看数字，它会暴露很多对话测试时发现不了的问题。

比如我上线第一周发现，晚上 8 点到 10 点的平均延迟明显高于白天，因为那段时间正好是用户下单咨询的高峰。另外，失败率曲线里有一波尖刺，点进日志一看是订单系统的一次临时故障，Skill 调用超时被模型判定为查询失败，回复了一堆道歉话术。这提醒我后续有必要在 Skill 执行逻辑里加上“调用失败时返回固定错误码”的处理，让 Agent 能区分“订单不存在”和“系统异常”，给用户更准确的反馈。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

个人开发者接入过程中，遇到的问题其实高度重复。我把几个常见的整理成一张速查表，方便直接对照：

其中 Skill 没被调用这个问题，个人开发者最容易忽略。平台模型判断是否调用 Skill，主要依赖 Skill 描述和输入参数描述。我遇到过一个问题：Skill 描述写的是“查询订单”，模型确实在用户问订单时调用了一次，但后来我在描述里补充了“如果用户未提供订单号，先追问用户”，调用率才真正稳定下来。描述写得越具体，模型的行为越可控。

5.2 实战中总结的几条经验

第一，Prompt 里要把“输出格式”钉死。刚开始使用开放平台时，我对 Agent 的回复格式没有要求，结果同样是查单成功的场景，有时候回复长句，有时候回复短句，用户看起来很不统一。后来我在人设里加上“查单成功时，回复必须包含订单号、物流状态、预计时间三个信息，按短句输出”，效果立刻稳定。结构化输出能省掉后面大量的解析和清洗工作。

第二，Skill 输入参数的描述，值得花时间反复打磨。模型不是程序员，它不会按照“传入正确类型的参数”这种工程思维来工作。它需要的是自然语言层面的引导。在 query_order 这个 Skill 里，我一开始的参数描述是“订单号”，后来改成“用户消息中与订单相关的数字编号，通常是一串数字，如果用户没有提供请先让用户提供，不要猜测”。改动之后，参数抽错率明显下降。

第三，个人开发者的免费额度要精打细算。模型调用成本虽然不高，但高频场景累积下来也不容小觑。我的优化思路有三个：一是把上下文轮数控制在合理范围，不需要无限记忆；二是为常见问题设计“快捷回复”逻辑，命中固定模式时不调用模型生成，直接返回模板；三是定期查看日志，把高频问题抽出来沉淀成固定话术。这样既省 token，又提升了响应速度。

第四，每次修改前备份一个版本。平台通常支持保存多个 Prompt 版本，但我建议修改前自己也在本地留一份文本。有几次我调 Prompt 调了一个小时，越调越差，最后想回到最初的版本，结果发现平台历史版本列表里只保留了三次，最初的版本早就被覆盖了。从那之后我就养成了本地备份的习惯。

第五，给 Agent 设计好“说不出来”的兜底。用户不可能都按预设路径提问。有人会发“你好”，有人会发“？？？”，有人会直接开骂。如果 Agent 对这类输入没有兜底策略，很可能给出莫名其妙或者机械重复的回复。我在人设里加了一条规则：如果用户输入与业务主题无关或信息不足，先礼貌说明自己能处理的问题范围，并引导用户提供订单号或选择常见问题入口。

5.3 从第一个 Agent 到更多场景的扩展

OrderHelper 上线稳定运行一周后，我开始考虑扩展。最自然的扩展方向是退款场景：用户申请退款时，Agent 需要先核查订单状态，再判断是否允许退款，最后生成退款单。这个流程已经不是一个 Skill 能搞定的，因为有几处固定分支，更适合用 Workflow 编排：查单、走退款判断、通知用户。

我现在把 WorkBuddy 开放平台上的这套架构理解为“搭积木”：Agent 是外壳，Skill 是积木块，Workflow 是拼装图纸。个人开发者完全可以从一个小积木开始，先做一个只解决单一问题的 Agent，跑顺之后再慢慢往上面加 Skill 和流程。每加一块，都要回到调试用例集里反复验证，避免新的能力影响旧场景的表现。

这次接入给我最大的感触是：平台解决的是“跑起来”的问题，但“跑得好”仍然取决于开发者对业务的理解。模型能力再强，如果 Prompt 含糊、Skill 边界不清、兜底策略缺失，最终交付给用户的依然是一个不稳定的体验。反过来，只要把业务规则梳理清楚，把每个边界场景都验证一遍，一个个人开发者完全可以在几天内做出一个可靠的 Agent 应用。

如果你也准备做自己的第一个 Agent，我的建议很简单：挑一个每天高频出现的重复问题，把它接进去，哪怕只解决一种问题，你的业务也算真正开始自动化了。我下一步打算给 OrderHelper 接上退款进度跟进的 Workflow，等验证完再写一篇流程编排的实战记录。