1. Agent Harness 单元测试跑通了，为什么真实 LLM 调用还是翻车
Agent Harness 是一类把 Agent 拆成 Agent Core、Tool Registry、Memory Store、Planner、Executor、Observer 等模块的开发框架，适合用 Python + pytest 做单元测试的团队。它的单元测试有个天然矛盾：LLM 输出随机、外部 API 依赖不稳定，所以大家都会用 Mock 把 LLM Client 和工具调用全部替换掉。Mock 让测试快、稳、可重复，但也带来一个盲区——所有用例都绿了，真实链路却可能因为 Base URL 写错、Key 没生效、请求格式不对而直接失败。
我试过在 Agent Harness 项目里只跑 Mock 用例，覆盖率报告很漂亮，结果把 LLM Client 切到真实通道时，返回体解析直接抛异常，因为 Mock 里我手写的 JSON 结构和真实响应字段对不上。这类问题单元测试永远发现不了，必须额外做一次真实调用验证。
这篇就按这个思路写：先按常规方式把 pytest Mock 用例写好，保证 Agent Core、Tool Registry、Memory Store 的逻辑被锁定；然后单独加一个“验证用量”的步骤，把 LLM Client 的 Base URL 指向 TaoToken，用同一个 Key 跑通一次真实请求，确认返回结果和 Token 消耗记录都正常。这样既不干扰单元测试里的 Mock 逻辑，又能补上“Mock 全过、真实调用却失败”的盲区。
2. 前置准备：TaoToken Key 与 LLM Client 配置
TaoToken 在这里的角色是验证用的模型通道。你不需要改单元测试里的任何 Mock，只需要在验证脚本或集成测试里，把 LLM Client 的请求地址和 Key 换成 TaoToken 的配置。
打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建账号并生成 Key。创建完成后，在控制台复制 Key，后面配置里会用到。Base URL 填https://taotoken.net/api，注意这里不加/v1，也不带任何 UTM 参数。很多 OpenAI 兼容客户端默认会在 Base URL 后面拼/v1/chat/completions，如果你填了带/v1的地址，最终路径就会变成/v1/v1/chat/completions，直接 404。
Key 的管理入口在 API Keys 页面，接入文档在 doc 页面，模型对话验证在模型对话页面。如果你后面要做长期编码或 Agent 任务，可以看 Coding Plan；如果只是验证链路，用按量 Key 就够了。
配置时建议把 Key 放在环境变量里，不要硬编码进测试文件：
export TAOTOKEN_API_KEY="你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"这样单元测试和验证脚本可以共用同一套环境变量，Mock 用例不会去读它，只有真实调用验证时才读取。
3. 可复制配置：LLM Client 指向 TaoToken
假设你的 Agent Harness 里有一个llm_client.py，原本指向外部 API。我们把它改成可配置的 Base URL，默认走 Mock，验证时走 TaoToken。
# src/agent_harness/llm_client.py import os import json import requests from typing import Optional class LLMClient: def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None): self.api_key = api_key or os.getenv("TAOTOKEN_API_KEY") self.base_url = base_url or os.getenv("TAOTOKEN_BASE_URL", "https://taotoken.net/api") self.model = "gpt-4o-mini" def generate(self, prompt: str, temperature: float = 0.0) -> str: url = f"{self.base_url}/chat/completions" headers = { "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json", } payload = { "model": self.model, "messages": [{"role": "user", "content": prompt}], "temperature": temperature, } resp = requests.post(url, headers=headers, json=payload, timeout=30) resp.raise_for_status() data = resp.json() return data["choices"][0]["message"]["content"]注意url的拼接方式：base_url是https://taotoken.net/api，后面直接接/chat/completions，最终请求地址是https://taotoken.net/api/chat/completions。如果你用的 SDK 会自动补/v1，那就把 Base URL 保持为https://taotoken.net/api，让 SDK 去拼。
单元测试里继续用 Mock，不受影响：
# tests/unit/test_agent_core.py from unittest.mock import MagicMock from src.agent_harness.agent_core import AgentCore from src.agent_harness.llm_client import LLMClient def test_process_direct_response(): mock_llm = MagicMock(spec=LLMClient) mock_llm.generate.return_value = '{"response": "你好，我是智能客服"}' mock_memory = MagicMock() mock_memory.search.return_value = [] agent = AgentCore(llm_client=mock_llm, memory_store=mock_memory) result = agent.process("你好") assert result["response"] == "你好，我是智能客服" mock_llm.generate.assert_called_once()这段用例不碰网络，跑起来毫秒级完成。验证脚本单独写，不放进tests/unit/，避免污染单元测试的隔离性。
4. 验证请求：真实调用与 Token 消耗确认
验证脚本放在scripts/verify_llm.py，它复用同一个LLMClient，但走真实网络：
# scripts/verify_llm.py import os import json from src.agent_harness.llm_client import LLMClient def main(): client = LLMClient() prompt = '请只返回 JSON：{"response": "验证成功"}' raw = client.generate(prompt, temperature=0.0) print("原始返回：", raw) cleaned = raw.strip().removeprefix("```json").removesuffix("```").strip() data = json.loads(cleaned) assert "response" in data, "返回体缺少 response 字段" print("解析结果：", data) print("Base URL：", client.base_url) print("Key 前缀：", client.api_key[:8] + "..." if client.api_key else "未设置") if __name__ == "__main__": main()运行：
python scripts/verify_llm.py预期输出类似：
原始返回： {"response": "验证成功"} 解析结果： {'response': '验证成功'} Base URL： https://taotoken.net/api Key 前缀： sk-xxxxx...如果返回体里带了 Markdown 代码块标记，脚本里的removeprefix/removesuffix会处理掉。这一步验证了三件事：Key 有效、Base URL 正确、返回结构能被 Agent Core 的解析逻辑消费。接着去控制台看用量记录，确认这次请求的 Token 消耗被正常统计。如果用量页面没有新增记录，说明请求可能没真正打到通道上，或者 Key 被用在了别的地址。
验证通过后，你可以把这次真实返回的 JSON 结构复制回单元测试的 Mock 返回值里，让 Mock 数据和真实响应保持一致。这是 Mock 测试和真实验证之间最实用的联动方式。
5. 本篇常见错排查
5.1 404 或路径重复
最常见的原因是 Base URL 填成了https://taotoken.net/api/v1，而客户端又自动拼了/v1/chat/completions。解决方法是 Base URL 只填https://taotoken.net/api，让客户端或 SDK 去补版本路径。如果你用的是 OpenAI Python SDK，可以这样初始化：
from openai import OpenAI client = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url="https://taotoken.net/api" )5.2 401 未授权
Key 没读到、Key 复制时带了空格、或者环境变量没生效。先在终端确认：
echo $TAOTOKEN_API_KEY如果输出为空，说明环境变量没导出成功。Windows 下用set TAOTOKEN_API_KEY=...，Mac/Linux 用export。另外注意不要把 Key 写进pytest.ini或提交到仓库。
5.3 Mock 用例被真实调用污染
如果你在conftest.py里定义了全局的llm_clientfixture，并且它直接实例化了真实LLMClient，那么单元测试可能会意外发起网络请求。正确做法是单元测试里始终用MagicMock(spec=LLMClient)，真实LLMClient只在验证脚本或集成测试里实例化。可以在pytest.ini里加标记区分：
[pytest] markers = integration: 需要真实网络和 Key 的测试然后集成测试用@pytest.mark.integration，日常跑pytest -m "not integration"只跑 Mock 用例。
5.4 返回体解析失败
真实 LLM 返回的 JSON 可能被包在 Markdown 代码块里，也可能前后有换行。Agent Core 的_parse_llm_response要做好清理：去掉```json和```，再strip()，最后json.loads。如果解析仍然失败，打印原始返回体，对比 Mock 里的结构差异。
5.5 用量记录对不上
验证请求成功后，去控制台看用量。如果记录延迟，等几秒刷新。如果一直没有，检查请求是否真的走了 TaoToken 的 Base URL，而不是被本地代理或缓存拦截。可以在验证脚本里打印client.base_url确认。
6. 拿到 Key 后怎么继续
验证链路跑通后，你的 Agent Harness 就有了两层保障：单元测试用 Mock 锁定组件逻辑，真实调用验证用 TaoToken 确认端到端可用。接下来可以按需分流：
排障和接入细节看 API Keys 页面和接入文档，里面有针对不同客户端的 Base URL 配置说明。想快速验证模型返回效果，用模型对话页面直接发请求，不用写代码。如果你要做长期编码任务或 Agent 自动化，Coding Plan 更适合持续调用场景。
把验证脚本里的返回结构同步回 Mock 用例，是保持测试和真实环境一致的关键动作。每次改 Prompt 或换模型后，先跑一遍验证脚本，再跑单元测试，顺序不要反。
