Context Engine

Context Engine - 面向 Agent / RAG / AI Coding 的上下文压缩引擎

把噪声日志、检索片段和代码上下文，压缩成大模型更容易使用的高信号输入。

面向 Agent 工作流、RAG 管线、AI Coding 助手的任务感知 Context Compression Layer。

PyPI · GitHub · MCP Registry

---

为什么需要 Context Engine

很多 Agent / RAG / AI Coding 系统的问题，不是“没有上下文”，而是“上下文太脏、太长、太乱”。

日志里有大量重复 heartbeat 和 retry；RAG 检索结果里混着相关与不相关 chunk；代码修复场景里，模型经常拿到一堆文件，却缺少最小修复线索。

Context Engine 解决的是这个中间层问题：

在把内容交给大模型之前，先按任务类型压缩、排序、去噪，并输出结构化的高信号上下文。

它不是普通摘要工具，而是一个更偏工程化的上下文整理层。

---

能力边界问题

---

系统架构

核心理念：先把上下文变成可解释、可预算、可消费的结构，再交给 LLM。

flowchart TB

classDef input fill:#fff7d6,stroke:#d99b00,stroke-width:2px,color:#5c3b00; classDef core fill:#e7f1ff,stroke:#2563eb,stroke-width:2px,color:#123c8c; classDef mode fill:#eaf8ef,stroke:#1f8a4c,stroke-width:2px,color:#0f4f2b; classDef output fill:#f5ecff,stroke:#7c3aed,stroke-width:2px,color:#3f1d7a;

subgraph Inputs["输入层"] CLI["CLI 本地文件 / 示例"]:::input SDK["Python API CompressionRequest"]:::input MCP["MCP Tool compress_context"]:::input end

subgraph Core["核心 Pipeline"] Validate["输入校验 schema + size guard"]:::core Normalize["标准化 ContextItem list"]:::core Dedupe["去重 重复内容折叠"]:::core Budget["预算控制 small / medium / large"]:::core end

subgraph Compressors["任务感知压缩器"] Logs["logs root cause + traceback"]:::mode Rag["rag question-aware evidence"]:::mode Code["code hotspot files + failure signal"]:::mode end

subgraph Outputs["输出契约"] Result["ok: true summary + key facts + llm_ready_context"]:::output Error["ok: false error_code + hint + details"]:::output end

CLI --> Validate SDK --> Validate MCP --> Validate Validate --> Normalize --> Dedupe --> Budget Budget --> Logs Budget --> Rag Budget --> Code Logs --> Result Rag --> Result Code --> Result Validate --> Error

数据流

sequenceDiagram

autonumber participant U as 用户 / Agent participant C as CLI / MCP / SDK participant V as Validator participant P as Pipeline participant M as Mode Compressor participant O as Output Envelope

U->>C: 提交 logs / rag / code 输入 C->>V: 校验字段、大小和模式 V->>P: 标准化为 ContextItem P->>P: 去重、排序、预算裁剪 P->>M: 进入任务压缩器 M->>O: 生成 summary / key_facts / llm_ready_context O-->>U: 返回结构化结果或结构化错误

---

核心能力

1. logs：根因导向的日志压缩

logs 模式面向长日志、重复日志、异常栈和混合噪声。

2. rag：围绕问题的证据重排

rag 模式接收 question 和 chunks，把检索结果从“按召回顺序堆叠”变成“围绕问题排序”。

3. code：最小修复上下文

code 模式接收 issue、可选 test_output 和 files，用于给 AI Coding 助手准备更聚焦的修复输入。

4. CLI + MCP 双入口

同一套压缩逻辑可通过三种方式使用：

---

快速开始

前置要求

安装

python -m venv .venv

.venv\Scripts\Activate.ps1 python -m pip install -e .[dev,mcp]

从 PyPI 安装发布包：

python -m pip install "melonelish-context-engine[mcp]"

运行示例

python -m pytest -q

context-engine --mode logs --input examples/logs/sample.log --budget medium context-engine --mode rag --input examples/rag/sample.json --budget medium context-engine --mode code --input examples/code/sample.json --budget medium

---

CLI 使用

context-engine --mode logs --input examples/logs/sample.log --budget small

context-engine --mode rag --input examples/rag/sample.json --budget medium context-engine --mode code --input examples/code/sample.json --budget large

输入格式

logs：纯文本

2026-07-03 10:01:12 ERROR payment.worker failed to charge order

Traceback (most recent call last): ... ValueError: missing customer_id

rag：JSON

{

"question": "Why did checkout fail?", "chunks": [ { "content": "Checkout fails when customer_id is missing.", "metadata": {"source": "runbook.md"} } ] }

code：JSON

{

"issue": "Checkout test fails when customer_id is omitted.", "test_output": "ValueError: missing customer_id", "files": [ { "path": "src/payments/checkout.py", "content": "def checkout(order): ..." } ] }

---

MCP 使用

通过 stdio 启动 MCP Server：

context-engine-mcp

当前暴露一个工具：

示例错误返回：

{

"ok": false, "error": { "error_code": "invalid_field", "message": "Field 'chunks' must be a non-empty list.", "hint": "Provide at least one item in 'chunks'." } }

---

输出契约

CLI 和 MCP 都返回统一结构：

成功结果会包含 schema version、summary、key facts、被丢弃或降权的噪声，以及 llm_ready_context。

---

安全边界

当前内置限制：

这些限制用于避免外部工作流把任意超大 payload 直接打进工具。

当前已支持

• Python 3.11 到 3.13
• logs / rag / code 三种模式
• 三种模式的 CLI 使用
• 通过 compress_context 暴露 MCP 工具
• 纯文本日志输入
• JSON 格式的 RAG 和 code 输入
• 结构化成功 / 失败 envelope
• 基础 benchmark 和 GitHub Actions CI

暂不支持

• PDF、图片、Office 文件等二进制输入
• embedding-aware reranking
• 仓库级依赖图分析
• 跨未来大版本的长期兼容性承诺
• 生产级鉴权、持久化、监控和审计能力

---

Benchmark

Benchmark 资料位于：

• benchmark_cases.md
• benchmark_results.md

当前样例集体现的行为：

v0.1.0 的 benchmark 还很小，适合作为回归检查和展示样例，不代表完整生产评测。

---

开发

python -m pip install -e .[dev,mcp]

python -m pytest -q python benchmarks/generate_benchmarks.py

CI 会在 push 和 pull request 时运行安装、测试和 benchmark 生成检查。

---

发布状态

当前版本目标：v0.1.0

已发布渠道：

• PyPI: https://pypi.org/project/melonelish-context-engine/
• MCP Registry: https://registry.modelcontextprotocol.io/v0/servers/io.github.melonelish/context-engine

这个版本适合早期外部试用、集成测试和开发者工作流验证。它已经具备可复用包结构、测试、文档，以及可直接安装的 PyPI / MCP Registry 发布入口，但仍然是范围明确的早期 beta。

---

Roadmap

• 引入 embedding 或 reranker 驱动的 RAG 排序。
• 加强 code hotspot 识别，加入更可靠的结构化代码信号。
• 扩展 benchmark，加入更多真实脏数据样本。
• 发布更易安装的正式包版本。
• 增加更多 Agent Runtime / MCP 集成示例。

---

License

本项目采用 MIT License。