## 它解决了什么问题？ 你是一家公司的资深工程师或架构师，负责的功能涉及 5–10 个代码仓库。
每个季度，你的团队都会重新讨论同样的架构决策：“我们应该用 Kafka 还是 SQS？”，“为什么我们有三种不同的认证模式？”，“谁负责限流层？” 这些决策散落在没人看的 Confluence 页面里、找不到的 Slack 消息中，以及已经离职的工程师脑海里。 当新工程师加入时——甚至当你重新接触一个半年没碰的服务时——一切都得从零开始。 **Corbell 为你的团队提供了一个活着的架构知识图谱** —— 基于你仓库中的实际代码和团队过往的设计文档构建。当你需要新的规范文档时，Corbell 生成的文档会遵循你既有的模式，而不是另起炉灶。当你推送到 Linear 时，每个任务都携带了 AI 编码 Agent 独立工作所需的确切方法签名、调用路径和跨服务影响信息。 ## 界面预览

## 工作原理 ``` Your repos → [graph:build] → Service graph (SQLite) Your docs → [docs:scan] → Design pattern extraction ↓ [spec new --feature "Payment Retry" --prd-file prd.md] → Generates 3-4 PRD-driven code search queries (LLM or regex) → Auto-discovers relevant services via embedding similarity → Injects graph topology + real code snippets → Applies your team's established design patterns → Calls Claude / GPT-4o to write the full design doc → Displays token usage and estimated cost → specs/payment-retry.md ✓ ↓ [spec review] → Checks claims against graph → .review.md [spec decompose] → Parallel task tracks YAML [export linear] → Linear issues with full method/service context ``` 无需服务器。无需云配置。完全在你的笔记本电脑上针对本地仓库运行。 ## 安装 ``` pip install corbell # 支持 LLM（选择其一）： pip install "corbell[anthropic]" # Claude (recommended) pip install "corbell[openai]" # GPT-4o # 通过导出文件： pip install "corbell[notion,linear]" # 所有内容： pip install "corbell[anthropic,openai,notion,linear]" ``` **系统要求**：Python ≥ 3.11 ## 快速开始（5 分钟） ### 1. 初始化工作区 ``` cd ~/my-platform # wherever your repos live corbell init ``` 编辑 `corbell-data/workspace.yaml`： ``` workspace: name: my-platform services: - id: payments-service repo: ../payments-service language: python # python | javascript | typescript | go | java - id: auth-service repo: ../auth-service language: go llm: provider: anthropic # or: openai, ollama model: claude-sonnet-4-5-20250929 api_key: ${ANTHROPIC_API_KEY} ``` ### 2. 构建知识图谱 ``` corbell graph build --methods # service + dependency graph + call graph, typed signatures, flows corbell embeddings build # code chunk index for semantic search corbell docs scan && corbell docs learn # extract patterns from existing RFCs/ADRs ``` ### 3. 生成设计文档 ``` export ANTHROPIC_API_KEY="sk-ant-..." # 从 PRD 文件 — 服务会自动发现，无需 --service 标志 corbell spec new \ --feature "Payment Retry with Exponential Backoff" \ --prd-file docs/payment-retry-prd.md # 包含完整调用图和基础设施上下文的 Spec corbell spec new --feature "Auth Flow" --prd-file prd.md --full-graph # 内联 PRD corbell spec new --feature "Rate Limiting" --prd "Tier 1: 100 req/min..." # 在完全没有 PRD 的情况下记录现有代码库 corbell spec new --existing # 添加现有设计文档作为上下文 (ADRs、Confluence 导出、RFCs) corbell spec new --feature "Auth Token Refresh" --prd-file prd.md \ --design-doc docs/auth-design-2023.md ``` 每次 LLM 调用后都会显示 Token 使用量和预估成本。模板模式（无需 LLM key）会生成一个填充了图谱上下文的结构化骨架。 ### 4. 记录架构约束 在任何 spec 文档中添加约束块，所有未来的 spec 都将遵循它： ``` - **Cloud provider**: Only Azure — no AWS services permitted - **Latency SLO**: p99 < 200ms for all synchronous API calls - **Security**: All PII encrypted at rest (AES-256) and in transit (TLS 1.2+) ``` `corbell spec review` 会根据这些约束检查提议的设计。`corbell ui serve` 图谱浏览器也会在底部持久的栏中展示这些约束。 ### 5. 审核、批准、分解、导出 ``` corbell spec review specs/payment-retry.md # → .review.md sidecar 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 ui serve # opens http://localhost:7433 · Ctrl+C to stop corbell ui serve --port 8080 --no-browser ``` 交互式本地图谱视图 —— 无需云端，无需登录，读取你现有的 SQLite 存储： - **力导向图** —— 服务（大小按方法数量缩放）、数据存储、队列、执行流。支持缩放、平移、拖拽。 - **详情面板** —— 点击任意服务查看：语言、依赖项、HTTP 调用方、类型化方法签名、执行流（例如 `LoginFlow`）、带有强度百分比的 Git 变更耦合对。 - **约束栏** —— 来自 spec 文件的所有 `CORBELL_CONSTRAINTS_START` 块以持久的琥珀色标签形式显示在底部。点击可展开。 - **侧边栏** —— 可过滤的服务列表、存储、队列、流，支持搜索。 ## CLI 参考 ``` graph Service dependency graph build --methods for call graph + typed signatures + git coupling + flows services List discovered services deps Show service dependencies callpath Find call paths between methods embeddings Code embedding index build Index code chunks query Semantic search docs Design doc patterns scan / learn / patterns spec Design spec lifecycle new --feature --prd-file --prd --design-doc --existing --no-llm lint Validate structure (--ci exits 1) review Check spec vs graph → .review.md approve / decompose / context export notion | linear ui Architecture graph browser serve --port (default 7433) --no-browser mcp Model Context Protocol server serve stdio transport for Claude Desktop / Cursor init Create workspace.yaml ``` ## MCP – Model Context Protocol Corbell 通过 MCP 暴露其架构图谱、代码 Embeddings 和 spec 工具，以便外部 AI 平台（Cursor、Claude Desktop、Antigravity）可以直接查询你的代码库上下文。 ### 可用工具 | Tool | Description | |---|---| | `graph_query` | 查询服务依赖、方法和调用路径 | | `get_architecture_context` | 根据功能描述自动发现相关服务 | | `code_search` | 跨代码 Embedding 索引的语义搜索 | | `list_services` | 列出工作区图谱中的所有服务 | ### 使用方式 ``` # 默认：stdio 传输（用于 IDE 集成） corbell mcp serve # SSE 传输（用于基于 Web 的 MCP 客户端 / MCP Inspector） corbell mcp serve --transport sse --port 8000 ``` ### IDE 配置 **Cursor** (`~/.cursor/mcp.json`): ``` { "mcpServers": { "corbell": { "command": "corbell", "args": ["mcp", "serve"] } } } ``` **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): ``` { "mcpServers": { "corbell": { "command": "corbell", "args": ["mcp", "serve"] } } } ``` 如果你的 IDE 覆盖了工作目录，请设置 `CORBELL_WORKSPACE` 环境变量： ``` env CORBELL_WORKSPACE=/path/to/my-platform corbell mcp serve ``` ## 自动服务发现 当你运行 `corbell spec new` 时，Corbell 会**自动**发现哪些服务与你的 PRD 相关 —— 无需你指定 `--service`： 1. 根据你的 PRD 生成 3-4 个自然语言代码搜索查询（使用 LLM 或正则回退机制） 2. 使用索引时相同的 `sentence-transformers/all-MiniLM-L6-v2` 模型对其进行编码 3. 对所有已索引的代码块运行相似性搜索 4. 根据各服务的代码块在顶部结果中出现的数量对服务进行排名 5. 自动包含任何标记为 `infrastructure` 的服务（例如 AWS CDK 仓库）以提供全面的上下文 6. 选择得分最高的服务并从中构建上下文 预览会发现什么（而不生成 spec）： ``` corbell spec context "Add exponential backoff retry to payment processing" ``` ## LLM 提供商 | Provider | Models | Key env var | |---|---|---| | `anthropic` | `claude-sonnet-4-5`, `claude-haiku-4-5` | `ANTHROPIC_API_KEY` | | `openai` | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` | `OPENAI_API_KEY` | | `ollama` | `llama3`, `mistral`, any local model | (none) | | `aws` | `us.anthropic.claude-sonnet-4-*` | `BEDROCK_API_KEY` or IAM | | `azure` | `gpt-4o`, any deployment | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` | | `gcp` | `claude-sonnet-4-5@20250514` | `GOOGLE_APPLICATION_CREDENTIALS` | ## 架构 Corbell 完全在本地运行，无需云服务： - **Graph store**：SQLite（默认）。可选：Neo4j，用于大型多仓库拓扑。 - **Embeddings**：`sentence-transformers/all-MiniLM-L6-v2`（本地）。存储后端可通过 `workspace.yaml` 中的 `storage.embeddings.backend` 插件化。 - **UI**：Python stdlib `http.server` + 通过 CDN 加载的 D3.js。零额外依赖。 - **LLM**：图谱/Embedding/UI 命令不需要。spec 生成使用 Claude/GPT-4o/Ollama。 ### `graph build --methods` 提取的内容 | Signal | Languages | Result | |---|---|---| | Typed method signatures | Python, TS, Go, Java | `MethodNode.typed_signature` | | Call edges | All 5 | `method_call` edges | | DB/queue/HTTP dependencies | All 5 | `DataStoreNode`, `QueueNode`, `http_call` | | Git change coupling | Any git repo | `git_coupling` edges with strength score | | Execution flow traces | All 5 | `FlowNode` + `flow_step` edges | | Infrastructure as Code | TS / JS | Auto-tags CDK/Terraform as `infrastructure` | ## CI 集成 ``` # .github/workflows/spec-lint.yml - name: Lint architecture specs run: | pip install corbell corbell spec lint specs/my-feature.md --ci ``` ## 开发 ``` git clone https://github.com/your-org/corbell && cd Corbell pip install -e ".[dev]" pytest tests/ -q corbell --help ``` ## 路线图 我们正在从硬编码的流程化工作流转向完全的 **Agentic 架构**。Corbell 不再使用固定的 Pipeline，而是将其核心能力视为动态工具： - **功能即工具**：使 Agent 能够根据功能请求的具体复杂度，自主选择何时查询图谱、搜索 Embeddings 或分析模式。 - **动态推理**：将编排逻辑移至 Agentic 层，使其能够在没有硬编码序列约束的情况下回溯、优化查询和交叉引用服务。 - **Agentic 审核流**：自我修正的设计文档，Agent 在生成过程中使用架构图谱作为实时验证器。 ## 许可证 Apache 2.0 — 详见 [LICENSE](LICENSE)。

标签：AI编码助手, AI风险缓解, Mermaid, SQLite, 云安全监控, 人工智能, 代码图谱, 代码审查, 代码搜索, 代码智能, 企业级软件, 后端开发, 多仓库管理, 威胁情报, 工作流自动化, 开发者工具, 技术债务管理, 文档生成, 架构分析, 用户模式Hook绕过, 系统设计, 网络调试, 自动化, 规格生成, 设计模式提取, 软件架构, 逆向工具, 静态分析