context-engine

Context Engine - AI Agent 上下文管理

Context Engine 提供用于管理 AI Agent 所知、所记及所检索内容的生产级模式。它涵盖完整生命周期：项目知识的摄取、上下文窗口的最优填充、跨会话的持久记忆，以及针对大型代码库的检索增强生成。实用 Agent 与会产生幻觉的 Agent 之间的区别，在于上下文管理。

核心能力

• 上下文窗口架构 — 令牌预算分配，以及贪心、分层和自适应压缩填充策略。
• 记忆架构 — 三层模型（工作记忆 / 会话记忆 / 知识库）、提升协议和过时检测。
• 代码检索 — 文件级、分块级（RAG）和依赖感知检索，并提供代码分块与嵌入指导。
• 知识图谱构建 — 代码库图谱架构（节点 + 边）和可解答 Agent 问题的图查询。
• 窗口优化模式 — 带锚点的滑动窗口、渐进式摘要、选择性缓存工具结果。
• 记忆工具与上下文编辑 — 跨会话的文件支持型持久记忆，以及上下文压缩（清除过时的工具输出、对历史进行摘要并替换），以避免长循环耗尽窗口。
• 长上下文策略 — 何时使用 1M 令牌窗口、RAG 或混合 Agent 循环，大型窗口中的预算分配，以及位置 / 注意力效应。
• 多 Agent 上下文共享 — 共享上下文总线和五要素交接协议。

适用场景

• 为新的代码库引导 Agent 上下文（索引 → 图谱 → 摘要 → 分层）。
• 针对特定任务优化上下文（修复缺陷、开发功能、重构、审查）。
• 跨会话捕获、提升和精简会话记忆。
• 设计代码检索的 RAG 流程。
• 协调多个协作 Agent 之间的上下文。

先行确认

设计或分析之前，请确认以下输入。如有任何未知或含糊之处，请先询问，不要擅自假设：

• 任务类型 — 为代码库引导上下文、针对特定任务优化、设计持久记忆，还是构建代码 RAG（决定使用哪个分析器 / 精简器 / 索引器，以及采用哪种操作手册）
• 令牌预算 — 上下文窗口上限（用于设置 --budget 并确定适用的填充策略）
• 源内容 — 要编入索引的文件 / 代码库或知识库（脚本处理的输入）

停止规则：只询问最能影响输出的 2-3 项。如果用户说“先起草吧”，则继续，并在产物开头列出假设。

工具

工具	用途	命令
context_analyzer.py	分析文件 / 提示词的令牌用量、相关性和优化建议	python scripts/context_analyzer.py src/ --budget 128000 --json
context_pruner.py	精简上下文中的低相关内容、冗余内容和冗长模式	python scripts/context_pruner.py src/main.py --aggressive --json
memory_indexer.py	使用 TF-IDF 相关性评分为记忆 / 知识库编制索引并进行搜索	python scripts/memory_indexer.py docs/ --query 'auth middleware' --top 5
context_budget_planner.py	在各组件之间分配窗口、标记超额，并建议优先压缩 / 清除哪些内容	python scripts/context_budget_planner.py --window-size 200000 --system 4000 --history 60000 --tools 90000 --rag 40000 --reserve-output 8000

参考资料

加载与任务匹配的参考资料 — 保持此文件精简，按需查阅详细内容：

• references/context-window-strategies.md — 预算分配、打包策略和窗口优化模式。规划预算或优化长对话时阅读。
• references/memory-architecture-guide.md — 三层记忆模型、晋升协议、过时检测、共享上下文总线与交接协议。设计持久化记忆或协调 Agent 时阅读。
• references/code-retrieval-patterns.md — 文件／代码块／依赖感知检索、代码块划分／嵌入指南、知识图谱架构与查询。构建代码 RAG 时阅读。
• references/memory-and-context-editing.md — 记忆工具模式（基于文件的记忆、存储与重新计算的内容、保留期限、安全性）以及上下文编辑／压缩（驱逐优先级、总结并替换、节省令牌的收益），以及二者如何融入 Agent 循环。跨会话持久化状态或防止长循环耗尽上下文窗口时阅读。
• references/long-context-strategies.md — 长上下文、RAG 与混合方案的决策，1M 令牌窗口的预算分配，位置／注意力效应，以及更大的窗口何时会带来负面影响（成本、延迟、干扰）。选择窗口与检索策略时阅读。
• references/workflows-and-quality.md — 三种工作流、反模式、评估指标、故障排查和成功标准。运行工作流前及发布前阅读。

范围与限制

本技能涵盖：

• 面向 AI 编码 Agent 的上下文窗口令牌预算规划、分配策略和打包算法。
• 多层记忆架构设计（工作记忆、会话记忆、知识库），包括晋升与过时处理协议。
• 代码专用检索策略，包括用于 RAG 流水线的文件级、代码块级和依赖感知检索。
• 从代码库构建知识图谱，以及面向 Agent 工作流的基于图谱的上下文查询。

本技能不涵盖：

• 向量存储基础设施搭建、嵌入模型选择或数据库部署 — 向量存储设计和嵌入策略请参阅 rag-architect。
• Agent 角色定义、个性设计或多 Agent 编排逻辑 — Agent 架构请参阅 agent-designer，编排模式请参阅 agent-workflow-designer。
• Agent 系统的运行时可观测性、指标仪表板或告警 — 监控和检测请参阅 observability-designer。
• 提示词工程技术、思维链设计或指令微调 — 提示词构建模式请参阅 prompt-engineer-toolkit。

集成点

技能	集成方式	数据流
rag-architect	Context Engine 定义检索策略；RAG Architect 实现向量存储和嵌入流程	检索查询从 Context Engine 流向 RAG Architect 的索引存储；排序后的结果以上下文片段的形式返回
agent-designer	Agent Designer 定义 Agent 的角色和能力；Context Engine 管理每个 Agent 的上下文预算和记忆层	Agent 规范定义上下文需求；Context Engine 根据每个 Agent 的角色返回定制的上下文窗口
self-improving-agent	Self-Improving Agent 识别反复出现的模式和纠正内容；Context Engine 决定何时将所学内容提升为持久记忆	候选学习内容从 Self-Improving Agent 流入；提升决策和记忆更新通过 Context Engine 的过时检测与提升协议返回
observability-designer	Observability Designer 为上下文利用率指标（相关性、过时程度、缓存命中）添加监测；Context Engine 暴露指标端点	原始指标事件从 Context Engine 流出；Observability Designer 将其汇总为仪表板和警报
agent-workflow-designer	Agent Workflow Designer 定义多 Agent 移交序列；Context Engine 实现共享上下文总线和移交协议	工作流定义指定哪些 Agent 共享上下文；Context Engine 管理上下文总线、序列化和移交载荷
codebase-onboarding	Codebase Onboarding 生成项目摘要和架构图；Context Engine 将其作为 Tier 0 引导上下文使用	入门材料（项目摘要、目录映射、入口点）馈入 Context Engine 的初始知识图谱和上下文层