code/chapter9/README.md
本目录包含第九章"上下文工程"的所有示例代码和演示文件。
chapter9/
├── 01_context_builder_basic.py # ContextBuilder 基础用法
├── 02_context_builder_with_agent.py # ContextBuilder 与 Agent 集成
├── 03_note_tool_operations.py # NoteTool 基本操作
├── 04_note_tool_integration.py # NoteTool 高级集成
├── 05_terminal_tool_examples.py # TerminalTool 使用示例
├── 06_three_day_workflow.py # 完整三天工作流演示
├── codebase_maintainer.py # 代码库维护助手（核心组件）
├── codebase/ # 示例代码库
│ ├── data_processor.py
│ ├── api_client.py
│ ├── utils.py
│ └── models.py
├── data/ # 示例数据
│ └── sales_2024.csv
├── logs/ # 示例日志
│ └── app.log
└── project/ # 示例项目
├── README.md
└── main.py
所有使用记忆功能的示例都需要配置嵌入模型。最简单的方式：
import os
# 使用 TF-IDF（无需额外依赖或下载）
os.environ['EMBED_MODEL_TYPE'] = 'tfidf'
os.environ['EMBED_MODEL_NAME'] = '' # 必须清空
# 进入 chapter9 目录
cd code/chapter9
# 运行 TerminalTool 示例（无需 LLM）
python 05_terminal_tool_examples.py
# 运行 NoteTool 基本操作（无需 LLM）
python 03_note_tool_operations.py
# 运行完整工作流演示（需要配置 LLM）
python 06_three_day_workflow.py
完整的长程智能体工作流演示，包括：
使用我们创建的示例代码库（./codebase），包含：
data_processor.py - 数据处理模块（含多个 TODO）api_client.py - API 客户端（需要改进错误处理）utils.py - 工具函数（需要优化）models.py - 数据模型（需要补充验证）核心组件：代码库维护助手，集成了：
有三种选择：
import os
os.environ['EMBED_MODEL_TYPE'] = 'tfidf'
os.environ['EMBED_MODEL_NAME'] = '' # 重要！
优点：
缺点：
import os
os.environ['EMBED_MODEL_TYPE'] = 'local'
os.environ['EMBED_MODEL_NAME'] = 'sentence-transformers/all-MiniLM-L6-v2'
os.environ['HF_TOKEN'] = 'your_huggingface_token'
需要：
pip install sentence-transformers配置 HF Token 的方式：
# 方式一：使用 huggingface-cli（推荐，一次配置永久使用）
pip install huggingface-hub
huggingface-cli login
# 方式二：在代码中设置
os.environ['HF_TOKEN'] = 'hf_your_token_here'
# 方式三：命令行设置
export HF_TOKEN="hf_your_token_here"
import os
os.environ['EMBED_MODEL_TYPE'] = 'dashscope'
os.environ['EMBED_MODEL_NAME'] = 'text-embedding-v3'
os.environ['EMBED_API_KEY'] = 'your_dashscope_api_key'
需要：
pip install dashscope如果使用需要 LLM 的示例，需要配置：
from hello_agents import HelloAgentsLLM
# 使用默认配置（需要设置 OPENAI_API_KEY）
llm = HelloAgentsLLM()
# 或者明确指定
llm = HelloAgentsLLM(
api_key="your_api_key",
base_url="https://api.openai.com/v1",
model="gpt-4"
)
建议直接在'.env'文件中设置。
codebase_maintainer.py 已配置为只使用 working 记忆，避免需要 Qdrant 向量数据库：
self.memory_tool = MemoryTool(
user_id=project_name,
memory_types=["working"] # 只使用工作记忆
)
如果需要更强大的记忆功能（episodic, semantic），需要安装并启动 Qdrant：
# 使用 Docker 启动 Qdrant
docker run -p 6333:6333 qdrant/qdrant
包含 40+ 条销售数据，字段包括：
模拟一天的应用日志，包含：
包含 4 个 Python 模块，共 10+ 个 TODO 注释，适合演示：
原因：嵌入模型配置不正确。
解决：确保设置了 EMBED_MODEL_NAME 为空字符串：
os.environ['EMBED_MODEL_TYPE'] = 'tfidf'
os.environ['EMBED_MODEL_NAME'] = '' # 必须有这行！
原因：默认配置尝试连接 Qdrant 向量数据库。
解决方案一（推荐）：使用只需 working 记忆的配置（已在 codebase_maintainer.py 中配置）
解决方案二：安装并启动 Qdrant：
docker run -p 6333:6333 qdrant/qdrant
原因：网络问题或缺少 Token。
解决方案：
export HF_ENDPOINT=https://hf-mirror.comos.environ['EMBED_MODEL_TYPE'] = 'tfidf'原因：TerminalTool 有白名单限制，只允许安全的命令。
解决：使用允许的命令列表中的命令，如：
先运行无需 LLM 的示例：
03_note_tool_operations.py - 了解 NoteTool05_terminal_tool_examples.py - 了解 TerminalTool配置嵌入模型后运行：
01_context_builder_basic.py - 理解上下文管理配置 LLM 后运行：
02_context_builder_with_agent.py - Agent 集成04_note_tool_integration.py - 高级集成06_three_day_workflow.py - 完整工作流01_context_builder_basic.py03_note_tool_operations.py, 05_terminal_tool_examples.py02_context_builder_with_agent.py04_note_tool_integration.py06_three_day_workflow.pydocs/chapter9/第九章 上下文工程.md如有问题或建议，欢迎提 Issue 或 PR！