Coderadius

说明

CodeRadius 处于维护模式，不再积极开发。代码仍以 Apache-2.0 许可证提供，并且功能与文档所述一致。请参阅项目状态。

随着团队采用 AI 编码工具，代码编写速度前所未有地快，但缺少全局系统上下文。CodeRadius 会静态构建涵盖整个架构的实时知识图谱，覆盖所有代码仓库中的每个服务、API、队列和数据库，让工程师和 AI Agent 能够评估影响范围、执行策略，并在交付时避免破坏下游系统。

在 order-service 中一次看似无害的重命名；几秒钟内，cr blast 就找到了它会破坏的 notification-service 消费者。探索在线演示仪表板 →

---

为什么选择 CodeRadius

AI 编码 Agent 速度很快，但对架构缺乏认知。它们可能完美地重构 API 载荷或重命名数据库字段，却不知道自己刚刚破坏了相隔三个团队的下游消费者。即使不使用 AI，未记录的依赖也会不断累积，直到每次跨服务变更都变成一次考古挖掘。

CodeRadius 借助同一张图谱上的三项能力解决这一问题：

• 合并前评估影响范围：cr blast 就是架构领域的 terraform plan。它会在内存中计算变更与图谱之间的拓扑差异，并在几秒内返回结构化发现。语义化退出码（0 SAFE、1 WATCH、2 BREAKING）让 CI 和 Agent 无需解析文本即可分支处理。
• 为 AI Agent 提供实时上下文：原生 MCP 服务让任何 Agent 都能在编写代码之前查询数据契约、下游消费者和变更影响。
• 将治理作为代码：以声明式 YAML 策略针对实时架构图谱进行评估，而不是针对文件级 lint：未指定所有者的服务、依赖已弃用组件且暴露 API 的服务，以及共享数据库反模式。

本地优先。 你的代码绝不会离开本机：可以使用自己的 LLM 密钥，也可以使用 Ollama 完全在本地运行。不收集遥测数据。唯一的其他网络请求是每天一次的版本检查（设置 CR_NO_UPDATE_CHECK=1 即可禁用）。

---

项目状态

CodeRadius 处于维护模式。目前没有路线图，也没有计划中的版本发布；问题和拉取请求不会得到积极的分流处理。

确定性核心（AST 解析、导入和污点分析、图谱构建、影响范围分析）由 5,400 多个单元测试和一套确定性评估套件保障；兼容性矩阵中标记为 eval-verified 的每个框架，均由已提交的测试固件进行回归测试。

LLM 语义提取的质量因技术栈和提供方而异。

欢迎基于 Apache-2.0 许可证创建分支。

---

快速开始

要求：Docker（用于本地图数据库）。CLI 随附适用于 macOS 和 Linux（x64/arm64）的独立二进制文件，无需安装其他内容。

npm i -g coderadius     # or: bun add -g coderadius

或不使用包管理器：

curl -fsSL https://raw.githubusercontent.com/coderadius-ai/coderadius/main/scripts/install.sh | bash

若要改为从源代码运行（贡献者；需要 Bun ≥ 1.0 和 Node.js ≥ 22）：

git clone https://github.com/coderadius-ai/coderadius.git
cd coderadius
bun install
bun link        # exposes the `cr` binary globally (runs from source, no build step)

然后，在你要分析的仓库中运行：

cr init                              # configure your LLM provider, generate a smart .crignore
cr up                                # start the local graph database (Memgraph via Docker)

cr analyze code .                    # build the graph (default: --depth semantic)
cr analyze code . --depth structure  # AST-only scan, zero LLM calls
cr analyze code . --depth contracts  # full semantic extraction with data contracts

cr blast                             # blast radius of your current changes vs origin/main
cr blast feature/checkout            # blast radius of a branch (shorthand for --head)
cr ui                                # generate the architecture dashboard
cr mcp start                         # MCP server for your IDE agent

将多个仓库分析到同一张图中（cr analyze code ../orders ../payments ../shipping），即可实现跨仓库影响范围分析。

---

工作原理

与依赖运行时流量的可观测性工具不同，CodeRadius 通过四阶段管线静态地构建图：

1. 自动发现：从代码库或 Backstage 目录中检测服务边界、单体仓库和多仓库架构。
2. 污点分析引擎：通过 Tree-sitter AST 解析，仅识别执行外部 I/O 的函数（HTTP 调用、数据库查询、消息代理事件）。忽略纯业务逻辑。污点引擎会在消耗任何 LLM 令牌之前过滤掉约 85% 的函数。
3. 语义提取：将带污点的函数发送给你选择的 LLM，以提取意图、负载和基础设施依赖项。Merkle 哈希缓存让增量运行只需几秒，而非几小时。
4. 全局边解析：将服务 A 中新发现的客户端调用与服务 B 中规范的 OpenAPI 端点匹配，弥合跨仓库分析的差距。

每个节点和边都包含依据：事实的来源（AST、LLM、声明、基础设施）、支持证据，以及可信度。

基于 Bun、tree-sitter、Mastra + Vercel AI SDK 和 Memgraph 构建。

---

MCP 服务

CodeRadius 附带原生 MCP 服务，可接入任何兼容 MCP 的 Agent（Claude Code、Cursor、Windsurf、Gemini CLI）。Agent 会发现这些工具，并在编写代码前检查影响：

{
  "mcpServers": {
    "coderadius": {
      "command": "cr",
      "args": ["mcp", "start"]
    }
  }
}

工具	对 Agent 的用途
resolve_service_context	帮助 Agent 定位：将文件路径、git 远程地址或仓库名称映射到对应的服务、团队和仓库。
list_services	列出所有服务及其负责人、语言和部署拓扑。
get_service_details	深入了解单个服务：公开的 API、端点数量、部署单元、CI/CD 和 Docker 基础设施。
get_repository_details	查看仓库状况：服务、管线、Docker 镜像、工具配置、构建任务和提交活跃度。
get_data_contract	在修改前查看负载、事件或数据库表的精确架构（字段和类型）。
analyze_blast_radius	分析资源（表、通道、端点）的上游生产者和下游消费者。
evaluate_code_change_impact	在提交前，通过内存中的拓扑差异分析评估拟议变更的影响范围。
trace_data_lineage	跨服务、代理和 API 跟踪数据字段。
analyze_architecture_gravity	按评分列出单点故障（SPOF）、共享数据库反模式和耦合热点。
analyze_agentic_context	按仓库查看 AI 工具的采用情况：工具、配置、技能和工作流。

完整指南：coderadius.ai/docs/guide/mcp-server

---

当前支持

语言：TypeScript · PHP · Python · Go · Java

框架（经评估验证）：NestJS · Express · Fastify · Hono · Koa · Symfony · Laravel · Slim · Spring Boot · JAX-RS

框架（启发式 + LLM）：FastAPI · Flask · Django · Gin · Fiber

协议和基础设施：REST · OpenAPI · GraphQL · RabbitMQ · Google Pub/Sub · PostgreSQL · MySQL

CI/CD 接入：GitHub Actions · GitLab CI

LLM 提供商：Google Vertex AI · Google Gemini API · OpenAI · Anthropic · Amazon Bedrock · Ollama（完全本地运行，无需 API 密钥）

→ 完整兼容性矩阵

---

基础功能之外

• 架构仪表板：独立的 HTML 报告，包含服务清单、单点故障（SPOF）分析、治理违规情况和依赖健康状况（cr ui）。
• Agent Harness：绘制整个服务群中 AI 工具的采用情况：成熟度级别、上下文缺口、团队覆盖范围。
• 运行时追踪：将 Datadog/Jaeger 追踪（cr analyze traces）叠加到静态图上，以验证架构是否符合实际情况。
• 动态文档：为任意服务自动生成 ARCHITECTURE.md（cr docs generate）。

---

文档

• 用户指南：docs/guide/，包括简介、CLI 命令、影响评估、治理策略、配置
• 架构深入解析：docs/architecture/，涵盖数据摄取管道、图数据模型、API 端点去重、服务拓扑、接地契约

---

参与贡献

本项目不再接受新功能。如果你将其 fork，语言插件、框架信号和连接提取器都设计为相互隔离的扩展点。请参阅 CONTRIBUTING.md。

---

许可证

Apache-2.0