Corbell快速上手:2分钟安装并生成你的第一份架构设计Spec(附完整命令清单)
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/)。效果如下:
五、进阶:评审、拆解与导出
生成 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 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 项,你的多仓库架构知识图谱就正式"活"起来了。项目社区的增长情况也值得一提:
📌 小结:pip install corbell → init → graph build → embeddings build → spec new,2 分钟安装 + 5 条命令,就能让 AI 基于真实代码结构生成第一份架构设计 Spec。更多细节见 README.md 与 CONTRIBUTING.md。


