企业官网建设流程全解析

1. 从 22 次点击到一句话：意图驱动交互到底卡在哪

如果你做过 To B 或复杂工具类产品的前端，大概率遇到过这种反馈：用户说“我就想查个数据，为什么要跳五个页面”。传统 GUI 的交互路径是产品经理提前画死的，功能越堆越多，路径就越长，体验熵只增不减。AI Agent 看起来是解药——用户说一句话，Agent 自己调工具把事办了。但真把 Agent 接到生产环境，你会发现三个致命问题：意图解析不稳定、执行边界模糊、过程完全黑盒。用户不敢用，因为不知道 Agent 下一秒会干什么。

这就是 AI Agent Harness Engineering 要解决的事。它不是让 Agent 更聪明，而是在用户、Agent、第三方服务之间加一层“管控 + 编排 + 状态同步”的中间层。对 UI/UX 来说，这层 Harness 才是新范式的真正载体：界面不再负责“功能操作映射”，而是负责“意图对齐协作”。用户输入自然语言或多模态意图，Harness 负责解析、校验、编排、拦截、反馈，前端只做四件事——收意图、补信息、看进度、做干预。

这篇不聊空泛的设计趋势，直接给你一套可复制的配置骨架：用settings.json和config.toml把代理编排层跑起来，通过 TaoToken 统一 Key/API 通道接入模型，再写一个最小前端联调验证意图驱动交互的完整链路。适合正在做 Agent 产品的前端、全栈和 AI 应用开发者，跟着配就能在本地跑通。

2. 前置准备：TaoToken 统一 Key 与代理编排层的关系

在 Harness 架构里，代理编排层需要频繁调用模型做意图解析、约束校验、结果整理。如果每个 Agent 各自管一套 Key，配置会散落在十几个文件里，联调时根本不知道哪个请求走了哪条通道。我的做法是统一走 TaoToken 的 API 通道，一个 Key 覆盖模型对话和后续的 coding 场景，Harness 层只认一个base_url和一个环境变量。

TaoToken 在这里的角色是统一接入层，不是替代你的编排逻辑。你仍然自己写 Harness 的意图解析和工具调度，只是把模型请求的出口收敛到一处。这样做的直接好处是：前端联调时只需要确认一个通道是否通，排障范围从“N 个 Agent 的 N 套配置”缩小到“一个 base_url + 一个 Key”。

你需要准备的东西不多：一个 TaoToken 账号、一个 API Key、本地 Node 或 Python 环境。Key 在控制台的 API Keys 页面创建，建议按项目建独立 Key，方便后续按 Key 维度看调用量。创建入口在这里：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_utm_medium=csdn&utm_campaign=rewrite&utm_content=apikeys 。注意 API 地址不带 UTM，配置里统一写https://taotoken.net/api。

提示：Harness 层不要硬编码 Key，全部走环境变量。前端联调阶段最容易犯的错就是把 Key 写进settings.json提交到仓库，后面换 Key 要改一堆文件。

3. 可复制配置：settings.json 与 config.toml 骨架

下面这套配置分两部分：settings.json管 Harness 运行时的行为参数，config.toml管模型通道和 Agent 编排声明。两个文件放在项目根目录，Harness 启动时读取。

3.1 settings.json：Harness 运行时骨架

{ "harness": { "version": "0.1.0", "intent": { "parser_model": "gpt-4o-mini", "temperature": 0, "max_retry": 2, "required_fields": ["action", "target", "constraints"], "fallback_prompt": "我没听懂你的需求，你可以试着这样说：帮我查一下上周的订单数据" }, "guard": { "enable_constraint_check": true, "max_budget": 10000, "blocked_actions": ["delete_database", "drop_table", "send_mass_email"], "require_confirm": ["write_file", "execute_shell"] }, "orchestration": { "max_steps": 8, "step_timeout_ms": 15000, "parallel_tools": false, "state_sync_interval_ms": 500 }, "ui_bridge": { "channel": "websocket", "port": 8787, "event_types": ["intent_parsed", "need_input", "executing", "need_select", "finished", "error"] } } }

几个参数值得单独说。required_fields决定 Harness 在意图解析后检查哪些字段缺失，缺了就通过ui_bridge推need_input事件给前端弹补全卡片。blocked_actions是硬拦截，Agent 一旦生成这类动作直接终止并推error。require_confirm是软拦截，推need_select让用户确认。state_sync_interval_ms控制进度同步频率，设太小会刷屏，设太大用户觉得卡，500ms 是实测比较舒服的值。

3.2 config.toml：模型通道与 Agent 声明

[model] provider = "taotoken" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" default_model = "gpt-4o-mini" timeout_seconds = 30 [model.models] intent_parser = "gpt-4o-mini" result_summarizer = "gpt-4o-mini" code_agent = "claude-3-5-sonnet" [agents.travel] name = "差旅助手" description = "处理机票、酒店、接送机编排" tools = ["search_flight", "search_hotel", "book_flight", "book_hotel"] guard_profile = "default" [agents.data_query] name = "数据查询助手" description = "查询订单、客户、报表数据" tools = ["query_orders", "query_customers", "export_report"] guard_profile = "readonly" [guard_profiles.default] max_budget = 10000 blocked_actions = ["delete_database", "drop_table"] require_confirm = ["write_file", "execute_shell"] [guard_profiles.readonly] max_budget = 0 blocked_actions = ["write_file", "execute_shell", "delete_database"] require_confirm = []

config.toml的核心是把“模型通道”和“Agent 编排”分开声明。[model]段只认 TaoToken 的base_url，所有模型请求都从这里出。[agents.*]段声明每个 Agent 能用哪些工具、走哪个 guard profile。这样前端联调时，你改guard_profiles就能模拟不同权限下的交互表现，不用动 Harness 代码。

环境变量这样设：

export TAOTOKEN_API_KEY="你的Key"

如果你用 Python 读配置，可以这样加载：

import json import os import tomllib with open("settings.json", "r", encoding="utf-8") as f: settings = json.load(f) with open("config.toml", "rb") as f: config = tomllib.load(f) api_key = os.environ.get(config["model"]["api_key_env"]) base_url = config["model"]["base_url"]

4. 验证请求：跑通意图解析到前端联调

配置写完，先别急着写完整前端。用一个最小脚本验证三件事：模型通道通不通、意图解析能不能出结构化结果、Harness 能不能把状态推给前端。

4.1 验证模型通道

import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url="https://taotoken.net/api" ) resp = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "只输出JSON，不要解释"}, {"role": "user", "content": "帮我查一下上周的订单数据，按地区分组"} ], temperature=0 ) print(resp.choices[0].message.content)

跑通会看到类似这样的结构化输出：

{"action": "query_orders", "target": "last_week", "constraints": {"group_by": "region"}}

这一步通了，说明 TaoToken 通道和 Key 都没问题。如果报 401，检查环境变量名是否和config.toml里的api_key_env一致；如果报模型不存在，检查default_model是否拼写正确。

4.2 验证 Harness 状态推送

用一个极简 WebSocket 服务模拟 Harness 推事件给前端：

import asyncio import json import websockets async def handler(websocket): events = [ {"type": "intent_parsed", "data": {"action": "query_orders"}}, {"type": "executing", "data": {"step": "query_orders", "progress": 0.5}}, {"type": "finished", "data": {"rows": 128, "summary": "上周订单共128条"}} ] for evt in events: await websocket.send(json.dumps(evt)) await asyncio.sleep(0.5) async def main(): async with websockets.serve(handler, "localhost", 8787): await asyncio.Future() asyncio.run(main())

前端用浏览器控制台验证：

const ws = new WebSocket("ws://localhost:8787"); ws.onmessage = (e) => { const evt = JSON.parse(e.data); console.log("Harness 事件:", evt.type, evt.data); };

你会依次看到intent_parsed、executing、finished三个事件。这就是意图驱动交互的最小闭环：用户输入意图，Harness 解析后推状态，前端根据事件类型渲染补全卡片、进度条或结果总览。实测下来，把state_sync_interval_ms设成 500，进度条动画最顺滑。

4.3 验证约束拦截

把settings.json里的max_budget改成 100，再发一个预算 5000 的请求，Harness 应该在 Agent 执行前就推error事件，而不是等 Agent 跑完才报错。这个“校验左移”是 Harness 和纯 Agent 方案的核心区别，也是 UI 上“提前拦截”体验的技术基础。

5. 本篇常见错排查

报错一：openai.AuthenticationError: 401

九成是环境变量没生效。先echo $TAOTOKEN_API_KEY确认有值，再检查config.toml里api_key_env写的是不是TAOTOKEN_API_KEY。如果你在 IDE 里跑，注意 IDE 的终端环境变量和系统终端可能不一致，建议在项目根目录放.env并用python-dotenv加载。

报错二：websockets.exceptions.ConnectionClosedError

前端连不上 8787 端口。先确认 WebSocket 服务真的在跑，再检查端口有没有被占用。Mac 上 8787 有时被其他服务占用，换成 8790 试试。另外注意settings.json里的ui_bridge.port要和实际启动端口一致，改了一处忘了另一处是高频错误。

报错三：意图解析返回的不是 JSON

模型偶尔会加“好的，这是解析结果：”这类前缀。两个办法：一是把temperature设成 0，二是在 system prompt 里加“只输出JSON，第一个字符必须是{”。如果还不行，在 Harness 里加一层json.loads的 try-catch，失败就重试，max_retry设 2 次基本能兜住。

报错四：guard_profiles不生效

检查config.toml里 Agent 声明的guard_profile名字和[guard_profiles.*]段名是否完全一致，TOML 对大小写敏感。另外blocked_actions里的动作名要和 Agent 实际生成的 action 字段完全匹配，差一个下划线就拦不住。

报错五：前端收到事件但渲染错乱

大概率是事件顺序问题。Harness 推事件是异步的，前端不能假设executing一定在intent_parsed之后到达。建议前端用一个状态机管理事件，每个事件带seq序号，乱序到达时按序号排序再渲染。

6. 下一步：把 Harness 接到真实编码场景

本地跑通意图解析和状态推送后，下一步是把 Harness 接到真实的编码或 Agent 场景。如果你要做长期编码类 Agent，建议直接上 Coding Plan，它把模型通道、额度、常用编码模型都配好了，你只需要专注 Harness 的编排逻辑：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=codingplan 。接入文档在这里，里面有完整的 base_url 和参数说明：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc 。

如果你只是想先验证模型对话和意图解析效果，可以直接在模型对话页面试：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=chat 。控制台看调用量和 Key 管理：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console 。

回到 UI/UX 范式这个问题：Harness Engineering 带来的不是又一个组件库，而是交互起点的迁移。以前设计师画的是“用户从 A 页面到 B 页面怎么走”，现在要画的是“用户意图不完整时怎么补、Agent 执行中怎么让用户放心、异常时怎么让用户一键干预”。这套配置骨架只是起点，真正的设计工作量在意图对齐卡片、进度反馈组件和干预入口的细节上。先把通道跑通，再慢慢磨交互。