Add comprehensive documentation

DOCS.md

@@ -0,0 +1,460 @@
+# CodePilot — 自我進化的 AI 程式助手
+
+> 像 Claude Code，但完全本地、免費，而且**越用越聰明**
+
+## 它是什麼？
+
+CodePilot 是一個終端 CLI 開發工具，可以直接在你的專案裡讀寫文件、跑指令、搜尋程式碼。
+它的核心特色是**自我進化**——你使用的過程就是在訓練它，讓它越來越懂你的風格和需求。
+
+```
+你用 CodePilot 寫 code
+        │
+        ▼ 自動收集回饋
+        │
+        ▼ 累積數據 → 訓練
+        │
+        ▼ 模型變更強
+        │
+        └──→ 繼續用，繼續進步 🔄
+```
+
+---
+
+## 功能一覽
+
+| 功能 | 說明 |
+|------|------|
+| 📁 讀取/編輯/建立文件 | 直接修改專案程式碼，顯示 diff |
+| 🖥️ 執行指令 | 跑 pytest、npm、git 等任何指令 |
+| 🔍 搜尋程式碼 | ripgrep/grep 搜尋 |
+| 🔀 Git 整合 | 自動偵測分支、狀態、最近 commit |
+| 🧠 四層記憶 | CODEPILOT.md + MEMORY.md + Session + 自動壓縮 |
+| ⚔️ Duel 模式 | 本地 vs 雲端，一鍵產生 DPO 訓練對 |
+| ⚗️ 知識蒸餾 | 用 Claude/GPT 的回答訓練你的本地模型 |
+| 🏋️ 自動刷題 | LeetCode 自動刷題，無人值守產生訓練數據 |
+| 👍👎 回饋收集 | 按一下就記錄，累積後一鍵訓練 |
+
+---
+
+## 安裝
+
+### 系統需求
+
+- Python 3.10+
+- NVIDIA GPU（8GB+ VRAM，推薦 RTX 3070 以上）
+- CUDA + PyTorch
+
+### 安裝步驟
+
+```bash
+# 1. 安裝 Python 依賴
+pip install transformers peft bitsandbytes accelerate trl datasets rich httpx
+
+# 2. 下載 CodePilot
+# 從 https://huggingface.co/spaces/Justin-lee/sandbox-5ca717e4 下載：
+#   - codepilot_v4.py   （主程式）
+#   - memory.py          （記憶模組，放同目錄）
+
+# 3. （可選）安裝為全域指令
+chmod +x codepilot_v4.py
+ln -s $(pwd)/codepilot_v4.py ~/.local/bin/codepilot
+
+# 4. 首次執行會自動下載模型（約 6GB）
+cd ~/my-project
+python codepilot_v4.py
+```
+
+---
+
+## 快速開始
+
+### 最簡單的用法（本地模型，免費離線）
+
+```bash
+cd ~/my-project
+python codepilot_v4.py
+```
+
+模型第一次啟動會下載 Qwen2.5-Coder-3B-Instruct（約 6GB），之後會快取在本地。
+
+### 使用雲端模型（更強，需要 API）
+
+```bash
+python codepilot_v4.py \
+    --provider openrouter \
+    --api-key sk-or-v1-xxxxx \
+    --cloud-model anthropic/claude-sonnet-4
+```
+
+### 開啟蒸餾模式（用雲端回答訓練本地模型）
+
+```bash
+python codepilot_v4.py \
+    --distill \
+    --provider openrouter \
+    --api-key sk-or-v1-xxxxx
+```
+
+---
+
+## 雲端模型接入方式
+
+CodePilot 支援 5 種方式接入雲端模型：
+
+### 方式 1：OpenRouter（推薦 — 一個 Key 用所有模型）
+
+OpenRouter 是一個 API 聚合器，一個帳號可以用 Claude、GPT、Gemini、Llama 等所有模型。
+
+```bash
+# 1. 註冊：https://openrouter.ai/
+# 2. 取得 API Key：https://openrouter.ai/keys
+# 3. 儲值（最低 $5）
+
+python codepilot_v4.py \
+    --provider openrouter \
+    --api-key sk-or-v1-xxxxx \
+    --cloud-model anthropic/claude-sonnet-4
+
+# 其他可用模型：
+#   anthropic/claude-opus-4         （最強，$15/M tokens）
+#   anthropic/claude-sonnet-4       （推薦，$3/M tokens）
+#   openai/gpt-4o                   （$2.5/M tokens）
+#   google/gemini-2.5-pro           （$1.25/M tokens）
+#   deepseek/deepseek-chat-v3       （最便宜，$0.27/M tokens）
+#   meta-llama/llama-4-maverick     （開源，$0.2/M tokens）
+```
+
+> 💡 **蒸餾建議用 Sonnet 或 DeepSeek** — 品質夠好，費用低，可以大量產生數據
+
+### 方式 2：Anthropic 直連
+
+```bash
+# 註冊：https://console.anthropic.com/
+# API Key：Settings → API Keys
+
+python codepilot_v4.py \
+    --provider anthropic \
+    --api-key sk-ant-xxxxx \
+    --cloud-model claude-sonnet-4-20250514
+```
+
+### 方式 3：OpenAI 直連
+
+```bash
+# 註冊：https://platform.openai.com/
+# API Key：https://platform.openai.com/api-keys
+
+python codepilot_v4.py \
+    --provider openai \
+    --api-key sk-xxxxx \
+    --cloud-model gpt-4o
+```
+
+### 方式 4：Ollama（本地跑其他模型，免費）
+
+不需要 API Key！在本機跑其他開源模型。
+
+```bash
+# 1. 安裝 Ollama：https://ollama.ai/
+# 2. 下載模型
+ollama pull qwen2.5-coder:7b
+ollama pull deepseek-coder-v2:16b
+ollama pull codellama:13b
+
+# 3. 啟動（Ollama 會自動在背景跑）
+python codepilot_v4.py \
+    --provider ollama \
+    --cloud-model qwen2.5-coder:7b
+
+# 不需要 --api-key！
+```
+
+> 💡 **Ollama 蒸餾**：用更大的 7B/13B 模型蒸餾你的 3B 模型，完全免費離線
+
+### 方式 5：任何 OpenAI 相容 API
+
+如果你有自己架設的推理服務（vLLM、TGI、LM Studio 等）：
+
+```bash
+# 修改 codepilot_v4.py 的 PROVIDER_CONFIGS，加入：
+"custom": {
+    "name": "My Server",
+    "type": "openai",
+    "base_url": "http://192.168.1.100:8000/v1",
+    "default_model": "my-model",
+}
+
+python codepilot_v4.py \
+    --provider custom \
+    --api-key dummy   # 有些本地伺服器不需要真的 key
+```
+
+### 方式比較
+
+| 方式 | 費用 | 模型品質 | 需要網路 | 設定難度 |
+|------|------|---------|---------|---------|
+| **OpenRouter** | 按量計費 | ⭐⭐⭐⭐⭐ (Opus/GPT-4o) | 是 | ⭐ 最簡單 |
+| Anthropic 直連 | 按量計費 | ⭐⭐⭐⭐⭐ | 是 | ⭐⭐ |
+| OpenAI 直連 | 按量計費 | ⭐⭐⭐⭐⭐ | 是 | ⭐⭐ |
+| **Ollama** | **免費** | ⭐⭐⭐⭐ (7B-13B) | **否** | ⭐⭐ |
+| 自架伺服器 | 電費 | 自訂 | 否 | ⭐⭐⭐⭐ |
+
+---
+
+## 蒸餾訓練完整教學
+
+### 什麼是知識蒸餾？
+
+用強大的雲端模型（老師）的回答，來訓練你的本地小模型（學生）。
+訓練完後，你的本地模型會學到老師的風格和能力，但完全免費、離線、隱私。
+
+### Phase 1：收集數據
+
+有三種收集方式，可以混合使用：
+
+#### A. 日常使用自動收集（推薦）
+
+```bash
+# 蒸餾模式 — 雲端回答自動記錄
+python codepilot_v4.py --distill --provider openrouter --api-key sk-or-v1-xxx
+
+# 正常使用，正常開發你的專案
+# 每個回答自動存入 ~/.codepilot/feedback.db
+```
+
+#### B. Duel 模式手動比較（最高品質）
+
+```bash
+python codepilot_v4.py \
+    --duel \
+    --provider openrouter \
+    --api-key sk-or-v1-xxx \
+    --adapter ~/.codepilot/adapter_latest   # 有的話帶上
+
+# 每個問題自動送給本地+雲端
+# 你選哪個好 → 自動產生 DPO 訓練對
+```
+
+#### C. LeetCode 自動刷題（無人值守）
+
+```bash
+# 掛著過夜，自動刷 500 題
+python codepilot_v4.py \
+    --grind --grind-count 500 \
+    --provider openrouter \
+    --api-key sk-or-v1-xxx \
+    --cloud-model anthropic/claude-sonnet-4
+
+# 全自動：出題 → 寫答案 → 跑測試 → 記錄
+# 約 3-4 小時，費用 ~$3 (Sonnet)
+```
+
+### Phase 2：查看收集狀態
+
+```bash
+python codepilot_v4.py --stats
+```
+
+**建議至少收集 200 條以上再訓練。**
+
+### Phase 3：訓練
+
+```bash
+python codepilot_v4.py --train
+
+# 在 RTX 3070 上約需 1-2 小時
+# 訓練完會顯示 adapter 路徑
+```
+
+### Phase 4：使用訓練後的模型
+
+```bash
+python codepilot_v4.py --adapter ~/.codepilot/adapter_20260423_0830
+```
+
+### Phase 5：持續循環
+
+```bash
+# 用新模型繼續 Duel → 看它進步了多少
+python codepilot_v4.py \
+    --duel \
+    --provider openrouter \
+    --api-key sk-or-v1-xxx \
+    --adapter ~/.codepilot/adapter_20260423_0830
+
+# 繼續收集 → 再訓練 → 再進步 🔄
+```
+
+---
+
+## 記憶系統
+
+CodePilot 使用四層記憶架構（仿 Claude Code）：
+
+### L1: CODEPILOT.md（專案指令）
+
+在專案根目錄建立 `CODEPILOT.md`，內容會自動注入每次對話：
+
+```markdown
+# 專案規範
+- 語言: Python 3.11+, TypeScript 5.x
+- 後端: FastAPI + SQLAlchemy + Alembic
+- 前端: React + TailwindCSS
+- 測試: pytest (後端), vitest (前端)
+- 風格: black, isort, ESLint
+- API 格式: { "data": ..., "error": null, "message": "ok" }
+- 不要用 print debug，用 logging
+- 所有 API 都要有 OpenAPI docstring
+```
+
+**搜尋順序**（越後面優先級越高）：
+```
+~/.codepilot/CODEPILOT.md        # 全域（所有專案）
+../../CODEPILOT.md                # 父目錄
+./CODEPILOT.md                    # 專案目錄（提交到 repo）
+./.codepilot/rules/*.md           # 條件規則
+./CODEPILOT.local.md              # 私人覆蓋（加到 .gitignore）
+```
+
+### L2: MEMORY.md（跨 Session 記憶）
+
+自動記住你的偏好和專案決策：
+
+```bash
+# 快速追加一條記憶
+🧑 You: /memo 用戶說 API 回傳格式統一用 {data, error, message}
+🧠 已追加到 MEMORY.md
+
+# 或者用 /memo 進入編輯模式
+🧑 You: /memo
+```
+
+存在 `~/.codepilot/projects/<project>/memory/MEMORY.md`
+
+### L3: Session 對話歷史
+
+- 自動保存每一輪對話
+- 關掉 CodePilot 再打開，**自動恢復上次對話**
+- 可以追問、修改之前的指令
+
+### L4: 自動壓縮
+
+- 對話超過 75% context window 自動觸發
+- 用 9 段摘要保留關鍵資訊
+- 壓縮後自動重新注入最近修改的 5 個文件
+
+---
+
+## CLI 指令表
+
+| 指令 | 功能 |
+|------|------|
+| `/duel on` / `/duel off` | 開關 Duel 模式（雙模型比較） |
+| `/memo` | 編輯 CODEPILOT.md 或 MEMORY.md |
+| `/memo 文字` | 快速追加一條記憶 |
+| `/grind` | LeetCode 自動刷題 |
+| `/switch` | 切換模型 |
+| `/ls` / `/ls *.py` | 列出專案文件 |
+| `/git` | 顯示 Git 狀態 |
+| `/clear` | 清除對話歷史 |
+| `/status` | 查看回饋統計 |
+| `/train` | 用收集的數據訓練 |
+| `/quit` | 退出 |
+
+---
+
+## 命令列參數
+
+```
+python codepilot_v4.py [OPTIONS]
+
+模型選項:
+  --model MODEL          本地模型名稱 (預設: Qwen/Qwen2.5-Coder-3B-Instruct)
+  --adapter PATH         LoRA adapter 路徑
+
+雲端模型:
+  --provider PROVIDER    模型提供者: local, openai, anthropic, openrouter, ollama
+  --api-key KEY          API 密鑰
+  --cloud-model MODEL    雲端模型名稱
+
+模式:
+  --duel                 啟動時開啟 Duel 模式
+  --distill              蒸餾模式（自動收集雲端回答）
+  --grind                LeetCode 自動刷題模式
+  --grind-count N        刷幾題 (預設: 100)
+
+其他:
+  --project PATH         專案目錄 (預設: 當前目錄)
+  --stats                查看統計
+  --train                用收集的數據訓練
+```
+
+---
+
+## 常見問題
+
+### Q: 第一次用，沒有 adapter，怎麼開始？
+
+直接不帶 `--adapter` 啟動就好，會用原始的 Qwen2.5-Coder-3B 模型。
+用一陣子收集數據後 `--train`，就會產生你的第一個 adapter。
+
+### Q: GPU 記憶體不夠怎麼辦？
+
+CodePilot 推理用 bfloat16（~6.5GB），訓練用 QLoRA 4-bit（~7.5GB）。
+RTX 3070 8GB 夠用。如果還是 OOM：
+- 關掉其他佔 GPU 的程式
+- 推理模式下不要同時開訓練
+
+### Q: 蒸餾是否違反模型的使用條款？
+
+- OpenAI ToS: 不允許用 GPT 輸出訓練競爭模型，但個人/學術用途的灰色地帶
+- Anthropic ToS: 類似限制
+- **建議**: 用 DeepSeek、Llama 等開源模型蒸餾，完全沒有法律問題
+- Ollama + 開源大模型蒸餾 = 100% 合法免費
+
+### Q: 數據存在哪裡？
+
+```
+~/.codepilot/
+├── feedback.db                    # 所有回饋（SQLite）
+├── CODEPILOT.md                   # 全域指令
+├── projects/
+│   └── <project-hash>/
+│       ├── memory/
+│       │   └── MEMORY.md          # 跨 session 記憶
+│       ├── <session-id>.jsonl     # 對話歷史
+│       └── ...
+├── sessions/
+│   └── <project>.json             # Session 快照
+└── adapter_20260423_0830/         # 訓練產生的 LoRA adapter
+```
+
+### Q: 可以匯出數據到 HuggingFace 嗎？
+
+用之前的 `code_llm_collector.py` 的 `export` 功能，或直接操作 SQLite：
+
+```python
+import sqlite3, json
+conn = sqlite3.connect("~/.codepilot/feedback.db")
+rows = conn.execute("SELECT * FROM feedback").fetchall()
+```
+
+---
+
+## 檔案清單
+
+| 檔案 | 說明 | 下載 |
+|------|------|------|
+| `codepilot_v4.py` | 主程式（813 行） | [下載](https://huggingface.co/spaces/Justin-lee/sandbox-5ca717e4/blob/main/codepilot_v4.py) |
+| `memory.py` | 記憶系統模組（407 行） | [下載](https://huggingface.co/spaces/Justin-lee/sandbox-5ca717e4/blob/main/memory.py) |
+| `code_llm_train.py` | 獨立 SFT 訓練腳本 | [下載](https://huggingface.co/spaces/Justin-lee/sandbox-5ca717e4/blob/main/code_llm_train.py) |
+| `code_llm_pipeline.py` | 完整進化流水線 (SFT→DPO→GRPO→Self-Play) | [下載](https://huggingface.co/spaces/Justin-lee/sandbox-5ca717e4/blob/main/code_llm_pipeline.py) |
+| `eval_humaneval.py` | HumanEval 評估腳本 | [下載](https://huggingface.co/spaces/Justin-lee/sandbox-5ca717e4/blob/main/eval_humaneval.py) |
+| `Code_LLM_Training.ipynb` | Google Colab Notebook | [下載](https://huggingface.co/spaces/Justin-lee/sandbox-5ca717e4/blob/main/Code_LLM_Training.ipynb) |
+
+---
+
+## License
+
+MIT