DOCS.md

# 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                用收集的數據訓練
```

---


---

## 方式 6：OpenAI Codex（最新）

OpenAI Codex 是 OpenAI 官方的 coding agent CLI（類似 Claude Code），支援 GPT-5 系列模型。

### 安裝 Codex

```bash
# 方式 A: npm
npm install -g @openai/codex

# 方式 B: brew (macOS)
brew install --cask codex

# 首次使用需要登入
codex    # 會跳出「Sign in with ChatGPT」
```

### 在 CodePilot 中使用 Codex

```bash
# 不需要 API Key！用你的 ChatGPT 帳號登入就好
python codepilot_v4.py --provider codex

# 指定模型
python codepilot_v4.py --provider codex --cloud-model gpt-5.4

# Duel：Codex vs 你的本地模型
python codepilot_v4.py \
    --duel \
    --provider codex \
    --adapter ~/.codepilot/adapter_latest

# 用 Codex 自動刷 LeetCode（蒸餾 GPT-5 的能力）
python codepilot_v4.py \
    --grind --grind-count 200 \
    --provider codex
```

### Codex 認證方式

| 方式 | 說明 |
|------|------|
| **ChatGPT 登入**（推薦）| 首次執行 `codex` 會引導你登入，支援 Plus/Pro/Enterprise |
| API Key | 設定環境變數 `OPENAI_API_KEY=sk-xxx` |

### Codex 整合方式

CodePilot 支援兩種方式連接 Codex：

1. **Python SDK**（優先）— 如果安裝了 `codex-app-server-sdk`
   ```bash
   pip install codex-app-server-sdk
   ```
   
2. **CLI subprocess**（自動 fallback）— 只要安裝了 `codex` CLI 就能用

### 完整方式比較（更新版）

| 方式 | API Key | 費用 | 模型品質 | 網路 | 設定 |
|------|:-------:|------|---------|:----:|------|
| **Codex** | ❌ ChatGPT 登入 | ChatGPT 訂閱 | ⭐⭐⭐⭐⭐ GPT-5 | ✅ | ⭐ 簡單 |
| **OpenRouter** | ✅ | 按量 | ⭐⭐⭐⭐⭐ 全部 | ✅ | ⭐ 簡單 |
| Anthropic | ✅ | 按量 | ⭐⭐⭐⭐⭐ Claude | ✅ | ⭐⭐ |
| OpenAI | ✅ | 按量 | ⭐⭐⭐⭐⭐ GPT | ✅ | ⭐⭐ |
| **Ollama** | ❌ | **免費** | ⭐⭐⭐⭐ | ❌ | ⭐⭐ |
| 自架伺服器 | ❌ | 電費 | 自訂 | ❌ | ⭐⭐⭐⭐ |



## 常見問題

### 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