{
  "markdown": "# Context Engine - 面向 Agent / RAG / AI Coding 的上下文压缩引擎\n\n<!-- mcp-name: io.github.melonelish/context-engine -->\n\n<p align=\"center\">\n  <strong>把噪声日志、检索片段和代码上下文，压缩成大模型更容易使用的高信号输入。</strong>\n</p>\n\n<p align=\"center\">\n  面向 Agent 工作流、RAG 管线、AI Coding 助手的任务感知 Context Compression Layer。\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-blue?style=flat-square&logo=python\" alt=\"Python\">\n  <img src=\"https://img.shields.io/badge/CLI-Typer-green?style=flat-square\" alt=\"Typer CLI\">\n  <img src=\"https://img.shields.io/badge/MCP-fastmcp-orange?style=flat-square\" alt=\"MCP\">\n  <img src=\"https://img.shields.io/badge/License-MIT-black?style=flat-square\" alt=\"License\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/melonelish-context-engine/\">PyPI</a>\n  ·\n  <a href=\"https://github.com/melonelish/context-engine\">GitHub</a>\n  ·\n  <a href=\"https://registry.modelcontextprotocol.io/v0/servers/io.github.melonelish/context-engine\">MCP Registry</a>\n</p>\n\n---\n\n## 为什么需要 Context Engine\n\n很多 Agent / RAG / AI Coding 系统的问题，不是“没有上下文”，而是“上下文太脏、太长、太乱”。\n\n日志里有大量重复 heartbeat 和 retry；RAG 检索结果里混着相关与不相关 chunk；代码修复场景里，模型经常拿到一堆文件，却缺少最小修复线索。\n\n`Context Engine` 解决的是这个中间层问题：\n\n> 在把内容交给大模型之前，先按任务类型压缩、排序、去噪，并输出结构化的高信号上下文。\n\n它不是普通摘要工具，而是一个更偏工程化的上下文整理层。\n\n---\n\n## 能力边界问题\n\n| 场景 | 直接丢给模型 | Context Engine |\n|:---|:---|:---|\n| 长日志 / traceback | 复制全部日志，或者简单截断 | 保留疑似根因、traceback 尾部，折叠重复噪声 |\n| RAG 检索结果 | 按检索顺序塞入所有 chunk | 围绕用户问题重新排序，区分高信号与低信号证据 |\n| AI Coding 修复 | 把附近文件全部塞进去 | 根据 issue / test output 排序 hotspot file |\n| 输入异常 | 抛原始 traceback | 返回结构化错误、错误码和修复提示 |\n| Token 不够 | 从头或从尾硬切 | 在标准化和去重后按预算裁剪 |\n\n---\n\n## 系统架构\n\n**核心理念**：先把上下文变成可解释、可预算、可消费的结构，再交给 LLM。\n\n```mermaid\nflowchart TB\n    classDef input fill:#fff7d6,stroke:#d99b00,stroke-width:2px,color:#5c3b00;\n    classDef core fill:#e7f1ff,stroke:#2563eb,stroke-width:2px,color:#123c8c;\n    classDef mode fill:#eaf8ef,stroke:#1f8a4c,stroke-width:2px,color:#0f4f2b;\n    classDef output fill:#f5ecff,stroke:#7c3aed,stroke-width:2px,color:#3f1d7a;\n\n    subgraph Inputs[\"输入层\"]\n        CLI[\"CLI<br/>本地文件 / 示例\"]:::input\n        SDK[\"Python API<br/>CompressionRequest\"]:::input\n        MCP[\"MCP Tool<br/>compress_context\"]:::input\n    end\n\n    subgraph Core[\"核心 Pipeline\"]\n        Validate[\"输入校验<br/>schema + size guard\"]:::core\n        Normalize[\"标准化<br/>ContextItem list\"]:::core\n        Dedupe[\"去重<br/>重复内容折叠\"]:::core\n        Budget[\"预算控制<br/>small / medium / large\"]:::core\n    end\n\n    subgraph Compressors[\"任务感知压缩器\"]\n        Logs[\"logs<br/>root cause + traceback\"]:::mode\n        Rag[\"rag<br/>question-aware evidence\"]:::mode\n        Code[\"code<br/>hotspot files + failure signal\"]:::mode\n    end\n\n    subgraph Outputs[\"输出契约\"]\n        Result[\"ok: true<br/>summary + key facts + llm_ready_context\"]:::output\n        Error[\"ok: false<br/>error_code + hint + details\"]:::output\n    end\n\n    CLI --> Validate\n    SDK --> Validate\n    MCP --> Validate\n    Validate --> Normalize --> Dedupe --> Budget\n    Budget --> Logs\n    Budget --> Rag\n    Budget --> Code\n    Logs --> Result\n    Rag --> Result\n    Code --> Result\n    Validate --> Error\n```\n\n### 数据流\n\n```mermaid\nsequenceDiagram\n    autonumber\n    participant U as 用户 / Agent\n    participant C as CLI / MCP / SDK\n    participant V as Validator\n    participant P as Pipeline\n    participant M as Mode Compressor\n    participant O as Output Envelope\n\n    U->>C: 提交 logs / rag / code 输入\n    C->>V: 校验字段、大小和模式\n    V->>P: 标准化为 ContextItem\n    P->>P: 去重、排序、预算裁剪\n    P->>M: 进入任务压缩器\n    M->>O: 生成 summary / key_facts / llm_ready_context\n    O-->>U: 返回结构化结果或结构化错误\n```\n\n---\n\n## 核心能力\n\n### 1. logs：根因导向的日志压缩\n\n`logs` 模式面向长日志、重复日志、异常栈和混合噪声。\n\n| 能力 | 说明 |\n|:---|:---|\n| 根因提取 | 优先保留 error、exception、failed、fatal 等关键行 |\n| Traceback 保留 | 保留更接近根因的 traceback 尾部 |\n| 噪声折叠 | 把重复 heartbeat、poll、retry、duplicate line 归并成计数 |\n| LLM-ready 输出 | 生成可以直接放进诊断或修复 prompt 的上下文块 |\n\n### 2. rag：围绕问题的证据重排\n\n`rag` 模式接收 `question` 和 `chunks`，把检索结果从“按召回顺序堆叠”变成“围绕问题排序”。\n\n| 分层 | 含义 |\n|:---|:---|\n| `HIGH` | 与问题重叠度高，可能直接支持回答 |\n| `SUPPORT` | 有帮助但不是核心证据 |\n| Low signal | 相关性弱，不应该占据主要上下文窗口 |\n\n### 3. code：最小修复上下文\n\n`code` 模式接收 `issue`、可选 `test_output` 和 `files`，用于给 AI Coding 助手准备更聚焦的修复输入。\n\n| 信号 | 作用 |\n|:---|:---|\n| Issue terms | 保留用户描述的问题焦点 |\n| Failure terms | 把测试失败、异常信息和候选文件关联起来 |\n| Hot path hints | 对 test、parser、pipeline、service、validator 等路径加权 |\n| Supporting files | 保留辅助上下文，但不让它淹没主线 |\n\n### 4. CLI + MCP 双入口\n\n同一套压缩逻辑可通过三种方式使用：\n\n| 入口 | 用途 |\n|:---|:---|\n| Python API | 集成到自己的包或服务里 |\n| CLI | 本地处理日志、样例和脚本任务 |\n| MCP Server | 接入支持 MCP 的 Agent / IDE / 自动化环境 |\n\n---\n\n## 快速开始\n\n### 前置要求\n\n| 项目 | 要求 |\n|:---|:---|\n| Python | `3.11` 到 `3.13` |\n| 包管理器 | `pip` |\n| MCP 运行时 | 可选，通过 `mcp` extra 安装 |\n\n### 安装\n\n```powershell\npython -m venv .venv\n.venv\\Scripts\\Activate.ps1\npython -m pip install -e .[dev,mcp]\n```\n\n从 PyPI 安装发布包：\n\n```powershell\npython -m pip install \"melonelish-context-engine[mcp]\"\n```\n\n### 运行示例\n\n```powershell\npython -m pytest -q\ncontext-engine --mode logs --input examples/logs/sample.log --budget medium\ncontext-engine --mode rag --input examples/rag/sample.json --budget medium\ncontext-engine --mode code --input examples/code/sample.json --budget medium\n```\n\n---\n\n## CLI 使用\n\n```powershell\ncontext-engine --mode logs --input examples/logs/sample.log --budget small\ncontext-engine --mode rag --input examples/rag/sample.json --budget medium\ncontext-engine --mode code --input examples/code/sample.json --budget large\n```\n\n### 输入格式\n\n#### logs：纯文本\n\n```text\n2026-07-03 10:01:12 ERROR payment.worker failed to charge order\nTraceback (most recent call last):\n  ...\nValueError: missing customer_id\n```\n\n#### rag：JSON\n\n```json\n{\n  \"question\": \"Why did checkout fail?\",\n  \"chunks\": [\n    {\n      \"content\": \"Checkout fails when customer_id is missing.\",\n      \"metadata\": {\"source\": \"runbook.md\"}\n    }\n  ]\n}\n```\n\n#### code：JSON\n\n```json\n{\n  \"issue\": \"Checkout test fails when customer_id is omitted.\",\n  \"test_output\": \"ValueError: missing customer_id\",\n  \"files\": [\n    {\n      \"path\": \"src/payments/checkout.py\",\n      \"content\": \"def checkout(order): ...\"\n    }\n  ]\n}\n```\n\n---\n\n## MCP 使用\n\n通过 stdio 启动 MCP Server：\n\n```powershell\ncontext-engine-mcp\n```\n\n当前暴露一个工具：\n\n| 工具 | 参数 | 功能 |\n|:---|:---|:---|\n| `compress_context` | `mode`、`budget`、`content` 或 `payload` | 压缩 logs / rag / code 上下文 |\n\n示例错误返回：\n\n```json\n{\n  \"ok\": false,\n  \"error\": {\n    \"error_code\": \"invalid_field\",\n    \"message\": \"Field 'chunks' must be a non-empty list.\",\n    \"hint\": \"Provide at least one item in 'chunks'.\"\n  }\n}\n```\n\n---\n\n## 输出契约\n\nCLI 和 MCP 都返回统一结构：\n\n| 结果 | 结构 |\n|:---|:---|\n| 成功 | `{ \"ok\": true, \"result\": ... }` |\n| 失败 | `{ \"ok\": false, \"error\": { \"error_code\": \"...\", \"message\": \"...\", \"hint\": \"...\", \"details\": ... } }` |\n\n成功结果会包含 schema version、summary、key facts、被丢弃或降权的噪声，以及 `llm_ready_context`。\n\n---\n\n## 安全边界\n\n当前内置限制：\n\n| 限制项 | 当前值 |\n|:---|---:|\n| 单段文本最大长度 | `200000` 字符 |\n| 结构化列表最大数量 | `64` 项 |\n| 输入文件最大大小 | `2000000` bytes |\n| Schema version | `1.0` |\n\n这些限制用于避免外部工作流把任意超大 payload 直接打进工具。\n\n### 当前已支持\n\n- Python `3.11` 到 `3.13`\n- `logs` / `rag` / `code` 三种模式\n- 三种模式的 CLI 使用\n- 通过 `compress_context` 暴露 MCP 工具\n- 纯文本日志输入\n- JSON 格式的 RAG 和 code 输入\n- 结构化成功 / 失败 envelope\n- 基础 benchmark 和 GitHub Actions CI\n\n### 暂不支持\n\n- PDF、图片、Office 文件等二进制输入\n- embedding-aware reranking\n- 仓库级依赖图分析\n- 跨未来大版本的长期兼容性承诺\n- 生产级鉴权、持久化、监控和审计能力\n\n---\n\n## Benchmark\n\nBenchmark 资料位于：\n\n- [benchmark_cases.md](benchmarks/benchmark_cases.md)\n- [benchmark_results.md](benchmarks/benchmark_results.md)\n\n当前样例集体现的行为：\n\n| 模式 | 对比对象 | 当前效果 |\n|:---|:---|:---|\n| `logs` | 原始日志 / 简单截断 | 保留根因，折叠重复噪声 |\n| `rag` | 直接 dump 检索 chunk | 围绕问题排序证据 |\n| `code` | 普通文件摘要 | 保留 issue、失败信号、hotspot file 和支持上下文 |\n\n`v0.1.0` 的 benchmark 还很小，适合作为回归检查和展示样例，不代表完整生产评测。\n\n---\n\n## 开发\n\n```powershell\npython -m pip install -e .[dev,mcp]\npython -m pytest -q\npython benchmarks/generate_benchmarks.py\n```\n\nCI 会在 push 和 pull request 时运行安装、测试和 benchmark 生成检查。\n\n---\n\n## 发布状态\n\n当前版本目标：`v0.1.0`\n\n已发布渠道：\n\n- PyPI: https://pypi.org/project/melonelish-context-engine/\n- MCP Registry: https://registry.modelcontextprotocol.io/v0/servers/io.github.melonelish/context-engine\n\n这个版本适合早期外部试用、集成测试和开发者工作流验证。它已经具备可复用包结构、测试、文档，以及可直接安装的 PyPI / MCP Registry 发布入口，但仍然是范围明确的早期 beta。\n\n---\n\n## Roadmap\n\n- 引入 embedding 或 reranker 驱动的 RAG 排序。\n- 加强 code hotspot 识别，加入更可靠的结构化代码信号。\n- 扩展 benchmark，加入更多真实脏数据样本。\n- 发布更易安装的正式包版本。\n- 增加更多 Agent Runtime / MCP 集成示例。\n\n---\n\n## License\n\n本项目采用 [MIT License](LICENSE)。\n",
  "bytes": 8359,
  "sha": "38226999c811c2322d5b366400d067ded8e91cdf70434b7caacdb57cf87a4b1b",
  "repo_slug": "melonelish/context-engine",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_melonelish_context_engine_a949eabd/readme"
}