🏛️ Code History (AI 程式碼考古學)

VS Code 擴充套件 + SVN + AI 演化分析
讓開發者選取任何一段程式碼，自動逆向穿透排版與重構歷史，鎖定這段代碼**「第一次出現的 SVN 版本」**，並可由 LLM 解釋程式碼為什麼演變成今天的樣貌。

🎯 產品核心價值 (Why & How)

平時維護老專案時，傳統工具（如 TortoiseSVN Blame、VS Code Git/SVN 擴充）只能查出 「最後更動這行的人 (Who & When)」。
但最後修改的人往往只是排版縮排、格式化、或是重構了附近幾行，根本不是這段程式碼的真正撰寫者！

Code History 的定位是「程式碼身世考古」：

穿透排版與縮排干擾：自動比對歷史前一版本，精準揪出這段特定程式碼到底是在誰的手上、哪一個 SVN 版本中第一次被寫入！
完全不依賴 AI 也能一目了然：頂部以 32px 特大醒目徽章 呈現版本號碼、Commit 原因與關鍵 Diff，0.1 秒得到答案。
預設純 SVN 模式，零外部開銷：初次安裝預設為純 SVN 考古模式，不發送任何 AI 網路請求。使用者可隨時按需求自由啟用 Google Gemini 或自建/本地端模型。

📦 安裝方式 (Installation)

方式 1：VS Code 市集線上安裝（推薦）

開啟 VS Code，進入左側 擴充功能 (Extensions)（快捷鍵 Ctrl + Shift + X）。
搜尋 Code History 或 ricky-huang.code-history。
點擊 安裝 (Install) 即可完成。

方式 2：終端機一行指令安裝

code --install-extension ricky-huang.code-history

方式 3：從 VSIX 安裝檔離線安裝

下載 .vsix 安裝檔後執行：

code --install-extension code-history-*.vsix

⚙️ 一鍵設定指南 (帳密與模型參數)

安裝完成後，VS Code 右下角狀態列 會顯示狀態按鈕：$(key) SVN: 未設定帳密 或 $(key) SVN: [帳號]。

💡 預設為【純 SVN 考古模式】（AI 預設停用），完全不發送任何 AI 網路請求。若需要 AI 生成演化總結，隨時依照下方說明一鍵啟用即可。

直接點擊右下角狀態列按鈕（或按 Ctrl + Shift + P 輸入 Code History: Show Menu），即可彈出控制選單：

1. ⚙️ 設定 LLM 模型與參數

點選後可透過選單精靈快速配置：

✨ Google Gemini 官方雲端：
- 推薦預設模型：gemini-3.5-flash-lite（最新超輕量旗艦，極速低延遲、性價比最高）。
- 熱門清單速選：支援 gemini-2.5-flash、gemini-2.5-pro、gemini-1.5-flash、gemini-1.5-pro 等。
- 自由手動輸入：點選「✏️ 自行手動輸入其他 Gemini 模型名稱...」，輸入任意 Google AI Studio 支援的模型代號。
🖥️ 設定自建 / 本地端模型 (OpenAI 相容協議)：
- 支援 Ollama, llama.cpp, vLLM, LM Studio 或企業私有自建模型，引導輸入 API 網址與模型名稱（支援免金鑰）。
🚫 停用 AI (純 SVN 考古模式) / ✅ 啟用 AI 功能：隨時一鍵切換。
🌐 自訂 API URL 與模型名稱：自由微調伺服器網址、模型代號、採樣溫度 (Temperature) 等。

💡 亦可隨時按 Ctrl + , 搜尋 Code History，在 VS Code 圖形化設定介面中進行調整。

2. 🔑 設定 SVN 帳號與密碼

輸入您的 SVN 使用者帳號與密碼。
密碼透過 VS Code 原生安全金鑰庫（SecretStorage）加密保護，不會以明文形式寫入設定檔中。

3. 🔌 測試 SVN 連線

點擊即可立即驗證與 SVN 伺服器的握手狀態與權限是否正常。

🖥️ 如何設定自建 / 本地端模型 (Ollama / llama.cpp / vLLM / 私有伺服器)

本套件完全遵循業界標準 OpenAI Chat Completions 規範，並內建 SSE 串流傳輸 與 內網 Proxy 自動繞過機制，非常適合開發團隊連接本地端或企業內部自建 LLM！

步驟說明：

點擊右下角狀態列按鈕 ➔ 選擇 「⚙️ 設定 LLM 模型與參數」。
點選 「🖥️ 設定自建 / 本地端模型 (OpenAI 相容協議)」。
輸入 API 伺服器網址 (API URL)：
- Ollama (本機)：http://localhost:11434/v1/chat/completions
- llama.cpp server：http://localhost:8080/v1/chat/completions 或 http://<伺服器IP>:8080/v1/chat/completions
- LM Studio：http://localhost:1234/v1/chat/completions
- vLLM / LocalAI：http://localhost:8000/v1/chat/completions
- 私有自建伺服器：http://<伺服器IP>:<連接埠>/v1/chat/completions
輸入模型名稱 (Model Name)：
- 例如：llama3, qwen2.5-coder, mistral, deepseek-r1，或私有伺服器自訂的模型名稱。
API Key (金鑰)：
- 本地或私有模型通常不需要金鑰，在提示輸入時直接按 Enter 留空即可進入免金鑰模式。
參數調優建議 (選填)：
- Temperature (採樣溫度)：建議設為 0，讓模型以最高確定性與嚴謹度依據 SVN 事實推論。
- Max Tokens：建議設為 2048 ~ 4096。

🌟 私有網路直連優勢：若伺服器架設在私有 IP（如 10.*、172.16~31.*、192.168.*、localhost），本擴充套件會採用底層 TCP Socket 直連，自動繞過系統環境 Proxy 代理伺服器干擾（避免 502 Bad Gateway 錯誤），並支援串流傳輸即時回報 Token 生成進度！

🚀 日常操作方式與畫面說明

在編輯器中（如 TypeScript, JavaScript, C#, Java, Python, Go 等任意檔案），反白選取您好奇身世的 1～5 行程式碼。
按滑鼠右鍵 ➔ 點選 「Code History: Analyze Selected Code」。
側邊會立即彈出 Code Evolution History 視覺化面板：

┌────────────────────────────────────────────────────────────────────────┐
│ 🏛️ AI Code Archaeology                                                 │
│                                                                        │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ 🌱 程式碼第一次出現版本 (First Appeared Revision)                   │ │
│ │   已穿透後續所有排版與重構，直達本段特定程式碼首次被引入之 SVN 版本   │ │
│ │                                                                    │ │
│ │   版本號碼： [  r1024  ]  ◀─── (32px 特大醒目綠色徽章)             │ │
│ │                                                                    │ │
│ │   • 首次引入作者： alex                                              │ │
│ │   • 首次提交時間： 2022/04/15 14:20:00                              │ │
│ │   • 當時 Commit 說明：                                              │ │
│ │     feat: Support dynamic cache expiration based on user tier        │ │
│ │   • 該版本變更 (Diff)：                                             │ │
│ │     - const cacheTtl = DEFAULT_TTL;                                 │ │
│ │     + const cacheTtl = getTierCacheTtl(user.tier);                  │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│ 📍 當前選取程式碼 (Current Code)                                       │
│   檔案路徑、行號，並自動辨識所屬 Class 與 Method 語法範圍。            │
│                                                                        │
│ ⏳ 演化歷程時間軸 (Evolution Timeline)                                 │
│   由遠到近列出所有關鍵歷史躍點，可展開查看每次變更的 Diff 片段。       │
│                                                                        │
│ ✨ AI 程式碼演化故事 (可選)                                            │
│   由本地端 LLM 或 Google Gemini 依據客觀事實清單撰寫演進歷程與建議。   │
└────────────────────────────────────────────────────────────────────────┘

🎬 經典展示案例（如何向團隊展示）

若要向團隊成員或主管展示這個工具的威力，最能引發共鳴的是**「對比演示法」**：

範例檔案：src/services/cacheService.ts

選取程式碼：

const cacheTtl = getTierCacheTtl(user.tier);

4 步驟展示腳本：

揭露傳統工具的盲點：
- 「平時我們維護專案遇到這行程式碼，通常會開 Blame 工具，查出來最後修改的人是 r1450 by bob。」
- 「但一問之下才發現，bob 當初只是格式化縮排或替函式重新命名，根本不是這行邏輯的真正作者！」
一鍵見證智慧穿透：
- 對著這行右鍵 ➔ Code History: Analyze Selected Code。
- 「最頂端直接以醒目大徽章顯示：這段邏輯真正的首次誕生版本是 r1024 by alex！」
不用 AI 也能看懂歷史脈絡：
- 「頂部卡片直接把 r1024 當初的 Commit 訊息與 Diff 展開呈現，立刻明白當初引進這個邏輯是為了解決什麼需求！」
結合 AI 的延伸價值：
- 「若開啟自建本地模型或 Google Gemini，還能整合多個躍點的紀錄，自動總結演進歷程並提供現代化重構建議。」

💡 常見問題 (FAQ)

Q1：我只想快速查版本，不想等 AI 或不想連外網怎麼辦？

預設安裝即為【純 SVN 考古模式】！完全不發送任何 AI 網路請求，右鍵分析僅需 1 秒即可直接在頂端看到首次出現的版本號與時間軸。

Q2：如何切換使用自建的本地 / 私有模型？

點選狀態列 ➔ 選擇「⚙️ 設定 LLM 模型與參數」 ➔ 點選「🖥️ 設定自建 / 本地端模型 (OpenAI 相容協議)」，依照提示填寫您的伺服器網址（如 http://<ip>:8080/v1/chat/completions）與模型代號即可。

Q3：密碼更改了，如何更新？

點擊狀態列 ➔ 選擇「🔑 設定 SVN 帳號與密碼」重新輸入即可。

Code History (AI Code Archaeology)

ricky-huang