code-context-control

align="center">代码上下文控制</h1> <p align="center"> <strong>适用于 AI 编程工具的本地代码智能层。</strong><br> 停止在整个文件读取、盲目搜索和无边界日志转浪费令牌。<br> 与 Claude Code、Codex、GeminiCopilot、Cursor 和 Antigravity 配合</p> <p align"> <a href="https://pypi.org/project/code-context-control/"><img alt="PyPI" src="https://img.shields.io/pypi/v/code-context-control?color=ypi&logoColor=white"></a> <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a> <img alt="Python 3.10+" src="https://img.shields.io3.10%2B-blue.svg"> <img alt="Platforms" src="https://img.shields/platform-windows%20%7C%20macos%20%7C%20linux-lightgrey"> <img alt="Status: Beta" src="https://img.shields/status-beta-yellow"> <a href="https://github.com/sponsors/drknowhow"><img alt="Sponsor" src="https://img.shields.io/badge/sponsor-%9D%A4-EA4AAA?logosponsors&logoColor=white"></a> </p> <p align="center"> <img src="https://raw/drknowhow/code-context/docs/screenshots/ui" alt="C3 per-project dashboard" width="900"> </p> --- ##LLM 驱动的编程工具存在一种昂贵的失败模式：**它们读取**。它们会读取整个文件，整个代码仓库进行正则表达式匹配，倾倒 10,000 行日志到上下文中，编辑后祈祷，然后在触代码之前就烧毁预算。在半天的会话中，您可能会花费 20 美元以上，得到的价值却为零。 ## C3 解决了这个问题 一个薄的**本地**层，位于您的 IDE 和代码仓库之间。每个 AI 工具调用都通过狭窄的手术操作进行路由，而不是广泛的浪费性操作： | 没有 C3 | 有 C3 | |---|---| | `读取` 整个0 行文件 | `c3_compress` 返回一个结构映射，令牌计数为原文件的 40-70%（缩小 30-60%）→ `c3_read(symbols=...)` 获取确切的函数 | | `Grep` 整个代码仓库盲目搜索 | `c` 返回-IDF + 符号意识的排名候选 | | 将整个 `pytest` 输出转储到提示中 | `c3_filter 500 行 → 可操作行 | ，希望它能编译 | `c3_edit` 通过账本写入 + `c3_validate` 自动运行 `pyright`/`tsc` | | 在 Windows 上运行 Bash 命令卡住c3_shell` 返回的 `{exit_code, stdout, stderr, duration}` 结构化数据 | | 在 `/clear` 上丢失所有上下文 | `c3_session(snapshot)` + `c3_memory` 跨会话持续决策 | | 每个会话重新解释项目 | 自动同步的 `CLAUDE.md` / `AGENTS.md`GEMINI.md` / `copilot-instructions.md` 从单一真实来源 | **本地**运行。 除非您明确选择模型 API，否则不会有源代码、提示或离开您的机器。 --- ## 安装 需要 Python +。无需克隆 - C3 已发布到 PyPI。 推荐的安装方法是 [pipx](x.pypa.io)（隔离环境 PATH 上）： ```bash pipx install code c3 init /path/to/your/project ``` 或者使用 pip： ```bash pip install "code-context-control[tui]" # [tui]的 Textual UI c3 init /path/to/project ``` 运行不带参数的 `c 会打开交互式 TUI。`c3 init` 将引导您完成： 1. **IDE 选择** Code CLI/App、Codex CLI、GeminiVS Code、Cursor、Antigravity 或自定义. 可选的本地 `git init` 3. MCP 服务器注册（自动连接到您的 IDE） 4. （仅 Claude Code）权限层选择 无头/脚本化安装```bash c3 init /path/to/project --force --ide claude --mcp-mode direct standard ``` ### 升级 ```bash c3 upgrade # 就地升级正在运行的安装 c3 upgrade --check # 仅报告是否存在新版本 # 等效： pipx upgrade code-context-control pip install -U code-context-control ``` MCP 通过3-mcp` 入，因此升级不需要重新配置**您的现有 `.m` 文件继续有效。 还会在有新版本可用时在应用程序中提示您。 ### 从源代码（贡献者） ```bash git clone https://github.com/drknowhow/code-context-control.git cd pip install -[dev]" # 可编辑的开发安装、linters、 ``` --- ## 界览 C3 带有两个 Web 界面（无 Electron，无安装 - Flask + 普通 JS）： - **Hub**（`c3-hub`，端口 3330）- 从一个仪表板 C3 项目。 - **每个项目的界面**（`c3 ui`，每个项目的端口）- 一个项目的会话、内存、编辑、指令和设置。 ### 1. 项目中心 - 多项目控制中心 <p align="centerimg src="https://raw.githubusercontent.com/dr-context-control/main/docs/screenshots/hub_projects.png" alt="C3 Project Hub - all projects" width="900"> </p> 上的每个 C3 初始化项目都会自动出现在此处c3 init` 在首次运行时将项目注册需额外步骤。分组，按活动/空闲过滤，查看每个项目使用的 IDE，点击即可跳转到您的 IDE，并一目了然地监控会话活动。每个项目卡片都、版本、 连接模式、端口和上次活动。 每个卡片的操作涵盖整个生命周期：启动 IDE、打开每个项目的界面、编辑名称/标签/备注、将注册转移到新路径、**合并**另一个项目的内存 + 会话历史 + 编辑账本到此项目（代码清理），或从删除它。 **在您选择的 IDE 中打开** - C3 自动检测您已安装的 CLI，并为您提供一键启动器： <p align="centerimg src="https://raw.githubusercontent.com/dr/code-context-control/main/docs/screenshots/hub_ide_config.png" alt="C3 Hub IDE picker" width="700"> </p> 中心作为**后台 Windows 服务**运行（无需终端，自动启动登录）： <p align="center"> <img src="https://raw.githubusercontent.com/drknowhow/code-context-control/main/docs/screenshots/hub_settings.png" alt="C3 Hub settings" width="700"> </p> ### 2. 每个项目的仪表板 - 一目了然的健康状况 ```bash c3 ui # 打开 http.0.0.1:3333 ``` <p align="center"> <img src="https://raw.githubusercontent.com/drknowhow/code-context-control/main/docs/screenshots/ui_dashboard.png" alt="C3 per-project width="900"> </p> 来自一个项目的示例仪表板（数字因项目而异）：**节省K 令牌**（89.9%）- C3完整文件读取基 + 208 个索引文件，20 个会话库按语言当前会话实时计数/输出令牌，缓存读取，在线服务）和最近的工具调用更改流。运行 bench session` 在您自己的项目上生成您自己的记分卡。 ### 3. 编辑账本 - 跟踪每个 AI 驱动的编辑 <p align="center"> <img src="https://raw.githubusercontent.com/drknowhow/code/main/docs/screenshots/ui_edits.png" alt="C3 Edit Ledger" width="900"> </通过 `c3或 C3 shell 拦截的 Bash git 命令）进行的每个文件更改的完整审计跟踪。每个条目显示时间戳、文件、版本号、更改摘要 行计数。按文件路径过滤，切换到**视图查看聚合趋势。由内容可存储支持，因此任何版本都是一键可达。 ### 4. 内存 - 跨会话的持久知识 <p align="center"> <="https://raw.githubusercontent.com/drknowhow/code-context-control/main/docs/s_memory.png" alt=" Memory" width="900"> </p> 项目关于项目（架构决策、陷阱、引用）的 AI 已学习事实的分类存储。类别，全文 + 语义搜索，决策跟踪，列表 ↔ 图切换和一键 Markdown 导出。由 TF-IDF + 可选 Ollama 嵌入 + `chromadb` 支持（当安装 `[vector]` 额外功能时）。 ### 5. 会话 - 历史、决策、成本 <p align="center"> <img src="https://raw.githubusercontent.com/drknowhow/code-context-control/main/docs/screenshots/ui_sessions.png" alt="C3 Sessions" width="900"> </p> 您曾经运行的，包含时长、决策次数、文件数量、工具调用、令牌和成本。自动通过 IDE 的 Stop 钩子捕获 - 不需要记住点击任何内容。点击任意行查看该会话的完整任务列表、决策和文件差异。 ### 6指令 - 跨 IDE 同步项目上下文 <p align="center"> <img src="https://raw.githubusercontent.com/drknowhow/code-context-control/main/docs/screenshots/ui_instructions.png" alt="C3 Instructions" width="900"> </p> 从一个编辑器管理 `CLAUDE.md`、`AGENTS.md`（Codex）、`GEMINI 和 `.githubstructions.md`。从项目状态生成，运行健康检查（与实际代码库的差异检测），压缩过时部分，或推广在会话期间捕获的见解。**单一真实来源** 而不是四个不同步的文件。 C3 生成的内容包裹在 `<!-- C3:BEGIN … -->` / `<!-- C3:END -->` 块生成（或压缩）只会重块 - **您外面编写的任何内容都将被保留**，因此可以安全地在保留您自己的备注 7. - 浏览之前的 AI 对话 <p"> ="https://.com/drknowhow/code-context-control/main/docs/s_chat.png" alt="C3 Chat" width="900"> </p> C3 同步并 IDE 的聊天目前为 Claude Code正在开发中）。过滤，搜索，点击。对于“上周我们对 X 做出了什么决定？”非常有用。 ### 8. 设置 - 功能标志 + 集成 <p align="center"> <img src="https://raw.githubusercontent.com/drknowhow/code-context-control/main/docs/screenshots/ui" alt=" Settings" width="</p> 每个调节参数：预算阈值、功能标志模式、编辑账本代理、委托路由、Codex/Gem集成、代理工作流、代理模式、M、Claude权限层等。 工具套C3 以原生的形式公开 工具。您的 IDE： | 工具 | 它能---|---| | `c3_search` | 索引仓库中-IDF / 正 / 语义搜索的排名 | | `c3_compress` | 基于 AST 的文件映射：`mapdense_map`, `diff`, ``, `ast| `c3_read` | 按符号正则表达式或外科手术式| `c3 | 具有日志记录 + 内容可寻址历史的原子补丁 | |_validate` | 类型 / 语法检查（pyright、tsc、 - 自动检测） | | `c | 通过模式摘要提炼长日志输出 | | `c3_shell` | 运行带有结构化返回 + 自动过滤 stdout | | `_status` | 项目健康状况、令牌、鬼文件检测 | | `c3_memory` | 具有类别、回忆和图查询事实存储 | | `c3_session` | 快照、恢复、日志决策、压缩会话历史 | | `c3_impact` | 编辑到共享符号之前的爆炸半径分析 | | `c3_delegate` | 将繁重工作卸载到本地 / Codex / Gemini / 等 | |3_agent` | 多步骤代理工作流调查、重构） | | `c3_edits` | 编辑账本查询 + 版本差异 + 还原点 + 按分支过滤 | | `c3_bitbucket` | Bitbucket 数据中心集成 - PR、分支、构建、仓库管理（v2.0） | | `c3_project 跨项目 - 发现和3 安装的项目；有保护的写入2.31.0） | | `_task` | 持久的每个项目任务程碑和决策备注（v2.45.0） | | `c3_artifacts 代理配置跟踪历史、差异和还原用于 CLAUDE.md、设置/钩子、MCP 配置、技能（v2.46.0） | 每个工具在**计划模式下都是安全的**（除了 `c3_edit`、`c3_shell`、`c3_artifacts(action='restore')` 和 `c3_bitbucket` / `c3_project` / `c3_task` 的写入操作）。 ### Bitbucket 数据中心 / 服务器（v2.30.0） `c3_bitbucket` 通过 REST + 个人访问令牌连接到自托管的企业 Bitbucket。令牌存储在 **OS 密钥环**（Windows 凭证管理器，macOS 钥匙串，Linux 机密服务）-不会存储在 `.c3/config.json` 中。 ```bash # 每个服务器的一次性登录（存储在 .c3/config.json 下） c3 bitbucket login --url https://bitbucket.example.com # -> 提示输入用户名 + PAT（掩码） # ... 或全局存储，以便每个 C3 项目都可以使用它 c3 bitbucket login --global --url https://bitbucket.example.com # 固定默认值，以便后续调用不需要项目/c3 bitbucket --project PROrepo my-service cbucket status ``` 解析优先级：的 `.c3` 优先，但当它没有活动帐户C3 会回落到全局 `~/.c3/config.json`。因此，单个 `login --global`（或从主目录执行的任何登录）可跨所有 C3 项目重用 - PAT 始终存储在 OS 密钥环中，而不存储上。 升级：** 在 `c3 upgrade之前停止正在c3-m 服务器/CLI。的进程包文件打开，留下 pip 的 `~` 前缀备份目录（`、`` 等）位于 `site-packages` 中；这些是惰性，在升级完成后CP 派通过 `action` 进行。只读操作：`statuswhoami`、`list_projects`、`list_repos`、`get_repo``、`get_pr`_pr_diff`、`get_pr_activities`、`list_branches`、`list_commits`、`list_activity`、`build_statusrepo_settings`、`list_webhooks`、`list_permissions`。写操作：``、`comment_pr`_pr`、`unapprove_pr`、`decline_pr`、`merge_pr`、``、`delete_branch`、`update_repo_settings`、`create_webhook`_webhook`。PR 合并和分支删除记录到 C3 编辑账本中，因此审计跟踪也涵盖平台侧更改。 中心 UI（每个项目）获得Bitbucket”选项卡，包含用于概览/拉取请求/分支/活动/管理员的子视图。 ### Oracle Discovery API（v2.32.0） **Oracle** 是 C3 的可选跨项目内存代理（一个本地 Web 应用程序）。从 v2.32.0 开始，它可以将 C3 的跨项目代码和内存智能公开为 **外部 LLM 的工具** - 将 Claude（或任何函数调用模型）指向正在运行的 Oracle，它可以跨所有项目发现您的项目并搜索代码、内存和跨项目图。 两种传输方式共享一个工具核心： - **MCP**（流式 HTTP/SSE）在 `http://127.0.0.1:3332/mcp` - 对 Claude Code / Claude Desktop / 任何 MCP 客户端都是原生的。 - **OpenAPI REST `http://127.0.0.1:3331/api/discovery` - 具有函数调用的 LLM（获取 `/openapi.json` 以自动）。 ```bash # 启动 Oracle（提供 REST + MCP 点） python oracle/oracle_serverno-browser # 打印 Bearer 令牌 + 一个可粘贴的 .mcp.json 片段 c3 oracle api info ``` 只有 **读取** 和 **安全操作** 工具被公开（无代码编辑）；请求需要一个 **Bearer 令牌**（存储 密钥环中），并且两个绑定到 `127.0.0.1`。在仪表板的 **设置 → 发现 API** 选项卡中生成、轮换和复制令牌。从 v2.38.0 开始，Oracle 还通过 `activity_report` 发现工具、`GET /api/activity/digest` 端点和仪表板的 **活动** 选项卡报告 **跨项目活动摘要** - 会话、工具调用、编辑、git 突变和令牌/成本每天。 --- ## 分层本地 AI（可选） C3 配备了可选的 Ollama 集成，因此不必浪费上下文进行繁琐工作： | 层级 | 模型类别 | 用途 | 延迟目标 | |---|---|---|---| | **纳米** | `qwen2:0.5b` | 意图路由，分类 | <100 毫秒微** | `deepseek-r1:1.5b` | 最后一次问答，总结 | <1 秒 | | **基础** | `2:3b`+ | 代码分析，技术推理 | <5 秒 | ```text c3_delegate(task="summarize this 4k-line stacktrace", backend="ollama") c3_delegate(task="rate-limit refactor", backend="auto") # 选择合适的层级 ``` Ollama 是**完全可选的**。C3 无需 Ollama 即可## 权限（Claude Code） C3 为您管理aude/settings.local.json`，具有三个合理的层级： | | 它允许什么 | |---|---| | `read-only` | 探索 - 无文件写入，无 git 写入，无安装 | | `standard` | 正常开发工作流 - 编辑、构建、测试、本地 git **）** | | `permissive` | 完全信任 - 除操作外的一切 | 所有层级始终允许 C3 MCP 工具，并包含一个硬否决名单（`rm -rf`、`sudo`、`git push --force` 等）。 ```bash c3 permissions show c3 permissions standard 或切换层级 **保留您自己的 `allow`/` 规则**（以及 `ask`/`defaultMode` 等密钥）- 只有 C3 管理的条目会被替换。同样，C3 永远不会覆盖 `.mcp.json`（仅其自己的 `c3` 服务器）或您添加到 `settings.local.json` 的钩子（仅其自己的钩子）。 ## 基准测试 不信我们所言 — C3 所宣传的每一项数据都可以在您自己的机器上针对您自己的项目进行复现： ```bash c3 bench session # 六个现实工作流场景，A/B 测试有无 C3 的情况 c3 benchmark /path/to/project # 每个操作的微基准测试（压缩、检索、过滤、验证） c3 bench aider # Aider 多语言套件（外部；消耗真实 API 代币） c3 bench swe # SWE-bench 精简版（外部） ``` 会话基准测试的基线模拟了一个 *称职* 的代理在没有 C3 的情况下工作 — 进行一次有针对性的搜索，每次读取文件 — 而不是一个重新读取所有内容的稻草人，它在评估答案质量的同时也评估 token 使用量。供参考，在 C3 自有仓库（v2.43.0，2026-07-02）中运行的测试，在六个场景中实现了 **51.8% token 节省（2.07 倍）**，且质量相当。您的项目情况不同，测试结果也会有所不同 — 这就是为什么我们提供此工具的原因。 除了合成场景外，C3 还会记录实际的每个工具的使用情况到 `.c3/tool_telemetry.jsonl`，因此可以随时检查预估的节省与实际使用情况是否一致。 报告包括 token 差异、成本差异、胜率、工具使用分析以及每个任务的详细情况。请在 Hub 中查看 **基准测试仪表盘**，位于“设置”→“后台代理”下。 --- ## 安全与隐私 - **所有 Web 服务器（Hub、每个项目的 UI、Oracle）默认绑定到 `127.0.0.1`，并防范基于浏览器的攻击，即使在环回地址上也是如此** — 采用主机头允许列表（防止 DNS 重新绑定）以及对每个请求的源/引用检查（防止跨源 CSRF），并使用范围限定、非通配符 CORS。因此，您访问的恶意网页无法驱动 C3 的本地端点。**目前尚无用户身份验证**，因此请勿在未部署身份验证/TLS 的情况下将这些服务器暴露在不受信任的网络中。在 `~/.c3/hub_config.json`（`host`) 或 Oracle 配置文件 (`bind_host`) 中绑定到非环回接口是可选的，并在启动时发出警告；请将面向外部的主机名/IP添加到 `allowed_hosts` 列表中，以便保护机制允许它们。（跨源/CSRF + DNS 重新绑定强化功能已在 v2.33.0 中添加。） - **默认无遥测功能**。开源软件包不会收集任何数据。选择加入 Sentry 崩溃报告需要 `[telemetry]` 额外功能以及 `SENTRY_DSN` 和 `C3_TELEMETRY_OPT_IN=1`。即使启用，请求体、局部变量和提示也会在发送前被剥离。 - **第三方模型提供商的 API 密钥** 从环境变量中读取，C3 绝不会持久化保存这些密钥。 - 有关完整的安全强化指南和披露政策，请参见 [`SECURITY.md`](SECURITY.md)。 --- ## 支持 C3 C3 是免费、开源的，由一人开发。如果它为您节省了 token（它应该会 — 这就是它的目的），请考虑在 [GitHub 上赞助](https://github.com/sponsors/drknowhow)。赞助直接用于支付跨模型测试运行的 API 费用以及专用开发时间。 --- ## 许可证 - **当前 OSS 许可证** — Apache License 2.0（[`LICENSE`](LICENSE)）。免费用于任何用途，包括商业用途。修改、fork、重新分发 — 在 Apache-2.0 条款下均允许。 - **第三方依赖** — 请参见 [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md)。 作者可能会引入付费产品或重新许可未来的主要版本；不会有任何承诺。已经在 Apache-2.0 下发布的版本（包括所有 2.x 版本）将继续保持 Apache-2.0 许可 — 该许可是不可撤销的。背景信息和常见问题请参见 [`LICENSING.md`](LICENSING.md)。不提供任何担保或支持义务；请参见 LICENSE 第 7-8 节。 --- ## 链接 - **PyPI:** https://pypi.org/project/code-context-control/ - **变更日志:** [`CHANGELOG.md`](CHANGELOG.md) - **Oracle Discovery API:** [`oracle-guide/discovery-api.md`](oracle-guide/discovery-api.md) - **安全政策:** [`SECURITY.md`](SECURITY.md) - **许可 FAQ:** [`LICENSING.md`](LICENSING.md) - **问题:** https://github.com/drknowhow/code-context-control/issues - **赞助:** https://github.com/sponsors/drknowhow