Skip to content

Commit 852c6fe

Browse files
lufftwlufftw
committed
docs: sync project structure and add AI features to zh-TW README
- Update project structure in both README.md and README_zh-TW.md to reflect actual directory layout - Add template_test.txt, tools subdirectories (mindmaps/, patterndocs/, shared/, tests/) - Add .dev/ details (tests_solutions/, run_all_tests, VIRTUAL_ENV_SETUP.md) - Sync README_zh-TW.md with English version: - Add AI Ontology Analysis to core features table - Add SOLUTIONS dict and get_solver() example - Add new AI Mind Map Generation section - Add documentation links (SOLUTION_CONTRACT, GENERATOR_CONTRACT, ARCHITECTURE_MIGRATION) - Update contributors section with AI-powered mind map generation
1 parent 97a19a3 commit 852c6fe

File tree

2 files changed

+181
-20
lines changed

2 files changed

+181
-20
lines changed

‎README.md‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -785,8 +785,9 @@ neetcode/
785785
│ └── util.py # Re-exports (backward compatible)
786786
│
787787
├── templates/ # 📄 Problem templates
788-
│ ├── template_solution.py # Single solution
789-
│ └── template_solution_multi.py # Multi-solution (polymorphic)
788+
│ ├── template_solution.py # Single solution template
789+
│ ├── template_solution_multi.py # Multi-solution (polymorphic)
790+
│ └── template_test.txt # Test case template
790791
│
791792
├── .vscode/ # 🔧 VS Code integration
792793
│ ├── settings.json # Python environment settings
@@ -802,14 +803,22 @@ neetcode/
802803
│ └── stylesheets/ # Custom CSS
803804
│
804805
├── tools/ # 🛠️ Utility scripts
805-
│ ├── generate_mindmaps_ai.py # 🤖 AI mind map generator
806-
│ ├── mindmap_ai_config.toml # AI generation configuration
807-
│ ├── generate_mindmaps.py # Rule-based mind map generator
808-
│ ├── generate_mindmaps.toml # Rule-based configuration
809-
│ ├── generate_pattern_docs.py # Generate pattern docs
810-
│ └── prompts/ # AI prompt management
811-
│ ├── README.md # Prompt documentation
812-
│ └── generated/ # Auto-generated prompts
806+
│ ├── generate_mindmaps_ai.py # 🤖 AI mind map generator
807+
│ ├── mindmap_ai_config.toml # AI generation configuration
808+
│ ├── generate_mindmaps.py # Rule-based mind map generator
809+
│ ├── generate_mindmaps.toml # Rule-based configuration
810+
│ ├── generate_pattern_docs.py # Generate pattern docs
811+
│ ├── generate_pattern_docs.toml # Pattern docs configuration
812+
│ ├── check_solutions.py # Solution validation tool
813+
│ ├── prepare_llm_input.py # Prepare LLM input data
814+
│ ├── text_to_mindmap.py # Convert text to mindmap
815+
│ ├── mindmaps/ # Mind map generator modules
816+
│ ├── patterndocs/ # Pattern docs generator modules
817+
│ ├── shared/ # Shared utilities
818+
│ ├── prompts/ # AI prompt management
819+
│ │ ├── README.md # Prompt documentation
820+
│ │ └── generated/ # Auto-generated prompts
821+
│ └── tests/ # Format validation tests
813822
│
814823
├── ontology/ # 🧬 Algorithm ontology (TOML)
815824
│ ├── api_kernels.toml # API kernel definitions
@@ -835,8 +844,12 @@ neetcode/
835844
│
836845
├── .dev/ # 🧪 Maintainer zone (unit tests)
837846
│ ├── tests/ # Unit test suite (150+ cases)
838-
│ ├── run_tests.bat/.sh # Run unit tests
847+
│ ├── tests_solutions/ # Solution validation tests
848+
│ ├── run_tests.bat/.sh # Run runner unit tests
849+
│ ├── run_all_tests.bat/.sh # Run all unit tests
850+
│ ├── run_tests_solutions.bat/.sh # Run solution tests
839851
│ ├── TESTING.md # Testing documentation
852+
│ ├── VIRTUAL_ENV_SETUP.md # Virtual environment guide
840853
│ └── README.md # Maintainer guide
841854
│
842855
├── .github/ # 🚀 GitHub configuration

‎README_zh-TW.md‎

Lines changed: 157 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,7 @@ run_tests.bat 0001_two_sum
253253

254254
| 功能 | 說明 |
255255
|:-----|:-----|
256+
| 🤖 **AI 本體論分析** | AI 驅動的知識圖譜合成 — 發現人類遺漏的模式關聯 |
256257
| 🧪 **自動化測試** | 自動執行多筆測資，清晰的通過/失敗報告與計時 |
257258
| 🎲 **隨機測資生成** | 帶 Seed 確保可重現，支援 1000+ 筆壓力測試，自動儲存失敗測資 |
258259
| ⚖️ **自訂 Judge 函式** | 驗證多個正確答案，ICPC 風格驗證，可不需要預期輸出 |
@@ -303,6 +304,96 @@ run_tests.bat 0001_two_sum
303304

304305
---
305306

307+
## 🤖 AI 心智圖生成
308+
309+
> **「軟體架構師的系統思維、演算法教授的教學智慧、資深工程師的實戰經驗，以及競程冠軍的模式識別能力 — 透過 AI 統一合成。」**
310+
311+
### 願景
312+
313+
傳統演算法學習資源孤立呈現知識。我們的 **AI 本體論分析器** 採用根本不同的方法：
314+
315+
| 傳統方法 | 我們的 AI 方法 |
316+
|:---------|:---------------|
317+
| 靜態題目清單 | 動態知識圖譜合成 |
318+
| 手動分類 | AI 發現模式關聯 |
319+
| 單一視角 | 多視角專家合成 |
320+
| 背誦解法 | 理解互聯關係 |
321+
322+
### 運作原理
323+
324+
```
325+
┌─────────────────────────────────────────────────────────────────┐
326+
│ 知識圖譜輸入 │
327+
├─────────────────────────────────────────────────────────────────┤
328+
│ ontology/ │ meta/problems/ │ docs/patterns/ │
329+
│ ├── api_kernels │ ├── 0001_*.toml │ ├── sliding_window │
330+
│ ├── patterns │ ├── 0003_*.toml │ └── ... │
331+
│ ├── algorithms │ └── ... │ │
332+
│ └── ... │ │ │
333+
└─────────────────────┴─────────────────────┴─────────────────────┘
334+
│
335+
▼
336+
┌─────────────────────────────────────────────────────────────────┐
337+
│ AI 合成引擎 │
338+
├─────────────────────────────────────────────────────────────────┤
339+
│ 🏗️ 軟體架構師 → 系統級模式組織 │
340+
│ 📚 演算法教授 → 教學結構與進程 │
341+
│ ⚙️ 資深工程師 → 實用性與權衡分析 │
342+
│ 🏆 競程冠軍 → 模式識別捷徑 │
343+
│ 🎨 API 設計師 → 清晰的知識介面 │
344+
└─────────────────────────────────────────────────────────────────┘
345+
│
346+
▼
347+
┌─────────────────────────────────────────────────────────────────┐
348+
│ 智能輸出 │
349+
├─────────────────────────────────────────────────────────────────┤
350+
│ ✅ 智能連結：GitHub 解答（如有）→ LeetCode 後備 │
351+
│ ✅ 多語言：EN / 繁體中文 / 简体中文 │
352+
│ ✅ Markmap 格式：互動式、可摺疊、美觀 │
353+
│ ✅ 自訂目標：面試準備 / 系統學習 / 複習 │
354+
└─────────────────────────────────────────────────────────────────┘
355+
```
356+
357+
### 快速開始
358+
359+
```bash
360+
# 互動模式（推薦）
361+
python tools/generate_mindmaps_ai.py
362+
363+
# 指定目標
364+
python tools/generate_mindmaps_ai.py --goal interview # 面試準備
365+
python tools/generate_mindmaps_ai.py --goal systematic # 學習路線圖
366+
python tools/generate_mindmaps_ai.py --goal pattern_mastery # 深度模式分析
367+
368+
# 聚焦特定主題
369+
python tools/generate_mindmaps_ai.py --topic sliding_window
370+
python tools/generate_mindmaps_ai.py --topic dynamic_programming
371+
372+
# 多語言
373+
# 在 tools/mindmap_ai_config.toml 中配置：
374+
# language = ["en", "zh-TW"]
375+
```
376+
377+
### 配置
378+
379+
編輯 `tools/mindmap_ai_config.toml` 進行自訂：
380+
381+
| 區段 | 可配置內容 |
382+
|:-----|:-----------|
383+
| `[model]` | LLM 模型、temperature、max tokens |
384+
| `[output]` | 目錄、檔名、HTML 生成 |
385+
| `[ontology]` | 包含哪些知識圖譜資料 |
386+
| `[problems]` | 問題篩選（難度、主題、路線圖） |
387+
| `[generation]` | 目標、風格、自訂指令 |
388+
| `[links]` | GitHub repo URL、分支、連結格式 |
389+
| `[advanced]` | 輸出語言、複雜度包含 |
390+
391+
### 沒有 API Key？沒問題
392+
393+
生成器會將完整提示詞儲存到 `tools/prompts/generated/mindmap_prompt.md`。複製並貼到 ChatGPT、Claude 或任何 LLM 網頁介面。
394+
395+
---
396+
306397
## 📐 模式文件
307398

308399
> **「不要死背 200 道題。掌握 10 個模式。」**
@@ -374,6 +465,16 @@ python runner/test_runner.py <problem_name> --estimate
374465
```python
375466
# solutions/0001_two_sum.py
376467
from typing import List
468+
from _runner import get_solver
469+
470+
SOLUTIONS = {
471+
"default": {
472+
"class": "Solution",
473+
"method": "twoSum",
474+
"complexity": "O(n) time, O(n) space",
475+
"description": "Single pass with hash map",
476+
},
477+
}
377478

378479
class Solution:
379480
def twoSum(self, nums: List[int], target: int) -> List[int]:
@@ -393,14 +494,17 @@ def solve():
393494
nums = list(map(int, lines[0].split(',')))
394495
target = int(lines[1])
395496

396-
# 執行解答
397-
result = Solution().twoSum(nums, target)
497+
# 執行解答（多型派發）
498+
solver = get_solver(SOLUTIONS)
499+
result = solver.twoSum(nums, target)
398500
print(result)
399501

400502
if __name__ == "__main__":
401503
solve()
402504
```
403505

506+
> 📖 完整規格請參見 [`docs/SOLUTION_CONTRACT.md`](docs/SOLUTION_CONTRACT.md)。
507+
404508
### 📋 測資檔案格式
405509

406510
| 規格 | 要求 |
@@ -502,6 +606,8 @@ greedy 44.82ms O(kN) 3/3
502606

503607
使用模板建立：`new_problem.bat 0023_merge_k_lists --multi`
504608

609+
> 📖 完整 SOLUTIONS schema 和驗證規則請參見 [`docs/SOLUTION_CONTRACT.md` §B](docs/SOLUTION_CONTRACT.md#b-solutions-metadata-schema)。
610+
505611
### 🔀 彈性輸出驗證
506612

507613
適用於有多個正確答案的題目（「可以任意順序回傳」）：
@@ -543,6 +649,8 @@ JUDGE_FUNC = judge
543649
COMPARE_MODE = "sorted" # 選項："exact" | "sorted" | "set"
544650
```
545651

652+
> 📖 完整 JUDGE_FUNC 簽章和驗證規則請參見 [`docs/SOLUTION_CONTRACT.md` §C](docs/SOLUTION_CONTRACT.md#c-judge--validation-contract)。
653+
546654
### 🎲 隨機測資生成
547655

548656
建立與解答同名的生成器檔案：
@@ -586,6 +694,8 @@ python runner/test_runner.py 0004_median --generate 10 --seed 42
586694
python runner/test_runner.py 0004_median --generate 10 --save-failed
587695
```
588696

697+
> 📖 完整生成器規格和最佳實踐請參見 [`docs/GENERATOR_CONTRACT.md`](docs/GENERATOR_CONTRACT.md)。
698+
589699
### 📈 時間複雜度估算
590700

591701
新增複雜度生成器函式：
@@ -650,8 +760,9 @@ neetcode/
650760
│ └── util.py # Re-exports（向後兼容）
651761
│
652762
├── templates/ # 📄 題目模板
653-
│ ├── template_solution.py # 單一解法
654-
│ └── template_solution_multi.py # 多解法（多型模式）
763+
│ ├── template_solution.py # 單一解法模板
764+
│ ├── template_solution_multi.py # 多解法（多型模式）
765+
│ └── template_test.txt # 測資模板
655766
│
656767
├── .vscode/ # 🔧 VS Code 整合
657768
│ ├── settings.json # Python 環境設定
@@ -667,10 +778,22 @@ neetcode/
667778
│ └── stylesheets/ # 自訂 CSS
668779
│
669780
├── tools/ # 🛠️ 工具腳本
670-
│ ├── generate_mindmaps.py # 生成心智圖
671-
│ ├── generate_mindmaps.toml # 心智圖配置
672-
│ ├── generate_pattern_docs.py # 生成模式文件
673-
│ └── text_to_mindmap.py # LLM 文字轉心智圖
781+
│ ├── generate_mindmaps_ai.py # 🤖 AI 心智圖生成器
782+
│ ├── mindmap_ai_config.toml # AI 生成配置
783+
│ ├── generate_mindmaps.py # 規則式心智圖生成器
784+
│ ├── generate_mindmaps.toml # 規則式配置
785+
│ ├── generate_pattern_docs.py # 生成模式文件
786+
│ ├── generate_pattern_docs.toml # 模式文件配置
787+
│ ├── check_solutions.py # 解答驗證工具
788+
│ ├── prepare_llm_input.py # 準備 LLM 輸入資料
789+
│ ├── text_to_mindmap.py # 文字轉心智圖
790+
│ ├── mindmaps/ # 心智圖生成器模組
791+
│ ├── patterndocs/ # 模式文件生成器模組
792+
│ ├── shared/ # 共用工具
793+
│ ├── prompts/ # AI 提示詞管理
794+
│ │ ├── README.md # 提示詞文件
795+
│ │ └── generated/ # 自動生成的提示詞
796+
│ └── tests/ # 格式驗證測試
674797
│
675798
├── ontology/ # 🧬 演算法本體論（TOML）
676799
│ ├── api_kernels.toml # API 核心定義
@@ -696,8 +819,12 @@ neetcode/
696819
│
697820
├── .dev/ # 🧪 維護者專區（單元測試）
698821
│ ├── tests/ # 單元測試套件（150+ 案例）
699-
│ ├── run_tests.bat/.sh # 執行單元測試
822+
│ ├── tests_solutions/ # 解答驗證測試
823+
│ ├── run_tests.bat/.sh # 執行 runner 單元測試
824+
│ ├── run_all_tests.bat/.sh # 執行所有單元測試
825+
│ ├── run_tests_solutions.bat/.sh # 執行解答測試
700826
│ ├── TESTING.md # 測試文件
827+
│ ├── VIRTUAL_ENV_SETUP.md # 虛擬環境設定指南
701828
│ └── README.md # 維護者指南
702829
│
703830
├── .github/ # 🚀 GitHub 配置
@@ -802,6 +929,24 @@ python -m pytest .dev/tests --cov=runner --cov-report=html
802929

803930
### 本地生成心智圖
804931

932+
**AI 驅動（推薦）：**
933+
934+
```bash
935+
# 互動模式
936+
python tools/generate_mindmaps_ai.py
937+
938+
# 指定目標
939+
python tools/generate_mindmaps_ai.py --goal interview
940+
941+
# 生成多語言
942+
# 編輯 tools/mindmap_ai_config.toml: language = ["en", "zh-TW"]
943+
python tools/generate_mindmaps_ai.py
944+
```
945+
946+
配置檔：`tools/mindmap_ai_config.toml`
947+
948+
**規則式：**
949+
805950
```bash
806951
# 生成 Markdown 心智圖
807952
python tools/generate_mindmaps.py
@@ -816,6 +961,9 @@ python tools/generate_mindmaps.py --html
816961

817962
- [`.dev/README.md`](https://github.com/lufftw/neetcode/blob/main/.dev/README.md) — 維護者指南
818963
- [`.dev/TESTING.md`](https://github.com/lufftw/neetcode/blob/main/.dev/TESTING.md) — 測試文件
964+
- [`docs/SOLUTION_CONTRACT.md`](docs/SOLUTION_CONTRACT.md) — 解答檔案規格（SOLUTIONS dict, JUDGE_FUNC）
965+
- [`docs/GENERATOR_CONTRACT.md`](docs/GENERATOR_CONTRACT.md) — 生成器檔案規格（generate(), edge cases, complexity）
966+
- [`docs/ARCHITECTURE_MIGRATION.md`](docs/ARCHITECTURE_MIGRATION.md) — 多型架構遷移指南
819967
- [`docs/GITHUB_PAGES_SETUP.md`](docs/GITHUB_PAGES_SETUP.md) — 部署指南
820968

821969
---

0 commit comments

Comments
 (0)