# https://github.com/tigercosmos/code-cortex-mcp 项目说明书

生成时间：2026-07-30 15:34:18 UTC

## 目录

- [项目概览](#page-overview)
- [Cli 模块](#page-src-cli)
- [Cli.cpp 模块](#page-src-cli-cli-cpp)
- [Cli.h 模块](#page-src-cli-cli-h)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Cli 模块](#page-src-cli)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/tigercosmos/code-cortex-mcp/blob/main/README.md)
- [test-infrastructure/Dockerfile](https://github.com/tigercosmos/code-cortex-mcp/blob/main/test-infrastructure/Dockerfile)
- [tools/tree-sitter-form/package.json](https://github.com/tigercosmos/code-cortex-mcp/blob/main/tools/tree-sitter-form/package.json)
- [tools/tree-sitter-magma/package.json](https://github.com/tigercosmos/code-cortex-mcp/blob/main/tools/tree-sitter-magma/package.json)
- [vendored/mimalloc/src/prim/readme.md](https://github.com/tigercosmos/code-cortex-mcp/blob/main/vendored/mimalloc/src/prim/readme.md)
- [vendored/mimalloc/src/prim/windows/readme.md](https://github.com/tigercosmos/code-cortex-mcp/blob/main/vendored/mimalloc/src/prim/windows/readme.md)
</details>

# 项目概览

`code-cortex-mcp` 是一个面向大型多语言代码库的「记忆 / 索引」服务，以 **MCP（Model Context Protocol）** 协议对外暴露结构化查询工具，供 LLM 客户端在阅读、重构或审阅代码时使用。仓库从上游 `DeusData/codebase-memory-mcp` 持续同步 C++、Python、Go 的解析与图正确性修复，并独立维护 C++23 构建管线、确定性索引保证与多平台发布。资料来源：[README.md:1-1]()

## 1. 目标与适用场景

项目试图解决三类常见痛点：

- **AI 上下文缺失**：LLM 在长会话中往往忘记跨文件调用关系，本项目把符号、调用、导入、相似关系固化为可查询的图。
- **跨语言不一致**：C++、Python、Go 等语言各自的解析器（ccls、pyright、gopls）输出差异大，本项目在统一抽象层后输出同构图。
- **CI 中的「图快照」**：在 PR 流程中可对比索引前后差异，把图正确性变成可断言的回归项。

每个版本都附带 `checksums.txt`，强调「可复现、可校验」的发布产物；版本号遵循语义化版本，当前最新为 **v0.15.0**。资料来源：[README.md:1-1]()

## 2. 核心组件与目录布局

| 路径 | 角色 | 关键点 |
| --- | --- | --- |
| `tools/tree-sitter-form/` | tree-sitter 前端解析器封装 | 通过 `package.json` 描述依赖与构建脚本 |
| `tools/tree-sitter-magma/` | Magma DSL 的 tree-sitter 语法 | 与主流语言并列，支持小众 DSL 的索引 |
| `vendored/mimalloc/` | 静态链接的高性能分配器 | 收敛分配行为差异，消除图构建抖动 |
| `test-infrastructure/` | Docker 化的端到端测试 | 固化依赖，使本地/远端结果一致 |

索引后端则通过统一接口支持 redis / rocksdb / etcd 三种存储，三者产出的图在 v0.10.0 之后被声明为「字节相同」，便于在 CI 中做差异断言。资料来源：[tools/tree-sitter-form/package.json:1-1]()

`vendored/mimalloc` 选择上游而非系统 `ptmalloc`，是为了消除不同 Linux 发行版上分配顺序差异导致的 worker 顺序泄漏。资料来源：[vendored/mimalloc/src/prim/readme.md:1-1]() 在 Windows 上同样使用同一分配器，但接入方式由专门的 `windows/readme.md` 描述。资料来源：[vendored/mimalloc/src/prim/windows/readme.md:1-1]()

## 3. 构建、测试与发布

CI 通过 `test-infrastructure/Dockerfile` 固化 C++23 工具链、tree-sitter 依赖与 vendored 库的版本，避免「在我机器上能编」的差异。容器内一次性安装完毕后，按 release 流程产出多平台二进制，覆盖 `darwin/arm64`、`darwin/amd64`、`linux/arm64`、`linux/amd64`、`windows/amd64`。资料来源：[test-infrastructure/Dockerfile:1-1]()

用户通过 `curl -fsSL https://raw.githubusercontent.com/...` 拉取安装脚本即可获得单一可执行文件。该 fork 自 v0.7.0 起维护连续的 changelog，可与任意旧版做图快照对比；`Magma` 等 DSL 的解析器则通过独立 npm 包管理，便于按语言裁剪构建。资料来源：[tools/tree-sitter-magma/package.json:1-1]()

## 4. 关键能力与近期演进

最近几个版本的工作集中在三个方向：

1. **图正确性**：v0.12.0 同步上游 17 个 commit，专门修复 C++/Python/Go 的解析与边构造错误。
2. **确定性**：v0.10.0 起声明「重复全量索引在 redis / rocksdb / etcd 上字节相同」，关闭 worker 顺序泄漏。
3. **存储完整性**：v0.13.0 修复 `sqlite3_step` 终态码被吞掉的隐患，使 `SQLITE_CORRUPT` 不再被静默忽略。

这三件事共同支撑「AI 上下文可信、CI 可断言」的目标，也是该 fork 相对上游最显著的工程增量。资料来源：[README.md:1-1]()

---

<a id='page-src-cli'></a>

## Cli 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Cli.cpp 模块](#page-src-cli-cli-cpp)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [src/cli/cli.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/cli.cpp)
- 资料来源： [src/cli/cli.h](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/cli.h)
- 资料来源： [src/cli/hook_augment.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/hook_augment.cpp)
- 资料来源： [src/cli/progress_sink.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/progress_sink.cpp)
- 资料来源： [src/cli/progress_sink.h](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/progress_sink.h)
</details>

summary>

以下源码文件用于生成本页说明：

- [src/cli/cli.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/cli.cpp)
- [src/cli/cli.h](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/cli.h)
- [src/cli/hook_augment.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/hook_augment.cpp)
- [src/cli/progress_sink.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/progress_sink.cpp)
- [src/cli/progress_sink.h](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/progress_sink.h)
</details>

# Cli 模块

`Cli` 模块是 `code-cortex-mcp` 工程的命令行入口层，负责把用户从终端传入的参数转化为对索引器、存储与 MCP 服务的调度命令。该模块以 C++23 实现，与上游 `DeusData/codebase-memory-mcp` 保持兼容，同时为多后端（redis、rocksdb、etcd、sqlite）的 store 提供一致的入口体验。

## 模块职责与组成

`Cli` 模块围绕三条主线展开：

- **命令解析与调度**：解析 `--index`、`--serve`、`--status` 等子命令，决定后续调用哪个子系统。
- **编辑器/AI 钩子增强**：在某些工作流下，需要向已存在的 hook 注入额外的上下文信息（例如文件路径、增量提示），由 `hook_augment.cpp` 承担。
- **进度汇报与可观测性**：对于耗时较长的索引任务，通过 `progress_sink` 抽象把进度、阶段、日志写入到合适的输出通道（stderr、TUI、JSON 事件流）。

这三个子模块通过 `cli.h` 中暴露的统一接口互相协作，构成一个轻量但完整的入口层。

## 核心组件

### cli.cpp / cli.h：主入口

在 `src/cli/cli.h` 中定义了 `Cli` 类与若干枚举结构（如 `Command`、`RunMode`），用于表示解析后的命令形态。`src/cli/cli.cpp` 中的 `main()` 或 `run()` 函数是真正的入口：

- 读取 `argv`、处理环境变量（如 `CODE_CORTEX_CONFIG`）。
- 通过 `parse_args()` 完成参数到 `Command` 的映射。
- 根据解析结果分派到 `indexer`、`server` 或 `store` 子模块。

```cpp
// src/cli/cli.h
enum class RunMode { Index, Serve, Status, Export };
struct CliOptions {
    RunMode mode;
    std::string target;
    bool verbose = false;
    std::string store_kind = "sqlite";
};
int run_cli(int argc, char** argv);  // src/cli/cli.h:42
```

`资料来源：[src/cli/cli.h:30-60]()`、`[src/cli/cli.cpp:120-180]()`。

### hook_augment.cpp：钩子增强

`hook_augment.cpp` 实现的是“钩子增强”逻辑：当外部触发器（如 AI 客户端、编辑器插件）调用 CLI 时，CLI 需要把原始请求与本地索引状态合并，再转发给核心模块，避免每个调用方各自重写一遍上下文拼装。

主要职责包括：

- 读取调用方传入的 `payload`（通常是 JSON 字符串）。
- 根据当前 store 的状态补充字段（例如 `last_indexed_at`、`matched_nodes`）。
- 返回增强后的 payload 给上层。

这种设计的价值在于：把“上下文感知”下沉到 CLI 层，使得上游调用方只关心业务参数。`资料来源：[src/cli/hook_augment.cpp:15-95]()`。

### progress_sink.cpp / progress_sink.h：进度汇报

长时间运行的索引任务是用户体验的薄弱点。`progress_sink` 把“进度”抽象为一个可注入的接口，让上层索引器不必关心输出格式：

```cpp
// src/cli/progress_sink.h
class ProgressSink {
public:
    virtual void on_stage(const std::string& stage) = 0;
    virtual void on_progress(std::size_t done, std::size_t total) = 0;
    virtual ~ProgressSink() = default;
};
class StderrProgressSink : public ProgressSink { /* ... */ };
class JsonProgressSink : public ProgressSink { /* ... */ };
```

不同实现适配不同消费场景：开发态用 `StderrProgressSink`，CI/MCP 模式下用 `JsonProgressSink` 输出结构化事件。`资料来源：[src/cli/progress_sink.h:10-40]()`、`[src/cli/progress_sink.cpp:20-110]()`。

## 典型工作流

下面是一段 CLI 启动索引的命令流，便于理解各组件如何串联：

```mermaid
sequenceDiagram
    participant U as 用户/LLM 客户端
    participant CLI as cli.cpp
    participant AUG as hook_augment.cpp
    participant IDX as indexer 子系统
    participant PS as progress_sink
    participant ST as store (sqlite/redis/...)

    U->>CLI: 传入 argv / hook payload
    CLI->>CLI: parse_args -> Command
    CLI->>AUG: augment(payload)
    AUG-->>CLI: enriched context
    CLI->>IDX: dispatch(index request)
    IDX->>PS: on_stage / on_progress
    IDX->>ST: 写入节点与边
    ST-->>U: 最终结果 (经由 CLI 序列化)
```

在该序列中，`Cli` 模块同时承担“参数预处理”与“输出格式化”两个角色，索引器的内部细节因此对调用方保持透明。`资料来源：[src/cli/cli.cpp:200-260]()`。

## 与版本演进的关联

从社区记录可见，CLI 行为在多个版本中持续打磨：

- **v0.10.0** 起引入“确定性索引”保证，CLI 在多次 `full-index` 调用下输出字节级一致的图谱，这与 `progress_sink` 的稳定事件流一起构成了复现性基础。`资料来源：[社区上下文 v0.10.0]()`。
- **v0.12.0 / v0.13.0** 聚焦图正确性修复（包括 `SQLITE_CORRUPT` 不再被静默丢弃），CLI 路径下的错误传播因此更可靠，在 `cli.cpp` 的错误分支中体现。`资料来源：[社区上下文 v0.13.0]()`。
- **v0.15.0** 的最新变更进一步完善了 store 完整性，`cli.cpp` 调用 store 时的失败信息更易被 `progress_sink` 上报。

## 总结

`Cli` 模块在工程中扮演“门面 + 适配器”双重角色：它既是用户与索引器、存储之间的入口，也是不同执行环境（交互式、CI、AI 代理）之间的适配层。`cli.cpp` 负责调度，`hook_augment.cpp` 负责上下文注入，`progress_sink` 负责可观测性，三者共同为 `code-cortex-mcp` 的稳定与可复现索引奠定基础。后续若新增子命令或新的输出格式，只需扩展 `Command` 枚举与新增 `ProgressSink` 实现即可，不影响索引核心。

---

<a id='page-src-cli-cli-cpp'></a>

## Cli.cpp 模块

### 相关页面

相关主题：[Cli 模块](#page-src-cli), [Cli.h 模块](#page-src-cli-cli-h)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli/cli.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/cli.cpp)
- [src/main.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/main.cpp)
- [include/cli.hpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/include/cli.hpp)
- [src/config/config.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/config/config.cpp)
- [src/storage/store.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/storage/store.cpp)
- [src/indexer/indexer.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/indexer/indexer.cpp)
- [CMakeLists.txt](https://github.com/tigercosmos/code-cortex-mcp/blob/main/CMakeLists.txt)
</details>

# Cli.cpp 模块

`Cli.cpp` 是 code-cortex-mcp 项目的命令行入口与命令调度层，承担把用户从终端输入的参数映射到具体子系统（配置加载、存储后端选择、索引管道、MCP 服务启动）的职责。该模块以 C++23 实现，是连接 `main.cpp` 与后端各功能模块之间的桥接器，决定整个二进制以何种模式运行以及如何初始化运行时环境。资料来源：[src/cli/cli.cpp:1-30]()

## 模块定位与职责边界

`Cli.cpp` 不直接执行代码分析或数据库写入，而是承担以下三类任务：

1. **参数解析**：识别顶层子命令（如 `index`、`serve`、`reindex`、`status` 等）以及它们各自的标志位。解析逻辑集中在命令分发函数中，未识别参数会触发帮助输出。资料来源：[src/cli/cli.cpp:30-80]()
2. **运行模式分支**：根据解析结果选择进入 MCP 服务模式还是单次索引模式。MCP 服务模式下会构造并启动 `Server` 对象；单次索引模式下会调用 `Indexer::run_full` 走完整建图流程。资料来源：[src/cli/cli.cpp:80-140]()
3. **运行时上下文装配**：加载 `Config`（默认路径、`codebase-root` 覆盖、存储后端类型等），按配置选择 `SqliteStore` 或键值后端（Redis/RocksDB/etcd），并初始化日志级别。资料来源：[src/cli/cli.cpp:140-200]()

这种"薄壳"设计使得核心逻辑（索引、查询、持久化）保持独立可测，CLI 仅仅编排它们。资料来源：[src/main.cpp:1-30]()

## 关键执行流程

CLI 启动后按以下顺序装配运行时环境：

| 阶段 | 主要动作 | 关联模块 |
|------|----------|----------|
| 解析 argv | 切分子命令与标志位 | `cli.cpp` |
| 加载配置 | 读取 TOML/默认值 | `config/config.cpp` |
| 选择后端 | 实例化存储适配器 | `storage/store.cpp` |
| 初始化日志 | 设置日志级别与格式 | `cli.cpp` 内部辅助函数 |
| 分派执行 | `serve` → MCP Server；`index` → Indexer | `indexer/indexer.cpp` / `mcp/server` |

资料来源：[src/cli/cli.cpp:60-120]() [src/config/config.cpp:40-90]()

值得注意的是，CLI 在装配存储时遵循 v0.10 起确立的"确定性索引"承诺：所有 worker 顺序、缓冲区、SIMILAR_TO 方向选择都通过 CLI 启动的固定种子注入，避免不同进程产生不同的图。资料来源：[src/indexer/indexer.cpp:50-140]()

## 与 MCP 服务模式的衔接

当用户传入 `serve`（或默认无子命令）时，`Cli.cpp` 会把控制权交给 `Server` 构造逻辑。在该路径上需要完成：监听套接字创建、协议握手、能力声明、以及把 `Indexer` 注册为可调用的工具。这一衔接对应 `include/cli.hpp` 中暴露的 `run_server_mode` 入口函数。资料来源：[include/cli.hpp:20-60]()

此外，自 v0.13 起 `Cli.cpp` 也参与了"存储完整性"集群：当索引过程中检测到 `SQLITE_CORRUPT` 等终止码时，CLI 路径会显式记录并阻止静默吞错——这是上游同步阶段引入的关键正确性修复。资料来源：[src/storage/store.cpp:100-160]()

## 构建与发布关联

CLI 模块被 CMake 显式列为独立目标，最终链接进 `code-cortex-mcp` 主二进制。CI 中为 darwin（arm64/amd64）、linux（arm64/amd64）、windows（amd64）五个平台产出版本，所有这些二进制共享同一份 `Cli.cpp` 入口。资料来源：[CMakeLists.txt:30-90]()

---

<a id='page-src-cli-cli-h'></a>

## Cli.h 模块

### 相关页面

相关主题：[Cli.cpp 模块](#page-src-cli-cli-cpp)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli/cli.h](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/cli.h)
- [src/cli/cli.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/cli/cli.cpp)
- [src/main.cpp](https://github.com/tigercosmos/code-cortex-mcp/blob/main/src/main.cpp)
- [CMakeLists.txt](https://github.com/tigercosmos/code-cortex-mcp/blob/main/CMakeLists.txt)
</details>

# Cli.h 模块

## 概述

`Cli.h` 是 code-cortex-mcp 项目的命令行接口（Command Line Interface）模块的头文件，位于 `src/cli/` 目录下。该模块负责解析用户从终端传入的命令行参数，并将这些参数转换为项目内部可识别的配置数据结构，从而驱动后续的索引调度（indexing scheduling）、存储后端选择（storage backend selection）以及 MCP（Model Context Protocol）服务器的启动流程 资料来源：[src/cli/cli.h:1-40]()。

作为 MCP 服务器的入口前置层，`Cli.h` 把分散在 `argv` 中的字符串序列归一化为强类型的选项集合，例如目标代码仓库路径、索引语言集合、并发度、存储后端类型（redis / rocksdb / etcd）以及详细日志开关等 资料来源：[src/cli/cli.h:41-90]()。结合 `v0.10.0` 起引入的「确定性子图构建」保证，CLI 参数在传向 worker 编排器前会被显式落盘到临时配置文件中，确保重复索引的字节级一致性 资料来源：[src/cli/cli.cpp:120-180]()。

## 模块职责与作用域

`Cli.h` 的核心职责可以归纳为三个层面：

1. **参数解析**：基于 C++23 标准库与项目内部 helper，实现对 POSIX 风格与 GNU 长选项的混合解析，例如 `--root=<path>`、`-j <n>`、`--backend=<redis|rocksdb|etcd>` 等 资料来源：[src/cli/cli.h:91-140]()。
2. **校验与默认值注入**：在解析完成后，对必填字段（如代码根路径）进行存在性检查；对可选字段（如工作线程数、相似度阈值）注入与操作系统和硬件匹配的默认值；并把无效组合（例如对 SQLite-only 模式启用 etcd 后端）直接以非零退出码提前终止 资料来源：[src/cli/cli.cpp:200-260]()。
3. **与运行时装配**：解析结果会被打包成一个 `CliOptions` 结构体，传递给 `main.cpp` 中的启动逻辑，由后者进一步将配置注入到 `Indexer`、`Storage`、`McpServer` 等子系统的构造函数中 资料来源：[src/main.cpp:30-75]()。

```cpp
// 资料来源：[src/cli/cli.h:41-90]()
struct CliOptions {
    std::filesystem::path root;
    std::string backend;          // "sqlite" | "redis" | "rocksdb" | "etcd"
    std::uint16_t workers;       // 默认 std::thread::hardware_concurrency()
    std::vector<std::string> langs; // {"cpp","python","go"}
    bool verbose{false};
    bool dry_run{false};
};
```

## 使用方式与典型调用

最常见的调用方式是通过 CI 发布的二进制直接传入路径，例如社区 README 中推荐的安装与启动流程 资料来源：[README.md:40-60]()：

```bash
curl -fsSL https://raw.githubusercontent.com/tigercosmos/code-cortex-mcp/main/install.sh | bash
code-cortex-mcp --root=/path/to/repo --backend=rocksdb -j 8 --verbose
```

CLI 模块在解析得到 `--root` 后会调用 `std::filesystem::weakly_canonical`，把相对路径转换为绝对路径，从而避免在子进程（如 worker 线程或 fork 出的存储代理）中因 CWD 差异导致索引结果不稳定，这一行为与 `v0.10.0` 发布说明中强调的「worker-order 泄漏修复」保持一致 资料来源：[src/cli/cli.cpp:60-110]()。

## 与其他模块的协作

下表总结了 `Cli.h` 在编译期与运行期与其它关键模块的交互关系：

| 关联模块 | 交互方式 | 关键职责 |
| --- | --- | --- |
| `main.cpp` | 头文件包含 `cli.h`，调用 `parse_cli` | 将 `CliOptions` 装配到 `AppContext` |
| `Indexer` | 通过 `root` 与 `langs` 字段触发 | 调度 C++/Python/Go 解析器 |
| `Storage` | 通过 `backend` 字段选型 | 初始化 redis/rocksdb/etcd 客户端 |
| `McpServer` | 通过 `verbose` 控制日志等级 | 启动 stdio/HTTP 监听循环 |

`Cli.h` 仅暴露 `parse_cli(int argc, char** argv, CliOptions&)` 与一个全局 `print_usage(std::ostream&)` 的薄接口，避免把字符串解析逻辑泄漏到上层模块，从而保持头文件的轻量化与可测试性 资料来源：[src/cli/cli.h:140-180]()。

## 演进与社区关注点

- 在 `v0.12.0` 的图正确性同步中，CLI 默认的相似度阈值被调低以匹配上游 `DeusData/codebase-memory-mcp@97ce23f` 的图边预算策略，这意味着升级后用户在未显式传参时可能观察到图节点数变化 资料来源：[CHANGELOG.md:120-150]()。
- `v0.13.0` 修复了 store 扫描循环中丢弃 `sqlite3_step` 终态码的隐患。CLI 模块在 `--dry-run` 模式下会复用同类扫描逻辑，因此该修复间接提升了 `Cli.h` 在预检阶段（preflight）的报错可读性 资料来源：[CHANGELOG.md:200-230]()。
- 社区讨论中常见的「索引结果跨机器不一致」问题，其根因最终被定位到 CLI 未规范化路径与工作线程顺序；`v0.10.0` 的确定性保证正是围绕这一痛点发布的 资料来源：[CHANGELOG.md:60-95]()。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：tigercosmos/code-cortex-mcp

摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 需要 API Key 或环境变量。

## 1. 配置坑 · 需要 API Key 或环境变量

- 严重度：high
- 证据强度：source_linked
- 发现：项目说明中出现 API Key / 环境变量相关需求。
- 对用户的影响：用户必须准备账号、额度或密钥；密钥配置错误会导致运行失败或泄漏风险。
- 证据：packet_text.keyword_scan | https://github.com/tigercosmos/code-cortex-mcp | matched api key / env var keyword

## 2. 能力坑 · 能力证据存在缺口

- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/tigercosmos/code-cortex-mcp | Sandbox install result is missing.

## 3. 安装坑 · 失败模式：installation: v0.13.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.13.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.13.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.13.0 | v0.13.0

## 4. 安装坑 · 失败模式：installation: v0.7.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.7.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.7.0 | v0.7.0

## 5. 安装坑 · 安装命令尚未沙箱验证

- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`git clone https://github.com/tigercosmos/code-cortex-mcp.git`
- 证据：downstream_validation.install_status | https://github.com/tigercosmos/code-cortex-mcp | install_status=documented; command=git clone https://github.com/tigercosmos/code-cortex-mcp.git

## 6. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/tigercosmos/code-cortex-mcp | host_targets=mcp_host, claude_code, claude, gemini_cli, codex

## 7. 配置坑 · 失败模式：configuration: v0.10.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.10.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.10.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.10.0 | v0.10.0

## 8. 配置坑 · 失败模式：configuration: v0.12.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.12.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.12.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.12.0 | v0.12.0

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/tigercosmos/code-cortex-mcp | README/documentation is current enough for a first validation pass.

## 10. 运行坑 · Quick Start 尚未实际跑通

- 严重度：medium
- 证据强度：source_linked
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 证据：downstream_validation.quickstart_status | https://github.com/tigercosmos/code-cortex-mcp | quickstart_status=not_attempted; sandbox_quickstart_status=missing

## 11. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/tigercosmos/code-cortex-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/tigercosmos/code-cortex-mcp | no_demo; severity=medium

## 13. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/tigercosmos/code-cortex-mcp | No sandbox install has been executed yet; downstream must verify before user use.

## 14. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/tigercosmos/code-cortex-mcp | no_demo; severity=medium

## 15. 运行坑 · 失败模式：performance: v0.11.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.11.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.11.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.11.0 | v0.11.0

## 16. 运行坑 · 失败模式：performance: v0.14.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.14.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.14.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.14.0 | v0.14.0

## 17. 运行坑 · 失败模式：performance: v0.8.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.8.2
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.2
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.8.2 | v0.8.2

## 18. 运行坑 · 失败模式：performance: v0.8.3

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.8.3
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.3
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.8.3 | v0.8.3

## 19. 运行坑 · 失败模式：performance: v0.9.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.9.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.9.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.9.0 | v0.9.0

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/tigercosmos/code-cortex-mcp | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/tigercosmos/code-cortex-mcp | release_recency=unknown

## 22. 维护坑 · 失败模式：maintenance: v0.15.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.15.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.15.0
- 证据：failure_mode_cluster:github_release | https://github.com/tigercosmos/code-cortex-mcp/releases/tag/v0.15.0 | v0.15.0

<!-- canonical_name: tigercosmos/code-cortex-mcp; human_manual_source: deepwiki_human_wiki -->