智能体工程：从一句话到一个闭环 — 配套代码

《智能体工程：从一句话到一个闭环》（Prompt · Context · Harness · Loop）的配套代码仓库。

代码仓库地址：https://github.com/LiuZhen515/agent-engineering-code 书稿仓库地址：https://github.com/LiuZhen515/agent_engineering 请先克隆本仓库，然后按照以下说明配置环境并运行各章代码。

---

环境配置

1. 安装依赖

python -m venv venv
source venv/bin/activate      # Linux / macOS
# venv\Scripts\activate       # Windows
pip install -r requirements.txt

2. 配置环境变量

在终端中设置以下环境变量：

# 【必设】API 密钥
export OPENAI_API_KEY=*** #API 密钥

# 【必设】API 地址
# 如果你使用 OpenAI 官方 API：
export OPENAI_BASE_URL=https://api.openai.com/v1
#
# 如果你在中国大陆，可以使用以下国内兼容接口：
#   DeepSeek:    export OPENAI_BASE_URL=https://api.deepseek.com/v1
#   月之暗面:   export OPENAI_BASE_URL=https://api.moonshot.cn/v1
#   通义千问:   export OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
#   GPU Stack:  export OPENAI_BASE_URL=http://<your-server>:11434/v1

# 【可选】模型名称（不设置时默认使用 gpt-4o-mini）
export LLM_MODEL_NAME=gpt-4o-mini

注意：logprobs_demo.py（Listing 2.1）需要模型支持 logprobs 参数。 已知支持的模型：gpt-4o-mini、gpt-4o、gpt-4-turbo。 不支持的模型：DeepSeek 全系列（脚本会自动检测并给出诊断提示）。

3. 验证配置

# 验证 API 是否正常工作
python part1-prompt/ch3-cot-examples/json_repair.py

# 运行所有 pytest 测试
pytest part1-prompt/ch4-prompt-eval/
pytest benchmarks/eval-scripts/

---

目录结构

agent-engineering-code/
├── requirements.txt              # Python 依赖
├── README.md                     # 本文件
│
├── part1-prompt/                 # 第一部分 · 提示词工程（第 2-4 章）
│   ├── ch2-logprobs-demo/        #   Listing 2.1 — logprobs 诊断
│   ├── ch3-cot-examples/         #   Listing 3.2 — JSON 修复型重试
│   └── ch4-prompt-eval/          #   Listing 4.2-4.3 — Golden Set 回归 & 双层评分
│
├── part2-context/                # 第二部分 · 上下文工程（第 5-8 章）
│   ├── ch6-rag-pipeline/         #   Listing 6.1 — RRF 融合
│   └── ch7-memory-system/        #   记忆评分模型（§7.2.3）
│
├── part3-harness/                # 第三部分 · 驾驭工程（第 9-12 章）
│   └── mini-harness/             #   Listing 9.2 — 最小 Harness 核心循环
│                                 #   Listing 10.1 — 原子工具四件套
│
├── part4-loop/                   # 第四部分 · 循环工程（第 13-16 章）
│   ├── ch13-react-loop/          #   Listing 13.1 — ReAct 循环
│   └── ch14-critic-agent/        #   Listing 14.1 — 多 Agent 辩论
│
└── benchmarks/                   # 基准评测
    └── eval-scripts/             #   ECL 测试 & 评分稳定性（第 18 章）

---

各章代码运行指南

章节	Listing	文件	运行命令	需要 API
Ch2	2.1	part1-prompt/ch2-logprobs-demo/logprobs_demo.py	python logprobs_demo.py	是（需 logprobs 支持）
Ch3	3.2	part1-prompt/ch3-cot-examples/json_repair.py	python json_repair.py	是
Ch4	4.2	part1-prompt/ch4-prompt-eval/golden_set_tests.py	pytest golden_set_tests.py	否（模拟输出）
Ch4	4.3	part1-prompt/ch4-prompt-eval/double_layer_scoring.py	pytest double_layer_scoring.py	是（LLM Judge）
Ch6	6.1	part2-context/ch6-rag-pipeline/rrf_fusion.py	python rrf_fusion.py	否
Ch7	§7.2.3	part2-context/ch7-memory-system/incremental_summary.py	python incremental_summary.py	否（演示模式）
Ch9	9.2	part3-harness/mini-harness/harness.py	python harness.py	是
Ch10	10.1	part3-harness/mini-harness/tools.py	python tools.py	否
Ch13	13.1	part4-loop/ch13-react-loop/react_cycle.py	python react_cycle.py	是
Ch14	14.1	part4-loop/ch14-critic-agent/debate_framework.py	python debate_framework.py	是
Ch18	ECL	benchmarks/eval-scripts/eval_helpers.py	pytest eval_helpers.py	否

---

运行全部测试

# 安装依赖后，在仓库根目录执行：
pytest part1-prompt/ch4-prompt-eval/ benchmarks/eval-scripts/ -v

预期输出：7 passed

---

许可证

本仓库代码采用 MIT 许可证。你可以自由使用、修改和分发，只需保留版权声明。

---

贡献指南

欢迎提交 Issue 和 Pull Request。在提交 PR 前请确保所有 pytest 测试通过。

本地测试

cd agent-engineering-code
pip install -r requirements.txt
python -m pytest

代码风格

• 禁止 hardcode API key——统一通过环境变量 OPENAI_API_KEY、OPENAI_BASE_URL、LLM_MODEL_NAME 读取，缺少时打印中文错误提示
• 禁止 numpy 依赖（统一使用 statistics 和 random 标准库）