概述

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 与简单方法调用,把目标写入 <unresolved>:: 前缀的关系,供后续统一解析 资料来源：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 <symbol> 给出符号签名、文档、依赖与调用链。检索结果可输出为 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 <path> 后,代理即可串联多个工具完成「搜索 → 取详情 → 拉依赖」的链式调用 资料来源：examples/mcp-claude/README.md:1-60。

架构总览

flowchart LR
  A[源码文件] --> B[语言解析器<br/>parsers/]
  B --> C[Symbol & Relationship]
  C --> D[图存储<br/>graph.db]
  D --> E[CLI 命令<br/>index/query/show/audit]
  D --> F[MCP Server<br/>serve]
  D --> G[Web UI<br/>Overview + Graph]
  E --> H[终端/脚本]
  F --> I[AI 代理<br/>Claude/Cursor]
  G --> J[浏览器]

失败模式与配置要点

• 首次索引需执行 codeatlas init 生成 codeatlas.toml,然后运行 codeatlas index 全量建图 资料来源：README.md:1-80。
• 解析器对未解析的跨文件目标统一以 <unresolved>::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

• 安装与发布说明
• MCP 集成示例
• 前端 Overview 页面

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())。

flowchart LR
    A[GitHub App] -->|签名 Webhook| B[托管控制平面<br/>hosted.py]
    B --> C[后台同步 Worker<br/>hosted_worker.py]
    C --> D[(知识图谱 DB<br/>.codeatlas/graph.db)]
    B --> E[远程 MCP 端点<br/>hosted_routes.py]
    E --> F[Claude Code / Cursor / 其他代理]
    B --> G[评估套件<br/>hosted_eval.py]
    B --> H[可观测性<br/>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())。

常见失败模式与排障

• 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 概览
• MCP 集成示例:Claude Code / Cursor
• 评估与基准报告
• 可观测性仪表盘规范

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 排序并以 <KindDot kind={r.kind} /> 高亮符号类型；点击条目通过 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 状态。

flowchart LR
    subgraph Clients["客户端"]
        Web["Web UI<br/>(React + Vite)"]
        VSCode["VS Code 扩展<br/>(codeatlas.* 命令)"]
        Agent["AI Agent / MCP 客户端"]
    end
    API["HTTP/JSON API<br/>(FastAPI)"]
    DB[("SQLite + FTS5<br/>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
• MCP / Claude Code 集成示例：examples/mcp-claude/README.md
• v1.0.0 发布说明：CodeAtlas v1.0.0

部署形态与运行入口

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 客户端的标准入口：

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）。

flowchart LR
  Repo[源代码仓库] -->|codeatlas index| DB[(graph.db)]
  DB --> CLI[codeatlas CLI]
  DB --> UI[Web UI<br/>frontend]
  DB --> MCP[FastMCP Server<br/>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 通过 <LivePill status={live.status} lastEventAt={live.lastEventAt} /> 组件实时展示后端事件状态，这是一种轻量的"心跳"指示（资料来源：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 中负责评估的关键命令包括：

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 中正常生成。

参见

• 代码解析与多语言支持
• 检索与图算法
• MCP 集成与代理工具

Pitfall Log / 踩坑日志

项目：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