ctx-manager

一个与提供商无关的上下文工程 CLI + MCP 服务器，用于多语言智能体开发。

ctx-manager 位于你的 Docs/ 文件夹（PRD、架构文档、阶段计划、API 规范）与 AI 编码智能体（Claude Code、Cursor、Windsurf）之间，从两个方面削减 token 开销：

• 确定性、基于标题的文档切片 — 从蓝图文件中精确提取你需要的部分，而不是整个文件。基于结构（对 Markdown 标题做正则匹配），而非 RAG/嵌入。

• 只追加、经 git 验证的 Memory_Ledger.md — 准确的会话状态，让智能体不会重新推导或幻觉化已经构建的内容。每条记录在标记为已验证之前，都会与真实的 git status 输出进行核对。

在 Rust、Go、TypeScript、Python 或任何其他技术栈上都能以相同方式工作 — ctx-manager 从不触碰你的应用程序源代码，只处理 Docs/。

安装

uvx --from ctx-manager ctx --help

无需 virtualenv 配置，无需全局安装。

Related MCP server: Claude Session MCP

用法

按标题切片蓝图文件：

ctx build --slice "PRD.md > 5. Feature List"

将匹配到的章节内容打印到 stdout — 可将其管道输入到 CLAUDE.md 或你的智能体读取上下文的任何位置。

基于账本历史自动切片下一阶段：

ctx build --auto-phase

读取 Memory_Ledger.md 获取最近完成的阶段，并自动从 Phase_file.md 中切出下一个阶段的章节 — 无需手动指定 --slice 目标。如果账本中还没有已完成的阶段记录，则回退到阶段 0 并发出警告。

向会话账本追加一条已验证的记录：

ctx append-ledger --summary "Implemented the login endpoint" --category completed

在写入之前对照你的项目检查 git status，并根据检查结果给记录加上 [Verified: N files changed]、[Reasoning/State Only] 或 [Unverified: not a git repo] 前缀 — 这样智能体自称的"已完成"声明就会与磁盘上实际发生的情况进行核对。

作为 MCP stdio 服务器运行（适用于 Cursor、Windsurf、Claude Desktop）：

ctx mcp

将 query_slice、append_ledger_entry 和 get_current_phase 作为 MCP 工具暴露，调用与上述 CLI 命令完全相同的代码路径。

配置

ctx-manager 从当前目录向上搜索 .context/config.toml。如果找不到，则使用合理的默认值（Docs/ 文件夹、Memory_Ledger.md 等）并警告一次。

[project]
docs_dir = "Docs/"
ledger_file = "Memory_Ledger.md"
phase_file = "Phase_file.md"

[blueprint_files]
files = ["PRD.md", "Architecture.md", "API_Spec.md"]

[git]
scope = "docs_dir"  # or "repo_root"

使用 --project-root 完全覆盖搜索路径。

Claude Code 集成

示例 SessionStart/SessionEnd 钩子（通过 --auto-phase 在会话前自动刷新 CLAUDE.md，会话后自动记录到账本）位于 examples/claude_code_hooks/。

设计原则

1. Docs/ 进，Docs/ 出 — 绝不触碰任何语言的应用程序源代码。

2. 先轻后重 — 先用标准库 re 而非嵌入，先用 subprocess git 而非 git 库，先用本地 stdio 而非任何网络服务。

3. 只追加的账本 — 没有任何代码路径会整体覆盖 Memory_Ledger.md。永远没有。

4. 响亮失败，而非静默 — 缺少标题或文件时返回明确的错误，绝不返回智能体可能产生幻觉的空内容。

完整的设计文档请参阅 Docs/Architecture.md 和 Docs/PRD.md（本项目自食其果 — 在自身开发过程中，它自己的 Docs/ 文件夹就是由 ctx-manager 切片和跟踪的）。

局限性

ctx-manager 无法阻止智能体绕过它。 这里没有任何机制能阻止拥有原始文件系统访问权限的智能体直接读取 Docs/PRD.md，而不是通过 ctx build。这是一个结构性限制，而非缺失的功能 — 基于子进程的 CLI 无法挂钩到另一个进程的文件读取工具调用。

如果你需要真正的强制执行（而不仅仅是约定），那必须来自智能体运行时本身：

• Claude Code：在 .claude/settings.json 中使用 permissions.deny 规则阻止 Read 工具直接触碰 Docs/*.md，强制依赖 ctx build --auto-phase 生成的 CLAUDE.md。请参阅 Claude Code 自己的权限文档 — 这不是 ctx-manager 为你配置的内容。

• MCP 客户端（Cursor、Windsurf 等）：该客户端暴露的任何文件系统访问控制（如果有的话）— 不在 ctx-manager 的控制范围内。

如果没有上述任何一种机制，ctx-manager 就是一种期望智能体遵守的约定，以经过验证的会话历史（账本）为支撑 — 而非沙箱。

开发

git clone <this-repo>
cd ctx-manager
uv sync
uv run pytest

许可证

MIT — 参见 LICENSE。