English | 简体中文

按 token 预算组织仓库文件，跟踪内容变化，并通过 CLI 或 MCP 提供项目上下文。

v0.8.0 · Python 3.12+ · MIT

Website · Demo record

为什么使用

把很多文件交给模型之前，先要知道哪些文件会被纳入、顺序是什么、相对上次修改了哪些内容。ctxfeed 用 ShardPlan 表达这些选择，保留稳定前缀、正文和变化集合，方便检查一次查询实际组织了什么。

架构

ingest 扫描并计数文件，shard 按预算和稳定顺序构建计划，CachePlan 将文件哈希写到仓库自己的 SQLite 缓存。CLI 和 MCP 共用该路径，模型适配器在查询时发送组装后的上下文。delta 是本地变化账本，不代表仅发送变化内容，也不是服务端 prefix cache 遥测。

源码入口：src/ctxfeed/cli.py · src/ctxfeed/cache_plan.py · src/ctxfeed/ingest.py · src/ctxfeed/shard.py · src/ctxfeed/mcp_server.py · src/ctxfeed/models/glm.py · src/ctxfeed/models/deepseek.py

安装

需要 Python 3.12+ 与 uv。演示只构建本地计划，无需 API key；首次 tokenizer 使用可能需要缓存其编码文件。

git clone https://github.com/SuperMarioYL/ctxfeed.git
cd ctxfeed
uv venv --python 3.12
uv pip install --python .venv/bin/python -e .

快速开始

完整脚本创建两份临时文件，连续构建三次计划。结果中的 cached_fraction 是本地文件哈希复用比例，不是模型缓存命中或实测费用。

.venv/bin/python examples/presentation-demo.py

完整输入与执行步骤见上方命令及 Demo 记录。

使用

.venv/bin/ctxfeed init --repo .
.venv/bin/ctxfeed add ./src/ctxfeed/cli.py
.venv/bin/ctxfeed cost --repo .
.venv/bin/ctxfeed mcp --repo .

init 在没有对应模型密钥时使用 dry-run；设置密钥后该命令可能调用服务。MCP 客户端应将 command 配置为本仓库 .venv/bin/ctxfeed 的绝对路径，args 为 ["mcp", "--repo", "/absolute/repo"]。

实际 Demo

查看三次计划

首次、未修改、修改一次的变化集合分别是 2、0、1。

$ .venv/bin/python examples/presentation-demo.py
[
  {
    "stage": "first",
    "files": 2,
    "delta_hashes": 2,
    "cached_fraction": 0.0,
    "stable_prefix": [
      "README.md"
    ]
  },
  {
    "stage": "unchanged",
    "files": 2,
    "delta_hashes": 0,
    "cached_fraction": 1.0,
    "stable_prefix": [
      "README.md"
    ]
  },
  {
    "stage": "edited",
    "files": 2,
    "delta_hashes": 1,
    "cached_fraction": 0.5,
    "stable_prefix": [
      "README.md"
    ]
  }
]

能力与接入

CLI 提供 init、add、cost、mcp。MCP 的 list_files 展示文件与缓存标记，query_repo 提交问题，cost_delta 按仓库内的静态费率估算。GLM 与 DeepSeek 是可选适配器，不会自动完成模型供应商间的运行时故障切换。

配置

--model 优先于 CTXFEED_MODEL，可选 glm 或 deepseek。GLM 读取 ZHIPU_API_KEY/GLM_API_KEY，DeepSeek 读取 DEEPSEEK_API_KEY。IngestConfig 管理 window、headroom、max_file_bytes 和 cache_db；默认缓存为 .ctxfeed/cache.db。供应商模型名、窗口和费率是适配器中的配置假设，应按实际账户核对。

路线图与范围

已实现预算计划、增量账本、两个适配器与 MCP。后续扩展应以真实仓库问答质量、服务端缓存遥测和供应商配置验证为依据。

• 文件可能因忽略规则、大小或预算被跳过；不能保证任意仓库完整进入上下文。
• dry-run 答案是内置模拟结果，cost 是静态估算；本示例没有调用模型。

· Recording script

许可证

MIT