Corbell快速上手:2分钟安装并生成你的第一份架构设计Spec(附完整命令清单)

原创2026-11-14 15:41:401,154 阅读

Corbell快速上手:2分钟安装并生成你的第一份架构设计Spec(附完整命令清单)

Corbell 是一款面向后端团队的 AI 架构设计 Spec(设计文档)生成与评审工具:它扫描你的多个代码仓库,构建"服务依赖图谱",再结合团队已有的设计文档,用 LLM 自动生成符合团队既有架构模式的技术设计文档(Spec),并支持一键评审、拆解任务、导出到 Linear / Jira。全程本地运行,无需部署任何服务端。

一、Corbell 能帮你做什么?

很多后端团队的痛点:新功能要横跨 5~10 个仓库,架构决策散落在没人看的 Wiki 和聊天记录里,新人上手只能从零开始。

Corbell 的解决思路(见 README.md):

你的代码仓库 ──> corbell graph build ──> 服务依赖图谱(SQLite 本地存储)
团队设计文档 ──> corbell docs scan  ──> 设计模式提取
                          ↓
        corbell spec new ──> 自动发现相关服务 + 注入图谱与代码片段
                          ↓
                   生成完整设计文档 specs/xxx.md ✓
                          ↓
        spec review / decompose / export linear / export jira

一句话:让 AI 基于你真实的代码结构写设计文档,而不是凭空想象。

二、一键安装步骤(2 分钟搞定)

⚠️ 环境要求:Python ≥ 3.11(见 pyproject.toml)

# 1. 基础安装(图谱、嵌入索引、UI 均不需要 LLM)
pip install corbell

# 2. 加上 LLM 支持(二选一,推荐 Claude)
pip install "corbell[anthropic]"    # Claude
pip install "corbell[openai]"       # GPT-4o

# 3. 需要导出到协作工具时
pip install "corbell[notion,linear,jira]"

验证安装成功:

corbell --help

能看到 graph、spec、embeddings、ui 等命令组即安装完成。CLI 入口定义在 corbell/cli/main.py。

三、从 init 到第一份 Spec:5 步走通全流程

第 1 步:初始化工作区

进入你的项目根目录(多个仓库的父目录),运行:

corbell init

✅ 会在 corbell-data/workspace.yaml 创建配置文件(创建逻辑见 corbell/core/workspace.py),并自动探测当前目录下的服务。

第 2 步:编辑 workspace.yaml

把要分析的服务仓库填进去,并配置 LLM:

services:
  - id: payments-service
    repo: ../payments-service
    language: python        # 支持 python | typescript | go | java | rust 等

llm:
  provider: anthropic
  model: claude-sonnet-4-5-20250929
  api_key: ${ANTHROPIC_API_KEY}

第 3 步:构建服务依赖图谱

corbell graph build --methods   # 服务依赖 + 方法调用图 + 类型化签名

实现位于 corbell/core/graph/builder.py,支持 9 种语言的方法级解析。如果提取到的方法数为 0,通常是缺少 tree-sitter 语法包,执行 pip install "corbell[treesitter]" 即可。

第 4 步:构建代码嵌入索引

corbell embeddings build

用本地 all-MiniLM-L6-v2 模型为代码块建立向量索引(见 corbell/core/embeddings/),这是后续"自动发现相关服务"的关键——写 Spec 时不用手动指定 --service。

第 5 步:生成第一份 Spec 🎉

export ANTHROPIC_API_KEY="sk-ant-..."

# 从 PRD 文件生成(推荐)
corbell spec new --feature "Payment Retry" --prd-file prd.md

# 或者内联写 PRD
corbell spec new --feature "Rate Limiting" --prd "Tier 1: 100 req/min..."

Corbell 会自动完成:从 PRD 生成 3~4 条代码检索查询 → 向量相似度检索相关服务 → 注入图谱拓扑与真实代码片段 → 调用 LLM 写出完整设计文档,并显示 Token 用量和预估成本(生成器实现见 corbell/core/spec/generator.py)。

💡 没有 API Key 也能跑:会降级为模板模式,生成带有图谱上下文的结构化骨架。已有文档想"逆向补文档"?直接 corbell spec new --existing,无需 PRD。

四、用浏览器查看架构图谱

corbell ui serve          # 打开 http://localhost:7433,Ctrl+C 停止
corbell ui serve --port 8080 --no-browser

本地起一个交互式图谱浏览器:力导向图展示服务、数据库、队列和执行流,点击任意服务可看语言、依赖、方法签名与 git 变更耦合度(UI 源码见 corbell/core/ui/)。效果如下:

Corbell 架构图谱浏览器界面:服务依赖关系、执行流与架构设计Spec上下文

五、进阶:评审、拆解与导出

生成 Spec 后的完整生命周期(命令定义见 corbell/cli/commands/spec.py):

corbell spec lint specs/payment-retry.md      # 结构校验,CI 里加 --ci
corbell spec review specs/payment-retry.md    # 对照图谱核查声明 → .review.md
corbell spec approve specs/payment-retry.md   # 标记批准
corbell spec decompose specs/payment-retry.md # 拆解为并行任务 → .tasks.yaml

# 导出到协作工具
export CORBELL_LINEAR_API_KEY="lin_api_..."
corbell export linear specs/payment-retry.tasks.yaml
corbell export jira specs/payment-retry.tasks.yaml

spec review 会逐条核对 Spec 中的声明是否与真实代码图谱一致,导出的依赖关系可以导出为 Mermaid 图(命令见 corbell/cli/commands/graph.py),类似下面这种服务与数据流依赖视图:

Corbell 架构评审导出的服务依赖关系图:HTTP调用与数据库读写关系

六、完整命令清单(建议收藏)

命令 作用
corbell init 创建 corbell-data/workspace.yaml 工作区
corbell graph build --methods 构建服务依赖图 + 方法调用图
corbell graph services / deps / callpath 查看服务、依赖、方法调用路径
corbell embeddings build / query 构建代码向量索引 / 语义搜索
corbell docs scan → docs learn 从既有 RFC/ADR 中提取团队设计模式
corbell spec new 生成设计文档(支持 --prd-file、--existing)
corbell spec lint / review / approve / decompose Spec 校验、图谱核查、批准、拆解任务
corbell export notion / linear / jira 导出到 Notion / Linear / Jira
corbell ui serve 本地架构图谱浏览器(默认 7433 端口)
corbell mcp serve 启动 MCP Server,接入 Cursor / Claude Desktop

MCP 相关命令见 corbell/cli/commands/mcp.py,可让 IDE 里的 AI 直接查询你的架构图谱。

七、上手验证清单

  • [ ] corbell --help 正常输出命令组
  • [ ] corbell-data/workspace.yaml 已配置好 services 与 LLM
  • [ ] graph build 输出的 Services/Edges 数量非零
  • [ ] spec new 成功生成 specs/xxx.md 并显示 Token 用量
  • [ ] corbell ui serve 能在浏览器看到图谱

跑通以上 5 项,你的多仓库架构知识图谱就正式"活"起来了。项目社区的增长情况也值得一提:

Corbell 开源项目 Star 数量增长历史曲线图

📌 小结:pip install corbell → init → graph build → embeddings build → spec new,2 分钟安装 + 5 条命令,就能让 AI 基于真实代码结构生成第一份架构设计 Spec。更多细节见 README.md 与 CONTRIBUTING.md。

登录后查看全文
Corbell