kenaz 0.3.18 → 0.3.19

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

@@ -1,1046 +0,0 @@
-# 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