「真正的理解，不是記住答案，而是能說出『為什麼』。」
SocratesApp 是一套反依賴型 AI 學習系統。它不直接給答案，而是透過蘇格拉底式「因為 → 所以」因果推理鏈，迫使學生建立真正的概念理解，而非單純記憶。
左側為技能樹（DAG），右側為蘇格拉底式問答對話；AI 針對每個回答給予即時評分與診斷回饋。
現有 AI 工具（ChatGPT、Copilot 等）的核心問題是「給魚」：學生提問，AI 直接給出答案，學生複製貼上，理解停留在表面。
SocratesApp 採用完全相反的策略：
- AI 只問問題，不給答案
- 每個問題從學生的上一個回答衍生，而非預先設定
- 錯誤時診斷根本原因，插入「修復性子問題」
- 連續三次錯誤才切換教師模式，提供引導文章後繼續提問
- 每個知識節點需完成 5 題並由 AI 評分（0–20.0 分 / 題，總分 100 分，60 分及格）
| 場景 | 說明 |
|---|---|
| 自學技術主題 | 輸入「算法」，系統自動生成包含排序、搜尋、動態規劃等分支的技能樹 |
| 課前預習 | 輸入「憲法」，沿著概念因果鏈逐步建立知識架構 |
| 深度複習 | 輸入「太空物理」，針對個人薄弱環節進行個性化提問 |
| 教師備課 | 用生成的技能樹（JSON 格式）了解學科概念依賴關係 |
適合任何需要真正理解、而非死記硬背的知識領域。
1. 學生輸入主題
↓
2. Claude AI 生成技能樹（3 個分支，9–12 個節點，含前置依賴）
↓
3. 從 A1 節點開始，AI 提出生活情境式問題
↓
4. 學生回答 → AI 評分（0–200 單位 / 題，精確至 0.1 分）
├─ 正確：引導至下一因果步驟
└─ 錯誤：診斷根本原因 → 插入修復性子問題
↓
5. 連續 3 次錯誤 → 教師模式：生成個性化教學文章 → 繼續提問
↓
6. 完成 5 題 → 節點完成，解鎖下一節點
↓
7. 所有節點完成 → 選擇：繼續深入（延伸技能樹）或產生診斷報告
每題由 Claude 評分，返回 0–200 點數：
| 點數 | 換算真實分數 | 意義 |
|---|---|---|
| 200 | 20.0 分 | 完整正確，因果關係清晰 |
| 160~190 | 16~19 分 | 基本正確，細節略有遺漏 |
| 120~150 | 12~15 分 | 部分正確，有明顯誤解 |
| 60~110 | 6~11 分 | 方向正確但嚴重錯誤 |
| 0~50 | 0~5 分 | 完全錯誤或「不知道」 |
5 題合計最高 100.0 分，60 分及格。
AI 自動生成 DAG（有向無環圖）技能樹：
- 3 個分支（例如：核心語法 / 資料結構 / 工具生態）
- 9–12 個節點，每節點 5 題
- 跨分支邊（至少 2 條），形成網狀依賴關係
- 節點狀態：
Locked→Available→InProgress→Completed
Browser (HTML + JS) ← 技能樹 UI（D3.js DAG）、WebSocket 聊天
↕ WebSocket (/ws)
C++ Backend (Drogon, :8080) ← 引擎、狀態機、AI 協作
↕ HTTPS
Claude API ← 問題評分、技能樹生成、教學文章
PostgreSQL 16 ← 持久化學習狀態（可選）
| 層級 | 技術 |
|---|---|
| C++ Web 框架 | Drogon（非同步、WebSocket） |
| JSON | jsoncpp |
| HTTP Client（Claude API） | cpp-httplib |
| 資料庫 | libpqxx（PostgreSQL 16） |
| C++ 套件管理 | vcpkg |
| 建置系統 | CMake + Ninja |
| AI | Claude API（claude-sonnet-4-6） |
| 前端數學渲染 | KaTeX |
- 每個 WebSocket 連線獨立 Session：
conn->setContext<Session>()— 無全域 Session Map - 每題評分由 AI 決定：Claude 返回 0–200 整數，後端除以 10 得 float 分數
- 教師模式文章個性化：根據本節點累積的誤解記錄生成，每次重新生成（不快取）
- 延伸技能樹：用數字前綴（
2A1、2B1）避免節點 ID 衝突，銜接上一輪最後完成節點
SocratesApp 從一個核心洞察出發：AI 最大的教育風險是讓學習者依賴它。
開發分幾個階段：
- 引擎層：
SkillGraph（DAG）、LearningStateMachine（狀態機）、MasteryEvaluator（因果鏈評估） - AI 整合：Claude SSE 串流文章、結構化 JSON 評分、技能樹自動生成
- 前端 UI：從簡單聊天框演進為帶互動 DAG 的完整學習介面
- 評分精細化：從二元對錯 → 整數計數 → AI 評分浮點數（0.0–20.0 / 題）。最初讓 Claude API 直接回傳浮點評分，但 LLM 輸出格式不穩定導致 JSON parse 失敗率偏高；後來改為整數協議（0–200），後端統一除以 10，穩定性大幅提升。
- 個性化：跨節點誤解追蹤 map、複習題組、延伸學習、診斷報告
| 工具 | 說明 |
|---|---|
| WSL2 (Ubuntu) | C++ 後端必須在 WSL2 內建置與執行 |
| Docker Desktop | 執行 PostgreSQL 16（選用） |
| Anthropic API Key | 從 console.anthropic.com 取得 |
在 Windows PowerShell：
docker run -d --name socrates-db `
-e POSTGRES_PASSWORD=socrates123 `
-e POSTGRES_DB=socratesapp `
-p 5432:5432 postgres:16sudo apt install -y cmake ninja-build g++ git curl zip unzip tar pkg-config \
libssl-dev uuid-dev zlib1g-dev libjsoncpp-dev libpq-dev postgresql-clientvcpkg 安裝（若尚未安裝）：
git clone https://github.com/microsoft/vcpkg ~/vcpkg
~/vcpkg/bootstrap-vcpkg.sh# 進入專案目錄（WSL2 路徑）
cd /mnt/<drive>/<path/to/SocratesApp>
# 首次設定（或 CMakeLists.txt 有變更時）
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_TOOLCHAIN_FILE=~/vcpkg/scripts/buildsystems/vcpkg.cmake
# 建置
cmake --build buildexport SOCRATES_DB="host=localhost dbname=socratesapp user=postgres password=socrates123"
psql $SOCRATES_DB -f src/db/schema.sqlexport ANTHROPIC_API_KEY="sk-ant-api03-..." # 必填
export SOCRATES_DB="host=localhost ..." # 選填，不設定則不持久化
./build/socrates-server
# 伺服器監聽 :8080直接用瀏覽器開啟（不需 Web Server）：
<project-root>\frontend\index.html
或偵錯用原始 WebSocket 測試介面：
<project-root>\frontend\test.html
# 全部測試
cd build && ctest
# 單一測試
./build/tests/test_skill_graph
./build/tests/test_state_machine
./build/tests/test_mastery| type | 說明 |
|---|---|
answer |
學生回答，含 text 欄位 |
confirm_understood |
教師模式文章已讀確認 |
request_article |
請求複習文章，含可選 nodeId |
request_graph |
請求目前技能樹狀態 |
navigate_node |
跳至指定節點（含 nodeId） |
continue_learning |
繼續深入，生成延伸技能樹 |
generate_report |
產生並下載 RESULT.md 診斷報告 |
| type | 說明 |
|---|---|
question |
AI 提出的問題文字 |
feedback |
評分回饋（含 correct、score、diagnosis） |
mode_change |
狀態機切換通知 |
graph |
完整技能樹 JSON |
chunk |
文章串流片段 |
article |
文章串流結束信號 |
node_completed |
節點完成通知 |
course_completed |
全部課程完成 |
report |
RESULT.md 內容（Markdown + Mermaid） |
error |
錯誤訊息 |
詳細欄位定義見 src/api/protocol.h。
SocratesApp/
├── src/
│ ├── main.cpp # Drogon 入口，4 執行緒，port 8080
│ ├── api/
│ │ ├── ws_controller.h/cpp # WebSocket 控制器
│ │ ├── session.h # 每連線學習狀態
│ │ └── protocol.h # 訊息格式文件
│ ├── engine/
│ │ ├── skill_graph.h/cpp # DAG 技能樹
│ │ ├── state_machine.h/cpp # 測驗 ↔ 教師模式狀態機
│ │ └── mastery.h/cpp # 因果鏈掌握度評估
│ ├── ai/
│ │ └── claude_client.h/cpp # Claude API（評分、生成、串流）
│ └── db/
│ ├── db_client.h/cpp # libpqxx PostgreSQL 客戶端
│ └── schema.sql # 資料庫建表語句
├── frontend/
│ ├── index.html # 主要學習介面（DAG UI + 聊天）
│ └── test.html # WebSocket 偵錯工具
├── tests/ # 單元測試
├── CMakeLists.txt
└── README.md
Q: 不設定 SOCRATES_DB 可以用嗎？
A: 可以。沒有資料庫時，學習狀態只存在記憶體中（斷線即消失），但核心功能完全正常。
Q: VS Code 顯示大量 IntelliSense 錯誤怎麼辦？
A: 這些是 Windows VS Code 無法解析 WSL2 標頭檔的假警告，不影響 WSL2 內的實際編譯。可忽略。
Q: Claude API 費用如何？
A: 每次學習階段約消耗數十次 API 呼叫（技能樹生成 + 每題評分 + 教學文章）。每連線設有速率限制（每 60 秒最多 20 次呼叫）。
Q: 支援中文以外的語言嗎？
A: 目前系統提示詞（system prompt）使用繁體中文，AI 回應也以繁體中文為主。修改 claude_client.cpp 中的系統提示詞即可調整語言。
歡迎任何形式的貢獻！請遵循以下流程：
- Fork 本倉庫
- 建立功能分支：
git checkout -b feature/your-feature-name - 提交變更：
git commit -m 'Add some feature' - 推送至分支：
git push origin feature/your-feature-name - 開啟 Pull Request
提交前請確保：
- 新功能附帶對應的單元測試（放在
tests/目錄） - 在 WSL2 內通過
cd build && ctest - 遵循現有程式碼風格（C++17，無裸指針）
本專案採用 MIT License 授權。
本專案由 Claude（Anthropic）AI 輔助設計與開發。