rushikeshmore/CodeCortex

# CodeCortex AI 智能体的持久化代码库知识层。您的 AI 不应在每次会话中重新学习您的代码库。 [网站](https://codecortex-ai.vercel.app) · [npm](https://www.npmjs.com/package/codecortex-ai) · [GitHub](https://github.com/rushikeshmore/CodeCortex) ## 问题所在 每次 AI 编程会话都从零开始。当上下文压缩或新会话开始时，AI 会重新扫描整个代码库。相同的文件、相同的 token、相同的浪费。这就像每次会话都雇佣一名新开发人员，在编写哪怕一行代码之前，都必须重新学习所有内容。 **数据证实了这一点：** - AI 智能体在处理不熟悉的代码时，缺陷风险增加 30% ([CodeScene + Lund University, 2025](https://codescene.com/hubfs/whitepapers/AI-Ready-Code-How-Code-Health-Determines-AI-Performance.pdf)) - AI 时代代码流失率增长了 2.5 倍 ([GitClear, 分析了 2.11 亿行代码](https://www.gitclear.com/coding_on_copilot_data_shows_ais_downward_pressure_on_code_quality)) - 没有任何工具能将结构化 + 语义 + 时序 + 决策知识结合在一个便携式工具中 ## 解决方案 CodeCortex 将代码库预处理为分层知识文件，并通过 MCP 将其提供给任何 AI 智能体。AI 不必在每次会话中重新理解您的代码库，而是直接从知识开始。 **混合提取：** tree-sitter 原生 N-API 用于结构（跨 27 种语言的符号、导入、调用）+ 宿主 LLM 用于语义（模块功能、构建原因）。无需额外的 API 密钥。 ## 快速开始 ``` # 安装 (针对 tree-sitter peer dep 不匹配需要 --legacy-peer-deps) npm install -g codecortex-ai --legacy-peer-deps # 初始化项目知识 cd /path/to/your-project codecortex init # 启动 MCP server (用于 AI agent 访问) codecortex serve # 检查知识新鲜度 codecortex status ``` ### 连接到 Claude Code 添加到您的 MCP 配置中： ``` { "mcpServers": { "codecortex": { "command": "codecortex", "args": ["serve"], "cwd": "/path/to/your-project" } } } ``` ## 生成内容 所有知识都以纯文本文件形式存储在您仓库的 `.codecortex/` 目录中： ``` .codecortex/ cortex.yaml # project manifest constitution.md # project overview for agents overview.md # module map + entry points graph.json # dependency graph (imports, calls, modules) symbols.json # full symbol index (functions, classes, types...) temporal.json # git coupling, hotspots, bug history modules/*.md # per-module deep analysis decisions/*.md # architectural decision records sessions/*.md # session change logs patterns.md # coding patterns and conventions ``` ## 六大知识层 | 层级 | 内容 | 文件 | |-------|------|------| | 1. 结构层 | 模块、依赖、符号、入口点 | `graph.json` + `symbols.json` | | 2. 语义层 | 每个模块的功能、数据流、陷阱 | `modules/*.md` | | 3. 时序层 | Git 行为指纹 - 耦合、热点、Bug 历史 | `temporal.json` | | 4. 决策层 | 为什么要这样构建 | `decisions/*.md` | | 5. 模式层 | 代码编写方式 | `patterns.md` | | 6. 会话层 | 会话间发生的变化 | `sessions/*.md` | ### 时序层 这是杀手级差异化特性。时序层告诉智能体*“如果你修改文件 X，你也必须修改文件 Y”*，即使它们之间没有导入关系。这源于 git 共变分析，而非静态代码分析。 来自真实代码库的示例： - `routes.ts` 和 `worker.ts` 在 9/12 次提交中共变（75%），且**两者之间零导入** - 如果没有这些知识，AI 编辑其中一个文件有 75% 的概率产生 Bug ## MCP 工具 (15) ### 读取工具 (10) | 工具 | 描述 | |------|-------------| | `get_project_overview` | 构成 + 概览 + 图谱摘要 | | `get_module_context` | 按名称获取模块文档，包含时序信号 | | `get_session_briefing` | 自上次会话以来的变更 | | `search_knowledge` | 跨所有知识的关键词搜索 | | `get_decision_history` | 按主题筛选的决策记录 | | `get_dependency_graph` | 导入/导出图，可过滤 | | `lookup_symbol` | 按名称/文件/类型查找符号 | | `get_change_coupling` | 如果我修改文件 X，还必须修改哪些文件？ | | `get_hotspots` | 按风险排名的文件（流失 x 耦合） | | `get_edit_briefing` | **NEW** — 编辑前风险简报：共变警告、隐藏依赖、Bug 历史、导入方 | 所有读取工具都包含 `_freshness` 元数据，用于指示知识的更新程度。 ### 写入工具 (5) | 工具 | 描述 | |------|-------------| | `analyze_module` | 返回源文件 + 用于 LLM 分析的结构化提示词 | | `save_module_analysis` | 将 LLM 分析持久化到 `modules/*.md` | | `record_decision` | 将架构决策保存到 `decisions/*.md` | | `update_patterns` | 将编码模式合并到 `patterns.md` | | `report_feedback` | 智能体报告错误知识以供下次分析 | ## CLI 命令 | 命令 | 描述 | |---------|-------------| | `codecortex init` | 发现项目 + 提取符号 + 分析 git 历史 | | `codecortex serve` | 启动 MCP 服务器 (stdio transport) | | `codecortex update` | 重新提取已更改的文件，更新受影响的模块 | | `codecortex status` | 显示知识新鲜度、过期模块、符号数量 | | `codecortex symbols [query]` | 浏览和过滤符号索引 | | `codecortex search ` | 搜索所有 CodeCortex 知识文件 | | `codecortex modules [name]` | 列出模块或深入查看特定模块 | | `codecortex hotspots` | 显示按风险排名的文件：流失 + 耦合 + Bug 历史 | | `codecortex hook install\|uninstall\|status` | 管理 git 钩子以自动更新知识 | | `codecortex upgrade` | 检查并安装最新版本 | ## Token 效率 CodeCortex 使用三层记忆模型来最小化 token 使用： ``` Session start (HOT only): ~4,300 tokens Working on a module (+WARM): ~5,000 tokens Need coding patterns (+COLD): ~5,900 tokens vs. raw scan of entire codebase: ~37,800 tokens ``` 减少 85-90% token。效率提升 7-10 倍。 ## 支持的语言 (27) | 类别 | 语言 | |----------|-----------| | Web | TypeScript, TSX, JavaScript | | 系统 | C, C++, Objective-C, Rust, Zig, Go | | JVM | Java, Kotlin, Scala | | .NET | C# | | 移动端 | Swift, Dart | | 脚本 | Python, Ruby, PHP, Lua, Bash, Elixir | | 函数式 | OCaml, Elm, Emacs Lisp | | 其他 | Solidity, Vue, CodeQL | ## 技术栈 - TypeScript ESM, Node.js 20+ - `tree-sitter` (原生 N-API) + 27 个语言语法包 - `@modelcontextprotocol/sdk` - MCP 服务器 - `commander` - CLI - `simple-git` - git 集成 - `yaml`, `zod`, `glob` ## 许可证 MIT

标签：Cilium, DLL 劫持, DNS解析, LLM, MCP, MITM代理, Model Context Protocol, NPM, RAG, Ruby, Token 优化, Tree-sitter, Unmanaged PE, 云安全监控, 人工智能, 代码上下文, 代码分析, 代码理解, 代码预处理, 凭证管理, 大语言模型, 威胁情报, 开发者工具, 开源项目, 检索增强生成, 用户模式Hook绕过, 知识库, 编程效率, 自动化攻击, 语义理解, 静态分析