Corbell

Corbell：用代码图谱武装每一个架构决策

一个团队的心碎时刻

想象这个场景：周一早上，你接手一个「只改一行配置」的任务。翻遍了 Confluence、Slack、设计文档，最后在一位已经离职的工程师的本地分支里找到了答案——原来这个接口依赖的是另一个服务的隐藏行为，而你根本不知道这个服务存在。

这是中大型工程团队的日常：架构知识散落在代码、文档、Slack 和离职员工的记忆里。当代码库从 1 个扩展到 10 个服务，「全局视角」就成了奢侈品。

Corbell 正是为解决这个问题而生的。

图1：Corbell 工作流：代码图谱 → 知识注入 → AI 规范生成

---

核心定位：给 AI 编程工具用的「架构记忆」

Corbell 的本质，是一个本地知识图谱构建 + AI 规范生成工具链。它不走云端，不建服务器，直接在你的笔记本上跑，对接你已有的代码仓库，输出结构化的设计文档。

如果你用过 Cursor、Claude Code、Copilot 等 AI 编程工具，你会发现一个痛点：AI 能写代码，但不知道你团队的整体架构。它可能生成一个 Kafka 消息队列方案，而你们公司明文规定「只用 SQS」。Corbell 通过构建跨仓库代码图谱，把这些隐式约束注入 AI 的上下文中。

类比：如果说 AI 编程工具是大脑，Corbell 就是海马体——负责存储和检索团队的系统记忆，让每次决策都基于真实的代码上下文，而不是凭空生成。

---

技术架构：图谱构建 → 语义搜索 → 规范生成

Corbell 的技术栈选型非常务实：纯 Python（≥3.11）、无重型依赖、功能模块化。核心依赖包括：

• Typer：构建 CLI 命令行界面（corbell init、corbell spec new、corbell graph build）
• Pydantic：数据建模与验证（workspace 配置、图谱节点/边、任务结构）
• GitPython：直接操作 Git 仓库，解析代码变更历史
• sentence-transformers + transformers：为代码片段生成语义向量，支持 embedding 相似性搜索
• tree-sitter（可选插件）：精确提取多语言（Python/JS/TS/Go/Java/Rust 等）方法签名和调用关系
• Rich：终端富文本输出，彩色日志和进度条

图2：Corbell UI 界面 — 交互式本地架构图谱浏览器（端口 7433）

目录结构体现了清晰的模块划分：

corbell/
  cli/commands/    # CLI 命令（spec、graph、export、docs、ui 等子命令）
  core/graph/      # 知识图谱构建（服务依赖、调用关系、方法签名）
  core/spec/       # 规范文档生成（PRD 处理、LLM 调用、模板渲染）
  core/embeddings/ # 代码向量索引（sentence-transformers）
  core/export/     # Linear / Jira / Notion 导出
  core/docs/       # 设计模式提取（扫描现有 RFC/ADR）
  core/ui/         # 本地 Web 图谱可视化（端口 7433）
  core/mcp/        # MCP (Model Context Protocol) 服务器集成

无数据库依赖：图谱数据存储在本地 SQLite 文件，不需要额外安装 Neo4j 或 Chroma（虽然可选插件支持两者）。这使得 Corbell 的部署复杂度降到了最低。

---

核心功能：从 PRD 到可执行任务的完整链路

Corbell 提供了一套完整的「架构决策 → 任务分解 → 导出到项目管理系统」的工作流：

第一步：初始化工作区

corbell init

创建 workspace.yaml，在里面声明你的多仓库拓扑（每个服务的 repo 路径、语言）和 LLM 提供商配置（Claude / GPT-4o / Ollama / AWS Bedrock / Azure OpenAI / GCP Vertex AI）。

第二步：构建代码知识图谱

corbell graph build --methods    # 服务依赖图 + 调用图 + 方法签名
corbell embeddings build         # 代码片段向量索引（语义搜索）
corbell docs scan && corbell docs learn  # 从现有 RFC/ADR 提取设计模式

Corbell 通过解析 Git 提交历史和代码结构，识别服务间的 HTTP 调用、数据流和依赖关系。tree-sitter 插件提供了精确的多语言解析能力。

第三步：AI 生成设计规范

corbell spec new --prd-file docs/payment-retry-prd.md

这是最核心的功能。Corbell 接收一个 PRD 文件或内联需求描述后：

1. 通过 embedding 相似性自动发现相关的代码模块（无需手动指定服务）
2. 从图谱中注入真实的调用路径和方法签名（不是泛泛而谈，而是具体的 HTTP 端点和接口）
3. 结合团队历史设计模式和约束（如「只用 Azure」、「p99 < 200ms」）
4. 调用 Claude 或 GPT-4o 生成完整设计文档，并显示 token 消耗和估算费用

生成的规范文档会放在 specs/ 目录，并附带一个 .review.md 侧边审查文件，由 AI 验证设计决策是否与代码图谱一致。

第四步：导出到 Linear / Jira / Notion

corbell export linear specs/payment-retry.tasks.yaml

Corbell 自动将设计规范拆解为并行可执行的任务，并导出到 Linear Issues 或 Jira Tickets，每个任务携带完整的方法上下文和服务归属——这是让 AI 编码代理真正能独立工作的关键。

---

MCP 集成：融入 AI Agent 工作流

Corbell 还支持 MCP（Model Context Protocol）服务器模式，允许 AI 编码代理在对话中直接查询架构图谱。这意味着 AI 代理在修改代码时，可以实时了解：「我改了这个方法，会影响哪些服务？这些服务各自用什么认证方式？」

图3：Corbell Star 增长曲线（2026 年初快速上升）

---

局限与挑战

没有银弹，Corbell 也有它的局限性：

1. 冷启动成本：首次构建图谱需要扫描所有仓库的 Git 历史和代码结构，对于 10+ 个仓库的大型 monorepo，这可能需要数分钟到数十分钟。
2. 多语言支持尚在完善：目前 tree-sitter 插件支持 9 种语言（Python、JS/TS、Go、Java、C#、Rust、Ruby、PHP），但对 Kotlin、Swift 等移动端语言支持尚未覆盖。
3. 无 Docker 支持：作为纯 CLI 工具，Corbell 依赖本地 Python 环境（≥3.11），团队成员的机器配置不一致时，安装和版本管理会成为一个摩擦点。
4. 知识图谱的保鲜问题：代码在演进，但图谱不会自动更新。需要定期运行 corbell graph build 维护，否则 AI 生成的内容会与实际架构脱节。

---

行业意义

在 AI 代码生成工具大爆发的当下，上下文的质量直接决定 AI 输出质量。Corbell 抓住的核心矛盾是：AI 能生成代码，但无法理解团队的架构约束和历史决策。

它代表了一个趋势：从「让 AI 写代码」到「让 AI 在约束下写正确的代码」。通过把架构知识编码为可查询的图谱，Corbell 为 AI 编程工具提供了「组织级记忆」，这可能是未来 AI 工程化协作的关键基础设施之一。