代码智能系统

代码图集

CodeAtlas是一个基于Rust的AI代理和开发人员代码智能系统 工具。

它对存储库进行一次索引，存储本地结构化索引，并允许您询问 关于符号、文件和存储库结构的高信号问题 每次都要重新读取整个代码库。

目录

• CodeAtlas是什么
• 你能用它做什么
• 安装
• 快速开始
• 语义适配器设置
• MCP服务器设置
• 如何在今天的AI中使用它
• MCP集成形状
• AI使用示例
• 服务架构
• 当前状态
• 设计原则
• 路线图
• 贡献

CodeAtlas是什么

CodeAtlas为您提供：

• 跨索引存储库快速搜索符号。
• 文件和存储库结构视图。
• 从本地索引检索文件内容。
• 语法索引基线，语义丰富，语言为母语 分析是可用的。
• 即使没有符号适配器，也能识别语言的文件级索引基线。
• 适用于自动化和人工智能工具的确定性输出。

如今，该存储库提供：

• 持久本地服务： codeatlas serve
• 具有生命周期操作的多仓库目录： codeatlas repo add/list/status/refresh/remove
• 用于AI客户端的MCP网桥： codeatlas mcp bridge
• 用于简单单仓库使用的直接MCP服务器： codeatlas mcp serve
• 用于索引和查询的本地CLI
• 具有托管就绪边界的本地优先架构

今天，这个存储库 不 提供：

• 独立托管部署
• 身份验证、租赁或多用户控制
• Docker打包（推迟跟进）

规范的本地使用模型是一个持久服务，管理多个 存储库。AI客户端通过MCP网桥连接。

你能用它做什么

服务和回购管理

• serve：启动持久本地HTTP服务
• repo add <path>：注册并索引存储库
• repo list：列出所有已注册的存储库及其状态
• repo status <repo_id>：显示存储库的详细状态
• repo refresh <repo_id>：重新索引已注册的存储库
• repo remove <repo_id>：注销存储库并清理数据

查询

• search-symbols：查找函数、类、方法、类型和常量
• get-symbol：通过稳定ID获取精确的符号（CLI使用连字符；MCP使用下划线，例如。 get_symbol / get_symbols)
• file-outline：检查文件中的符号
• file-tree：检查存储库中的索引文件
• repo-outline：检查存储库结构和计数

人工智能整合

• mcp bridge：启动指向持久服务的MCP网桥（推荐）
• mcp serve：启动一个直接的stdio MCP服务器（简单的单仓库使用）

其他

• index：构建或更新本地索引（较低级别；首选 repo add)
• quality-report：检查语义覆盖率并合并质量指标

安装

选项1：使用Cargo从源代码安装（建议用于v1）

需要Rust工具链（1.81+）。

cargo install --git https://github.com/developepper/CodeAtlas.git --bin codeatlas

这将构建并安装 codeatlas 二进制到 ~/.cargo/bin/.确保 该目录位于您的 PATH.

安装后，验证其是否正常工作：

codeatlas help

选项2：从本地克隆构建

git clone https://github.com/developepper/CodeAtlas.git
cd CodeAtlas
cargo build --release -p cli

二进制文件位于 ./target/release/codeatlas。将其复制到您的 PATH 或者直接运行它。

尚未支持的内容

• 预构建的GitHub发布二进制文件
• 自制配方
• 平台特定安装程序(.deb, .rpm, .msi)
• Docker镜像

这些可能会根据需求在未来的版本中添加。

快速开始

1.安装代码图集

看 安装 上面。以下示例假设 codeatlas 在你的 PATH.

2.启动服务并添加存储库

# Start the persistent service (runs in foreground).
codeatlas serve &

# Add repositories to the catalog.
codeatlas repo add /absolute/path/to/my-app
codeatlas repo add /absolute/path/to/billing

# Check what's registered.
codeatlas repo list

该服务将数据存储在 ~/.codeatlas/ 默认情况下（用覆盖 --data-root <path> 或 CODEATLAS_DATA_ROOT).这 repo_id 源自于 目录名--索引 /Users/alex/work/my-app 生产 repo_id my-app.

3.连接AI客户端

配置您的AI客户端以使用MCP网桥：

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "bridge"]
    }
  }
}

就是这样。网桥连接到正在运行的服务，并公开所有索引 通过标准MCP工具界面访问存储库。看 MCP服务器设置 以客户为例。

4.从CLI查询

所有查询命令默认为共享存储 ~/.codeatlas/metadata.db. 使用 --db <path> 以覆盖。

codeatlas search-symbols greet --repo my-app
codeatlas get-symbol 'my-app//src/lib.rs::greet#function'
codeatlas file-outline src/lib.rs --repo my-app
codeatlas file-tree --repo my-app
codeatlas repo-outline --repo my-app

5.管理存储库

# Re-index after code changes.
codeatlas repo refresh my-app

# Check status.
codeatlas repo status my-app

# Remove a repo and clean up its data.
codeatlas repo remove my-app

语义适配器设置

语义覆盖是可选的。没有它，索引仍然有效--已识别 文件总是在文件级别（文件树、文件内容检索、文件索引等）进行索引， repo大纲），即使没有可用的符号适配器。详细诊断 步骤，请参阅 操作手册.

TypeScript语义适配器

CodeAtlas寻找 tsserver 按照以下顺序：

1. TSSERVER_PATH
2. node_modules/.bin/tsserver
3. 系统 PATH

Kotlin语义适配器

CodeAtlas按以下顺序查找Kotlin运行时依赖关系：

1. JAVA_HOME/bin/java
2. 系统 PATH
3. KOTLIN_BRIDGE_JAR
4. 回购本地 .codeatlas/kotlin-bridge.jar

如果缺少这些运行时，CodeAtlas将回退到语法适配器，其中 政策允许。

MCP服务器设置

CodeAtlas提供了两种MCP集成路径：

1. MCP电桥 （推荐）--一个代理工具调用的精简stdio进程 到持久的CodeAtlas服务。一个服务，多个仓库，一个客户 配置。
2. 直接MCP服务器 --用于简单单仓库的独立stdio服务器 工作流程。不需要服务。

两者都使用换行符分隔的JSON-RPC 2.0（MCP规范2025-11-25）。兼容性 注释和互操作性垫片记录在 docs/architecture/mcp-client兼容性.md.

方案1:MCP桥（推荐）

先决条件：

1. 安装 codeatlas （参见 安装).
2. 启动服务： codeatlas serve
3. 添加至少一个repo： codeatlas repo add /path/to/repo

客户端配置

克劳德桌面版

添加到您的Claude Desktop MCP配置(claude_desktop_config.json):

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "bridge"]
    }
  }
}

光标

添加到光标MCP设置(.cursor/mcp.json):

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "bridge"]
    }
  }
}

OpenAI Codex命令行界面

创建或编辑 .codex/config.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "bridge"]
    }
  }
}

通用stdio MCP客户端

将其配置为生成：

codeatlas mcp bridge

这座桥连接到服务站 127.0.0.1:52337 默认情况下。以（权力）否决 随着 --service-url <host:port> 或 CODEATLAS_PORT/CODEATLAS_HOST 环境变量。

选项2：直接MCP服务器

对于不运行持久化服务的简单单仓库使用：

codeatlas mcp serve --db ~/.codeatlas/metadata.db

客户端配置与上述相同，但使用 ["mcp", "serve"] （或 ["mcp", "serve", "--db", "/path/to/metadata.db"])而不是 ["mcp", "bridge"].

可用工具

网桥和直接服务器都通过以下方式公开这些工具 tools/list:

接受存储库范围的工具 repo_id 作为一个参数。符号ID包括 回购前缀（例如。， my-app//src/lib.rs::Config#class).这 repo_id 是 从索引目录名称派生（例如，索引 /home/user/my-app 生产 repo_id my-app).

故障排除

“无法访问CodeAtlas服务” （bridge）--服务未运行。 从以下内容开始 codeatlas serve.

“找不到数据库” （直接服务器）-- --db 路径不存在。 跑 codeatlas repo add <path> 或 codeatlas index <path> 第一。

空工具结果 --验证 repo_id 匹配索引存储库。 使用 codeatlas repo list 或 list_repos 查看可用存储库的工具。

stdout上没有响应 --确保客户端使用换行符分隔的JSON-RPC， 不是内容长度框架。

不支持的内容

• 内容物长度框架MCP（2024-11-05运输）
• 身份验证、租赁或多用户访问
• 远程/托管服务
• 服务HTTP API(/tools/call, /repos等等）是内部的 本地机器。AI客户端应使用MCP网桥，而不是HTTP端点 直接。

如何在今天的AI中使用它

选项1：具有持久服务的MCP网桥（推荐）

启动服务，添加您的repos，并配置您的AI客户端以使用 桥。看 快速开始 和 MCP服务器设置.

选项2：将CLI用作代理工作流中的检索工具

典型回路：

1. 对存储库进行一次索引。
2. 让代理人打电话 codeatlas 当需要结构时，CLI命令。
3. 仅将相关输出反馈给代理。

代理或包装器可以调用的shell命令示例：

codeatlas search-symbols AuthService --repo my-app
codeatlas file-outline src/server.ts --repo my-app
codeatlas repo-outline --repo my-app

MCP集成形状

MCP服务器将工具结果作为结构化信封返回，信封中包含：

• status — "success" 或 "error"
• payload --工具的JSON结果
• error --带有代码、消息和可重试标志的结构化错误
• _meta --信封元数据

这 _meta 有效载荷包括：

• timing_ms --工具调用的挂钟时间
• truncated --结果是否受到限制
• quality_stats --返回结果的语义/语法质量混合
• index_version --为查询提供服务的索引的架构版本

这使得它适用于需要结构化检索、稳定工具的代理 行为和质量来源。

AI使用示例

示例：缩小重构目标

1. 运行：

codeatlas search-symbols PaymentService --repo billing

2. 从结果中选择确切的符号ID（符号ID包括repo 前缀，例如。 billing//src/payment/service.ts::PaymentService#class).
3. 运行：

codeatlas get-symbol 'billing//src/payment/service.ts::PaymentService#class'

4. 请代理仅对该类及其文件大纲进行推理，而不是 整个存储库。

示例：编辑前检查可疑文件

codeatlas file-outline src/auth/session.rs --repo my-app

使用该输出询问代理：

• 其功能是自己的会话无效
• 在哪里修补身份验证行为
• 文件是否包含相关的辅助方法

示例：在信任结构结果之前验证语义覆盖率

codeatlas quality-report /absolute/path/to/repo

使用该输出来决定代理是否应该信任语义结果或 回到更广泛的文件读取。

服务体系结构

规范的本地部署是一个持久的CodeAtlas服务管理 多个存储库：

AI Client (Claude, Cursor)
    |  stdio MCP
MCP Bridge (codeatlas mcp bridge)
    |  HTTP (localhost)
CodeAtlas Service (codeatlas serve)
    |
Shared Store (~/.codeatlas/)
    ├── metadata.db
    ├── blobs/
    ├── repo: my-app
    ├── repo: billing
    └── repo: shared-lib

服务正在监听 127.0.0.1:52337 默认情况下，并公开：

• GET /health --健康检查
• GET /status --服务元数据（版本、正常运行时间、仓库计数）
• GET /repos --列出所有存储库
• GET /repos/{repo_id} --存储库详细信息
• DELETE /repos/{repo_id} --删除存储库
• POST /tools/call --执行查询工具

直接存储命令(codeatlas index, codeatlas mcp serve --db, codeatlas search-symbols --repo等）继续为低级别工作 工作流程。服务模型是日常多仓库使用的推荐路径。

对于架构决策以及与未来托管部署的关系， 看见 docs/architecture/persistent-local-service.md.

当前状态

里程碑M0-M9已完成：

• M0-M4：治理、核心模型、发现/适配器、存储和索引管道。
• M5：查询引擎和确定性排名。
• M6:MCP服务器合同和本地CLI接口。
• M7：增量索引、git diff加速和确定性回归覆盖率。
• M8:OpenTetry跟踪、带编辑的结构化日志记录、安全回归套件和基准阈值强制。
• M9:TypeScript和Kotlin语义适配器、置信度感知语法+语义合并、语义质量回归门控和语义覆盖率/胜率指标。

工作区板条箱

基础设施

• 产品和实施规范 docs/specifications/.
• 问题驱动的执行计划，每个问题有一个PR政策。
• 治理和贡献工作流程文档。
• GitHub为PR设置CI质量门并推动 master （fmt、clippy、测试、构建、文档、MSRV检查）。
• Serde兼容性夹具和快照测试，用于模式前向兼容性。
• 适配器合同测试工具，用于防止适配器在不同实施方式之间漂移。
• 语义回归利用TypeScript和Kotlin的基于夹具的KPI阈值。
• OpenTetry跨索引、查询和MCP请求流进行检测。
• 结构化CLI日志记录，具有敏感字段编辑功能，用于本地和机器可读输出。
• 恶意输入、遍历/符号链接转义、格式错误的文件和资源限制的安全回归覆盖率。
• CI中用于发现、索引和查询延迟回归的基准和阈值覆盖率。

语言覆盖范围

CodeAtlas在发现过程中识别了许多语言（Rust、TypeScript、Python等）， JavaScript、Kotlin、Java、Python、PHP、Go、Ruby、C、C++、C#、Swift、Shell， JSON、YAML、TOML、Markdown、SQL、Dockerfile）。索引深度取决于 适配器可用性：

语法索引是主要公认代码语言的基准。每 识别的文件获取文件记录、存储的内容blob，并显示在文件中 树和repo大纲查询。符号提取是附加的 基线。

能力层次模型

CodeAtlas将每个索引文件分类到一个功能层中，该功能层描述 它收到的索引深度：

• 仅限文件：仅文件记录和内容blob；没有提取符号。
• 仅语法：由树型语法后端提取的符号。
• 语法加语义：语义后端丰富了语法基线。
• 仅限语义 （过渡性）：语义后端产生符号，但没有 语法后端仍然可用。这目前适用于TypeScript和 Kotlin具有语义后端，但尚未迁移到 语法平台。此层将通过添加语法后端来解决 这些语言。

所有查询表面都公开了文件和符号记录的功能层，因此 消费者可以理解索引深度。看 docs/architecture/capability-tier-query-behavior.md 对于完整查询 行为规范。

建筑

语法索引是公认代码语言的默认基线，有支持 基于多语言树形图平台(syntax-platform 板条箱）。语义 索引丰富了语言本机运行时的语法基线 可用。TypeScript和Kotlin目前只运行语义路径，因为 它们在新的子系统上还没有语法后端；一旦这些 添加后，它们将实现完整的语法和语义层。仅限文件 索引仍然是没有语法后端的语言的后备方案。

规范的架构设计在 docs/architecture/universal-syntax-indexing-architecture.md.规划 工件在 docs/planning/universal-syntax-indexing.md.

什么还不存在

• 监视器/本地文件系统触发更新模式。
• 超越当前TypeScript和Kotlin实现的语义适配器。
• 当前集合之外的其他语言（Go、Java、JavaScript、PHP、Python、Rust）的语法后端。
• Docker为持久服务打包。
• 托管身份验证、配额和多租户控制。
• 超出本地CLI基线的生产可观察性仪表板和托管遥测/导出集成。

语义适配器运行时发现

生产CLI索引将在语义适配器的本地运行时注册它们 依赖关系是可用的，否则将退回到仅语法解析。

• TypeScript语义适配器：
  • TSSERVER_PATH
  • 回购本地 node_modules/.bin/tsserver
  • 系统 PATH
• Kotlin语义适配器：
  • JAVA_HOME/bin/java 或系统 PATH
  • KOTLIN_BRIDGE_JAR
  • 回购本地 .codeatlas/kotlin-bridge.jar

如果这些依赖关系不存在，索引仍然会成功。语言与 语法适配器退回到仅语法提取。公认的语言 没有任何适配器的情况下，仍然在文件级别进行索引——文件树、文件 即使没有符号，内容检索和仓库大纲仍然有用。

设计原则

• 广泛的语法基线，语义丰富。
• 具有托管就绪架构的本地优先信任模型。
• 设计安全性（将索引代码视为敏感、不可信的输入）。
• 强确定性和稳定的API/工具行为。
• 可观察性和质量指标是首要要求。
• 支持干净的长期架构而不是向后兼容性，同时 这个项目还处于早期阶段。

路线图

规划工件：

• docs/architecture/rust-code-intelligence-plan.md
• docs/architecture/deployment-modes.md
• docs/operations/runbook.md
• docs/planning/issue-backlog.md
• docs/planning/post-v1-roadmap.md
• docs/planning/universal-syntax-indexing.md
• docs/workflow/github-process.md
• docs/engineering-principles.md

规范规范：

• docs/specifications/rust-code-intelligence-platform-spec.md

贡献

投稿遵循严格的质量门和问题/公关纪律。

从这里开始：

• CONTRIBUTING.md

许可证

许可证尚未定义。

添加一个 LICENSE 首次公开发布之前的文件。