给 Agent 一个能动手的环境

先看出事的那一刻

2026 年 7 月 19 日，知识库 Agent 第一次接上第三方的兼容模型。同一段代码，在自己的终端里运行正常；从 Claude Code 的会话里启动，就一直返回 401。

第 18 课讲过它的来龙去脉和修法。这节课要说的是它背后更大的一件事：Agent 不是飘在云上的一段对话，而是你机器上的一个进程。它从哪个目录启动、继承了哪些变量、手里有哪些工具、开局读到了什么，决定了它能做什么，也决定了它会做错什么。这一次，宿主会话留下的几个变量，就让它拿着别人的身份去发请求。

这节课要回答的是：搭一个 Agent，除了选模型、写提示词，还要给它准备什么？

装备几个词

为什么要懂

流程图，还是 Agent

不用 Agent 的时候，"根据资料回答问题"要写成一张流程图：先按关键词查，查到了就总结，查不到就回复"没有"。每一步、每个分支都由你预先写好。

用户换一种说法提问，流程图就接不住了：资料里写的是英文缩写，用户问的是中文全称；第一次没搜到，要不要换个词再搜？这些分支，写流程图的人很难都想到。

知识库 Agent 的做法是：给它一个资料目录、三个工具、一份写清楚的提示词，剩下的让它自己来。它会先搜关键词，读命中的段落；一次没搜到，就换中文、英文、缩写再搜；还是没有，才回答查不到。

所以判断要不要用 Agent，看步骤是不是固定的：每次都一样的活（每晚同步一次数据、按模板生成周报），写成脚本更稳；步骤要看情况而定的活（回答五花八门的问题、根据报错决定下一步），才轮到 Agent。

环境的三样东西：在哪干活、用什么工具、开局知道什么

拿两个真实的 Agent 对照：

工具：少而通用

知识库 Agent 只有三个工具，没有用向量库。回答资料里的问题，只需要"找"和"读"；能写、能执行的工具用不上，多开一个就多一份风险。它搜了什么、读了哪些文件，界面上都看得到，每条回答下面的出处可以点开对照原文。

E2E 导师多了 5 个自定义工具，因为它要用的数据不在它的工作目录里：词条和论文在后端读进内存的内容里，学员的背景和进度在数据库里。要接外部的数据和系统时，才值得专门做工具，而且数量越少越好。

开局：提示词像一份上岗说明

知识库 Agent 的提示词是一份通用模板，主要交代干活的规矩：

1. 你是谁：知识库的名字，加配置里的一句领域说明；
2. 只能依据检索到的原文作答，不许用自己的知识补；
3. 怎么找：先搜关键词、再读原文；同一个概念换中文、英文、缩写多搜几次；
4. 怎么答：每条结论标出处；查不到，就原样回答一句固定的拒答语；
5. 一张资料地图：每个文件的路径和第一行。地图只告诉它去哪找，内容一律以读到的原文为准。

开局放什么，看它是不是每次都要用：一定会用到的，直接给；可能用到的，给它找的办法。E2E 导师把当前页面的词条直接放进提示词，省掉了一次查询，首字从 13 秒降到了 7 秒左右（第 17 课）；其余 30 个词条，让它用查词条、搜词条两个工具自己去取。

环境要能搬走

知识库 Agent 的引擎按"领域无关"来设计：换一个资料目录、改一份配置、配一套新的评测题，就是另一个知识库。（也有没清干净的地方：提示词里教它换词搜索时举的几个例子，用的还是上一套资料的术语。）仓库里带了一个只有咖啡资料的例子，问它自动驾驶的问题，它回答查不到，没有拿自己的知识去补。

能搬走，还意味着它只依赖说明里写明的那几样东西：

• 变量给白名单：E2E 导师只交给 Agent 四个变量。知识库 Agent 是先整体继承、再删掉可疑的，第一次就漏删了一个（第 18 课）；开场的 401，就是继承来的。
• 启动先自检：必需的目录、配置、变量，启动时就检查；缺了就一次说清缺什么、怎么补。
• 配置跟着内容走：注入提示词的领域说明、首页的示例问题，换资料时要一起换。

找茬

 1  // 知识库 Agent 的开发计划（PLAN.md，7 月 19 日）里的 SDK 配置草稿（节选）
 2  options: {
 3    systemPrompt: KB_SYSTEM_PROMPT,        // 字符串形式，领域无关模板
 4    allowedTools: ["Read", "Grep", "Glob"],
 5    model: process.env.KB_MODEL,
 6    env: {                                  // 注意：env 会整体替换 process.env
 7      ...process.env,
 8      ANTHROPIC_BASE_URL: process.env.KB_BASE_URL,
 9      ANTHROPIC_AUTH_TOKEN: process.env.KB_API_KEY,
10    },
11    maxTurns: 15,                          // 防失控
12  },
13  
14  # kb.config.yaml（换成新知识库之后，节选；名字已隐去）
15  name: <新知识库的名字>
16  description: 端到端自动驾驶的学习资料……（上一套资料的说明，原文略）
17  
18  // server/config.ts 与 server/index.ts（交接之前，节选）
19  corpusDir: resolve(configDir, raw.corpus_dir ?? "./corpus"),
20  console.log(`KB 后端已启动 → http://localhost:${info.port}`);

快测

判断时刻

带走