cortex

Cortex

为 AI 编码 Agent 提供来自代码库的正确上下文。

Cortex 会在本地构建代码、符号、关系和项目规则的映射。编码 Agent 通过 CLI 查询该映射，而不是凭猜测或读取整个代码库。

你的代码会留在自己的设备上。无需 MCP。

开始使用

需要 Node.js 20.9+ 和 Git。

npm install --global @danielblomma/cortex-mcp
cd your-project
cortex init --bootstrap

此操作会为代码库建立索引、将 Cortex 指令添加到 AGENTS.md、安装 Git 钩子，并启动后台监视器。

检查设置：

cortex doctor

使用

# Find relevant code.
cortex search "where is authentication handled?" --json

# Follow relationships from a search result.
cortex related <entity-id> --json

# See what a change may affect.
cortex impact "authentication" --json

# Read repository rules.
cortex rules --json

# Compare a changed file with nearby patterns.
cortex pattern-evidence src/auth.ts --json

# Inspect deterministic active conventions for a file or indexed entity.
cortex conventions src/payments/retry.ts --json

# Get cited, deterministic context before implementing a code task.
cortex guidance src/payments/retry.ts --task "add bounded retry handling" --json

# Review the staged, unstaged, and non-ignored untracked candidate against HEAD.
cortex review --diff --json

# Refresh context after significant changes.
cortex update

Agent 可以直接运行这些命令。cortex init 会添加指令，告诉它们在回答前先搜索，并在重构前检查影响。 它们不需要 MCP 连接。

Cortex 提供的功能

不使用 Cortex 时，Agent 往往会按文件名搜索，并读取许多无关文件。Cortex 会提供结构化的代码库上下文：

• 在代码、规则和架构决策中进行语义搜索；
• 符号定义和文件关系；
• 调用方和依赖关系遍历；
• 重构前的影响分析；
• 当前生效的规则、弃用项和事实来源信号；
• 确定性、按子系统限定范围的约定配置文件，并附有引用的可复用符号；
• Git 和文件系统发生变化后进行增量更新。

整个流程都在本地运行，简单明了：

repository -> local index -> Cortex CLI -> coding agent

常用命令

命令	用途
cortex search "..." --json	查找相关代码和上下文
cortex related <entity-id> --json	从搜索结果追踪关系
cortex impact "..." --json	评估变更的影响范围
cortex rules --json	显示当前生效的代码库规则
cortex pattern-evidence <file> --json	查找附近的实现模式
cortex conventions <file-or-entity> --json	检查范围有限的代码库约定配置文件
cortex guidance <file-or-entity> --task <text> --json	获取范围有限且附带引用的编码前指导
cortex review --diff --json	使用附带引用的本地证据审查当前 Git 候选变更
cortex update	刷新已变更的上下文
cortex status	显示索引状态
cortex doctor	诊断本地设置
cortex watch status	检查后台同步状态
cortex dashboard	打开本地状态面板

运行 cortex help 查看完整命令列表。

cortex conventions 只使用本地索引。它返回范围有限、由实时数据支持的 1 版配置文件，不会调用模型、规划器、提供方或网络 服务。具体的适用条件、限制、哈希、持久化和安全约定，请参阅代码库约定配置文件。

开始实现代码任务前，请使用 cortex guidance 获取附带引用的补充 上下文，不要将其视为策略权威。根据需要继续使用常规的 search、related 和 impact，并且绝不要跳过明确生效的规则或冲突。 该命令仅在本地运行，且只用于检查；请参阅编码前指导中的精确版本化约定。

完成编码后、最终定稿前，请使用 cortex review --diff。它会区分精确的事实来源违规与启发式本地模式警告，且仅用于检查。请参阅确定性差异审查。

保持索引最新

Git 钩子和监视器通常会自动更新 Cortex。

cortex status
cortex watch status
cortex update

大幅变更后，或结果看起来过时时，请手动运行 cortex update。

大型代码库

在语义索引于后台持续运行的同时，先启用词法搜索和图搜索：

cortex bootstrap --background --profile interactive
cortex indexing status --json

此模式支持 macOS、Linux 和 WSL。原生 Windows 应使用常规前台引导流程。

升级

npm install --global @danielblomma/cortex-mcp@latest
cortex init --force
cortex bootstrap
cortex update

项目配置和规则均会保留。特定版本的说明请参阅 CHANGELOG.md。

可选的 MCP 兼容性

常规 Cortex 工作流使用 CLI。如果客户端明确要求 MCP， 请运行 cortex connect。

DeepSeek Harness 集成

Cortex 通过 V1 显式工具和技能集成支持 DeepSeek Harness。Cortex 2.6.0 包含该集成源码，并已针对固定的 Harness 0.1.1-rc.2 版本完成验证。单独的 npm 捆绑包分发已延期，目前不可用。

该捆绑包提供四个 Agent 级工具（cortex_search、 cortex_related、cortex_impact 和 cortex_rules）以及五个 Cortex 行为技能（change-impact、context-review、pattern-review、repo-research 和 using-cortex）。检索在本地进行，范围限于仓库，且需要明确调用，由用户控制。该集成不会自动初始化、更新或监视仓库。

V2 主动式／辅助式检索仍处于规划和实验阶段；Cortex 2.6.0 未包含此功能。详情请参阅 V1 到 V2 集成计划。

链接

• 网站
• 更新日志
• 问题

许可证

MIT