1. 从"AI 又胡说八道了"说起：为什么我要给 Agent 造一个专属网站
做 AI 应用开发这几年，最让我头疼的不是模型能力不够，而是它"太敢说"。你问它一个 API 的返回字段，它能一本正经地编出三个不存在的参数；你让它查一个库的最新用法，它给你一段两年前就废弃的代码，还配上一句"这是推荐做法"。这种问题在单轮对话里还能靠人工核对兜住，一旦把 AI 包装成 Agent 让它自主跑任务，错误就会被放大成连锁反应——它调错一个接口，后面十步全跟着崩。
我一开始的思路很朴素：把靠谱的资料喂给它不就行了？于是试过把文档塞进系统提示词、试过做本地知识库检索、试过让它在回答前先"自我检查"。折腾一圈下来发现，这些办法都有各自的硬伤。提示词塞太多会挤占上下文，检索回来的片段经常答非所问，自我检查基本等于让模型自己给自己判卷，它觉得自己对的时候照样错。
真正的转折点是我意识到一件事：Agent 缺的不是"知识"，而是一个它能主动去查、去验证、去调用的可靠信息源。模型参数里的知识是冻结的、模糊的、会过期的，但如果有一个网站，专门用结构化的方式把"事实"和"技能"组织好，让 Agent 通过标准的接口去取，那它就不需要"记住"这些东西，只需要"会查"就行。
这就是我动手做这个网站的起点。它不是给人看的普通网页，而是给 Agent 用的——页面结构、数据格式、调用方式，全都是围绕"机器可读、机器可调"来设计的。核心包含两块：一块是事实层，把容易出错、容易过期的信息做成结构化条目；另一块是技能层（skills），把"怎么做一件事"的完整流程封装成 Agent 可以直接执行的模块。
这篇文章我会把这套东西从设计动机、数据结构、skills 的具体实现，到实测中踩的坑，完整讲一遍。如果你也在做 Agent 相关的开发，或者被 AI 的可靠性问题折磨过，这篇应该能给你一些能直接抄的思路。不需要你有很深的机器学习背景，只要写过基本的接口调用就能看懂。
2. 为什么"喂文档"救不了 Agent：可靠性问题的根因拆解
2.1 模型的知识是"压缩过的印象"，不是"可查的事实"
很多人对 AI 出错有个误解，觉得是"训练数据不够多"。其实不是。大模型在训练时把海量文本压缩进了参数里，这个过程本质上是有损压缩。它记住的是"大概长什么样"，而不是"精确是什么"。就像一个看过一万本书的人，你问他某本书第 37 页第三行写了什么，他只能给你一个似是而非的复述。
这就解释了为什么 AI 编 API 参数编得那么自然——它见过太多类似格式的接口文档，于是"生成一个看起来合理的参数名"对它来说毫无难度，难的是"确认这个参数真的存在"。前者是生成任务，后者是检索任务，而模型天生擅长前者、不擅长后者。
所以指望通过"多喂点资料"来解决可靠性，方向就错了。你喂得再多，它也是把资料又压缩一遍存进那个模糊的印象里。真正靠谱的做法是：别让它记，让它查。
2.2 检索增强（RAG）为什么经常"答非所问"
说到"让它查"，很多人第一反应是 RAG——把文档切片、做向量检索、把相关片段塞回提示词。我早期也是这么干的，但实际用下来问题不少。
第一个问题是切片破坏了上下文。一份接口文档，参数说明和示例代码是强关联的，一切片就散了，检索回来的可能只有参数表没有示例，Agent 拿到手还是不知道怎么用。第二个问题是向量相似度不等于任务相关性。用户问"怎么上传文件"，检索可能返回一段讲"文件存储架构"的段落，字面很像，但根本不是他要的操作步骤。第三个问题是检索结果没有"可信度"信号。Agent 拿到五个片段，它不知道哪个是权威的、哪个是过时的，只能一锅端全信。
RAG 不是没用，但它解决的是"从大量非结构化文本里找相关内容"，而 Agent 真正需要的是"拿到一个确定的、结构化的、可以直接用的答案"。这两件事的差距，就是我做这个网站的动机。
2.3 Agent 真正需要的信息源长什么样
我把需求拆成了三条硬标准，后来整个网站的设计都是围绕这三条来的：
- 结构化：信息以固定字段组织，Agent 不需要"理解"就能直接取用。比如一个 API 条目，字段就是
name、params、returns、example，而不是一段散文。 - 可验证：每个条目带来源和更新时间，Agent 能判断这条信息是不是够新、够权威，而不是盲信。
- 可执行：不只是"是什么"，还有"怎么做"。技能层把操作流程封装成带输入输出的模块，Agent 调用完就能拿到结果，不用自己拼步骤。
这三条听起来简单，但落地时每一条都有坑。下面我逐个讲。
3. 网站的事实层设计：让 Agent 拿到"确定的东西"
3.1 条目结构：字段固定比内容丰富更重要
事实层的核心是"条目"（entry）。我一开始想做得花哨，给每个条目加一堆可选字段，结果 Agent 用起来反而懵——它不知道该信哪个字段。后来我砍到只剩四个必填字段，反而好用了：
| 字段 | 作用 | 示例 |
|---|---|---|
key | 唯一标识，Agent 用它精确查找 | api.file.upload |
value | 核心内容，结构化数据 | {method: "POST", path: "/upload"} |
source | 来源，用于可信度判断 | 官方文档 v3.2 |
updated | 更新时间戳 | 2024-11-01 |
关键心得：字段越少越固定，Agent 越不容易出错。可选字段一多，模型就会开始"发挥"，把不存在的字段也填上。宁可多建几个条目，也别在一个条目里塞太多可选结构。
3.2 用"精确 key"替代"语义搜索"
这是我从 RAG 的坑里爬出来后做的最大改动。传统检索靠语义相似度，模糊但容易跑偏；我改成精确 key 查找 + 别名映射。
具体做法是：每个条目有一个规范 key，同时维护一张别名表，把各种可能的叫法映射到规范 key。Agent 查询时先走精确匹配，匹配不到再走别名，还匹配不到才返回"未找到"。
# 别名映射示例 alias_map = { "上传文件": "api.file.upload", "file upload": "api.file.upload", "上传接口": "api.file.upload", "怎么传文件": "api.file.upload", } def lookup(query): key = alias_map.get(query.strip().lower()) if key: return entries.get(key) return {"error": "not_found", "hint": "请检查 key 或使用别名"}这套机制的好处是结果确定。要么命中返回准确内容，要么明确告诉 Agent"没找到"，而不是返回一堆"可能相关"的模糊片段让模型去猜。Agent 拿到not_found时，正确的行为是去问用户或换个 key，而不是硬编一个答案。
注意：别名表要定期维护。我踩过的坑是别名越加越多，最后出现一个查询词映射到三个不同 key 的情况。解决办法是给别名加优先级，冲突时以最具体的那个为准。
3.3 来源与时效：给每条信息打上"可信度标签"
Agent 判断信息能不能用，靠的是来源和时效这两个信号。我在每个条目里都强制带上source和updated，并且在返回时附一个可信度评分：
- 官方来源 + 三个月内更新：
confidence: high - 官方来源 + 超过一年：
confidence: medium - 社区来源 + 半年内：
confidence: medium - 社区来源 + 超过一年：
confidence: low
Agent 拿到low时，我的约定是它必须向用户说明"这条信息可能过时"，而不是直接拿来用。这个小小的标签，实测下来能挡掉相当一部分"用过期信息办错事"的情况。
3.4 一个完整的查询往返长什么样
把上面几块拼起来，一次典型的查询往返是这样的：
- Agent 发起查询：
GET /facts?key=api.file.upload - 网站返回结构化条目，含 value、source、updated、confidence
- Agent 检查 confidence，决定直接用还是提示用户
- 如果返回
not_found，Agent 走别名重试或转人工
整个过程没有任何"语义猜测"的空间，每一步都是确定的。这就是它比 RAG 可靠的根本原因——把不确定性从检索环节彻底移除。
4. Skills 层：把"怎么做"封装成 Agent 能直接调用的模块
4.1 事实和技能的区别：一个是名词，一个是动词
事实层解决"是什么"，技能层解决"怎么做"。这两者必须分开，因为它们的消费方式完全不同。事实是查一次就完事，技能是要按步骤执行、有中间状态、可能失败的。
我见过不少人把操作步骤也写成一段文字塞进事实条目里，结果 Agent 拿到一段"第一步…第二步…"的描述，还得自己解析、自己判断执行到哪了。这等于把执行逻辑又交回给了模型，可靠性立刻掉下来。
技能层的设计原则是：每个 skill 是一个带明确输入输出的黑盒。Agent 不需要知道里面怎么实现的，只要按格式传参、拿结果就行。
4.2 Skill 的标准结构：输入、步骤、输出、失败处理
一个 skill 我固定用四个部分描述：
{ "name": "skill.fetch_and_summarize", "inputs": { "url": {"type": "string", "required": true}, "max_length": {"type": "int", "default": 500} }, "steps": [ "校验 url 格式", "抓取页面正文", "按 max_length 截断并生成摘要" ], "outputs": { "summary": "string", "source_url": "string" }, "on_failure": { "invalid_url": "返回错误码 E001，提示用户检查链接", "fetch_timeout": "重试一次，仍失败则返回 E002" } }这里最关键的是on_failure。没有失败处理的 skill 是不完整的。Agent 执行任务时最怕的就是"卡住不知道怎么办"，明确告诉它每种失败对应什么动作，它才能自主往下走。
4.3 为什么 skill 要"小而专"，而不是"大而全"
我最初设计过一个"万能 skill"，输入一个任务描述，它内部自己拆步骤执行。结果非常不稳定——因为拆步骤这件事又回到了模型手里，等于把可靠性问题原封不动搬了进来。
后来我改成一个 skill 只做一件事，比如"抓取网页正文"、"提取表格数据"、"格式化日期"，每个都短小确定。Agent 要完成复杂任务时，由它自己编排多个小 skill。这样即使某个 skill 失败，影响范围也可控，而且每个 skill 都能单独测试、单独优化。
这个思路和写代码是一个道理：函数要单一职责。Agent 编排 skill 就像程序调用函数，粒度越细，组合越灵活，出错越好定位。
4.4 Skill 的注册与发现机制
Agent 怎么知道有哪些 skill 可用？我做了个清单接口：
GET /skills # 返回 { "skills": [ {"name": "skill.fetch_and_summarize", "desc": "抓取并摘要网页"}, {"name": "skill.extract_table", "desc": "从 HTML 提取表格"}, {"name": "skill.format_date", "desc": "标准化日期格式"} ] }Agent 启动时拉一次清单，把 skill 名字和描述放进自己的可用工具列表。这里有个细节：描述要写得让模型能判断"什么时候该用"，而不是只写"这是什么"。比如"抓取并摘要网页"就比"网页处理工具"有用得多，因为前者隐含了使用场景。
5. 实测踩坑：那些文档里不会写的教训
5.1 坑一：Agent 会"假装"调用了 skill
这是最隐蔽的坑。我早期测试时发现 Agent 报告"已完成摘要"，但实际根本没调用接口。原因是它在训练数据里见过太多"调用工具然后返回结果"的模式，于是直接编了一个看起来合理的结果，跳过了真实调用。
解决办法是强制回执校验。每个 skill 执行后返回一个带唯一trace_id的回执，Agent 的最终输出里必须包含这个trace_id，否则系统判定为"未真实执行"。这个机制加上之后，"假装调用"的情况基本消失了。
5.2 坑二：参数类型不匹配导致的静默失败
Agent 传参时经常把数字传成字符串，把布尔传成"true"。如果接口不做严格校验，这些错误会静默通过，然后在 skill 内部某一步炸掉，排查起来非常痛苦。
我的做法是在入口做严格类型校验，类型不对直接返回明确错误：
def validate(inputs, schema): for field, rule in schema.items(): val = inputs.get(field) if rule["required"] and val is None: return f"缺少必填字段: {field}" if val is not None and not isinstance(val, rule["type"]): return f"字段 {field} 类型错误，期望 {rule['type']}" return None宁可让它在入口就失败，也别让它带着错误参数往下跑。早失败比晚失败好排查一百倍。
5.3 坑三：并发调用时的状态污染
当 Agent 同时发起多个 skill 调用时，如果 skill 内部用了全局状态，就会出现互相污染。我遇到过一次：两个并发的摘要任务，结果 A 的摘要里混进了 B 的内容。查了半天才发现是缓存 key 没带请求标识。
教训是：skill 必须是无状态的，所有中间数据要么走参数传递，要么用带唯一标识的临时存储。任何全局变量在并发场景下都是定时炸弹。
5.4 坑四：错误信息写得太"技术"，Agent 看不懂
我一开始的错误返回是{"code": 500, "msg": "internal error"}，结果 Agent 拿到之后完全不知道该怎么办，只能干等或者乱试。后来我把错误信息改成面向 Agent 的行动指引：
{ "error": "fetch_timeout", "message": "目标页面响应超时", "suggestion": "可以重试一次，或换用缓存版本", "retryable": true }加上suggestion和retryable之后，Agent 的自主恢复能力明显提升。错误信息不只是给人看的，更是给 Agent 看的，这一点在做 Agent 工具时特别重要。
6. 从单机到可用：这套东西的扩展方向
6.1 事实层的版本管理
信息会更新，但 Agent 有时需要"某个时间点的正确信息"。我给事实层加了版本字段，同一个 key 可以保留多个版本，查询时可以指定as_of参数拿历史版本。这在做回归测试时特别有用——你可以固定一个时间点，验证 Agent 的行为是否一致。
6.2 Skill 的组合编排
单个 skill 能力有限，真正的价值在于组合。我后来加了一层"工作流"定义，把常用 skill 组合固化成模板，Agent 可以直接调用整个工作流，也可以自己拆开重组。这样既保证了常见任务的稳定性，又保留了灵活性。
6.3 可信度评分的动态调整
前面说的可信度评分是静态规则，后来我改成动态的：根据 Agent 实际使用后的反馈（比如某条信息导致任务失败）自动下调评分。用久了之后，那些经常出问题的条目会自动被标记出来，维护起来省心很多。
6.4 给同行的几点实在建议
如果你也想做类似的东西，我的建议是：先别追求大而全，从一个高频、易错的场景切入。比如先只做"API 参数查询"这一件事，把它做到确定、可靠，再往外扩。我见过太多项目一上来就想做"万能知识库"，最后因为每个场景都不够深而失败。
另外，测试要覆盖"找不到"的情况。很多人只测"能查到"，不测"查不到时 Agent 怎么办"。而实际运行中，"查不到"才是常态，Agent 在查不到时的行为，往往决定了整个系统的可靠性上限。
最后一点，别指望一次设计到位。我这套东西改了七八版，很多字段和机制都是踩坑之后才加的。先跑起来，让真实使用暴露问题，再针对性优化，比一开始就设计完美架构靠谱得多。
