《AI Agent 开发入门》附录 D.常见错误与 FAQ

读懂报错，是这本书希望帮你建立的独立能力。这一页把学习与实战中最常撞上的问题按「症状 / 原因 / 处置」整理出来，每条都给最小复现与修法。

建议用法：先按报错原文匹配条目，再照「处置」改。下面所有报错文本都在本机实际触发过。

D.1 环境与安装

D.1.1 pip 找不到包：No matching distribution found

症状

ERROR: No matching distribution found for tabulate

原因：pip 走的源没有这个包，或该源的索引不完整。本机实测清华源与阿里云源都不可靠——清华源直接「找不到」，阿里云源在装 pydantic 时报 wheel 元数据 404。

处置：换中科大源，它是本机唯一稳定的源。

python -m pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple <pkg>

想一劳永逸就写进配置：python -m pip config set global.index-url https://mirrors.ustc.edu.cn/pypi/simple。

D.1.2 装了包但 import 还是失败

症状：pip install 成功，运行时报 ModuleNotFoundError。

原因：多半是 pip 与 python 不是同一个解释器——装进了系统 Python，却用 venv 的 python 运行（或反之）。

处置：始终用 python -m pip install ...，让 pip 跟当前解释器绑定；先 source /tmp/agentbook/venv/bin/activate 再操作。用 which python 和 python -m pip --version 核对路径一致。

D.1.3 版本不符：语法报错

症状：list[str] | None、match 等语法在本机报 SyntaxError。

原因：解释器低于 Python 3.10，而本书按 3.14.6 写。

处置：python --version 确认为 3.14.6，低于此版本重装 Homebrew Python 3.14。

D.2 Node 与 TypeScript

D.2.1 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX：参数属性

症状

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript parameter property is not supported in strip-only mode

原因：Node 26 只做类型擦除，参数属性（constructor(public x: number)）会生成运行时代码，无法被擦除。

处置：声明字段、在构造函数函数体内赋值。

class Agent {
  model: string;
  constructor(model: string) {
    this.model = model;   // 不用参数属性
  }
}

D.2.2 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX：enum / namespace

症状

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode

原因：enum 与 namespace 同样不是纯类型语法，擦除后会丢失运行时行为。

处置：enum 改用 const 对象 + 联合类型；namespace 改用普通模块导出。

const Color = { Red: "red", Green: "green" } as const;
type Color = (typeof Color)[keyof typeof Color];

D.2.3 bad option: –experimental-transform-types

症状

node: bad option: --experimental-transform-types

原因：Node 26 已移除该实验开关，只保留类型擦除。

处置：不要加任何转换开关，直接 node file.ts。要检查类型就 npx tsc --noEmit。

D.2.4 tsc：tsconfig.json is present but will not be loaded

症状

error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline.

原因：tsc 同时收到配置文件和命令行文件名，两者冲突。

处置：不要指定文件名，直接 npx tsc --noEmit，让 tsconfig.json 的 include 决定检查范围。

D.3 minagent 运行时

D.3.1 RuntimeError: FakeModel 脚本已耗尽

症状

RuntimeError: FakeModel 脚本已耗尽：Agent 没有收敛

原因：脚本没给出终止的文本回复，模型还想继续，但脚本已消费完——本质上就是「Agent 没收敛」。

处置：补一条 str 作为终止轮；或检查工具名是否拼错，导致模型拿到错误后空转。

D.3.2 工具抛异常，但循环没有中断

症状：工具函数 raise ValueError(...)，但 run() 没崩，轨迹里却出现 {"error": "ValueError: ..."}。

原因：这是设计，不是 bug。ToolRegistry.call 把异常转成错误 JSON 回灌给模型，让它自己决定重试、换工具还是道歉。

处置：不用改。要断言这一点就检查轨迹：assert "ValueError" in result.steps[0].detail。真正想中断循环时才需要在工具外显式抛。

D.3.3 TypeError: 不认识的脚本项

症状

TypeError: 不认识的脚本项：None

原因：脚本里放了 str / ToolCall 列表 / ModelResponse 之外的东西。

处置：只放这三种。尤其注意单个 ToolCall 不是合法项，工具调用轮必须写成列表 [ToolCall(...)]。

D.3.4 工具没被调用

症状：脚本写了工具调用，但轨迹里没有 tool_call。

原因：脚本项写成了裸 ToolCall 而非列表；或 ToolCall.name 与注册的工具名不一致。

处置：改成 [[ToolCall("c1", "add", {...})], ...]，并核对名字逐字一致。

D.3.5 unexpected keyword argument

症状：工具执行时报 TypeError: func() got an unexpected keyword argument 'b'。

原因：parameters["properties"] 的键与 func 的形参名对不上，arguments 展开时多传/少传。

处置：让 properties 的键、required 列表与函数形参逐字对齐。

D.3.6 RuntimeError: 超过 N 步仍未收敛

症状

RuntimeError: 超过 8 步仍未收敛

原因：模型连续发工具调用、始终不给终止文本，触发了 max_steps 护栏。

处置：这是护栏在正常工作。要定位真因，检查是不是工具结果让模型「越看越想调」——把工具结果裁剪得更聚焦，或调大 max_steps 后重试观察。若脚本本身就永不收敛，属于测试用例预期，用 pytest.raises(RuntimeError) 断言即可。

D.3.7 stop_reason 一直是 max_tokens

症状：result.messages[-1].content 为空，stop_reason 为 max_tokens。

原因：模型这一轮的输出被截断，没有给出完整文本；假模型里通常是你显式构造了这样的 ModelResponse。

处置：真实场景下调大 max_tokens 或缩短上下文；测试场景下这正是「注入截断错误」的手段，用于验证第 6 章结构化输出与第 14 章重试逻辑。

D.4 内容与站点

D.4.1 YAML 解析失败：列表项以 @ 开头

症状：frontmatter 解析报错，构建失败。

原因：@ 在 YAML 里是保留指示符，- @tool 会被当非法节点。

处置：给这样的列表项加引号：- "@tool"。

D.4.2 tags 里的 # 被吃掉

症状：标签页 URL 少了 # 后面的内容，或指向了错误页面。

原因：Hugo 的 urlize 会把 # 处理掉，#c 之类的标签会退化成 c。

处置：tags 里不要出现 #，换用不含 # 的写法。

D.4.3 hugo –quiet 掩盖 REF_NOT_FOUND

症状：hugo --quiet 显示成功，但页面上有链接 404。

原因：--quiet 把 REF_NOT_FOUND 这类错误也吞掉了；短代码引用失败时页面照样生成。

处置：验证构建必须用非 quiet 模式，让 REF_NOT_FOUND 显式报出来。日期晚于构建时刻的文章会被 buildFuture=false 静默跳过，从而引发一批 ref 失败——这也是必须非 quiet 才能发现的一类问题。

D.4.4 单段站内链接 // 是死链

症状：正文里写了 [LLM](/llm/)，点击 404。

原因：[Permalinks] 把文章压到根级 /<slug>/，而专题 section 页在 /posts/<topic>/。/llm/ 这种单段链接指向的专题页根本不存在。

处置：专题链接一律写 /posts/<topic>/，例如 [LLM](/posts/llm/)。手写单段 /<某个slug>/ 去指专题是死链；指文章才用根级 slug。

D.4.5 正文出现一级标题

症状：目录层级错乱，或页面出现两个 h1。

原因：页面模板已经渲染了 title 作为 h1，正文里再写 # 标题 就会重复。

处置：正文从 ## 起，章内用 ##、###、#### 分层，不要用 #。

D.4.6 slug 与文件名不一致

症状：构建报 slug 校验失败，或 URL 与预期不符。

原因：frontmatter 的 slug 与文件名（去 .md）不一致，而本书要求两者逐字相同。

处置：把 slug 改成与文件名一致；改名时要意识到它会影响公开 URL。

D.4.7 代码围栏缺语言或未闭合

症状：构建后代码块渲染成普通段落，或整页排版错乱。

原因：代码围栏的开标记后面没写语言（python / typescript / bash / yaml / json / text），或开合数量不匹配。

处置：每个围栏都标语言，并确保成对闭合。这类问题肉眼可见，但很容易在长文档里漏掉一个。

D.5 三条通用排查思路

遇到报错先别改代码：把报错原文与上面的「症状」对齐，绝大多数问题在环境层或夹具层，改一行命令就能解决。真正的 Agent 逻辑问题——不收敛、工具选错、上下文丢失——才是第 3–16 章正文要解决的问题；环境问题不该占用你的调试预算。