文章目录
- [上下文工程 知识树](#上下文工程 知识树)
文档来源 https://github.com/datawhalechina/hello-agents/blob/main/docs/chapter9/
上下文工程 知识树
一、ContextBuilder（hello_agents/context/builder.py）
核心定位
实现GSSC流水线，统一上下文管理接口，保障token预算内高价值信息留存
核心数据结构
- ContextPacket：信息基本单元，封装content/timestamp/token_count/relevance_score/metadata，含__post_init__参数校验
- ContextConfig：配置管理，含max_tokens/reserve_ratio/min_relevance等参数，__post_init__验证参数合法性
GSSC流水线实现（核心函数）
- Gather（_gather）：多源信息汇集，容错机制包裹外部调用，系统指令高优先级，对话历史仅保留最近N条，整合系统指令/记忆/RAG/对话历史/自定义包
- Select（_select）：智能信息选择，分离系统指令与其他信息，计算综合分数（相关性×权重+新近性×权重），贪心算法按分填充token，_calculate_relevance（杰卡德相似度）/_calculate_recency（指数衰减模型）辅助评分
- Structure（_structure）：结构化输出，按类型分组信息，构建Role \& Policies/Task/Evidence/Context/Output分区模板
- Compress（_compress）：兜底压缩，分区压缩保持结构完整，超限则截断，_truncate_text/_count_tokens实现文本截断与token估算
核心功能函数
- build：整合GSSC全流程，对外提供上下文构建入口
集成与实践
- 与Agent集成：封装为ContextAwareAgent，run方法中自动构建上下文并调用LLM
- 最佳实践：动态调整token预算、向量相似度优化相关性计算、缓存不变内容、监控日志、A/B测试参数
二、NoteTool（hello_agents/tools/builtin/note_tool.py）
核心定位
Markdown+YAML结构化笔记，智能体持久化记忆管理，适配长时程任务
存储格式
- 单笔记文件：YAML前置元数据（id/title/type/tags等）+Markdown正文
- 索引文件：notes_index.json，维护笔记元数据与文件路径，支持快速检索
核心操作函数（七大核心）
- _create_note：生成唯一ID，构建元数据与MD内容，保存文件并更新索引，_build_markdown辅助构建文件格式
- _read_note：根据note_id读取文件，_parse_markdown分离YAML与正文，返回元数据+内容
- _update_note：更新笔记字段，刷新时间戳，重新构建并保存文件，同步更新索引
- _search_notes：按query/type/tags过滤，标题+内容检索，按更新时间排序
- _list_notes：按type/tags过滤，返回笔记元数据，按更新时间倒序
- _summary：生成笔记统计，含总数/类型分布/最近更新笔记
- _delete_note：删除笔记文件，从索引中移除并保存索引
核心集成函数
- run：统一调用入口，分发不同action至对应核心操作函数
- _notes_to_packets：将笔记转换为ContextPacket，适配ContextBuilder
与ContextBuilder集成
在Agent的run方法中检索相关笔记，转换为ContextPacket传入build方法，按笔记类型设置相关性分数
三、TerminalTool（hello_agents/tools/builtin/terminal_tool.py）
核心定位
安全的命令行执行能力，支持即时文件系统操作，实现JIT上下文检索
安全机制
- 命令白名单：仅允许ls/cat/grep等只读/文本处理命令
- 沙箱隔离：限制工作目录，禁止访问外部路径与通过...逃逸
- 超时控制：设置command执行超时时间，防止资源耗尽
- 输出限制：限制命令输出大小，避免内存溢出
核心功能函数
- _execute_command：执行命令，cwd指定当前目录，捕获stdout/stderr，检查输出大小与返回码，处理超时/异常
- _handle_cd：专属处理cd命令，解析目标路径，校验是否在工作目录内，更新当前目录
- run：统一调用入口，校验命令白名单，分发cd命令至_handle_cd，其余至_execute_command
典型使用模式
探索式导航、数据文件分析、日志文件分析、代码库分析
与其他工具协同
- 与MemoryTool：将文件系统探索结果存入语义记忆
- 与NoteTool：将关键发现记录为blocker/action等类型笔记
- 与ContextBuilder：将命令输出转换为ContextPacket，传入build方法补充上下文
四、三大工具整合实战-代码库维护助手
核心架构
整合ContextBuilder+NoteTool+TerminalTool+MemoryTool，实现跨会话长程任务管理
核心类：CodebaseMaintainer
- init：初始化LLM与所有工具，配置ContextConfig，初始化对话历史与统计信息
- run：按模式预处理（探索/分析/规划），检索相关笔记并转换为ContextPacket，构建上下文调用LLM，后处理自动创建笔记，更新对话历史
- 模式化函数：explore/analyze/plan_next_steps，封装不同模式的run调用
- 工具封装函数：execute_command/create_note，直接调用TerminalTool/NoteTool并更新统计
- 统计与报告：get_stats/generate_report，收集会话数据，生成并保存JSON报告
核心流程
探索代码库→分析代码质量→规划重构任务→跨会话追踪进度，自动化记录问题与计划