| name | concept-discover |
| description | 研究程式語言的函式庫、標準標頭檔或語言特性。從文件和網路資源中探索函式簽名、 常見用法模式，按 Topic 層級樹分類，並依 Semorphe 慣例提出概念命名。 用於新增任何語言的函式庫、標頭檔或語言特性支援時。
|
| user-invocable | true |
語言指示：所有輸出文件（報告、摘要、註解）必須使用當前對話的語言撰寫。下方模板僅為結構參考，實際用語應配合使用者的語言設定。
⛔ 調用要求
此 skill 必須透過 Skill tool 調用，不可手動替代。當由 /concept.pipeline 編排時，pipeline 會使用 Skill tool 調用此 skill。
完成時必須輸出完成標記（見最後一節）。
概念探索
使用者輸入
$ARGUMENTS
你必須先考慮使用者輸入再繼續。參數格式為 [語言] <目標>，例如：
cpp <algorithm> — 研究 C++ 的 <algorithm> 標頭檔python list comprehension — 研究 Python 的 list comprehensionjava Stream API — 研究 Java 的 Stream API<string> — 未指定語言時，根據語法推斷（此例為 C++）
背景
你正在研究某個程式語言的函式庫或語言特性，準備將其整合進 Semorphe — 一個以語義樹驅動的程式教育工具。你的任務是探索有哪些概念存在、它們通常如何被使用，以及如何為學習者分類。
關鍵：開始前請先閱讀專案的第一性原理：
docs/first-principles.md — 特別是 P2（概念代數）和 P4（漸進式揭露）src/core/types.ts — 現有的 UniversalConcept 和 LanguageSpecificConcept 型別
然後確認目標語言的現有支援：
src/languages/ — 查看已有哪些語言模組src/languages/{lang}/ — 該語言的現有概念、積木、提升器、產生器
工作流程
階段零：Feature Branch（獨立使用時）
如果不是由 /concept.pipeline 調用，且目前不在概念 feature branch 上：
- 偵測當前分支：檢查是否已在
{NNN}-{lang}-{topic} 格式的 feature branch 上
- 如果不在：詢問使用者是否要建立 feature branch
- 如果要建立：
- 掃描所有本地分支和
specs/ 目錄，找到最大編號 N，使用 N+1
- 命名規則：
{NNN}-{lang}-{short_name}（如 024-cpp-string-ops）
short_name 從使用者輸入推導（標頭檔名、特性名、概念群組名）- 執行
git checkout -b {NNN}-{lang}-{short_name}
- 如果不要：在當前分支上繼續（使用者自行管理 branch）
階段一：研究
-
網路搜尋 目標函式庫/特性：
- 搜尋官方文件（如 cppreference、Python docs、MDN、Java docs）
- 搜尋常見用法模式和教學
- 搜尋「most commonly used functions in [library]」
- 搜尋「beginner vs advanced [library] features」
-
取得文件：
- 取得每個相關函式/特性的官方文件頁面
- 提取函式簽名、參數型別、回傳型別
- 記錄在教育中最常使用的函式
階段二：概念萃取
對每個發現的函式/特性，萃取以下資訊：
| 欄位 | 說明 |
|---|
| 語法 | 實際的語法（例如 C++ sort(v.begin(), v.end())、Python sorted(lst)） |
| 語義意義 | 它在概念上做了什麼（例如「排序一個範圍」） |
| 參數 | 學習者需要提供什麼 |
| 常見模式 | 在真實程式碼中通常如何使用 |
| 先備知識 | 學習者必須已經知道的概念 |
| 錯誤模式 | 初學者常犯的錯誤 |
四路完備性 gate：每個概念必須滿足四路完備性（lift → render → extract → generate），缺一 = 覆蓋缺口（§2.2）。Extract 路徑由 PatternExtractor 自動從 blockDef args + concept children 推導（auto-derive），無需手寫 extractor——只需確保 blockDef 和 concept 定義正確即可。若概念有動態結構（repeat inputs、multi-mode slots 等），renderMapping 須包含 dynamicRules。當系統提供語義直譯器時，還需要第五層——execute path（concept → Behavior）：可執行概念需 interpreter executor，宣告性概念需 noop executor（見 docs/technical-experiences.md §20）。
階段三：Topic 層級樹分類
概念透過 Topic JSON 檔案（例如 src/languages/{lang}/topics/{lang}-beginner.json）中的 levelTree 組織為樹狀結構。每個 LevelNode 有 id、label、level（深度）、concepts[]、children[]。
倍增軟指引：每往下一層，新增積木數約為上一層兩倍（L08, L116, L2~32）（§2.4）。
表面形態：注意 Surface Form（F0/F1/F2）與概念層級正交——控制同一概念展示多少結構（§2.4）。
為每個概念決定它應歸屬於哪個 Topic 的哪個層級樹節點：
根節點（基礎） — 最少的先備知識：
- 不需理解型別、記憶體或進階控制流程即可解釋
- 用於第一週的程式練習
- 認知負載：積木上 1-2 個輸入
第一層分支（中級） — 需要基本程式理解：
- 需要理解函式、回傳值或基本資料結構
- 用於典型的作業
- 認知負載：積木上 2-4 個輸入
第二層以上分支（進階） — 需要更深入的理解：
- 涉及泛型、迭代器、指標、閉包或複雜型別系統
- 用於競賽或進階課程
- 認知負載：4+ 個輸入或需要理解隱藏概念
參考現有 Topic 檔案了解該語言已有的層級樹結構，將新概念加入適當的節點。
階段四：命名
按照 Semorphe 慣例提出概念名稱：
- 通用概念（跨語言共通）：
snake_case（例如 sort_range、find_element）
- 語言特定概念：
{lang}:snake_case（例如 cpp:vector_push、py:list_append、java:stream_map）
- 語言前綴使用 ConceptId 的
lang:concept 格式
- 名稱應描述語義動作，而非語法
- 偏好簡短、描述性名稱（最多 2-3 個詞）
檢查 src/core/types.ts 中現有名稱以避免衝突。
概念分層目錄對應：概念所屬層級決定檔案存放位置：
- universal（跨語言共通）→
src/blocks/semantics/
- lang-core（語言核心語法）→
src/languages/{lang}/core/（blocks.json、concepts.json）
- lang-library（語言標準庫）→
src/languages/{lang}/std/{module}/（blocks.json、concepts.json）
階段五：輸出
產生結構化報告，放在 specs/concepts/ 目錄下，如 specs/concepts/{lang}-{topic}.md：
# 概念探索：{Language} — {Topic}
## 摘要
- 語言：{language}
- 目標：{library/feature}
- 發現概念總數：N
- 通用概念：N、語言特定概念：N
- 建議歸屬的 Topic 層級樹節點：{各節點概念數}
## 概念目錄
按 Topic 層級樹節點分組：
### {根節點 label} — 基礎
| 概念名稱 | 語法 | 語義意義 | 積木輸入 | Layer | 通用/特定 | 降級路徑 | 備註 |
|---|---|---|---|---|---|---|---|
### {第一層分支 label} — 中級
| 概念名稱 | 語法 | 語義意義 | 積木輸入 | Layer | 通用/特定 | 降級路徑 | 備註 |
|---|---|---|---|---|---|---|---|
### {第二層以上分支 label} — 進階
| 概念名稱 | 語法 | 語義意義 | 積木輸入 | Layer | 通用/特定 | 降級路徑 | 備註 |
|---|---|---|---|---|---|---|---|
**降級路徑說明**：每個概念須指明降級路徑（§2.2）：
- D1（專屬積木）→ D2（通用概念 fallback）→ D3（raw_code）→ D4（不支援）
- 降級路徑欄填寫 D2 fallback 概念名稱（例如 `func_call`），無則填 `raw_code`
## 依賴關係圖
{哪些概念依賴哪些}
## 建議實作順序
{按依賴關係 + Topic 層級樹深度排序}
## 跨語言對應
{與已支援語言中現有概念的對應關係}
## 需注意的邊界案例
{棘手語法、模糊語義、常見陷阱}
同時檢查現有概念以識別：
- 與已支援概念的重疊（特別是通用概念）
- 可以泛化的概念（將語言特定升級為通用）
- 目前概念覆蓋的缺口
準則
- 以教育價值為優先 — 不是所有語言特性都需要積木
- 最小化認知負載 — 如果一個概念需要 6 個輸入，考慮拆分
- 以語義動作思考 — 語義上是「排序這個容器」，而非「用兩個迭代器參數呼叫 sort」
- 考慮積木 UX — 學習者不讀文件就能理解這個積木嗎？
- 優先考慮通用概念 — 如果概念在多個語言中存在（如 for 迴圈、排序），盡量定義為通用概念
- 一個積木 = 一個語義概念（Sc3 認知一致性）— 不要把兩個不同的語法結構合成一個積木，也不要把一個語法結構拆成兩個積木
- 積木不可引入程式碼中不存在的概念（§1.4 Sc2）— 積木只能表達原始碼中實際存在的結構
- 區分 concept layer — 每個概念必須標明層級：universal（跨語言共通）、lang-core（語言核心語法）、lang-library（語言標準庫）
完成標記（強制）
此 skill 完成後，必須輸出以下格式的完成標記：
🏁 SKILL_COMPLETE: concept-discover | {lang} | {target} | 發現 {N} 個概念 | 報告：{report_path}
如果未輸出此標記，pipeline 不會繼續下一階段。
