Add Claude Code vs CodePilot gap analysis

GAP_ANALYSIS.md

@@ -0,0 +1,253 @@
+# CodePilot vs Claude Code — 差距分析報告
+
+> 基於論文 "Dive into Claude Code" (arXiv:2604.14228) 的完整架構分析
+
+## 現狀：CodePilot 已有的功能 ✅ (37/37)
+
+### 核心工具
+- ✅ read_file（帶行號、offset/limit）
+- ✅ edit_file（精確字串替換、diff 顯示）
+- ✅ write_file（建立/覆寫）
+- ✅ run_command（超時保護、安全檢查）
+- ✅ search_files（ripgrep/grep）
+- ✅ list_files（遞迴搜尋、排除 .git 等）
+- ✅ git_status（branch、status、log）
+
+### 記憶系統
+- ✅ L1 CODEPILOT.md 指令層級（遞迴搜尋）
+- ✅ L2 MEMORY.md 跨 session 記憶
+- ✅ L3 Session JSONL 持久化
+- ✅ L4 自動壓縮（9段摘要）
+- ✅ FileStateCache（read-before-edit 強制）
+- ✅ 文件未變更去重（UNCHANGED_STUB）
+- ✅ HTML 註解移除
+
+### 模型/訓練
+- ✅ 6 種模型後端（local、codex、openrouter、anthropic、openai、ollama）
+- ✅ Duel 模式 + DPO 自動配對
+- ✅ 蒸餾模式
+- ✅ LeetCode 自動刷題
+- ✅ KTO / SFT / DPO 訓練
+
+---
+
+## 差距：Claude Code 有但 CodePilot 缺少的 ❌
+
+### 優先級 P0（影響最大，應該先做）
+
+#### 1. ❌ /init 初始化指令
+Claude Code 有 `claude init` 指令，自動分析專案結構並產生 CLAUDE.md。
+
+**缺少的**：CodePilot 需要用戶手動建立 CODEPILOT.md，新用戶不知道該寫什麼。
+
+**實作建議**：
+```python
+# /init 指令：讀取專案結構，用模型自動產生 CODEPILOT.md
+def cmd_init(tools, model):
+    files = tools.list_files("*", max_depth=2)
+    git = tools.git_context()
+    # 讀取幾個關鍵檔案
+    readme = tools.read_file("README.md") if exists("README.md") else ""
+    pkg = tools.read_file("package.json") if exists("package.json") else ""
+    req = tools.read_file("requirements.txt") if exists("requirements.txt") else ""
+    
+    prompt = f"""Analyze this project and generate a CODEPILOT.md file.
+    Files: {files}
+    Git: {git}
+    README: {readme[:2000]}
+    Config: {pkg or req}
+    
+    Generate markdown with: tech stack, coding conventions, test commands, key files."""
+    
+    codepilot_md = model.chat([{"role":"user","content":prompt}])
+    tools.write_file("CODEPILOT.md", codepilot_md)
+```
+
+#### 2. ❌ 子代理（Sub-agents）
+Claude Code 有 6 種內建子代理：Explore、Plan、Verification、General、Guide、Statusline。
+
+**缺少的**：CodePilot 只有單一主循環，無法平行處理或分工。
+
+**最重要的子代理**：
+- **Explore agent**：只能讀/搜尋，不能寫。用於深入調查問題。
+- **Verification agent**：完成任務後自動跑測試驗證。
+- **Plan agent**：先產生計劃，用戶確認後才執行。
+
+**實作建議**：
+```python
+def run_subagent(model, task, tools, allowed_tools=None, deny_tools=None):
+    """在隔離的 context 中執行子任務"""
+    sub_messages = [
+        {"role": "system", "content": f"You are a sub-agent. Task: {task}"},
+    ]
+    # 跑獨立的工具循環，只回傳摘要
+    result = agent_loop(model, sub_messages, tools, max_rounds=5,
+                        allowed_tools=allowed_tools)
+    return summarize(result)
+```
+
+#### 3. ❌ 5 層漸進壓縮（Graduated Compaction）
+Claude Code 有 5 層壓縮，從輕到重依序觸發：
+1. Budget reduction（每個工具結果限制大小）
+2. Snip（裁剪舊歷史）
+3. Microcompact（細粒度快取壓縮）
+4. Context collapse（讀取時虛擬投影）
+5. Auto-compact（完整摘要）
+
+**缺少的**：CodePilot 只有第 5 層（直接摘要），前 4 層都沒有。
+
+**最該先加的**：Budget reduction — 限制每個工具結果的長度。
+
+**實作建議**：
+```python
+# 在 execute_tool 後加入
+MAX_TOOL_RESULT_TOKENS = 3000  # ~12KB
+
+def truncate_tool_result(result, max_chars=12000):
+    if len(result) > max_chars:
+        return result[:max_chars//2] + f"\n\n... ({len(result)} chars total, truncated) ...\n\n" + result[-max_chars//4:]
+    return result
+```
+
+#### 4. ❌ 錯誤恢復機制
+Claude Code 有：
+- Max output token 自動升級（最多重試 3 次）
+- Prompt-too-long 自動壓縮重試
+- Streaming fallback
+- Fallback model 切換
+
+**缺少的**：CodePilot 工具失敗或模型錯誤時只顯示錯誤訊息，沒有自動恢復。
+
+**實作建議**：
+```python
+for attempt in range(3):
+    try:
+        response = model.chat(messages)
+        break
+    except ContextTooLong:
+        messages = compact_messages(messages, model.chat)  # 壓縮重試
+    except ModelError:
+        if fallback_model:
+            model = fallback_model  # 切換備用模型
+```
+
+### 優先級 P1（重要但可以稍後做）
+
+#### 5. ❌ 權限/審批系統
+Claude Code 有 7 種權限模式：plan、default、auto-edit、full-auto、auto、deny、bubble。
+
+**缺少的**：CodePilot 的 edit_file 和 run_command 都是直接執行，沒有確認步驟。
+
+**實作建議**：
+```python
+APPROVAL_MODES = {
+    "ask": "每次工具��叫都問用戶",     # 最安全
+    "auto-edit": "文件編輯自動，指令要問",
+    "auto": "全部自動（危險指令除外）",
+}
+# 加入 --approval ask|auto-edit|auto 參數
+```
+
+#### 6. ❌ 背景任務管理
+Claude Code 的 BashTool 支援 `run_in_background`，長時間指令在背景跑。
+
+**缺少的**：CodePilot 的 run_command 是阻塞的，超時就斷。
+
+**實作建議**：
+```python
+import threading
+
+class BackgroundTask:
+    def __init__(self, command, cwd):
+        self.id = str(uuid.uuid4())[:8]
+        self.process = subprocess.Popen(command, shell=True, cwd=cwd,
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    
+    def check(self):
+        if self.process.poll() is not None:
+            return {"status": "done", "output": self.process.stdout.read().decode()}
+        return {"status": "running"}
+```
+
+#### 7. ❌ Hooks 系統（27 種事件鉤子）
+Claude Code 支援 pre/post tool execution hooks，可以：
+- 在工具執行前/後注入自訂邏輯
+- 自動 lint/format 修改後的文件
+- 自動跑測試
+
+**實作建議**：
+```python
+# .codepilot/hooks.json
+{
+    "post_edit_file": "black {file} && isort {file}",
+    "post_write_file": "black {file}",
+    "post_all_tools": "python -m pytest tests/ -x --tb=short"
+}
+```
+
+#### 8. ❌ 自訂代理（.codepilot/agents/*.md）
+Claude Code 可以用 markdown 定義自訂代理，包含自己的工具集、模型、權限。
+
+**實作建議**：
+```markdown
+# .codepilot/agents/reviewer.md
+---
+description: Code review agent
+tools: [read_file, search_files, git_status]
+disallowedTools: [write_file, edit_file, run_command]
+model: anthropic/claude-sonnet-4
+---
+You are a code reviewer. Read the code and provide feedback.
+Never modify files directly.
+```
+
+#### 9. ❌ Session Fork/Resume
+Claude Code 支援 `--resume` 恢復之前的 session，以及 fork 分支對話。
+
+**缺少的**：CodePilot 只能恢復最後一個 session。
+
+#### 10. ❌ MCP（Model Context Protocol）整合
+Claude Code 可以連接外部 MCP 伺服器（資料庫、API 等）。
+
+### 優先級 P2（錦上添花）
+
+#### 11. ❌ WebFetch / WebSearch 工具
+讀取網頁或搜尋網路。
+
+#### 12. ❌ 多模態支援
+讀取圖片、PDF、.ipynb notebook。
+
+#### 13. ❌ Streaming 輸出
+逐字顯示模型回應，而不是等全部生成完才顯示。
+
+#### 14. ❌ Shell 沙盒
+OS 層級的 filesystem/network 隔離。
+
+#### 15. ❌ ML 分類器判斷指令安全性
+Claude Code 用 ML 模型判斷 bash 指令是否安全。
+
+#### 16. ❌ 自動 Git Commit
+完成一組修改後自動 commit。
+
+---
+
+## 實作優先級排序
+
+| 優先級 | 功能 | 工作量 | 價值 |
+|--------|------|--------|------|
+| **🔴 P0** | /init 自動產生 CODEPILOT.md | 小 | ⭐⭐⭐⭐⭐ |
+| **🔴 P0** | 工具結果截斷（Budget reduction） | 小 | ⭐⭐⭐⭐⭐ |
+| **🔴 P0** | 錯誤恢復（重試 + 壓縮 + fallback） | 中 | ⭐⭐⭐⭐⭐ |
+| **🔴 P0** | Verification 子代理（自動跑測試） | 中 | ⭐⭐⭐⭐ |
+| **🟡 P1** | 權限/審批系統 | 中 | ⭐⭐⭐⭐ |
+| **🟡 P1** | Hooks（post-edit 自動 lint） | 小 | ⭐⭐⭐⭐ |
+| **🟡 P1** | 背景任務 | 中 | ⭐⭐⭐ |
+| **🟡 P1** | 自訂代理 (.codepilot/agents/) | 中 | ⭐⭐⭐ |
+| **🟡 P1** | Session fork/resume | 小 | ⭐⭐⭐ |
+| **🟡 P1** | 自動 Git Commit | 小 | ⭐⭐⭐ |
+| **🟢 P2** | Streaming 輸出 | 中 | ⭐⭐⭐ |
+| **🟢 P2** | WebFetch / WebSearch | 中 | ⭐⭐ |
+| **🟢 P2** | MCP 整合 | 大 | ⭐⭐ |
+| **🟢 P2** | 多模態（圖片/PDF） | 大 | ⭐⭐ |
+| **🟢 P2** | Shell 沙盒 | 大 | ⭐ |
+| **🟢 P2** | ML 安全分類器 | 大 | ⭐ |