concept-discover

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 comprehension
• java 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 上：

1. 偵測當前分支：檢查是否已在 {NNN}-{lang}-{topic} 格式的 feature branch 上
2. 如果不在：詢問使用者是否要建立 feature branch
3. 如果要建立：
   • 掃描所有本地分支和 specs/ 目錄，找到最大編號 N，使用 N+1
   • 命名規則：{NNN}-{lang}-{short_name}（如 024-cpp-string-ops）
   • short_name 從使用者輸入推導（標頭檔名、特性名、概念群組名）
   • 執行 git checkout -b {NNN}-{lang}-{short_name}
4. 如果不要：在當前分支上繼續（使用者自行管理 branch）

階段一：研究

1. 網路搜尋 目標函式庫/特性：

   • 搜尋官方文件（如 cppreference、Python docs、MDN、Java docs）
   • 搜尋常見用法模式和教學
   • 搜尋「most commonly used functions in [library]」
   • 搜尋「beginner vs advanced [library] features」

2. 取得文件：

   • 取得每個相關函式/特性的官方文件頁面
   • 提取函式簽名、參數型別、回傳型別
   • 記錄在教育中最常使用的函式

階段二：概念萃取

對每個發現的函式/特性，萃取以下資訊：

欄位	說明
語法	實際的語法（例如 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 不會繼續下一階段。