kenaz 0.0.0-stage → 0.3.2

package/core/.system/cortex/MODULES.md

@@ -0,0 +1,1046 @@
+# kenaz-cortex RAG 引擎模組詳解
+
+> **版本**: 2.0.0
+> **最後更新**: 2026-02-20
+> **模組總數**: 58 個 Python 檔案
+
+## 目錄
+
+- [系統架構](#系統架構)
+- [核心模組](#核心模組)
+  - [chunker - 語義切片器](#chunker---語義切片器)
+  - [vectordb - 向量資料庫](#vectordb---向量資料庫)
+  - [sync - Git 增量同步](#sync---git-增量同步)
+  - [api - 語義檢索 API](#api---語義檢索-api)
+  - [context - 混合 Context 策略](#context---混合-context-策略)
+  - [mcp - MCP Server](#mcp---mcp-server)
+  - [symbols - 符號索引](#symbols---符號索引)
+  - [retrieval - 混合檢索 V2](#retrieval---混合檢索-v2)
+- [輔助模組](#輔助模組)
+  - [decomposition - 任務分解](#decomposition---任務分解)
+  - [optimization - 代碼優化](#optimization---代碼優化)
+  - [cli - 命令列介面](#cli---命令列介面)
+- [模組間依賴圖](#模組間依賴圖)
+
+---
+
+## 系統架構
+
+kenaz-cortex 是一個**智能 RAG 引擎**，模擬人腦的知識管理與檢索系統。主要功能包括：
+
+1. **語義切片** - 按語義單位切分代碼和文檔
+2. **向量存儲** - 使用 ChromaDB 進行本地向量存儲
+3. **增量同步** - 與 Git commit 同步，自動更新索引
+4. **智能檢索** - 四層混合檢索架構
+5. **Context 管理** - 根據專案規模自動切換策略
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     kenaz-cortex 架構                            │
+│                                                                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │   輸入層     │  │   處理層     │  │   輸出層     │          │
+│  │              │  │              │  │              │          │
+│  │ • chunker    │  │ • vectordb   │  │ • api        │          │
+│  │ • sync       │  │ • symbols    │  │ • mcp        │          │
+│  │              │  │ • retrieval  │  │ • context    │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │              Git 增量同步（sync/）                        │  │
+│  │    Git Commit → 文件變更 → AST 切片 → 向量化 → 索引     │  │
+│  └──────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 核心模組
+
+### chunker - 語義切片器
+
+**路徑**: `kenaz-cortex/src/cortex/chunker/`
+
+**職責**: 按語義單位切分代碼和文檔，確保邏輯完整性。
+
+#### 子模組
+
+| 模組 | 說明 | 支援特性 |
+|------|------|---------|
+| `python_chunker.py` | Python AST 切片器 | 函式、類別、模組頭部、Docstring、裝飾器、類型註解 |
+| `typescript_chunker.py` | TypeScript/JS 切片器 | 函式、類別、介面、型別別名、React Component |
+| `yaml_chunker.py` | YAML 語義切片器 | 頂層鍵值對、嵌套結構、任務定義 |
+| `markdown_chunker.py` | Markdown 切片器 | 章節、代碼塊、列表、表格 |
+| `__init__.py` | 模組匯出 | 統一介面 |
+
+#### 核心類別
+
+```python
+@dataclass
+class Chunk:
+    """代碼切片"""
+    id: str                    # 唯一標識（SHA256 hash）
+    file_path: str             # 檔案路徑
+    chunk_type: ChunkType      # 切片類型（function, class, module_header）
+    name: str                  # 名稱（函式名、類別名）
+    content: str               # 原始內容
+    start_line: int            # 起始行
+    end_line: int              # 結束行
+    metadata: ChunkMetadata    # 元數據（裝飾器、Docstring、依賴等）
+```
+
+#### 使用範例
+
+```python
+from cortex.chunker import PythonChunker
+
+chunker = PythonChunker()
+chunks = chunker.chunk_file("src/auth/login.py")
+
+for chunk in chunks:
+    print(f"{chunk.name} ({chunk.chunk_type})")
+    print(f"  Lines: {chunk.start_line}-{chunk.end_line}")
+    print(f"  Decorators: {chunk.metadata.decorators}")
+```
+
+#### 設計特點
+
+1. **語義完整性** - 每個切片都是完整的邏輯單位
+2. **元數據保留** - Docstring、裝飾器、類型註解不丟失
+3. **多語言支援** - Python、TypeScript、YAML、Markdown
+4. **可配置** - 支援最小切片長度、模組頭部包含等選項
+
+---
+
+### vectordb - 向量資料庫
+
+**路徑**: `kenaz-cortex/src/cortex/vectordb/`
+
+**職責**: 使用 ChromaDB 進行本地向量存儲，支援專案隔離。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `chroma.py` | ChromaDB 管理器 |
+| `__init__.py` | 模組匯出 |
+
+#### 核心類別
+
+```python
+class ChromaManager:
+    """
+    ChromaDB 管理器
+
+    負責管理 ChromaDB 的連接、Collection 操作和資料 CRUD。
+    支援專案隔離，每個專案使用獨立的 Collection。
+    """
+
+    def __init__(self, config: CortexConfig | None = None, project_path: Path | str | None = None):
+        """初始化，支援專案隔離"""
+
+    def add_chunks(self, chunks: list[Chunk]) -> None:
+        """批次新增切片"""
+
+    def query(self, query_text: str, top_k: int = 5, where: dict | None = None) -> list[QueryResult]:
+        """語義搜尋"""
+
+    def delete_by_file(self, file_path: str) -> None:
+        """刪除指定檔案的所有切片"""
+```
+
+#### 專案隔離機制
+
+```python
+# 不同專案使用不同 Collection
+manager_A = ChromaManager(project_path="/path/to/projectA")
+manager_B = ChromaManager(project_path="/path/to/projectB")
+
+# Collection 名稱：kenaz_<project_hash>
+# projectA → kenaz_abc123
+# projectB → kenaz_def456
+```
+
+#### 向量化模型
+
+- **預設模型**: `all-MiniLM-L6-v2` (Sentence Transformers)
+- **維度**: 384
+- **速度**: 快速（本地推理）
+- **精度**: 中等（適合代碼檢索）
+
+#### 資料庫路徑
+
+- **預設位置**: `.cortex/db/chroma.sqlite3`
+- **可配置**: 透過 `CortexConfig.db_path` 設定
+
+---
+
+### sync - Git 增量同步
+
+**路徑**: `kenaz-cortex/src/cortex/sync/`
+
+**職責**: 與開發節奏同步，透過 Git hook 觸發增量索引。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `git_sync.py` | Git 增量同步管理器 |
+| `__init__.py` | 模組匯出 |
+
+#### 核心類別
+
+```python
+class GitSyncManager:
+    """
+    Git 增量同步管理器
+
+    負責偵測 Git 變更並同步到向量資料庫。
+    支援增量更新、批次處理和同步日誌記錄。
+    """
+
+    def sync_from_last_commit(self) -> SyncStats:
+        """從上次同步的 commit 開始增量同步"""
+
+    def sync_commits(self, from_commit: str, to_commit: str) -> SyncStats:
+        """同步指定 commit 範圍的變更"""
+
+    def full_reindex(self) -> SyncStats:
+        """全量重新索引"""
+```
+
+#### 變更類型處理
+
+```python
+class ChangeType(str, Enum):
+    ADDED = "A"         # 新增 → 切片 + 索引
+    MODIFIED = "M"      # 修改 → 刪除舊切片 + 索引新切片
+    DELETED = "D"       # 刪除 → 移除索引
+    RENAMED = "R"       # 重命名 → 移除舊索引 + 索引新檔案
+```
+
+#### 支援的檔案類型
+
+| 副檔名 | 語言 | Chunker |
+|--------|------|---------|
+| `.py` | Python | PythonChunker |
+| `.ts`, `.tsx` | TypeScript | TypeScriptChunker |
+| `.js`, `.jsx` | JavaScript | TypeScriptChunker |
+| `.yaml`, `.yml` | YAML | YamlChunker |
+| `.md` | Markdown | MarkdownChunker |
+
+#### Git Hook 整合
+
+```bash
+# .git/hooks/post-commit
+#!/bin/bash
+cortex sync --incremental
+```
+
+#### 符號索引整合
+
+如果 Universal Ctags 可用，會自動整合符號索引：
+
+```python
+if is_ctags_available():
+    symbol_index = SymbolIndex(project_root)
+    symbol_index.update(changed_files)
+```
+
+---
+
+### api - 語義檢索 API
+
+**路徑**: `kenaz-cortex/src/cortex/api/`
+
+**職責**: 供 Agent 查詢相關代碼的高階介面。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `search.py` | 語義檢索 API |
+| `__init__.py` | 模組匯出 |
+
+#### 核心類別
+
+```python
+class CortexSearch:
+    """
+    Cortex 語義檢索 API
+
+    提供語義搜尋、名稱查找、檔案切片獲取等功能。
+    """
+
+    def query(self, query: str, top_k: int = 5, filters: SearchFilters | None = None) -> list[SearchResult]:
+        """語義搜尋"""
+
+    def find_by_name(self, name: str, chunk_type: str | None = None) -> list[SearchResult]:
+        """按名稱搜尋"""
+
+    def get_file_chunks(self, file_path: str) -> list[SearchResult]:
+        """獲取檔案的所有 chunks"""
+```
+
+#### 跨專案搜尋
+
+```python
+class CrossProjectSearch:
+    """跨專案語義搜尋"""
+
+    def query(self, query: str, top_k: int = 5, project_filter: list[str] | None = None) -> list[CrossSearchResult]:
+        """在多個專案中搜尋"""
+```
+
+#### 搜尋過濾器
+
+```python
+@dataclass
+class SearchFilters:
+    language: str | None = None           # 語言過濾（python, typescript）
+    chunk_type: list[str] | str | None    # 類型過濾（function, class）
+    file_path: str | None = None          # 路徑過濾
+    min_relevance: float | None = None    # 最低相關性分數
+```
+
+#### 使用範例
+
+```python
+from cortex.api import CortexSearch
+
+search = CortexSearch(project_path="/path/to/project")
+
+# 語義搜尋
+results = search.query(
+    query="用戶登入驗證邏輯",
+    top_k=5,
+    filters=SearchFilters(language="python", chunk_type=["function", "class"])
+)
+
+# 按名稱搜尋
+results = search.find_by_name("authenticate_user")
+
+# 獲取檔案的所有 chunks
+chunks = search.get_file_chunks("src/auth/login.py")
+```
+
+---
+
+### context - 混合 Context 策略
+
+**路徑**: `kenaz-cortex/src/cortex/context/`
+
+**職責**: 提供混合 Context 策略的實作，根據專案規模自動選擇最佳策略。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `structure_extractor.py` | 結構提取器，生成 Always In Context |
+| `smart_switch.py` | 智能切換器，根據專案規模自動選擇策略 |
+| `map_reduce.py` | Map-Reduce 聚合器，生成專案級概覽 |
+| `__init__.py` | 模組匯出 |
+
+#### 核心類別
+
+```python
+class SmartContextSwitch:
+    """
+    智能 Context 切換器
+
+    根據專案規模自動選擇最佳 Context 策略：
+    - 初期：全量 Context + Prompt Caching（tokens < 40k AND files < 20）
+    - 成長期：精簡 Context + RAG 檢索（tokens > 40k OR files > 20）
+    """
+
+    def get_context(self, mode: str = "auto") -> str:
+        """
+        獲取 Context
+
+        Args:
+            mode: "auto" (自動), "full" (全量), "hybrid" (混合)
+        """
+```
+
+#### 雙閥值判斷
+
+```python
+@dataclass
+class SmartSwitchConfig:
+    # 切換閥值（任一超過即啟用 RAG）
+    threshold_tokens: int = 40000  # Token 閥值
+    threshold_files: int = 20      # 檔案數閥值
+
+    # 全量 Context 配置
+    prompt_caching: bool = True    # 啟用 Prompt Caching
+    exclude_patterns: list[str]    # 排除模式（node_modules, tests 等）
+
+    # 精簡 Context 配置
+    project_tree_depth: int = 3    # 目錄樹深度
+    essential_max_tokens: int = 2000
+
+    # RAG 檢索配置
+    rag_top_k: int = 5
+    rag_min_relevance: float = 0.6
+```
+
+#### Context 模式
+
+| 模式 | 條件 | 策略 |
+|------|------|------|
+| **Full** | tokens < 40k AND files < 20 | 全量 Context + Prompt Caching |
+| **Hybrid** | tokens > 40k OR files > 20 | 精簡 Context + RAG 檢索 |
+
+#### 結構提取器
+
+```python
+class StructureExtractor:
+    """
+    結構提取器
+
+    生成專案的 Always In Context（固定注入的結構概覽）。
+    """
+
+    def extract(self) -> str:
+        """
+        提取專案結構
+
+        Returns:
+            專案目錄樹 + 類型定義 + README + SPEC
+        """
+```
+
+#### Map-Reduce 聚合器
+
+```python
+class MapReduceContext:
+    """
+    Map-Reduce 聚合器
+
+    生成專案級概覽，適用於大型專案。
+    """
+
+    def generate_overview(self) -> ProjectOverview:
+        """
+        生成專案概覽
+
+        Returns:
+            專案摘要、架構、技術棧、關鍵模組
+        """
+```
+
+---
+
+### mcp - MCP Server
+
+**路徑**: `kenaz-cortex/src/cortex/mcp/`
+
+**職責**: 提供 Model Context Protocol (MCP) 整合，讓 Claude Code 可以自動使用 RAG 功能。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `server.py` | MCP Server 實作 |
+| `__init__.py` | 模組匯出 |
+
+#### 提供的 MCP 工具
+
+| 工具 | 說明 | 參數 |
+|------|------|------|
+| `cortex_search` | 語義代碼搜索 | query, top_k, language, chunk_type |
+| `cortex_context` | 專案結構 Context（自動切換全量/RAG） | mode (auto, full, hybrid) |
+| `cortex_file_chunks` | 文件切片查詢 | file_path |
+| `cortex_symbols` | 符號索引搜尋 | name, kind, file_path |
+| `cortex_status` | RAG 引擎狀態 | - |
+| `cortex_reindex` | 重新索引 | - |
+
+#### 自動切換策略
+
+```python
+def cortex_context(mode: str = "auto") -> str:
+    """
+    專案結構 Context
+
+    自動切換策略：
+    - 小型專案（<40k tokens, <20 files）→ 全量 Context
+    - 大型專案（>40k tokens 或 >20 files）→ RAG 模式
+    """
+    switch = get_smart_switch()
+    return switch.get_context(mode=mode)
+```
+
+#### MCP Server 配置
+
+設定檔：`~/.config/claude-code/config.json`
+
+```json
+{
+  "mcpServers": {
+    "kenaz-cortex": {
+      "command": "python",
+      "args": ["-m", "cortex.mcp"],
+      "env": {
+        "CORTEX_PROJECT_PATH": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+#### 啟動方式
+
+```bash
+# 方式 1：透過 CLI
+cortex mcp
+
+# 方式 2：透過 Python 模組
+python -m cortex.mcp
+
+# 方式 3：程式碼調用
+from cortex.mcp import run_server
+run_server()
+```
+
+---
+
+### symbols - 符號索引
+
+**路徑**: `kenaz-cortex/src/cortex/symbols/`
+
+**職責**: 整合 Universal Ctags 工具，為專案建立結構化的符號索引。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `ctags_runner.py` | Ctags 執行器 |
+| `symbol_index.py` | 符號索引管理器 |
+| `__init__.py` | 模組匯出 |
+
+#### 核心類別
+
+```python
+class SymbolIndex:
+    """
+    符號索引管理器
+
+    讓 Agent 能不經向量搜索就精確定位函數/類/介面定義。
+    """
+
+    def build(self) -> SymbolIndexStats:
+        """建立完整符號索引"""
+
+    def update(self, changed_files: list[str]) -> SymbolIndexStats:
+        """增量更新索引"""
+
+    def find_by_name(self, name: str) -> list[SymbolEntry]:
+        """按名稱搜尋符號"""
+
+    def find_by_kind(self, kind: SymbolKind) -> list[SymbolEntry]:
+        """按類型搜尋符號"""
+```
+
+#### 支援的符號類型
+
+```python
+SymbolKind = Literal[
+    "function",    # 函式
+    "class",       # 類別
+    "method",      # 方法
+    "interface",   # 介面
+    "type",        # 型別
+    "variable",    # 變數
+    "constant",    # 常數
+    "property",    # 屬性
+    "module",      # 模組
+    "namespace",   # 命名空間
+    "enum",        # 枚舉
+    "member",      # 成員
+    "parameter",   # 參數
+]
+```
+
+#### Ctags 整合
+
+```python
+def is_ctags_available() -> bool:
+    """檢查 Universal Ctags 是否可用"""
+
+def run_ctags(project_root: Path) -> list[SymbolEntry]:
+    """執行 ctags 並解析輸出"""
+```
+
+#### 索引持久化
+
+- **檔案**: `.cortex/symbols.json`
+- **格式**: JSON
+- **更新時機**: Git commit 時自動增量更新
+
+---
+
+### retrieval - 混合檢索 V2
+
+**路徑**: `kenaz-cortex/src/cortex/retrieval/`
+
+**職責**: 四層混合檢索架構，根據任務特徵自動選擇最佳檢索策略。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `strategy.py` | 策略選擇器 |
+| `rule_first.py` | Layer 1 - 規則優先層 |
+| `architecture.py` | Layer 2 - 架構視角層 |
+| `dependency_expander.py` | Layer 3 - 依賴擴展 |
+| `similar_finder.py` | Layer 3 - 相似檢索 |
+| `__init__.py` | 模組匯出 |
+
+#### 四層架構
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Layer 1: 規則優先層 (Rule-First Layer)                    │
+│  確保 Agent 理解專案規範                                    │
+│  • .rule/ → CLAUDE.md → .failure/                          │
+└────────────────────────────────────────────────────────────┘
+                          ↓
+┌────────────────────────────────────────────────────────────┐
+│  Layer 2: 架構視角層 (Architecture Layer)                  │
+│  提供系統架構鳥瞰視角                                       │
+│  • full: 完整專案結構                                      │
+│  • simplified: 精簡版                                      │
+│  • disabled: 禁用（符號查找等簡單任務）                    │
+└────────────────────────────────────────────────────────────┘
+                          ↓
+┌────────────────────────────────────────────────────────────┐
+│  Layer 3: 智能檢索層 (Smart Retrieval Layer)               │
+│  • RAG: 語義檢索                                            │
+│  • Dependency: 依賴擴展                                     │
+│  • Similar: 相似特徵查找                                    │
+└────────────────────────────────────────────────────────────┘
+                          ↓
+┌────────────────────────────────────────────────────────────┐
+│  Layer 4: 全局驗證層 (Global Validation Layer)             │
+│  重構/架構變更的全局驗證                                    │
+│  • 影響分析                                                 │
+│  • 依賴檢查                                                 │
+│  • 測試覆蓋                                                 │
+└────────────────────────────────────────────────────────────┘
+```
+
+#### 策略選擇器
+
+```python
+class StrategySelector:
+    """
+    策略選擇器
+
+    根據任務描述、複雜度、優先級、路徑範圍等多維度特徵，
+    自動選擇最佳的檢索策略。
+    """
+
+    def select_strategy(self, task: Task) -> RetrievalStrategy:
+        """
+        選擇檢索策略
+
+        流程：
+        1. 關鍵字分析 → 確定基礎任務類型
+        2. 複雜度分析 → 計算複雜度分數
+        3. 優先級覆蓋 → 根據 P0/P1/P2/P3 調整
+        4. 路徑範圍分析 → 根據影響範圍微調
+        5. 特殊情況處理 → 處理邊界 case
+        """
+```
+
+#### 支援的任務類型
+
+```python
+class TaskType(Enum):
+    NEW_FEATURE = "new_feature"          # 新功能開發
+    BUG_FIX = "bug_fix"                  # Bug 修復
+    REFACTOR = "refactor"                # 重構
+    ARCHITECTURE = "architecture"        # 架構變更
+    TEST = "test"                        # 測試撰寫
+    DOCUMENTATION = "documentation"      # 文檔更新
+    PERFORMANCE = "performance"          # 性能優化
+    SECURITY = "security"                # 安全修復
+    DEPENDENCY_UPDATE = "dependency_update"  # 依賴更新
+    UI_UX = "ui_ux"                      # UI/UX 調整
+    DATA_MIGRATION = "data_migration"    # 數據遷移
+    SYMBOL_LOOKUP = "symbol_lookup"      # 符號查找
+```
+
+#### 檢索策略配置
+
+```python
+@dataclass
+class RetrievalStrategy:
+    task_type: TaskType
+    layer1_enabled: bool = True           # Layer 1 啟用
+    layer2_mode: str = "full"             # Layer 2 模式（full, simplified, disabled）
+    layer3_components: list[str]          # Layer 3 組件（rag, dependency, similar）
+    layer4_enabled: bool = False          # Layer 4 啟用
+```
+
+#### 策略範例
+
+| 任務類型 | Layer 1 | Layer 2 | Layer 3 | Layer 4 |
+|---------|---------|---------|---------|---------|
+| 新功能開發 | ✅ | full | [rag, similar] | ❌ |
+| Bug 修復 | ✅ | simplified | [rag, dependency] | ❌ |
+| 架構變更 | ✅ | full | [rag, dependency] | ✅ |
+| 符號查找 | ❌ | disabled | [] | ❌ |
+
+---
+
+## 輔助模組
+
+### decomposition - 任務分解
+
+**路徑**: `kenaz-cortex/src/cortex/decomposition/`
+
+**職責**: 自動將 PRODUCT_SPEC 特性分解為可執行的開發任務。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `engine.py` | 分解引擎 |
+| `graph.py` | 任務圖 |
+| `rules.py` | 分解規則 |
+| `__init__.py` | 模組匯出 |
+
+#### 核心類別
+
+```python
+class DecompositionEngine:
+    """
+    任務分解引擎
+
+    自動分解 PRODUCT_SPEC 特性為開發任務。
+    """
+
+    def decompose(self, spec: ProductSpec) -> TaskGraph:
+        """
+        分解規格為任務圖
+
+        Returns:
+            包含任務、依賴關係、並行組的任務圖
+        """
+```
+
+#### 任務圖
+
+```python
+class TaskGraph:
+    """
+    任務圖
+
+    表示任務間的依賴關係和並行執行策略。
+    """
+
+    def to_mermaid(self) -> str:
+        """輸出 Mermaid 格式的依賴圖"""
+
+    def write_to_pipeline(self, output_dir: str) -> None:
+        """寫入 Pipeline 任務目錄"""
+```
+
+#### 使用範例
+
+```python
+from cortex.spec import SpecParser
+from cortex.decomposition import DecompositionEngine
+
+parser = SpecParser()
+spec = parser.parse("dev/PRODUCT_SPEC.yaml")
+
+engine = DecompositionEngine()
+task_graph = engine.decompose(spec)
+
+# 輸出任務列表
+for task in task_graph.tasks:
+    print(f"{task.id}: {task.title}")
+    print(f"  Agent: {task.agent_type}")
+    print(f"  Depends on: {task.dependencies}")
+
+# 輸出依賴圖（Mermaid 格式）
+print(task_graph.to_mermaid())
+```
+
+---
+
+### optimization - 代碼優化
+
+**路徑**: `kenaz-cortex/src/cortex/optimization/`
+
+**職責**: 提供代碼品質監控和優化建議生成功能。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `agent.py` | 優化 Agent |
+| `analyzer.py` | 代碼分析器 |
+| `suggestion.py` | 建議生成器 |
+| `__init__.py` | 模組匯出 |
+
+#### 核心類別
+
+```python
+class OptimizationAgent:
+    """
+    優化 Agent
+
+    主動監控代碼品質，生成優化建議。
+    """
+
+    def analyze(self, file_path: str) -> SuggestionReport:
+        """分析檔案並生成建議"""
+```
+
+#### 建議類型
+
+```python
+class SuggestionType(Enum):
+    PERFORMANCE = "performance"    # 性能優化
+    SECURITY = "security"          # 安全修復
+    CODE_SMELL = "code_smell"      # 代碼異味
+    BEST_PRACTICE = "best_practice"  # 最佳實踐
+    REFACTOR = "refactor"          # 重構
+```
+
+#### 嚴重程度
+
+```python
+class SeverityLevel(Enum):
+    CRITICAL = "critical"  # 嚴重（必須修復）
+    HIGH = "high"          # 高（優先修復）
+    MEDIUM = "medium"      # 中（計劃修復）
+    LOW = "low"            # 低（可選修復）
+```
+
+---
+
+### cli - 命令列介面
+
+**路徑**: `kenaz-cortex/src/cortex/cli/`
+
+**職責**: 提供 cortex 命令列工具。
+
+#### 子模組
+
+| 模組 | 說明 |
+|------|------|
+| `main.py` | CLI 主程式 |
+| `__init__.py` | 模組匯出 |
+
+#### 可用命令
+
+```bash
+# 語義搜尋
+cortex search "用戶登入驗證"
+
+# 查看狀態
+cortex status
+
+# 重新索引
+cortex reindex
+
+# 增量同步
+cortex sync --incremental
+
+# 啟動 MCP Server
+cortex mcp
+
+# 符號查找
+cortex symbols --name authenticate_user
+
+# 專案概覽
+cortex overview
+```
+
+#### CLI 實作
+
+基於 **Typer** 框架，提供：
+
+- 彩色輸出（rich）
+- 進度條
+- 自動補全
+- 參數驗證
+
+---
+
+## 模組間依賴圖
+
+```mermaid
+graph TD
+    A[config.py] -->|配置| B[chunker/]
+    A -->|配置| C[vectordb/]
+    A -->|配置| D[sync/]
+    A -->|配置| E[api/]
+
+    B -->|切片| C
+    B -->|切片| D
+
+    C -->|存儲| E
+
+    D -->|同步| C
+    D -->|Git 變更| B
+    D -->|符號| F[symbols/]
+
+    E -->|檢索| G[retrieval/]
+    E -->|Context| H[context/]
+
+    F -->|索引| E
+
+    G -->|策略| H
+
+    H -->|智能切換| I[mcp/]
+    E -->|API| I
+
+    J[decomposition/] -->|分解| K[spec/]
+
+    L[optimization/] -->|分析| E
+
+    M[cli/] -->|CLI| E
+    M -->|CLI| D
+    M -->|CLI| I
+
+    classDef core fill:#f9f,stroke:#333,stroke-width:2px
+    classDef aux fill:#bbf,stroke:#333,stroke-width:1px
+    classDef interface fill:#bfb,stroke:#333,stroke-width:2px
+
+    class B,C,D,E,F,G,H core
+    class J,L aux
+    class I,M interface
+```
+
+### 依賴層級
+
+#### Layer 0: 基礎層
+- `config.py` - 配置管理
+
+#### Layer 1: 輸入層
+- `chunker/` - 語義切片
+- `symbols/` - 符號索引
+
+#### Layer 2: 存儲層
+- `vectordb/` - 向量資料庫
+- `sync/` - Git 增量同步
+
+#### Layer 3: 檢索層
+- `api/` - 語義檢索 API
+- `retrieval/` - 混合檢索 V2
+- `context/` - 混合 Context 策略
+
+#### Layer 4: 介面層
+- `mcp/` - MCP Server
+- `cli/` - 命令列介面
+
+#### Layer 5: 輔助層
+- `decomposition/` - 任務分解
+- `optimization/` - 代碼優化
+- `spec/` - 規格解析
+- `integration/` - Agent 整合
+- `summary/` - 摘要生成
+
+---
+
+## 關鍵設計決策
+
+### 1. 為何選擇 ChromaDB？
+
+- **本地優先** - 不依賴雲端服務
+- **易於整合** - Python 原生支援
+- **持久化存儲** - 支援 SQLite 後端
+- **專案隔離** - 每個專案獨立 Collection
+
+### 2. 為何選擇 AST 切片？
+
+- **語義完整性** - 確保邏輯單位不被切斷
+- **元數據保留** - Docstring、裝飾器、類型註解
+- **依賴分析** - 可分析函式間依賴關係
+
+### 3. 為何選擇 Git 同步？
+
+- **與開發節奏同步** - 不需要手動觸發
+- **增量更新** - 只處理變更檔案，效率高
+- **歷史記錄** - 可回溯任意 commit 的索引狀態
+
+### 4. 為何選擇四層檢索架構？
+
+- **Layer 1（規則優先）** - 確保 Agent 遵守專案規範
+- **Layer 2（架構視角）** - 提供全局視野，避免局部優化
+- **Layer 3（智能檢索）** - 根據任務特徵動態調整檢索策略
+- **Layer 4（全局驗證）** - 防止架構變更破壞系統穩定性
+
+### 5. 為何選擇 MCP？
+
+- **標準化介面** - Claude Code 官方支援
+- **自動整合** - 無需手動配置
+- **工具豐富** - 支援多種檢索模式
+
+---
+
+## 性能指標
+
+### 索引速度
+
+| 專案規模 | 檔案數 | 索引時間 | 記憶體使用 |
+|---------|-------|---------|-----------|
+| 小型 | < 50 | 2-5 秒 | < 100 MB |
+| 中型 | 50-500 | 10-30 秒 | 100-500 MB |
+| 大型 | > 500 | 1-3 分鐘 | 500 MB - 1 GB |
+
+### 檢索速度
+
+| 檢索類型 | 延遲 | Top-K |
+|---------|------|-------|
+| 語義搜尋 | 50-200 ms | 5-10 |
+| 符號查找 | 10-50 ms | - |
+| 檔案切片 | 5-20 ms | - |
+
+### Context 生成速度
+
+| 模式 | 延遲 | Token 數 |
+|------|------|---------|
+| Full | 100-500 ms | 5k-40k |
+| Hybrid | 200-800 ms | 2k-10k |
+
+---
+
+## 未來規劃
+
+### Phase 1: 增強檢索能力
+- [ ] 支援更多語言（Go, Rust, Java）
+- [ ] 混合檢索優化（BM25 + Dense）
+- [ ] 跨專案檢索增強
+
+### Phase 2: 智能 Context 管理
+- [ ] 動態 Token 預算分配
+- [ ] Context 緩存與復用
+- [ ] 多模態 Context（圖片、圖表）
+
+### Phase 3: Agent 整合深化
+- [ ] 任務自動分解與規劃
+- [ ] 代碼自動優化建議
+- [ ] 持續學習與改進
+
+---
+
+## 相關文檔
+
+| 文檔 | 路徑 |
+|------|------|
+| Cortex 整合指南 | `.memory/CORTEX_GUIDE.md` |
+| 完整規格 | `docs/specs/MEMORY_SYSTEM_SPEC.md` |
+| MCP 設置指南 | `dev/scripts/setup_mcp.ps1` |
+| RAG 引擎設置 | `dev/scripts/SETUP_RAG.bat` |
+
+---
+
+**版本**: 2.0.0
+**最後更新**: 2026-02-20
+**維護者**: Kenaz AI Team