ctxfile

<p align="center"> <img src="apps/web/public/brand/logo-mark-256.png" alt="ctxfile" width="96" height="96" /> </p> <h1 align="center">ctxfile</h1> <p align="center"><strong>一个上下文，多个代理，全部本地。</strong></p> <p align="center"> <a href="https://github.com/ctxfile/ctxfile/actions/workflows/ci.yml"><img src="https://github.com/ctxfile/ctxfile/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://www.npmjs.com/package/ctxfile"><img src="https://img.shields.io/npm/v/ctxfile" alt="npm" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-2025--11--25-black" alt="MCP" /></a> <a href="https://github.com/ctxfile/ctxfile/stargazers"><img src="https://img.shields.io/github/stars/ctxfile/ctxfile?style=social" alt="GitHub stars" /></a> </p> <p align="center"> <a href="https://ctxfile.dev">官网</a> · <a href="https://ctxfile.dev/docs">文档</a> · <a href="#30-second-quickstart">快速开始</a> · <a href="https://ctxfile.dev/docs/clients">客户端</a> · <a href="https://ctxfile.dev/convention">.ctxfile 协议</a> · <a href="https://ctxfile.dev/security">安全</a> </p> --- 你同时使用多个 AI 代理。Claude Code 在终端，Cursor 在编辑器，一个聊天标签用于思考。每个代理都从头开始，因为你的工作状态（计划、关键文件、git 状态、一个小时前你做出的决定）存在于你的脑海中和滚动历史中。 **ctxfile** 是一个本地优先的 [MCP](https://modelcontextprotocol.io) 服务器，它将项目的上下文快照到一个结构化的上下文对象，并将其交给任何 MCP 代理。可以在一个代理中保存会话，在另一个代理中继续。没有任何内容离开你的机器。 ``` 你 → ctxfile → 相同的上下文，在每个代理中 ``` ## 30 秒快速开始 **Claude Code** ```bash claude mcp add ctxfile -- npx -y ctxfile ``` **Cursor**（`.cursor/mcp.json` 在你的项目中，或 `~/.cursor/mcp.json` 在全局） ```json { "mcpServers": { "ctxfile": { "command": "npx", "args": ["-y", "ctxfile"] } } } ``` **Codex CLI** ```bash codex mcp add ctxfile -- npx -y ctxfile --root . ``` **Claude Desktop**：从 [releases](https://github.com/ctxfile/ctxfile/releases) 下载 `ctxfile.mcpb` 并将其拖到设置 → 扩展。 **其他客户端**：ctxfile 是一个标准的 stdio 服务器，因此 `npx -y ctxfile` 就是整个命令。复制粘贴设置到 **OpenCode, Gemini CLI, OpenClaw, Hermes, Aider** 等客户端选项卡在 [ctxfile.dev/docs/clients](https://ctxfile.dev/docs/clients)。 然后，在你的代理中：*加载我的上下文*（或调用 `get_context`）。需要 Node ≥ 20（Windows 上 ≥ 22）。 ## 自动安装 你不再需要输入“保存此内容”。一条命令安装一个 **技能**，该技能教任何代理在执行其正常工作的同时，何时检查点上下文以及何时宣布每次保存（从不静默，从不暂停，始终可审查）： ```bash ctxfile init ``` 它从一个规范生成每个 harness 读取的内容：一个 Agent `SKILL.md` 用于 **Claude Code, OpenCode, OpenClaw, 和 Hermes** （一个跨所有四个技能系统的便携文件），一个 **Cursor** 规则，以及一个受管理的 **GEMINI.md** / **AGENTS.md** 块。详细信息在 [ctxfile.dev/docs/automatic](https://ctxfile.dev/docs/automatic)。 ## 它也适用于聊天标签 CLI 和编辑器代理加载的相同上下文可以通过 MCP 传递给网络聊天机器人。通过自定义 MCP 连接器将 **Grok, ChatGPT, Claude web, 或 Perplexity** 连接到你的加密 [Sync](https://ctxfile.dev/docs/sync) 保险库，或 `ctxfile export` 并将信封粘贴到任何提示框（Gemini 等）。演练： [ctxfile.dev/docs/webchat](https://ctxfile.dev/docs/webchat)。 ## 默认私有 这是我们最关心的内容，因此放在首位： - 默认路径 **不进行网络调用**。仅限文件和 git。 - 看起来像秘密的内容（云密钥、令牌、私钥、JWT、`password=` 赋值）**在进入快照之前被编辑**。`.env*`、密钥文件和凭证文件永远不会被读取。 - 核心 **只读**你的项目。它永远不会写入你的仓库、git 状态或其他内容。 - **默认情况下无遥测**。存在一个匿名每周安装 ping，它是仅限选择的。 - 网络连接器（Notion、本地 Ollama 总结、Sync）仅在您明确配置它们时激活。 完整的模型，包括 Pro 和 Sync 新增的内容以及它们永远无法看到的内容，都记录在 [ctxfile.dev/security](https://ctxfile.dev/security)。 ## 它做什么 | | | |---|---| | **快照** | `get_context` 返回一个结构化的 `ContextObject`：计划文档、按令牌预算拟合的关键文件、git 状态、选定的 Notion 页面和本地 LLM 摘要。 | | **保存和恢复** | `save_session` 存储代理编写的当前对话摘要。`continue_thread` 将合并的、具有溯源标签的历史记录交给下一个代理。不同的 harness，不同的提供商，冷启动：它从你离开的地方继续。 | | **线程** | 一个作品的持久身份（“Q3 活动”），跨代理和机器。`handoff: true` 强制执行完整的接管包：状态、带有理由的决策、已排序的开放项、需要注意的事项。 | | **通用摄入** | `ingest_context` 是任何 harness 的模式强制门户，无原生解析器。提示是适配器，因此每个 MCP 代理都受支持，包括尚不存在的代理。 | | **云代理** | `ctxfile export` 为从未接触过你的机器的代理（托管编码代理、CI）编写静态、仓库安全的工件。格式是开放规范： [the .ctxfile convention](https://ctxfile.dev/convention). | | **仪表盘** | `ctxfile ui`：一个本地驾驶舱，运行在 127.0.0.1 上。运行快照，监视连接器，浏览上下文，检查 git 状态。 | | **Sync（可选）** | 一个端到端加密的保险库，通过中继器，您可以自行托管。Argon2id 密钥派生，XChaCha20-Poly1305 每 blob。中继器仅存储密文。 | ## 源码仓库 | 包 | 什么 | 许可证 | |---|---|---| | [`packages/core`](packages/core) | `ctxfile` 在 npm 上：MCP 服务器、快照引擎、线程、摄入、导出、Sync 客户端、仪表盘主机 | Apache-2.0 | | [`packages/relay`](packages/relay) | `@ctxfile/relay` 在 npm 上：可自行托管的 Sync 中继器和团队中心（加密保险库、`/mcp` 端点、联合身份验证、审计日志）。一个 Docker 镜像 | Apache-2.0 | | [`packages/dashboard`](packages/dashboard) + [`packages/ui-kit`](packages/ui-kit) | `ctxfile ui` 服务的本地仪表盘 UI | Apache-2.0 | | [`apps/web`](apps/web) | [ctxfile.dev](https://ctxfile.dev)：网站和文档 | Apache-2.0 | ## 开放核心，诚实 此仓库中的所有内容都是 Apache-2.0 许可的，并且可以独立运行，永久免费。付费的 [Pro](https://ctxfile.dev/pricing) 插件（一个单独的封闭包）添加会话连接器，从 **Claude Code, Cursor, Codex CLI, OpenCode, Gemini CLI, Aider, OpenClaw, 和 Hermes Agent** 读取您的最近会话，加密的跨会话内存，多提供商 [consult](https://ctxfile.dev/docs/pro)（Anthropic，**OpenRouter** 支持数百个模型，一个密钥，任何 OpenAI 兼容的端点，或本地 Ollama），AI 蒸馏的提示 [Playbooks](https://ctxfile.dev/docs/playbooks)，和本地语音捕获。许可验证是使用 Ed25519 签名的密钥离线验证的。永不电话回家。Pro 资助开源工作。 ## 贡献 我们需要您的 issues、PR 和奇怪的 harness 报告。从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始。每个摄入格式、每个 MCP 客户端怪癖、您发现的每个编辑漏洞都使整个项目变得更好。 - **错误和功能**： [issues](https://github.com/ctxfile/ctxfile/issues) - **问题和展示**： [discussions](https://github.com/ctxfile/ctxfile/discussions) - **安全报告**： [SECURITY.md](SECURITY.md) （请不要为漏洞打开公共问题） ```bash git clone https://github.com/ctxfile/ctxfile.git && cd ctxfile npm install npm run build && npm test # 整个关卡：lint、类型检查、测试 ``` ## 星历史 如果 ctxfile 为您节省了冷启动，[一颗星](https://github.com/ctxfile/ctxfile) 就是其他人找到它的方式。 <a href="https://star-history.com/#ctxfile/ctxfile&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ctxfile/ctxfile&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ctxfile/ctxfile&type=Date" /> <img alt="Star history chart" src="https://api.star-history.com/svg?repos=ctxfile/ctxfile&type=Date" /> </picture> </a> ## 许可证 [Apache-2.0](LICENSE)。 “ctxfile” 和 ctxfile 标志是 ctxfile 的商标；许可证涵盖代码，而不是名称。