手写 Agent 之前先把 Python 环境理顺: 一个独立的虚拟环境, 装好依赖, 让编辑器和终端都用对解释器, 最后跑一次自检脚本确认能调通模型.

📌 下文命令里的 <项目目录> 指你放这个练习的目录, 换成自己的路径即可.

为什么用独立虚拟环境​

系统全局 Python 里通常装着一堆别的项目的包, openai 这类库的版本会互相牵扯. 项目用独立 venv, requirements.txt 才有意义, 换一台机器也能一次装齐.

创建虚拟环境​

Windows 环境​

在 PowerShell 里进入代码目录:

cd "<项目目录>"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

不激活也能用: 直接调 .venv\Scripts\python.exe, 省得被 PowerShell 执行策略拦. 想激活就用:

.\.venv\Scripts\Activate.ps1

被拦的话先跑一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

让 VS Code 用这个解释器​

Ctrl + Shift + P → Python: Select Interpreter → 输入解释器路径... → 粘贴 .venv\Scripts\python.exe 的绝对路径.

下拉列表里通常看不到它: venv 埋得比较深, 路径还可能带中文, 自动扫描不会下探这么远. 手动填路径最省事, 选一次就会记住, 右下角状态栏会显示 .venv.

验证解释器​

python -c "import sys; print(sys.executable)"

输出的路径里要带 .venv\Scripts\python.exe. 显示的是系统 Python 路径, 说明没选对解释器, 或者终端是选之前开着的——新开一个终端再试.

WSL 环境​

Windows 的 .venv 和 WSL 的虚拟环境分开使用, 建议把 Linux 环境放到家目录下, 例如 ~/.venvs/agent.

首次创建与安装依赖​

以下命令在 Ubuntu 的 Bash 终端执行. 如果创建环境时提示 ensurepip is not available, 先安装虚拟环境组件; 已经装过就跳过:

sudo apt-get update
sudo apt-get install -y python3-venv

进入代码目录, 创建并激活环境, 再安装项目依赖:

cd "<项目目录>"

python3 -m venv ~/.venvs/agent
source ~/.venvs/agent/bin/activate

python -m pip install -r requirements.txt

创建环境和安装依赖通常只做一次; 依赖清单更新后再安装. 关闭终端不会删除虚拟环境或已安装的包.

每次打开终端后激活​

source ~/.venvs/agent/bin/activate

激活只影响当前终端: 它会把虚拟环境的 bin 目录放到 PATH 前面, 让 python 和 pip 优先使用这个环境里的版本. 新终端需要重新激活.

📌 文件名是 activate, 最后有一个 e. 写成 activat 会报 No such file or directory, 环境也不会激活.

验证当前解释器:

python -c 'import sys; print(sys.executable)'
python -m pip --version

路径应指向 ~/.venvs/agent/bin/python 对应的绝对路径. 如果显示 /usr/bin/python3, 说明还在用系统 Python; 激活成功后提示符通常也会显示 (agent).

退出与直接运行​

deactivate

退出只取消当前终端的激活状态, 不删除环境. 也可以不激活, 直接指定虚拟环境里的解释器:

~/.venvs/agent/bin/python -c 'import sys; print(sys.executable)'

命令格式固定, 换项目时改环境路径即可. 创建用的是环境目录 ~/.venvs/agent, 激活用的是目录中的脚本 ~/.venvs/agent/bin/activate.

检查环境​

Windows 终端:

cd "<项目目录>"
python 00-check-env.py

WSL 终端:

source ~/.venvs/agent/bin/activate
cd "<项目目录>"
python 00-check-env.py

正常输出分几段, 逐段对:

看到「环境没问题」就算过了.

💡 每跑一次会真实调用一次模型, 费用可以忽略, 但别写成循环反复跑.

常见报错​

收工自检​

• 解释器指向当前系统的独立环境: Windows 的 .venv 或 WSL 的 ~/.venvs/agent
• python 00-check-env.py 输出「环境没问题」
• git status 里看不到 .venv

更新记录: 2026-11-02 发布版, 去掉本地路径和凭证配置细节, 保留虚拟环境, 解释器选择与自检部分.

本课已完成手写与断点调试。核心是：模型提出工具调用请求，Python 执行工具，把结果追加到 messages，再请求模型；没有工具调用请求时结束，达到轮数上限时强制停止。

自己的实现见 code/01-minimal-loop.py，环境配置见 环境准备，参考教程见 NamiAgent 第 1 课。本文按当前代码整理，重点记录返回结构和消息流转。

工具与模型的分工​

三个工具与两份数据​

工具就是普通的 Python 函数。模型拿到工具说明后，生成“调用哪个函数、传什么参数”的结构化请求；真正读文件、写文件和执行命令的是本地 Python 代码。

当前实现中，有两份名字相近、用途不同的数据：

• TOOLS：工具说明列表，传给模型，包含名称、描述和参数结构。def_tools() 负责生成这些说明。
• TOOL_MAP：函数映射字典，留在本地，根据模型返回的工具名找到 Python 函数。

TOOL_MAP = {
    "read_file": read_file,
    "write_file": write_file,
    "run_shell": run_shell,
}

左边的 "write_file" 是字符串键，右边的 write_file 是函数对象。没有加调用括号，所以定义字典时不会执行函数。

什么任务容易触发工具调用​

“给我一段打印 hello 的代码”通常直接回复文字就能完成。“实际创建文件，再读取并运行它”则需要操作本地环境。

当前代码末尾的任务要求依次使用 write_file、read_file、run_shell：创建 tool_demo.py，写入 print(17 * 23)，读回检查，再运行并总结实际输出。

这只是预期流程。模型可能一轮请求多个工具，也可能分几轮请求。后一个操作需要前一个工具的实际结果时，通常需要下一轮才能作出判断。

📌 当前 01-minimal-loop.py 在末尾定义 task，然后执行 run(task)。修改任务要改这个字符串；当前入口没有读取 sys.argv[1]，在启动命令后追加任务文本不会替换它。

create 的返回结构​

这次调用发出了什么​

resp = client.chat.completions.create(
    model=MODEL,
    messages=messages,
    tools=TOOLS,
)

三个参数分别表示：

• model：使用哪个模型。代码中的默认值是 deepseek-flash，启动前可以调整。
• messages：到目前为止的对话，包括任务、模型回复和已有工具结果。
• tools：本轮向模型提供的工具说明。

当前没有设置 stream=True，所以拿到的是一次完整的非流式响应。虽然使用 OpenAI Python SDK，当前默认请求地址是 DeepSeek；SDK 将兼容接口返回的 JSON 解析成 ChatCompletion 对象，赋值给 resp。

resp 包含本轮模型响应，不是完整对话历史，也不是工具已经执行后的结果。 工具请求返回后，还需要下面的 Python 循环来执行。

情况一：直接回复文字​

下面是用于阅读结构的简化 JSON，编号和正文均为示例，不是本次调试的真实记录。省略了 created、usage 等字段；实际响应还可能包含服务商或模型相关字段。

{
  "id": "chatcmpl_text_demo",
  "object": "chat.completion",
  "model": "deepseek-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么需要我帮忙的吗？",
        "tool_calls": null
      },
      "finish_reason": "stop"
    }
  ]
}

message.content 是正文。这个例子没有工具调用，所以 tool_calls 为 null，在 Python 中对应 None。实际响应也可能省略这个可选字段，SDK 中通常仍能读到 None。

finish_reason 属于 choices[0]，说明本轮生成为什么结束。这里的 stop 表示正常结束生成；它本身不证明外部任务已经完成。

情况二：请求调用工具​

假设任务是“在当前目录创建 tool_note.txt，内容为 hello”，模型可能返回：

{
  "id": "chatcmpl_tool_demo",
  "object": "chat.completion",
  "model": "deepseek-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_write_001",
            "type": "function",
            "function": {
              "name": "write_file",
              "arguments": "{\"path\":\"tool_note.txt\",\"content\":\"hello\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

这个例子表达的是：请调用 write_file，参数是文件路径和文件内容。看到这个返回时，文件还没有被本地代码写入。

重点看这些字段：

choices[0] 取的是本轮第一个候选回复，不是 messages 中第一条历史消息。tool_calls[0] 才是这条助手消息中的第一个工具调用请求。

工具请求可以带有文字正文，所以不能只靠 content 是否为空判断是否需要工具。当前实现检查的是 msg.tool_calls。返回字段依据见 DeepSeek Chat Completions 文档。

怎样看见自己的真实返回​

在 create() 后面临时打印：

print(type(resp))
print(resp.model_dump_json(indent=2))

msg = resp.choices[0].message
print(msg.model_dump_json(indent=2))

model_dump_json() 将 SDK 对象转成 JSON 字符串；indent=2 让每层缩进两个空格。这是 SDK 解析后的响应视图。

也可以转成字典后访问，两种写法对应同一份数据：

data = resp.model_dump()

print(resp.choices[0].message.content)             # 对象访问
print(data["choices"][0]["message"]["content"])     # 字典访问

从响应取出工具调用​

逐层理解取值路径​

msg = resp.choices[0].message

拆开后是：

choices = resp.choices  # 取出候选回复列表
choice = choices[0]    # 取出第一个候选回复
msg = choice.message  # 取出助手消息

SDK 对象用点号取属性，列表用下标取元素。拿到 msg 后，再遍历它请求的工具：

for call in msg.tool_calls:
    name = call.function.name
    args = json.loads(call.function.arguments)
    result = str(TOOL_MAP[name](**args))

这里的 call 是列表里当前遍历到的一条调用请求。实际代码在进入循环前，已经通过 if not msg.tool_calls 排除了没有工具请求的情况。

arguments 为什么还要解析​

示例中的 arguments 看起来像一个对象，但外面有引号，它实际是字符串。内部的 \" 是 JSON 字符串里的双引号转义。

raw = call.function.arguments
# raw 是字符串：'{"path":"tool_note.txt","content":"hello"}'

args = json.loads(raw)
# args 是字典：{"path": "tool_note.txt", "content": "hello"}

解析后的字典，用 JSON 表示就是：

{
  "path": "tool_note.txt",
  "content": "hello"
}

外层 SDK 对象已经被解析，不代表 arguments 这个字段里的 JSON 字符串也会自动变成字典。因此这里还需要 json.loads()。

根据名字执行本地函数​

result = str(TOOL_MAP[name](**args))

这句可以拆成三步：

func = TOOL_MAP[name]  # 根据工具名取出函数
value = func(**args)   # 展开参数并执行函数
result = str(value)   # 把函数返回值转成字符串

使用上面的写文件参数时，相当于：

result = str(write_file(path="tool_note.txt", content="hello"))

**args 把字典展开成关键字参数，字典的键需要匹配函数参数名。这里传入的是 path 和 content 两个参数。

它与 Java 反射都有“运行时选择调用目标”的使用场景；这里的机制更接近在 Map 中保存函数式接口，取出来后调用，不需要通过类元数据查找方法。

messages 如何记录过程​

每条消息是谁写的​

这些消息都由 Python 代码放入 messages。其中，模型生成的助手消息由 SDK 返回，工具结果由本地函数返回。

先记请求，再记结果​

拿到助手消息后，先追加它：

messages.append(msg.model_dump(exclude_none=True))

model_dump() 把 SDK 消息对象转成字典，exclude_none=True 表示省略值为 None 的字段。追加的是 msg，不是包含 choices 等信息的完整 resp。

执行每一个工具后，再追加对应结果：

messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": result,
})

tool_call_id 必须匹配原调用请求的 id。它用来告诉模型：这条结果属于哪一次调用，而不是只按工具名关联。

下面展示一次写文件再总结的简化消息历史。为突出结构，省略了实际模型可能返回的其他消息字段：

[
  {
    "role": "system",
    "content": "你是一个能操作本地文件和命令行的编程助手。需要时调用工具，完成任务后直接用文字总结。"
  },
  {
    "role": "user",
    "content": "请在当前目录创建 tool_note.txt，内容为 hello。"
  },
  {
    "role": "assistant",
    "tool_calls": [
      {
        "id": "call_write_001",
        "type": "function",
        "function": {
          "name": "write_file",
          "arguments": "{\"path\":\"tool_note.txt\",\"content\":\"hello\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_write_001",
    "content": "已写入 tool_note.txt（5 字符）"
  },
  {
    "role": "assistant",
    "content": "已创建 tool_note.txt，写入内容为 hello。"
  }
]

第五条消息来自工具执行后的下一轮模型响应。模型会看到前四条记录，再根据执行结果生成总结。这段 JSON 是说明用的示例，不代表程序已经实际执行了写文件操作。

如果同一条助手消息请求了多个工具，代码要执行并记录每个请求的结果，再进入下一轮模型请求。当前内层 for 是顺序执行，没有并发执行工具。

📌 工具报错也要回填。当前 try/except 会把文件不存在、参数错误等异常转成文字，作为 tool 消息交给模型；下一轮模型可能修正参数，也可能解释失败后结束。

循环何时继续和停止​

两种正常停止路径​

for step in range(1, MAX_STEPS + 1):
    # 请求模型，记录助手消息

    if not msg.tool_calls:
        print(msg.content)
        return

    # 执行本轮全部工具，记录结果，进入下一轮

这是省略了请求与执行细节的流程片段。正常控制流程中有两种停止路径：

• 模型本轮没有请求工具：if not msg.tool_calls 成立，输出正文，通过 return 退出 run()。
• 模型持续请求工具：最多完成 MAX_STEPS 轮请求，循环结束后输出达到上限的信息。当前上限为 20。

range(1, MAX_STEPS + 1) 在这里产生 1 到 20，不包含 21。上限限制的是模型请求轮数，不是工具执行总次数。 一轮可以包含多个工具请求，最后一轮纯文字总结也占一轮。

工具返回结果并追加到 messages，不会自动再次调用模型。真正让流程继续的是外层 for 的下一次迭代，以及下一次 create()。

停止不等于验证成功​

当前代码的结束条件是“没有工具调用请求”，不是“已验证任务成功”。模型解释失败后也可能不再请求工具；达到上限则表示流程被强制停止。

finish_reason="length" 等情况还可能表示生成被截断。当前最小实现没有按 finish_reason 进一步区分这些情况；它仍然只检查 msg.tool_calls。网络或鉴权等模型请求异常也没有被工具的 try/except 捕获，会直接中断程序。

本课先理解这个边界，不把最小循环的“停止”当成完整的业务验收。

断点调试​

重点查看的位置​

在 msg = resp.choices[0].message 的下一行设置断点。暂停时模型请求已经返回，resp 和 msg 都有值，可以依次展开：

resp
  choices
    [0]
      message
        content
        tool_calls
          [0]
            id
            function
              name
              arguments

在工具执行后的 messages.append(...) 下一行再设置断点，查看新追加的 tool 消息，以及它的 tool_call_id 是否对应原请求的 id。

调试器还会显示 SDK、Pydantic 和 Python 使用的内部属性。_xxx 通常约定供内部使用，__xxx__ 通常是特殊属性；本课先关注上面的消息与工具字段。

工作目录影响工具操作​

文件读写和命令执行没有显式切换目录，所以相对路径以 Python 进程的当前工作目录为准。运行或调试时，将工作目录设为 项目里的 playground 目录，不要让示例文件落到仓库根目录。

run_shell 每次执行命令前要求输入 y/n；当前 write_file 和 read_file 没有这一步。命令被拒绝时，返回的“用户拒绝执行该命令”也会作为工具结果进入下一轮。

本课实现记录​

与参考代码的差异​

以下差异按当前 code/01-minimal-loop.py 与 NamiAgent 的 lesson-01/agent.py 核对：

• 配置读取：自己的实现通过 code/model_client.py 统一加载配置文件，导入 MODEL 并调用 create_client()。参考代码直接在文件内创建客户端。
• 工具说明与分发：自己的函数名是 def_tools()，映射名是 TOOL_MAP；参考代码分别叫 _tool() 和 TOOL_FUNCS。当前两种说明构造函数都把简写的参数说明展开成字符串参数的 JSON Schema。
• 工具返回值：自己的实现使用 str(...) 将函数返回值转成字符串，再放入 tool.content；参考实现直接使用工具返回值。
• 任务入口：自己的实现把三工具任务写在文件末尾并调用 run(task)；参考实现通过 if __name__ == "__main__" 读取命令行参数。

外层模型请求循环、内层工具执行循环、助手消息与工具消息回填，以及轮数上限的核心逻辑一致。

参考资料​

• DeepSeek Chat Completions API：本项目默认服务商的请求参数与返回字段。
• OpenAI Python SDK 的 Chat Completions 参考：SDK 的返回类型与兼容接口结构。

更新记录：2026-11-01 完成本课复习笔记，补充返回 JSON、取值路径、工具执行、消息回填和停止条件；同日按课编号更新脚本路径；示例数据不代表新的真实模型调用。

第 1 课的三个工具是写死的. 本课把它改成注册表加统一执行器: 新增工具只写一个函数, 主循环一行不改; 工具报错不再让程序崩, 而是变成模型能读到的一条结果.

代码见 code/02-tools/tools.py, 参考教程见 NamiAgent 第 2 课, 上一课见 最小循环.

📌 本课代码是单个文件, 工具定义和主循环都在 tools.py 里. 参考教程拆成 tools.py 和 agent.py 两个文件, 差异见文末.

下文代码块均为节选, 省略了函数注释和部分类型标注; 字符串和标点与源文件一致, 完整代码以 code/02-tools/tools.py 为准.

第 1 课留下的三个问题​

本课用两个东西解决: 装饰器让"说明跟着函数走", 执行器让"错误统一变成结果".

一个工具由什么组成​

前三项是发给模型的说明书, 第四项是本地实现. 模型看不到你的代码, 只看到前三项.

description 本质上是提示词, 它决定模型选不选这个工具, 以及传什么样的参数. 同一段代码, 说明写成"执行命令"和写成"在当前工作目录执行 shell 命令, 返回退出码和输出", 模型的表现不一样.

装饰器与注册表​

@tool 做了什么​

def tool(name, description, parameters):
    """创建用于注册模型工具说明的装饰器."""
    def decorator(func):
        TOOLS.append({
            "type": "function",
            "function": {
                "name": name,
                "description": description,
                "parameters": {
                    "type": "object",
                    "properties": {k: {"type": "string", "description": v} for k, v in parameters.items()},
                    "required": list(parameters.keys()),
                },
            },
        })
        TOOL_NAME[name] = func
        return func
    return decorator

分成两层, 执行顺序是:

1. tool("list_dir", "...", {...}) 先执行, 把名称, 描述和参数记在闭包里, 返回 decorator
2. @ 把下面定义好的函数交给 decorator
3. decorator 往 TOOLS 追加一条说明, 往 TOOL_NAME 登记函数, 然后把原函数原样返回

@tool(name="read_file", description="读取本地文件内容", parameters={"path": "文件位置"})
def read_file(path: str) -> str:
    ...

装饰之后 read_file 还是原来那个函数, 可以直接调用, 也可以按名字查出来调用.

两份数据​

第 1 课也有这两份数据, 叫 TOOLS 和 TOOL_MAP. 区别只在名字和填空时机: 第 1 课是手写列表, 本课是装饰器在导入时自动追加.

注册发生在什么时候​

@tool(...) 在 模块导入时 就执行完, 不是调用工具时. 所以脚本一启动, TOOLS 里已经有 7 条说明, TOOL_NAME 里已经有 7 个函数.

顺序就是代码里函数定义的顺序: list_dir, write_file, run_shell, fetch_url, read_file, get_weather, get_current_time. 这个顺序只是说明书的排列顺序, 不影响模型选谁.

类型标注保住了什么​

ToolFunction = TypeVar("ToolFunction", bound=Callable[..., object])

def tool(name: str, description: str, parameters: dict[str, str]) -> Callable[[ToolFunction], ToolFunction]:

装饰器如果不标注, 类型检查器会认为被装饰的函数变成了"任意可调用对象", 函数名和参数都对不上. 用 TypeVar 绑定后, 装饰前后签名一致, 编辑器还能提示 read_file(path=...).

参数简写的代价​

parameters 收的是"参数名到说明"的字典, 装饰器统一展开成:

{
  "path": {
    "type": "string",
    "description": "文件位置"
  }
}

这带来两个限制:

• 所有参数都是 string, 写不了 integer, enum, 数组
• 所有参数都进 required, 写不了可选参数

本课 7 个工具的参数刚好都是必填字符串, 所以够用. 遇到 timeout 这类有默认值的参数, 就得自己写完整 schema, 不能再用这个简写.

无参数工具传空字典, 展开后 required 是空列表:

@tool(name="get_current_time", description="获取本机当前日期和时间（使用系统本地时区）", parameters={})

七个工具​

确认放在工具里​

write_file 和 run_shell 都先 input() 问一句 y/n:

confirmation = input(
    f"\n[需要确认] 写入文件：{path}（{len(content)} 字符，已有文件会被覆盖）\n"
    "允许？(y/n) "
)
if confirmation.strip().lower() != "y":
    return "用户拒绝写入文件"

放在工具里而不是循环里, 原因是: 循环只认"工具名加参数", 它不知道哪个工具危险. 危险与否是工具自己的属性, 写在工具里才对.

用户拒绝时返回的字符串会作为 tool 消息进历史, 模型下一轮能看到"用户拒绝了", 不会死循环重试.

截断分三种口径​

def truncate_output(text: str, limit: int = MAX_OUTPUT) -> str:
    if len(text) <= limit:
        return text
    return f"{text[:limit]}\n...（已截断，原文共 {len(text)} 个字符）"

• 目录列表: 按字符数截断, 上限 8000
• 命令: 标准输出和标准错误各 4000, 合计不超过 8000
• 网页: 先只读 8001 字节, 超过 8000 就截断并说明
• 文件读取: 不截断, read_file 直接返回全文

网页用字节而不是字符, 是因为此时还没解码, 不知道一个字符占几个字节.

工具函数不吞异常​

fetch_url 遇到不合法的地址直接抛:

if parsed.scheme not in ("http", "https") or not parsed.hostname:
    raise ValueError("只支持完整的 HTTP 或 HTTPS 地址")

这不是疏忽. 工具只管干活, 出错就抛; 统一由下一节的执行器接住, 转成模型能读的文字. 这样每个工具里都不用复制一遍 try/except.

统一执行器 excute​

def excute(tool_name: str, tool_args: dict[str, str]) -> str | dict[str, str | int]:
    if tool_name not in TOOL_NAME:
        return f"工具 {tool_name} 不存在"

    tool_func = TOOL_NAME[tool_name]
    try:
        res = tool_func(**tool_args)
        return res
    except Exception as e:
        return f"调用工具 {tool_name} 时发生错误: {str(e)[:4000]}"

错误也是一种结果​

这是本课最关键的设计. 工具报错时, 程序不崩, 而是把报错原文交回模型:

调用工具 read_file 时发生错误: [Errno 2] No such file or directory: 'notes.txt'

模型看到这句, 通常会先调 list_dir 看看目录里有什么, 再读正确的文件. 这个"看报错, 自己改"的过程, 就是 Agent 和普通脚本的区别.

如果这里直接抛异常, 整个程序退出, 模型连补救的机会都没有.

工具名不存在也走这条路​

模型偶尔会编一个不存在的工具名. TOOL_NAME 里查不到, 直接返回一句"工具 xxx 不存在", 不用抛异常.

💡 这里的提示只写了工具名, 没有列出可用工具. 参考实现会补一句"可用工具: ...", 模型改了名字后更容易一次改对. 要加的话, 在返回值里拼上 ", ".join(TOOL_NAME) 即可.

返回值可能是字典​

get_weather 返回的是字典, 不是字符串:

return {"city": city, "temperature": 25, "description": "晴天"}

而 tool 消息的 content 必须是字符串, 所以循环里回填前要转:

messages.append({"role": "tool", "tool_call_id": call.id, "content": str(tool_res)})

不转的话, 下一次请求会因字段类型不对而失败.

📌 函数名是 excute, 是 execute 的拼写笔误. 当前代码按这个名字调用, 本文也照原样记录. 改名要同时改定义和调用处.

主循环 run_task​

与第 1 课逐块对照​

循环本体​

for step in range(1, MAX_STEPS + 1):
    res = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
    message = res.choices[0].message
    messages.append(message.model_dump(exclude_none=True))

    tool_calls = message.tool_calls
    if not tool_calls:
        print(f'第 {step} 步模型没有调用工具，任务完成，输出结果：{res.choices[0].message.content}')
        return

    for call in tool_calls:
        tool_name = call.function.name
        tool_args = json.loads(call.function.arguments)
        tool_res = excute(tool_name, tool_args)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": str(tool_res)})

和第 1 课相比, 循环里已经没有任何具体工具的名字. 它只做四件事: 问模型, 记助手消息, 分发工具调用, 回填结果.

三处没变的地方​

• 先追加助手消息, 再处理工具结果. 顺序反了下一次请求会报缺少对应调用
• tool_call_id 用 call.id, 不是工具名
• 一轮可能有多个 tool_calls, 每个都要回一条 tool 消息

这三条是协议要求, 不因工具变多而变.

注释掉的那行​

# print(f'第 {step} 步模型工具调用请求：{tool_calls}\n')

调试时用过的打印, 已经注释掉. 想看原始结构时取消注释即可.

运行与边界​

跑起来​

当前入口写死了一个任务:

run_task("请列出当前目录，创建 notes/hello.txt 写入 Hello, Agent!，然后读取并总结。")

在 playground 目录里跑, 预期过程:

=== 第 1 步 ===
调用工具名称:list_dir,参数:{'path': '.'}
=== 第 2 步 ===
调用工具名称:write_file,参数:{'path': 'notes/hello.txt', 'content': 'Hello, Agent!'}

[需要确认] 写入文件：notes/hello.txt（13 字符，已有文件会被覆盖）
允许？(y/n) y
=== 第 3 步 ===
调用工具名称:read_file,参数:{'path': 'notes/hello.txt'}
=== 第 4 步 ===
第 4 步模型没有调用工具，任务完成，输出结果：已创建 notes/hello.txt，内容为 Hello, Agent!

模型可能少走一步, 多走一步, 或者把读取和创建的顺序换掉. 这都正常, 只要最后的结果对.

三个观察点:

• 每步打印的工具名和参数, 是不是你预期的路径
• 写文件和执行命令时, 确认提示出现了没有
• 最后一条 assistant 消息里, tool_calls 是不是 None

这一课的边界​

• read_file, list_dir, fetch_url 不确认, 模型可以随便读, 随便访问任意 http 地址
• 相对路径以 Python 进程的当前工作目录为准, 在 code 目录里跑会把文件写进 code
• 停止条件仍是"模型不再请求工具", 不代表任务验证成功
• MAX_STEPS 是 10, 一轮里有多个工具也只占一轮
• 模型请求本身失败 (网络, 鉴权) 不被 excute 捕获, 会直接中断

最后一条尤其要注意: 第 1 课循环里的 try/except 也是只包工具, 不包 create(). 本课把工具的异常搬到执行器里, 这个边界没有变.

与参考实现的差异​

剩下的部分一致: 装饰器注册, 说明与函数同步, 错误当结果, 输出截断, 轮数上限.

参考实现把 messages 提到循环外, 支持连续多轮对话; 本课每次 run_task() 都从新历史开始. 下一课改权限时再决定要不要保留会话.

断点调试​

看注册结果​

在第一个 @tool(...) 之后任意位置打断点, 或在文件末尾加一行:

print(json.dumps(TOOLS, indent=2, ensure_ascii=False))

能直接检查七条说明的 name 和 properties 有没有写错. 这个打印只用于调试, 不要留在循环里.

看一次工具调用​

在 tool_args = json.loads(call.function.arguments) 下一行打断点, 展开:

call
  id
  function
    name
    arguments   ← 字符串
tool_args       ← 解析后的字典

重点看 tool_args 的键能不能对上函数参数名, 对不上会在 tool_func(**tool_args) 处抛 TypeError.

看回填的消息​

在 messages.append({"role": "tool", ...}) 下一行打断点, 检查:

• content 是字符串, 不是字典
• tool_call_id 和刚才 call.id 一致

参考资料​

• DeepSeek Chat Completions API: tools 参数和 tool_calls 返回字段.
• OpenAI Function Calling 指南: 工具说明的结构与调用流程.
• JSON Schema 入门: parameters 里各关键字的含义.
• 参考实现: NamiAgent 的 lesson-02/tools.py

更新记录: 2026-11-02 创建, 按 code/02-tools/tools.py 当前实现整理, 补充装饰器注册, 七个工具, 执行器, 主循环对照与调试位置; 示例输出为示意, 不代表本次真实运行记录.

从喜欢的博客出发​

动手之前，我先看了其他人已经搭建好的博客。其中，勾玉博客的阅读体验给了我启发：导航清楚，文章列表以文字为主，页面没有堆叠太多装饰。

我希望自己的博客也有类似的简洁感，同时保留一点温暖的颜色。讨论后，确定了两种可以切换的主题：清爽的纯白色，以及偏米白、带陶土色点缀的暖色。

正式实现前，我们制作了双主题概念图，用来比较配色：

这张图是设计参考，实际页面会根据阅读体验继续调整。

确定页面和功能​

首页采用“简短介绍 + 最新文章”的结构。读者打开网站后，既能知道这是谁的博客，也能直接看到最近发布的内容。

导航暂时分为五个入口：

• 博客：查看文章列表和文章详情。
• 分类：按主题查找文章，最多支持两级分类。
• 归档：按时间浏览发布过的文章。
• 我的项目：以后整理项目介绍和实践经历。
• 关于我：以后补充个人介绍和联系方式。

一篇文章可以有一个主要分类和多个标签。搜索覆盖标题、分类、标签和正文，并优先展示标题匹配的结果。文章页暂时不提供评论功能。

选择技术方案​

平时已经习惯用 Markdown 写学习笔记，所以这个博客选择了静态网站的方式：用 Docusaurus 把文章和页面生成为网站，再通过 GitHub 和 Cloudflare Pages 完成部署。

发布流程大致是：

本地 Markdown
    ↓
挑选并整理为博客文章
    ↓
提交到 GitHub 私有仓库
    ↓
Cloudflare Pages 自动构建
    ↓
访问线上博客

GitHub 仓库用于保存源码和文章；Cloudflare Pages 负责根据仓库里的内容构建和发布网站。仓库是私有的，但发布后的网站可以公开访问。

做一个本地发布助手​

如果每篇文章都手动整理元信息、复制图片、执行 Git 命令，用久了可能比较繁琐。所以这个项目还做了一个在本机运行的文章发布助手。

助手提供图形界面，用来选择 Markdown 文件、填写标题和分类、添加标签，以及查看发布预览。对于支持的本地图片，它会生成博客用的副本并调整路径，保留原来的学习笔记。

确认发布后，助手会提交本次选择的文章和相关图片，再推送到博客仓库。Git 推送和网站部署是两个不同的步骤：推送成功后，还需要等 Cloudflare 完成构建，网站才会更新。

目前助手主要支持标准 Markdown 图片写法；引用式图片和 HTML 图片尚不支持。真实学习文章的完整发布流程还需要继续验证，已发布文章的图形化更新流程也有待完善。

上线后遇到的问题​

博客上线后，分类页面出现过崩溃。最开始根据报错做了一次空值保护，但问题仍然存在。后来结合浏览器控制台提供的调用堆栈，才定位到生产构建中的实际问题：分类数据使用的 Map 在展开时，被构建工具转换成了不合适的数组操作。

修复时，将遍历方式改为显式使用 Array.from(...)，再重新构建并发布。这次排查也提醒我：构建通过和部署成功，并不等于页面在浏览器里一定能正常使用。 后续还需要把实际页面交互验证做得更完整。

接下来​

目前网站和发布助手已经有了第一版。后面准备逐步完成：

• 整理并发布真正想分享的学习笔记。
• 补充“我的项目”和“关于我”页面。
• 继续检查手机端与不同浏览器的使用体验。
• 完善已发布文章的修改和更新流程。

这个小站会随着学习和实践继续调整。先把内容写下来，再慢慢把体验做好。

一点记录​

学习过程中留下的笔记、遇到的问题和解决方法，都可以慢慢整理成文章。

一段示例代码​

print("记录学习，分享实践")

以上内容是示例，可以在准备好自己的文章后替换。