够用就好的 Python 基础

学习目标

在终端运行一个 Python 文件。
用函数、列表和字典表示一次工具调用。
将数据编码成 JSON，并为错误输入返回可读信息。

本节只需要 Python 3.10 或更新版本，不需要 API Key 或第三方依赖。如果尚未安装，可从 Python 官网下载适合你的系统的安装包。

准备一个独立目录

在终端执行下面的命令。Windows 的 Python 命令通常也可以使用 py。

mkdir agent-lab
cd agent-lab
python3 --version
python3 -m venv .venv

macOS / Linux 用 source .venv/bin/activate 激活环境。 Windows PowerShell 用 .venv\Scripts\Activate.ps1 激活。激活后，本课后续命令统一使用 python。虚拟环境隔离项目依赖；现在虽然没有额外依赖，先养成这个习惯。

数据先于框架

Python 的字典适合表达有名字的字段，列表适合保存多条结果。函数接收输入、完成一项工作、返回结果，这就是后面工具的雏形。

book = {"title": "Python 入门", "stock": 3}
books = [book, {"title": "Agent 实践", "stock": 0}]

for item in books:
    print(item["title"], item["stock"])

字典字段的名称本身也是一个契约。如果上游返回 stock，下游却读取 quantity，程序就无法正确协作。所以字段应该少而明确，并在数据进入系统时校验。

写一个能独立运行的工具

把以下完整代码保存为 inventory.py：

import json

CATALOG = {
    "python-book": {"title": "Python 入门", "stock": 3},
    "agent-book": {"title": "Agent 实践", "stock": 0},
}

def lookup_stock(product_id):
    if not isinstance(product_id, str) or not product_id.strip():
        return {"ok": False, "error": "product_id 必须是非空字符串"}

    item = CATALOG.get(product_id)
    if item is None:
        return {"ok": False, "error": "商品不存在"}

    return {
        "ok": True,
        "product_id": product_id,
        "title": item["title"],
        "stock": item["stock"],
    }

if __name__ == "__main__":
    for product_id in ["python-book", "missing-book", None]:
        result = lookup_stock(product_id)
        encoded = json.dumps(result, ensure_ascii=False)
        decoded = json.loads(encoded)
        print(decoded)

运行 python inventory.py。预期看到一条成功结果和两条错误结果，程序不会因为一个无效商品就中止整个批次。 if __name__ == "__main__" 让文件既能独立运行，也能在以后作为模块导入。

JSON 与 Python 字典不是一回事

字典是内存中的 Python 对象；JSON 是便于跨语言传输的文本格式。 json.dumps 把对象编码成文本，json.loads 把 JSON 文本解析成对象。 HTTP 服务、模型输出和日志通常会用到这个边界。

JSON 使用双引号，并把真假和空值写成 true、false、null。 Python 对应的是 True、False、None。不要用 eval 解析外部内容；它会把内容当成代码执行。

区分预期失败和程序缺陷

“商品不存在”是正常业务分支，可以返回结构化错误。 JSON 语法不合法可以捕获 json.JSONDecodeError。变量拼错等程序缺陷应该被修复，不应使用一个空泛的异常捕获把它隐藏。

import json

try:
    json.loads("这不是 JSON")
except json.JSONDecodeError:
    print("输入格式错误，请提供合法 JSON")

练习与验收

为库存工具增加一个商品，然后增加 in_stock 字段，表示库存是否大于零。再传入空字符串、未知商品和库存为零的商品。

已知商品保留 ok: True，即使库存为零。
空字符串和未知商品返回 ok: False。
所有结果都能完成 JSON 编码和解码。
不使用 eval，不依赖网络。

不要把“库存为零”和“查询失败”混在一起；它们需要不同的用户提示。

延伸阅读

下一课会把这个本地函数的输入和输出放到 HTTP 请求的语境中。