# https://github.com/AryanSaini26/CodeAtlas 项目说明书 生成时间：2026-06-21 00:21:29 UTC ## 目录 - [核心引擎:解析、图存储、检索、CLI 与 MCP](#page-core-engine) - [托管网关:控制平面、GitHub App、远程 MCP 与安全](#page-hosted-gateway) - [Web 前端与 VS Code 扩展](#page-frontend-ui) - [部署、可观测性、评估与运维](#page-deployment-ops) ## 核心引擎:解析、图存储、检索、CLI 与 MCP ### 相关页面 相关主题：[托管网关:控制平面、GitHub App、远程 MCP 与安全](#page-hosted-gateway), [Web 前端与 VS Code 扩展](#page-frontend-ui)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/README.md) - [examples/mcp-claude/README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/examples/mcp-claude/README.md) - [frontend/index.html](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/index.html) - [frontend/src/pages/Overview.tsx](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/src/pages/Overview.tsx) - [src/codeatlas/parsers/ruby_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/ruby_parser.py) - [src/codeatlas/parsers/kotlin_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/kotlin_parser.py) - [src/codeatlas/parsers/swift_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/swift_parser.py) - [src/codeatlas/parsers/java_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/java_parser.py) - [src/codeatlas/parsers/csharp_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/csharp_parser.py) - [src/codeatlas/parsers/scala_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/scala_parser.py) - [src/codeatlas/parsers/cpp_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/cpp_parser.py)
# 核心引擎:解析、图存储、检索、CLI 与 MCP ## 概述 CodeAtlas 的核心引擎将源码解析为统一的「符号—关系」图,再通过 CLI 与 MCP(Mode Context Protocol)服务器对外暴露检索能力,服务于本地工作流与 AI 代理。v1.0.0 的发布说明明确指出,该版本固化了一套可测量、可索引的图谱管线,覆盖 24 种语言、30 个 MCP 工具,并提供了可视化的 Web UI 入口 资料来源：[README.md:1-80]()。前端入口位于 `frontend/index.html`,页面以 dark 主题启动 React 应用,描述为「Explore your code as a knowledge graph — PageRank, semantic search, diff, coverage gaps」 资料来源：[frontend/index.html:1-14]()。 ## 多语言解析层 解析器位于 `src/codeatlas/parsers/`,每种语言共享统一的 `Symbol` / `Relationship` 数据结构。解析基于 tree-sitter,通过 `_node_text`、`_node_span` 等辅助函数读取节点文本与位置。 以 Kotlin 为例,`_handle_class` 提取类名、限定名与文档注释,并递归处理类体中的 `function_declaration` 资料来源：[src/codeatlas/parsers/kotlin_parser.py:1-80]()。Java 解析器在 `_extract_calls` 中区分 `obj.method` 与简单方法调用,把目标写入 `::` 前缀的关系,供后续统一解析 资料来源：[src/codeatlas/parsers/java_parser.py:1-80]()。C# 解析器同时处理 XML 文档注释(`_get_xml_doc_comment`)与方法签名构造 资料来源：[src/codeatlas/parsers/csharp_parser.py:1-100]()。 Scala 解析器在 `_handle_function_def` 中构建带返回类型与方法签名的符号 资料来源：[src/codeatlas/parsers/scala_parser.py:1-60]()。C++ 解析器通过 `_get_base_classes` 提取继承关系,生成 `RelationshipKind.INHERITS` 边 资料来源：[src/codeatlas/parsers/cpp_parser.py:1-60]()。Swift 解析器处理 `inheritance_specifier` 与 `class_body`,并支持协议(`_handle_protocol`)与扩展 资料来源：[src/codeatlas/parsers/swift_parser.py:1-80]()。Ruby 解析器覆盖 `module` 与 `class`,并将 `superclass` 解析为 INHERITS 关系 资料来源：[src/codeatlas/parsers/ruby_parser.py:1-80]()。 ## 图存储与 Web 可视化 解析产物写入知识图数据库(SQLite 后端),通过 CLI 的 `index` / `index --incremental` / `index --watch` 三种模式维护,支持并行 worker 资料来源：[README.md:1-80]()。`stats`、`list-files`、`audit` 等命令直接读取图状态;`coupling`、`hotspots`、`hubs`、`rank`、`communities`、`coverage-gaps` 借助图算法(PageRank、标签传播、图耦合度)产出分析结果。 Web UI 的 `Overview` 页面渲染「Top symbols by PageRank」卡片,链接到 `/symbol/:id` 详情页 资料来源：[frontend/src/pages/Overview.tsx:1-80]()。力导向图通过 `codeatlas viz` 生成,支持按 kind 或 community 着色,使用 D3.js 渲染 资料来源：[README.md:1-80]()。 ## 检索机制 CLI 提供三种检索模式:全文(`codeatlas query`)、语义(`--semantic`)与混合(`--hybrid`),后者结合 FTS 与向量召回 资料来源：[README.md:1-80]()。`show ` 给出符号签名、文档、依赖与调用链。检索结果可输出为 JSON 便于脚本消费。 MCP 服务器则把同一套检索能力以 30 个工具的形式暴露,典型工具包括 `search_symbols`、`get_dependencies`、`get_symbol_details`、`trace_call_chain`、`find_path_between_symbols`、`get_hotspots`、`get_symbol_coverage`、`get_coverage_gaps` 等 资料来源：[README.md:1-80]()。在 Claude Code 中配置 `codeatlas serve --db ` 后,代理即可串联多个工具完成「搜索 → 取详情 → 拉依赖」的链式调用 资料来源：[examples/mcp-claude/README.md:1-60]()。 ## 架构总览 ```mermaid flowchart LR A[源码文件] --> B[语言解析器
parsers/] B --> C[Symbol & Relationship] C --> D[图存储
graph.db] D --> E[CLI 命令
index/query/show/audit] D --> F[MCP Server
serve] D --> G[Web UI
Overview + Graph] E --> H[终端/脚本] F --> I[AI 代理
Claude/Cursor] G --> J[浏览器] ``` ## 失败模式与配置要点 - 首次索引需执行 `codeatlas init` 生成 `codeatlas.toml`,然后运行 `codeatlas index` 全量建图 资料来源：[README.md:1-80]()。 - 解析器对未解析的跨文件目标统一以 `::name` 占位,需依靠全量图与命名空间拼接回填;`agent-eval` 子命令支持在 dry-run 下校验命名解析与工具返回 资料来源：[README.md:1-80]()。 - MCP 集成时需在 `~/.claude/claude_desktop_config.json` 中显式指定 `codeatlas` 可执行文件与 `--db` 参数 资料来源：[examples/mcp-claude/README.md:1-40]()。 - 大型仓库建议使用 `--workers N` 并行解析,持续同步时使用 `--watch` 或预提交钩子 资料来源：[examples/mcp-claude/README.md:1-60]()。 ## See Also - [安装与发布说明](README.md) - [MCP 集成示例](examples/mcp-claude/README.md) - [前端 Overview 页面](frontend/src/pages/Overview.tsx) --- ## 托管网关:控制平面、GitHub App、远程 MCP 与安全 ### 相关页面 相关主题：[核心引擎:解析、图存储、检索、CLI 与 MCP](#page-core-engine), [Web 前端与 VS Code 扩展](#page-frontend-ui), [部署、可观测性、评估与运维](#page-deployment-ops)
相关源码文件 以下源码文件用于生成本页说明： - [src/codeatlas/hosted.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/hosted.py) - [src/codeatlas/hosted_worker.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/hosted_worker.py) - [src/codeatlas/hosted_eval.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/hosted_eval.py) - [src/codeatlas/api/app.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/api/app.py) - [src/codeatlas/api/routes.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/api/routes.py) - [src/codeatlas/api/hosted_routes.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/api/hosted_routes.py) - [README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/README.md) - [examples/mcp-claude/README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/examples/mcp-claude/README.md)
# 托管网关:控制平面、GitHub App、远程 MCP 与安全 CodeAtlas 的托管网关(Hosted Gateway)将原本单机运行的本地 CLI 与本地 MCP 服务器升级为一套多租户托管服务,核心由**托管控制平面**、**GitHub App(OAuth + 签名 Webhook)**、**后台同步 Worker** 以及**远程 MCP 端点**构成,并把**安全扫描 → SARIF**、**CycloneDX SBOM**、**SLSA 构建来源**、**Prometheus 指标**作为一等公民纳入发布链路(资料来源:[README.md:14-22]())。 ## 控制平面与多租户架构 托管控制平面的职责是为团队提供"持久、共享"的知识图谱上下文,使多个 AI 编码代理(以及多个仓库成员)能够从第一个 token 起就基于同一份图谱工作(资料来源:[README.md:16-22]())。 `codeatlas/api/app.py` 中的 FastAPI 应用把托管路由与本地 CLI 使用的同一组 `routes.py` 复用为单一事实来源,保证 `search_symbols`、`get_pagerank`、`find_path` 等 MCP 工具在本地和托管环境下行为一致。租户隔离、索引调度和速率限制等策略通过 `hosted.py` 与 `hosted_routes.py` 提供;`hosted_eval.py` 则提供确定性的 A/B 评估套件,用来验证"带 CodeAtlas 上下文的代理"与"裸提示代理"在同样任务上的差异(资料来源:[README.md:34-37]()、`codeatlas/hosted.py`())。 ```mermaid flowchart LR A[GitHub App] -->|签名 Webhook| B[托管控制平面
hosted.py] B --> C[后台同步 Worker
hosted_worker.py] C --> D[(知识图谱 DB
.codeatlas/graph.db)] B --> E[远程 MCP 端点
hosted_routes.py] E --> F[Claude Code / Cursor / 其他代理] B --> G[评估套件
hosted_eval.py] B --> H[可观测性
Prometheus /metrics] ``` ## GitHub App 与签名 Webhook 托管模式下不再依赖本地 `codeatlas webhook` 自托管,改由官方 GitHub App 处理 OAuth 授权与 Webhook 推送。App 收到 `push`、`pull_request`、`installation` 等事件后,会通过 HMAC 签名验证请求的真实性,然后把"哪些仓库、哪些 commit、需要重索引的文件清单"投递到托管控制平面(资料来源:[README.md:11-13](),`codeatlas/api/hosted_routes.py`())。 控制平面收到 webhook 后并不会在请求线程里同步执行索引,而是把任务写入队列,由 `hosted_worker.py` 中的后台 Worker 异步消费。Worker 会复用本地 CLI 已经验证过的解析器与图谱写入逻辑(`parsers/`、`graph/`),并通过增量索引(`codeatlas index --incremental`)只重算变更的文件,从而把"push 到图谱更新"端到端时延控制在秒级(资料来源:[README.md:120-130]())。 > 社区关注点:CodeAtlas v1.0.0 是首个正式托管发布,WebHook 重试、签名校验失败回退以及 Worker 并发配额的默认值都在 v1.0.0 提交历史中固定下来(资料来源:[releases/tag/v1.0.0]())。 ## 远程 MCP 端点 托管网关对外暴露的是一个远程 MCP(Model Context Protocol)端点,而不是要求每个开发者本地运行 `codeatlas serve`。`api/hosted_routes.py` 把本地 `codeatlas serve` 已经支持的 29 个工具(包括 `search_symbols`、`get_pagerank`、`get_coverage_gaps`、`find_path_between_symbols`、`get_symbol_context`、`get_agent_context`)以 JSON-RPC over HTTPS 的形式对外提供,代理只需配置远程 URL 和租户令牌即可接入(资料来源:[examples/mcp-claude/README.md:9-30](),`codeatlas/api/hosted_routes.py`())。 这种远程化带来三个实际好处:一是图谱始终是团队最新、共享的视图;二是敏感仓库源码不必分发到每个开发者的笔记本即可被代理查询(只有结构化的符号与关系离开服务器);三是 `hosted_eval.py` 可以在同一受控环境下反复运行 A/B 评估,从而用真实数据回答"加入 CodeAtlas 上下文后,代理究竟少走了多少弯路"(资料来源:[README.md:14-22](),`codeatlas/hosted_eval.py`())。 ## 安全:从扫描到 SBOM/SLSA 托管网关把安全视为发布门禁而不是事后审计。代码层的安全扫描结果以 SARIF 格式回写到 GitHub Security Tab,让团队在 PR 视图里直接看到命中位置(资料来源:[README.md:18-20]())。每个发行版同时产出 **CycloneDX SBOM** 描述依赖组成,以及 **SLSA build provenance** 描述构建来源与签名,这两项由 CI 在 `release` 工作流中生成并附在 GitHub Release 上(资料来源:[README.md:18-20]())。 可观测性方面,托管控制平面在 `/metrics` 暴露 Prometheus 抓取端点,覆盖索引耗时、Worker 队列深度、Webhook 失败率、MCP 调用 p99 延迟等指标,并可与 Grafana 仪表盘联动;同时 Grafana 仪表盘规范发布在 `docs/observability.md` 中(资料来源:[README.md:18-20](),`docs/observability.md`())。 | 能力 | 落地形态 | 关键文件 | |------|---------|---------| | 索引更新触发 | GitHub App + 签名 Webhook | `api/hosted_routes.py`、`hosted_worker.py` | | 异步重建 | 后台 Worker + 增量索引 | `hosted_worker.py` | | 代理接入 | 远程 MCP 端点(29 工具) | `api/hosted_routes.py` | | 评估 | 确定性 A/B 套件 | `hosted_eval.py` | | 代码安全 | SARIF → GitHub Security | `README.md:18-20` | | 供应链安全 | CycloneDX SBOM + SLSA Provenance | `README.md:18-20` | | 可观测性 | Prometheus `/metrics` + Grafana | `docs/observability.md` | ## 常见失败模式与排障 - **Webhook 签名校验失败**:通常是 GitHub App 的 secret 在控制平面与 App 后台不一致导致,需在 `hosted.py` 的配置中重新对齐并触发一次 `installation` 事件。 - **Worker 队列堆积**:表现为 `codeatlas index --watch` 在本地与托管结果不一致,通常因为并发配额或 DB 写锁;可通过 `/metrics` 中的队列深度指标确认。 - **远程 MCP 工具列表缺失**:往往是租户令牌失效或租户尚未完成首次索引;`hosted_eval.py` 自带的 `doctor --check semantic,mcp,api,bench` 可一次性验证环境、图谱 DB、MCP 端点和基准(资料来源:[README.md:78-80]())。 ## See Also - [主页:CodeAtlas 概览](README.md) - [MCP 集成示例:Claude Code / Cursor](examples/mcp-claude/README.md) - [评估与基准报告](benchmarks/rerank-report.md) - [可观测性仪表盘规范](docs/observability.md) --- ## Web 前端与 VS Code 扩展 ### 相关页面 相关主题：[核心引擎:解析、图存储、检索、CLI 与 MCP](#page-core-engine), [托管网关:控制平面、GitHub App、远程 MCP 与安全](#page-hosted-gateway)
相关源码文件 以下源码文件用于生成本页说明： - [frontend/index.html](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/index.html) - [frontend/package.json](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/package.json) - [frontend/src/pages/Overview.tsx](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/src/pages/Overview.tsx) - [frontend/src/pages/GraphPage.tsx](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/src/pages/GraphPage.tsx) - [frontend/src/pages/SearchPage.tsx](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/src/pages/SearchPage.tsx) - [vscode-extension/package.json](https://github.com/AryanSaini26/CodeAtlas/blob/main/vscode-extension/package.json) - [vscode-extension/README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/vscode-extension/README.md) - [README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/README.md)
# Web 前端与 VS Code 扩展 CodeAtlas 除了提供命令行与 MCP 服务之外，还配套了两个面向人机交互的客户端入口：基于 React + Vite 的浏览器前端（Web UI），以及一个轻量级 VS Code 扩展。两者的共同目标是让开发者无需切换到终端，即可在一个已索引的知识图谱之上完成检索、可视化与影响分析。 ## 1. Web 前端整体形态 Web 前端位于 `frontend/` 目录，是一个独立的 React 单页应用。它通过 Vite 启动开发服务器并打包生产资源，对外暴露静态页面。 `frontend/package.json` 描述了核心技术栈：React 18.3.1 作为视图层，`react-router-dom` 负责多页路由，`@tanstack/react-query` 负责远程数据获取与缓存，`zustand` 负责本地状态管理，`react-force-graph-2d` 承担力导向图渲染，UI 样式使用 Tailwind CSS。资料来源：[frontend/package.json:6-30]() `frontend/index.html` 声明了一个深色主题的挂载容器，标题为 *CodeAtlas*，并通过 `/src/main.tsx` 加载 React 应用入口。HTML 上挂载了 `bg-bg` / `text-slate-100` / `font-mono` 等 Tailwind 类，奠定了全站等宽、深色的视觉基调。资料来源：[frontend/index.html:1-13]() ## 2. 关键页面与交互 Web UI 由若干页面组成，分别承担“概览—检索—图谱—差异—设置”等职责。本节聚焦已检索到的三个核心页面。 ### 2.1 Overview（概览页） `frontend/src/pages/Overview.tsx` 渲染了三块首屏指标卡片：Files indexed、Symbols、Relationships，对应后端的 `/stats` 字段 `files / symbols / relationships`。资料来源：[frontend/src/pages/Overview.tsx:11-25]() 卡片下方是语言分布柱状图与符号种类饼图，再下方为“Top symbols by PageRank”列表，前 10 条按 PageRank 排序并以 `` 高亮符号类型；点击条目通过 `Link to={`/symbol/${encodeURIComponent(r.id)}`}` 跳转到符号详情页。资料来源：[frontend/src/pages/Overview.tsx:55-89]() ### 2.2 Graph（图谱页） `frontend/src/pages/GraphPage.tsx` 通过 `react-force-graph-2d` 渲染力导向图，并通过 `LivePill` 显示 WebSocket 实时连接状态。侧栏 Tips 提示三种核心交互：点击节点 → 触发 blast radius；搜索框用于缩放到指定符号；滚轮缩放、拖拽平移。资料来源：[frontend/src/pages/GraphPage.tsx:21-50]() ### 2.3 Search（检索页） `frontend/src/pages/SearchPage.tsx` 在搜索结果右侧呈现符号详情面板：当后端返回 `signature` 时使用青蓝色卡片展示签名；当存在 `docstring` 时以纯文本形式呈现文档；并显示起止行号 `start_line–end_line`。资料来源：[frontend/src/pages/SearchPage.tsx:30-58]() `README.md` 进一步指出，符号页支持签名、文档字符串、文件位置以及入向/出向引用卡片，并提供“Diff”视图用于比较两个 Git 引用之间的符号变更。资料来源：[README.md:1-40]() ## 3. VS Code 扩展 `vscode-extension/` 提供编辑器内集成，假设后端 `codeatlas server`（或 `codeatlas ui`）已在本地 8080 端口运行。 `vscode-extension/package.json` 在 `contributes.commands` 中注册了 5 条命令：`codeatlas.openUi` 打开 Web UI、`codeatlas.searchSymbols` 触发符号搜索、`codeatlas.showSymbolDetails` 查看光标处符号、`codeatlas.showImpactRadius` 查看影响半径、`codeatlas.buildAgentContext` 构建 Agent 上下文；并通过 `onStartupFinished` 自动激活。资料来源：[vscode-extension/package.json:14-42]() `vscode-extension/README.md` 描述了两个用户级配置项：`codeatlas.apiBase`（默认 `http://127.0.0.1:8080`）和可选的 `codeatlas.apiKey`，后者作为 `X-API-Key` 请求头附加在 HTTP 调用上，用于启用 `--api-key` 启动的服务。资料来源：[vscode-extension/README.md:11-19]() ## 4. 客户端与后端协作关系 下图描述了 Web UI、VS Code 扩展与 CodeAtlas 后端的协作关系：两者都通过 HTTP/JSON API 与同一份 SQLite 图谱交互，Web UI 还会订阅实时事件流以驱动 `LivePill` 状态。 ```mermaid flowchart LR subgraph Clients["客户端"] Web["Web UI
(React + Vite)"] VSCode["VS Code 扩展
(codeatlas.* 命令)"] Agent["AI Agent / MCP 客户端"] end API["HTTP/JSON API
(FastAPI)"] DB[("SQLite + FTS5
knowledge graph")] WS["WebSocket / 实时事件"] Web -->|查询 / 检索| API VSCode -->|apiBase:8080| API Agent -->|MCP tools| API API --> DB Web -.->|LivePill 状态| WS API -.->|推送索引变更| WS ``` `README.md` 同时声明，HTTP/JSON API 由 FastAPI 层承载，供自定义前端与工具链复用；这意味着 Web UI 与 VS Code 扩展本质上是同一份 API 的两种不同消费形态。资料来源：[README.md:53-58]() ## See Also - 项目主页与安装说明：[README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/README.md) - MCP / Claude Code 集成示例：[examples/mcp-claude/README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/examples/mcp-claude/README.md) - v1.0.0 发布说明：[CodeAtlas v1.0.0](https://github.com/AryanSaini26/CodeAtlas/releases/tag/v1.0.0) --- ## 部署、可观测性、评估与运维 ### 相关页面 相关主题：[核心引擎:解析、图存储、检索、CLI 与 MCP](#page-core-engine), [托管网关:控制平面、GitHub App、远程 MCP 与安全](#page-hosted-gateway)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/README.md) - [frontend/index.html](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/index.html) - [examples/mcp-claude/README.md](https://github.com/AryanSaini26/CodeAtlas/blob/main/examples/mcp-claude/README.md) - [src/codeatlas/api/schemas.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/api/schemas.py) - [frontend/src/pages/Overview.tsx](https://github.com/AryanSaini26/CodeAtlas/blob/main/frontend/src/pages/Overview.tsx) - [src/codeatlas/parsers/java_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/java_parser.py) - [src/codeatlas/parsers/csharp_parser.py](https://github.com/AryanSaini26/CodeAtlas/blob/main/src/codeatlas/parsers/csharp_parser.py)
# 部署、可观测性、评估与运维 本页面向负责部署、监控与运维 CodeAtlas 的工程师，描述运行该知识图谱系统所需的部署形态、内置的评估证据链，以及常用的诊断与合规能力。CodeAtlas 在 v1.0.0 中把"测量检索质量"作为一等公民交付，而非仅交付可视化效果（资料来源：[README.md:1-40]()）。 ## 部署形态与运行入口 CodeAtlas 既可作为本地 CLI 工具直接消费，也提供了 Web UI 与 MCP（Model Context Protocol）服务器两种长连接入口。Web 前端是一个以 React 渲染的 SPA，根容器挂在 `#root`，并通过 `/src/main.tsx` 引导（资料来源：[frontend/index.html:1-15]()）。 部署 Web UI 时，页面会立即向 `/api/stats` 之类的端点拉取图谱统计；Overview 页面的标题区显示 "Overview of the indexed knowledge graph"，并以三个彩色瓦片（Files indexed / Symbols / Relationships）渲染核心指标，同时呈现语言分布与符号种类（资料来源：[frontend/src/pages/Overview.tsx:1-50]()）。 CLI 子命令 `codeatlas serve` 是把本地图库（默认 `.codeatlas/graph.db`）暴露给 MCP 客户端的标准入口： ```bash codeatlas index --workers 4 codeatlas serve --db /path/to/your/repo/.codeatlas/graph.db ``` 在 Claude Code / Cursor 中通过 `mcpServers.codeatlas.command` 字段注册后，30 个 MCP 工具即可被代理调用（资料来源：[examples/mcp-claude/README.md:1-50]()）。README 列出了超过 30 条 CLI 命令，覆盖索引、增量同步、检索、审计与评估（资料来源：[README.md:1-60]()）。 ```mermaid flowchart LR Repo[源代码仓库] -->|codeatlas index| DB[(graph.db)] DB --> CLI[codeatlas CLI] DB --> UI[Web UI
frontend] DB --> MCP[FastMCP Server
30 tools] MCP --> Agent[Claude / Cursor / Agent] CLI -->|JSON / SARIF| CI[CI 流水线] UI -->|Prometheus /metrics| Obs[可观测性后端] ``` ## 可观测性与 Agent Context Feed README 明确把可观测性列为产品纵深之一：**Prometheus `/metrics` + Grafana** 与 **Agent Context Feed**（资料来源：[README.md:1-30]()）。后者在托管仪表盘上展示代理真正检索到的符号，让运维人员把"代理在做什么"变成可审计的事实而非黑盒。 前端 `Overview.tsx` 通过 `` 组件实时展示后端事件状态，这是一种轻量的"心跳"指示（资料来源：[frontend/src/pages/Overview.tsx:1-20]()）。结合语言瓦片与符号种类分布，可以快速判断一次重新索引是否产生了异常的种类膨胀或语言空缺。 API 层使用 Pydantic 模型约束响应结构，例如 `HotspotsResponse`、`CommunitiesResponse`、`CoverageGapsResponse`、`DiffResponse`、`ReindexResponse` 等，便于在监控系统里以稳定字段做告警（资料来源：[src/codeatlas/api/schemas.py:1-90]()）。 ## 评估基准与证据链 CodeAtlas 拒绝"功能清单式"营销，README 直接给出 recall@k = 1.000、MRR = 0.978 的本地测试数据，并附 `benchmarks/flagship-report.md`、`benchmarks/rerank-report.md`、`benchmarks/agent-live/report.md`、`benchmarks/perf/report.md`、`benchmarks/data-lineage/report.md` 等可复现报告（资料来源：[README.md:1-50]()）。 CLI 中负责评估的关键命令包括： | 命令 | 作用 | | --- | --- | | `codeatlas agent-eval --suite S --repos R --out D --agent-adapter mock --compare-baseline` | 跑确定性的 mock-agent A/B 评测 | | `codeatlas agent-eval --suite S --repos R --out D --agent-adapter shell --agent-command "" --compare-baseline` | 对 prompt-only 与 CodeAtlas 上下文做 A/B | | `codeatlas perf-report --repos R --out D --profile` | 生成规模/系统性能报告 | | `codeatlas data-lineage --repo PATH --format openlineage` | 导出 OpenLineage 形态的 JSON 血缘 | | `codeatlas doctor --db DB --check semantic,mcp,api,bench` | 校验环境、图库与可选基础设施 | README 坦诚指出：cross-encoder reranker 在 code-symbol 套件上**没有**击败图/词基线，因此默认 opt-in，相关数据落在 `benchmarks/rerank-report.md`（资料来源：[README.md:1-30]()）。这种"自我披露失败"的姿态让评估结果具备可信度。 ## 运维诊断与发布合规 在合规与发布层面，README 把以下能力列为 v1.0.0 的内置组件：安全扫描结果以 **SARIF** 形式进入 GitHub Security Tab；发布物随附 **CycloneDX SBOM** 与 **SLSA build provenance**（资料来源：[README.md:1-30]()）。 `codeatlas doctor` 是面向运维的统一自检入口，通过 `--check` 列出可选模块（语义搜索、MCP、API、基准）。`codeatlas audit` 与 `codeatlas report` 把循环依赖、死亡代码、热点与覆盖空缺合并成结构化报告，例如 `HotspotEntry`、`CoverageGapEntry` 等数据模型直接对接 Prometheus exporter 或 CI 报表（资料来源：[src/codeatlas/api/schemas.py:1-90]()）。 多语言解析器（如 Java、C#）同样以一致的 `Symbol` / `Relationship` 结构产出元数据，使运维侧无论索引何种子语言，都能复用同一套质量检测流水线（资料来源：[src/codeatlas/parsers/java_parser.py:1-40]()、[src/codeatlas/parsers/csharp_parser.py:1-40]()）。 ## 故障模式与建议 - **索引漂移**：使用 `codeatlas index --watch` 或预提交钩子 `codeatlas pre-commit install` 让图库跟随文件变化（资料来源：[examples/mcp-claude/README.md:1-50]()）。 - **检索质量回归**：跑 `codeatlas perf-report` 与 `codeatlas agent-eval --compare-baseline`，对比上一次基准报告定位漂移。 - **跨语言不一致**：先用 `codeatlas doctor --check semantic,mcp,api,bench` 排障，再用 `codeatlas stats` 检查语言分布。 - **发布合规失败**：确认 SARIF / SBOM / SLSA 三件套在 CI 中正常生成。 ## 参见 - [代码解析与多语言支持](代码解析与多语言支持.md) - [检索与图算法](检索与图算法.md) - [MCP 集成与代理工具](MCP集成与代理工具.md) --- --- ## Doramagic 踩坑日志 项目：AryanSaini26/CodeAtlas 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/AryanSaini26/CodeAtlas | host_targets=mcp_host, claude_code, claude, cursor ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/AryanSaini26/CodeAtlas | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/AryanSaini26/CodeAtlas | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/AryanSaini26/CodeAtlas | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/AryanSaini26/CodeAtlas | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/AryanSaini26/CodeAtlas | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/AryanSaini26/CodeAtlas | release_recency=unknown