架構與內部原理

了解 Boring 的內部運作方式。

🏗️ 系統架構

Boring 建立在 有狀態自主迴圈 (Stateful Autonomous Loop) 模式之上。

graph TD
    User[使用者 / CLI] -->|啟動| AgentLoop

    subgraph "Boring 引擎"
        AgentLoop[StatefulAgentLoop]
        Memory[BoringMemory]
        RAG[RAGRetriever]
        Verifier[平行驗證器]
        Circuit[斷路器]
    end

    AgentLoop -->|思考| LLM[Google Gemini / Claude]
    LLM -->|工具呼叫| AgentLoop

    AgentLoop -->|讀/寫| FS[檔案系統]
    FS -->|變更事件| RAG

    AgentLoop -->|驗證| Verifier
    Verifier -->|結果| Circuit
    Circuit -->|狀態| AgentLoop

    style AgentLoop fill:#f9f,stroke:#333,stroke-width:2px

🔄 開發循環流程

Boring 遵循持續回饋循環以確保程式碼的正確性。

sequenceDiagram
    participant U as 使用者/CLI
    participant A as Agent (思考)
    participant E as 執行器 (工具)
    participant V as 驗證器 (測試)
    participant M as 記憶 (大腦)

    U->>A: 提交任務
    loop 直到完成或斷路器開啟
        A->>M: 獲取上下文與學習經驗
        M-->>A: 上下文數據
        A->>A: 生成計畫
        A->>E: 執行工具 (編輯/執行)
        E-->>A: 執行結果
        A->>V: 觸發驗證
        V->>V: 執行 Lint 與測試
        V-->>A: 通過/失敗 + 日誌
        alt 如果失敗
            A->>M: 記錄錯誤模式
            A->>A: 分析下一步修復原因
        else 如果通過
            A->>M: 更新進度
        end
    end
    A->>U: 最終報告

1. 模組化核心與延遲載入 (src/boring/)

從 v10.28.0 開始，Boring 採用了 「瘦身架構」(Diet Architecture)： - 延遲載入 (Lazy Loading)：大幅利用 __init__.py 中的 __getattr__ 技巧，僅在真正存取時才匯入子模組。這讓冷啟動時間從約 2.5 秒降至 < 600 毫秒。 - 依賴管理器 (Dependency Manager)：統一的 DependencyManager (位於 core/dependencies.py) 負責管理所有可選的「加點」(Extras，如 ChromaDB, FastAPI, Streamlit)，確保核心 CLI 保持輕量化 (< 50MB)。

2. 子模組重構

源代碼現在按功能層級組織： - core/：常量、遙測與依賴管理。 - services/：核心邏輯，如健康檢查與監控。 - cli/：基於 Typer 的界面與指令定義。 - tools/：原子化的工具，用於文件操作與分析。 - intelligence/：大腦 (Memory)、RAG 與模式學習。 - loop/：自主運作的狀態機。 - mcp/：Model Context Protocol 伺服器與工具曝露。

3. 大腦與記憶 (src/boring/intelligence/)

Boring 不只讀取檔案；它維護「狀態」： - Context (context.json)：當前任務、計畫和進度。 - Learnings (learnings.json)：錯誤模式和成功的修復。 - RAG Index (ChromaDB)：[選配] 代碼庫的向量嵌入，用於語意搜尋。

🕵️ 混合 RAG (Hybrid RAG) 工作流

Boring 採用多層檢索策略以確保上下文精確度：

graph LR
    Query[使用者查詢] --> HybridSearch

    subgraph "Hybrid Search Engine"
        HybridSearch --> Keyword[關鍵字搜尋 (BM25)]
        HybridSearch --> Vector[向量搜尋 (ChromaDB)]

        Keyword --> Merger[結果合併 & 重排序]
        Vector --> Merger
    end

    Merger --> TopK[Top-K 初選結果]

    subgraph "Graph Expansion"
        TopK --> DepGraph[依賴圖分析]
        DepGraph --> Callers[調用者]
        DepGraph --> Callees[被調用者]
    end

    Callers --> FinalContext[最終上下文]
    Callees --> FinalContext
    TopK --> FinalContext

3. 評估與審判 (`src/boring/judge/`)

Boring 內建 LLM-as-a-Judge 系統，用於自我評估與品質控制：

sequenceDiagram
    participant Agent as Agent
    participant Judge as Judge Engine
    participant Rubric as 動態評分表
    participant LLM as Evaluator Model

    Agent->>Judge: 請求評估 (Code/Plan)
    Judge->>Rubric: 生成/載入評分標準
    Judge->>LLM: 執行 Direct Scoring / Pairwise Comparison
    loop Bias Mitigation
        LLM->>LLM: 自我反思 (校準分數)
    end
    LLM-->>Judge: 評分結果 + 改進建議
    Judge-->>Agent: 結構化報告 (JSON)

4. 驗證引擎 (`src/boring/verification/`)

與只生成代碼的典型 Agent 不同，Boring 會驗證它。

平行執行：使用 ThreadPoolExecutor 並發執行 linter/測試。
快取：對檔案內容進行雜湊，以跳過未變更檔案的重複驗證 (.boring/cache)。
層級：
靜態：語法檢查、linting (ruff, eslint)。
動態：單元測試 (pytest)。
安全：漏洞掃描 (bandit)。

5. 斷路器 (`src/boring/util/circuit_breaker.py`)

防止 Agent 重複嘗試並失敗的「無限迴圈災難」。

CLOSED：正常運作。
OPEN：連續失敗次數過多。停止執行以節省 Token/時間。
HALF_OPEN：允許一次嘗試，查看問題是否已解決。

🔒 安全架構（影子模式）

Boring 在高風險操作的「影子模式」沙箱中運作。

請求（刪除檔案）
       │
       ▼
[影子攔截器]
       │
  安全嗎？(配置) ──▶ 是 ──▶ [檔案系統]
       │
       ▼
      否
       │
  [使用者批准 UI] ──▶ 是 ──▶ [檔案系統]
       │
       ▼
      否 ──▶ [阻擋並報告]

此邏輯存在於 src/boring/security/shadow_mode.py 中。

🔌 MCP 整合

Boring 透過 Model Context Protocol (MCP) 暴露其內部功能。

工具：暴露為 boring_tool_name。
資源：boring://logs, boring://config。
提示：/vibe_start, /quick_fix。

這允許 Boring 在其他 AI 客戶端（如 Claude Desktop 或 Cursor）內部運行。