文档来源 https://github.com/datawhalechina/hello-agents/blob/main/docs/chapter9/

上下文工程 知识树

一、ContextBuilder（hello_agents/context/builder.py）

核心定位

实现GSSC流水线，统一上下文管理接口，保障token预算内高价值信息留存

核心数据结构

1. ContextPacket：信息基本单元，封装content/timestamp/token_count/relevance_score/metadata，含__post_init__参数校验
2. ContextConfig：配置管理，含max_tokens/reserve_ratio/min_relevance等参数，__post_init__验证参数合法性

GSSC流水线实现（核心函数）

1. Gather（_gather）：多源信息汇集，容错机制包裹外部调用，系统指令高优先级，对话历史仅保留最近N条，整合系统指令/记忆/RAG/对话历史/自定义包
2. Select（_select）：智能信息选择，分离系统指令与其他信息，计算综合分数（相关性×权重+新近性×权重），贪心算法按分填充token，_calculate_relevance（杰卡德相似度）/_calculate_recency（指数衰减模型）辅助评分
3. Structure（_structure）：结构化输出，按类型分组信息，构建[Role & Policies]/[Task]/[Evidence]/[Context]/[Output]分区模板
4. Compress（_compress）：兜底压缩，分区压缩保持结构完整，超限则截断，_truncate_text/_count_tokens实现文本截断与token估算

核心功能函数

1. build：整合GSSC全流程，对外提供上下文构建入口

集成与实践

1. 与Agent集成：封装为ContextAwareAgent，run方法中自动构建上下文并调用LLM
2. 最佳实践：动态调整token预算、向量相似度优化相关性计算、缓存不变内容、监控日志、A/B测试参数

二、NoteTool（hello_agents/tools/builtin/note_tool.py）

核心定位

Markdown+YAML结构化笔记，智能体持久化记忆管理，适配长时程任务

存储格式

1. 单笔记文件：YAML前置元数据（id/title/type/tags等）+Markdown正文
2. 索引文件：notes_index.json，维护笔记元数据与文件路径，支持快速检索

核心操作函数（七大核心）

1. _create_note：生成唯一ID，构建元数据与MD内容，保存文件并更新索引，_build_markdown辅助构建文件格式
2. _read_note：根据note_id读取文件，_parse_markdown分离YAML与正文，返回元数据+内容
3. _update_note：更新笔记字段，刷新时间戳，重新构建并保存文件，同步更新索引
4. _search_notes：按query/type/tags过滤，标题+内容检索，按更新时间排序
5. _list_notes：按type/tags过滤，返回笔记元数据，按更新时间倒序
6. _summary：生成笔记统计，含总数/类型分布/最近更新笔记
7. _delete_note：删除笔记文件，从索引中移除并保存索引

核心集成函数

1. run：统一调用入口，分发不同action至对应核心操作函数
2. _notes_to_packets：将笔记转换为ContextPacket，适配ContextBuilder

与ContextBuilder集成

在Agent的run方法中检索相关笔记，转换为ContextPacket传入build方法，按笔记类型设置相关性分数

三、TerminalTool（hello_agents/tools/builtin/terminal_tool.py）

核心定位

安全的命令行执行能力，支持即时文件系统操作，实现JIT上下文检索

安全机制

1. 命令白名单：仅允许ls/cat/grep等只读/文本处理命令
2. 沙箱隔离：限制工作目录，禁止访问外部路径与通过…逃逸
3. 超时控制：设置command执行超时时间，防止资源耗尽
4. 输出限制：限制命令输出大小，避免内存溢出

核心功能函数

1. _execute_command：执行命令，cwd指定当前目录，捕获stdout/stderr，检查输出大小与返回码，处理超时/异常
2. _handle_cd：专属处理cd命令，解析目标路径，校验是否在工作目录内，更新当前目录
3. run：统一调用入口，校验命令白名单，分发cd命令至_handle_cd，其余至_execute_command

典型使用模式

探索式导航、数据文件分析、日志文件分析、代码库分析

与其他工具协同

1. 与MemoryTool：将文件系统探索结果存入语义记忆
2. 与NoteTool：将关键发现记录为blocker/action等类型笔记
3. 与ContextBuilder：将命令输出转换为ContextPacket，传入build方法补充上下文

四、三大工具整合实战-代码库维护助手

核心架构

整合ContextBuilder+NoteTool+TerminalTool+MemoryTool，实现跨会话长程任务管理

核心类：CodebaseMaintainer

1. init：初始化LLM与所有工具，配置ContextConfig，初始化对话历史与统计信息
2. run：按模式预处理（探索/分析/规划），检索相关笔记并转换为ContextPacket，构建上下文调用LLM，后处理自动创建笔记，更新对话历史
3. 模式化函数：explore/analyze/plan_next_steps，封装不同模式的run调用
4. 工具封装函数：execute_command/create_note，直接调用TerminalTool/NoteTool并更新统计
5. 统计与报告：get_stats/generate_report，收集会话数据，生成并保存JSON报告

核心流程

探索代码库→分析代码质量→规划重构任务→跨会话追踪进度，自动化记录问题与计划