agent

《AI Agent 开发入门》附录 C.环境与离线复现速查

本附录固定全书的环境口径：Python 3.14.6 与 Node 26.5.0 的实测版本表、用中科大源建 venv 与装依赖的步骤（清华源与阿里云源在本机不可用）、Node 26 只支持类型擦除的可擦除语法规则、离线复现的必需与可选依赖清单，以及 postgres:17-alpine 与 redis:7-alpine 的本地起法。

Leeting Yan 5 分钟阅读 2038 字

卷一从头到尾只需要一条命令就能跑起来：建好 venv、装上几个纯标准库之外的可选依赖、再准备两个本地服务。这一页把版本、安装口径、TypeScript 的可擦除语法约束、离线清单和 Docker 起法全部固定下来，避免你在环境上反复试错。

本附录所有版本号与命令都在本机实测过；标了「不可用」的源是真实失败，不是传闻。

C.1 实测版本表

正文提到版本号时以此表为准。

组件实测版本备注
Python3.14.6（Homebrew）venv 在 /tmp/agentbook/venv
Node26.5.0 / npm 11.17.0TS 直接 node file.ts 运行
anthropic1.13.0Python SDK，可选项
pydantic2.14.0参数校验，可选项
httpx0.28.1可选项
pytest9.1.1测试，推荐
pytest-asyncio1.4.0异步测试，可选项
fastapi0.143.0第 17 章服务层，可选项
uvicorn0.54.0可选项
starlette1.7.0随 FastAPI 安装
anyio4.15.1随 FastAPI 安装
@anthropic-ai/sdk0.133.0Node SDK，可选项
@modelcontextprotocol/sdk1.32.1Node MCP SDK，可选项
typescript7.0.2仅用于 tsc --noEmit

关键前提：minagent 引擎（卷一绝大部分章节）只用 Python 标准库——dataclasses / typing / json / asyncio / sqlite3 / math / re / hashlib。pydantic / FastAPI / httpx / anthropic 只在明确写「可选」「工程化」的章节出现，不装也能跑完前 16 章。

C.2 Python 环境

C.2.1 建 venv

python3.14 -m venv /tmp/agentbook/venv
source /tmp/agentbook/venv/bin/activate
python --version        # Python 3.14.6

Windows 上用 \tmp\agentbook\venv\Scripts\activate；本文后续一律用 python 代指该 venv 里的解释器。

C.2.2 pip 源：必须用中科大源

PyPI 官方源、清华源、阿里云源在本机 pip 下都不可靠，只有中科大源稳定：

python -m pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple <pkg>
源地址本机实测
中科大（推荐）https://mirrors.ustc.edu.cn/pypi/simple正常
清华https://pypi.tuna.tsinghua.edu.cn/simple不可用：No matching distribution found
阿里云https://mirrors.aliyun.com/pypi/simple不完整：pydantic wheel 元数据 404
PyPI 官方https://pypi.org/simple不稳定，不要作主路径

想省事可以把源写进配置，之后 pip install 自动走中科大：

python -m pip config set global.index-url https://mirrors.ustc.edu.cn/pypi/simple

C.2.3 装依赖

# 必需：测试框架
python -m pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple pytest

# 可选：第 17 章服务层
python -m pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple \
    fastapi uvicorn httpx

# 可选：第 18 章真实 API 冒烟
python -m pip install --index-url https://mirrors.ustc.edu.cn/pypi/simple \
    anthropic pydantic pytest-asyncio

C.3 Node 与 TypeScript

C.3.1 关键约束：只有类型擦除

Node 26 只支持「类型擦除」（type stripping），不支持 --experimental-transform-types（会直接报 bad option）。这意味着：所有 TS 示例必须只用可擦除语法，类型注解被逐字删掉后剩下的就是合法 JS。

语法能否擦除处理
类型注解 x: number可以直接用
interface / type 别名可以直接用
as 断言、泛型参数可以直接用
参数属性 constructor(public x: number)不行声明字段 + 函数体内赋值
enum不行用 const 对象 + 联合类型
namespace不行用普通模块导出

违规会抛 SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]，例如参数属性：

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

C.3.2 可擦除写法的构造函数

class Agent {
  model: string;
  maxSteps: number;

  constructor(model: string, maxSteps: number) {
    this.model = model;       // 在函数体内赋值，而不是参数属性
    this.maxSteps = maxSteps;
  }
}

console.log(new Agent("fake-1", 8).maxSteps);   // 8

node ok_erasable.ts 零构建直接执行；把上面换成 constructor(public model: string, ...) 立刻报错。

C.3.3 运行与类型检查

node file.ts                 # 直接跑，无需编译
npx tsc --noEmit             # 只做类型检查，不产出文件

tsconfig.json 里打开 "erasableSyntaxOnly": true，让 tsc 主动拦住不可擦除语法：

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  },
  "include": ["**/*.ts"]
}

C.3.4 npm 依赖（第 17 章）

第 17 章的 TS 客户端需要一个最小的 package.json，"type": "module" 是必须的：

{
  "name": "minagent-ts",
  "private": true,
  "type": "module",
  "version": "0.0.0",
  "dependencies": {
    "@anthropic-ai/sdk": "^0.133.0",
    "@modelcontextprotocol/sdk": "^1.32.1"
  },
  "devDependencies": {
    "typescript": "^7.0.2"
  }
}

npm install                  # 安装上面三个包
node probe.ts                # 零构建跑通，验证 SDK 可导入

probe.ts 只构造 SDK 客户端、不发任何网络请求，因此离线也能跑。它验证的是「Node 26 能直接执行可擦除 TS」与「SDK 能被导入」两件事。

C.4 离线复现清单

把这一节当成「断网时我还能跑什么」的核对表。

依赖必需性缺了会怎样
Python 3.14.x必需引擎用了 list[str] | None 等新语法
pytest推荐无法跑确定性测试，但示例脚本仍可 python 直跑
pydantic可选只影响第 4 章参数校验的「工程化」变体
fastapi / uvicorn / httpx可选只影响第 17 章服务层
anthropic可选只影响第 18 章真实 API 冒烟
Node 26 + typescript可选只影响第 17 章 TS 客户端
@anthropic-ai/sdk / MCP SDK可选同上
Docker可选只影响需要真数据库的章节

断网也能跑完前 16 章：minagent 引擎零第三方依赖，假模型零凭据，测试零网络。只有第 17–18 章的服务层、TS 客户端与真实冒烟需要额外依赖。

C.5 本地服务（Docker）

需要真数据库时用 Docker 起，端口映射到非默认值以免和本机已有实例冲突。

docker run -d --name minagent-pg \
  -e POSTGRES_PASSWORD=devpass -e POSTGRES_DB=minagent \
  -p 55432:5432 postgres:17-alpine

docker run -d --name minagent-redis \
  -p 56379:6379 redis:7-alpine

健康检查：

docker exec minagent-pg pg_isready -U postgres      # accepting connections
docker exec minagent-redis redis-cli ping           # PONG

两个镜像本机均已就绪（postgres:17-alpine 415MB、redis:7-alpine 58.7MB），docker info 的 Server Version 为 29.5.2。用完清理：

docker rm -f minagent-pg minagent-redis

连接串：

postgresql://postgres:devpass@127.0.0.1:55432/minagent
redis://127.0.0.1:56379/0

C.6 网络与真实 API

目标可达性本书态度
api.anthropic.com可达第 18 章可做一次冒烟，需你同意
api.openai.com不可达只讲接口设计与对照，不作可运行主路径
中科大 pip 源可达唯一推荐的装包源

假模型是默认路径。全书的示例、测试、断言都用 FakeModel，不需要任何密钥。真实 API 调用只在每卷末尾一次，且须先获得你明确同意才消耗额度。正文与代码里绝不出现真实密钥，只写 os.environ["ANTHROPIC_API_KEY"] 或占位符 "sk-ant-***"。

C.7 一分钟自检

python --version                    # Python 3.14.6
node --version                      # v26.5.0
python -c "import minagent; print(minagent.__all__[:3])"
node /tmp/agentbook/ts/probe.ts     # 可擦除 TS 直接跑通
python -m pytest -q                 # 确定性测试全绿

四条都过，说明你的环境与本书一致。任何一条失败，先回到 C.2 的 venv 与 pip 源、C.3 的可擦除语法、或 C.5 的 Docker 服务排查。真实模型与假模型的差异不在环境层，而在 Model.complete() 的实现——换后端不改环境，也不改上层循环。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「agent」更多文章

  1. 《AI Agent 高级编程》目录
  2. 《AI Agent 高级编程》11.3 全景回顾：从零到框架的完整路径与展望
  3. 《AI Agent 高级编程》11.2 真实 API 冒烟：假模型 vs 真模型量化差距