---
date: 2025-10-22T17:34:52+08:00
researcher: Claude (Sonnet 4.5)
git_commit: 2555260
branch: main
repository: fwauto
topic: "Makefile 管理系統設計研究"
tags:
  [
    research,
    codebase,
    makefile,
    template,
    architecture,
    extensibility,
    init,
    user-config,
  ]
status: complete
last_updated: 2025-10-23
last_updated_by: Claude (Sonnet 4.5)
last_updated_note: "更新 Init 流程機制的執行流程圖，加入雙層 Config 架構和兩條平行路徑設計"
---

# Research: Makefile 管理系統設計研究

**Date**: 2025-10-22T17:34:52+08:00
**Researcher**: Claude (Sonnet 4.5)
**Git Commit**: 2555260
**Branch**: main
**Repository**: fwauto

---

## Research Question

> **如何設計一套 makefile 管理機制，能夠同時支援「已知 SDK/開發板的組織」和「未知 SDK/開發板的使用者定製」？**

基於問題定義文件 `.ai/prpi/problems/2025-10-22-makefile-management-system.md` 的核心需求：

1. Template 識別與選擇機制
2. 使用者定製能力
3. 管理結構的可擴展性

---

## Summary

本研究透過分析 FWAuto 現有的 template 結構、init 流程、config schema 和 workflow 整合，並參考外部系統（CMake Presets、Cargo Features、Docker Multi-Stage Builds）的設計，發現以下關鍵洞察：

### 核心發現

1. **目前結構極簡且功能完整**
   - Templates 採用「build/flash」兩層分離
   - 所有配置透過 `config.toml` + 預設值機制管理
   - Makefile 作為 wrapper 呼叫 PowerShell scripts

2. **缺少的識別機制**
   - 無 template metadata（名稱、描述、適用範圍）
   - 無自動選擇機制（手動複製 `.minimal` template）
   - Config schema 未包含 SDK/板子識別欄位
   - ❌ **無 User Scope (全域) Config**：目前只有 Project Scope

3. **擴展的方向**
   - 可借鑒 CMake Presets 的 metadata + 繼承設計
   - 可參考 Cargo Features 的功能開關機制
   - 需要建立 template registry 支援多板子選擇
   - ✅ **建立雙層 Config 架構**：User Scope (`~/.fwauto/config.toml`) + Project Scope (`.fwauto/config.toml`)

### 技術可行性

| 面向                | 可行性     | 說明                               |
| ------------------- | ---------- | ---------------------------------- |
| **資料夾結構擴展**  | ⭐⭐⭐⭐⭐ | 可直接在 `templates/` 下建立子目錄 |
| **Metadata Schema** | ⭐⭐⭐⭐⭐ | 可使用 JSON/TOML + Pydantic 驗證   |
| **Init 流程整合**   | ⭐⭐⭐⭐   | 需改寫 `init.py` 加入選單邏輯      |
| **Config 擴展**     | ⭐⭐⭐⭐⭐ | `ProjectConfig` 設計支援新增欄位   |
| **向後相容**        | ⭐⭐⭐⭐   | 可透過預設值維持現有專案運作       |

---

## Detailed Findings

### 1. 現有 Templates 結構

#### 目錄組織

```mermaid
graph TD
    A["templates/"] --> B["build/"]
    A --> C["flash/"]

    B --> D["Makefile.minimal"]
    B --> E["build.ps1"]

    C --> F["Makefile.minimal"]
    C --> G["flash.ps1"]

    style A fill:#FFE4B5
    style B fill:#90EE90
    style C fill:#87CEEB
```

**發現**：

- ✅ Build 和 Flash 完全分離，職責清晰
- ✅ Makefile 作為統一入口，script 處理實際邏輯
- ❌ 只有 `.minimal` 一個版本，無其他變體
- ❌ 無 metadata 描述檔案

#### Template 內容分析

| 檔案                     | 用途             | 關鍵參數                                 |
| ------------------------ | ---------------- | ---------------------------------------- |
| `build/Makefile.minimal` | Build wrapper    | `PROJECT_ROOT`, `KEIL_UV4`               |
| `build/build.ps1`        | Keil 編譯邏輯    | 自動搜尋 `.uvprojx`                      |
| `flash/Makefile.minimal` | Flash wrapper    | `PROJECT_ROOT`, `HEX_FILE`, `STLINK_CLI` |
| `flash/flash.ps1`        | ST-LINK 燒錄邏輯 | 驗證檔案存在 + 執行燒錄                  |

**參考**：

- [`templates/build/Makefile.minimal`](src/fwauto/templates/build/Makefile.minimal)
- [`templates/build/build.ps1`](src/fwauto/templates/build/build.ps1:16-94)
- [`templates/flash/Makefile.minimal`](src/fwauto/templates/flash/Makefile.minimal)
- [`templates/flash/flash.ps1`](src/fwauto/templates/flash/flash.ps1:17-60)

---

### 2. Init 流程機制

#### 執行流程圖

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant InitWizard as run_init_wizard
    participant UserConfig as UserConfig<br/>(~/.fwauto/config.toml)
    participant TemplateManager as TemplateManager
    participant ProjectConfig as ProjectConfig<br/>(.fwauto/config.toml)

    User->>CLI: fwauto init
    CLI->>InitWizard: 執行初始化

    Note over InitWizard: Project Scope 覆寫檢查
    InitWizard->>InitWizard: .fwauto/ 已存在？
    alt 已存在 且 無 --overwrite
        InitWizard-->>User: ⚠️ 已初始化
        InitWizard-->>CLI: return False
    end

    Note over InitWizard,UserConfig: ⭐ 步驟 1: 列出已存在的 SDK

    InitWizard->>UserConfig: 載入 ~/.fwauto/config.toml
    UserConfig-->>InitWizard: configured_sdks (可能為空)

    Note over InitWizard: 建立選項列表

    alt configured_sdks 非空
        InitWizard->>User: 已配置的 SDK:<br/>  1. am62x (/path) - 裝置: am62x/ATK-DLAM62xB<br/>  2. stm32f4 (C:\Keil_v5\ARM) - 裝置: stm32f4/STM32F407VGT6<br/>  3. 新增 SDK<br/><br/>請選擇:
    else configured_sdks 為空
        InitWizard->>User: 1. 新增 SDK<br/><br/>請選擇:
    end

    User-->>InitWizard: 選擇編號

    Note over InitWizard: ⭐ 步驟 2: 根據選擇決定流程

    alt 選擇已存在的 SDK
        rect rgb(200, 255, 200)
            Note over InitWizard,UserConfig: ✅ 使用現有 SDK 流程

            InitWizard->>UserConfig: get_sdk_config(sdk_type)
            UserConfig-->>InitWizard: {path, version}

            InitWizard->>UserConfig: get_device_config(sdk_type)
            UserConfig-->>InitWizard: {family, model}

            Note over InitWizard: 零輸入完成
        end

    else 選擇「新增 SDK」
        rect rgb(255, 230, 200)
            Note over InitWizard,TemplateManager: 🆕 建立新 SDK 流程

            InitWizard->>TemplateManager: list_available_templates()
            TemplateManager-->>InitWizard: all_templates

            InitWizard->>User: 可用的 SDK Templates:<br/>  1. STM32F4 (Keil ARM SDK)<br/>  2. AM62x (ATK SDK)<br/><br/>請選擇:
            User-->>InitWizard: 選擇編號

            InitWizard->>User: 請輸入 SDK 路徑、版本
            User-->>InitWizard: 輸入資訊

            InitWizard->>UserConfig: set_sdk_config()
            Note over UserConfig: ✅ 儲存到<br/>~/.fwauto/config.toml

            InitWizard->>User: 請輸入裝置系列、型號
            User-->>InitWizard: 輸入資訊

            InitWizard->>UserConfig: set_device_config()
            Note over UserConfig: ✅ 儲存裝置資訊
        end
    end

    Note over InitWizard,ProjectConfig: ⭐ 最終階段: 建立 Project Scope

    InitWizard->>TemplateManager: copy_template_to_project(sdk_type)
    TemplateManager->>ProjectConfig: 建立 .fwauto/ 目錄<br/>build/ flash/ logs/
    TemplateManager->>ProjectConfig: 複製 template 檔案

    InitWizard->>ProjectConfig: 生成 config.toml<br/>(包含 SDK + 裝置資訊)

    InitWizard-->>User: ✅ 初始化完成！
```

**關鍵設計原則**：

- User Scope Config 是流程決策點（存在 vs 不存在）
- 所有 SDK templates 都是可用的（無需分類「已配置」vs「未配置」）
- 「新增 SDK」選項總是存在
- Project Scope Config 總是被建立（從 User Config 繼承）

**關鍵程式碼位置**：

- [`cli_commands/init.py:52-130`](src/fwauto/cli_commands/init.py:52-130) - 主流程
- [`cli_commands/init.py:24-49`](src/fwauto/cli_commands/init.py:24-49) - Template 複製邏輯

---

### 3. Config Schema 設計

#### 雙層 Config 架構

**User Scope Config** (`~/.fwauto/config.toml`)：

儲存開發環境共用的 SDK 和裝置資訊。

```toml
# ~/.fwauto/config.toml - User Scope (全域設定)
# 注意：SDK 是指 Firmware BSP (Board Support Package)，不是 compiler/toolchain

[sdk.stm32f4]
type = "stm32f4"
path = "C:\\Keil_v5\\ARM"
version = "5.0"

[sdk.am62x]
type = "am62x"
path = "/home/alientek/ATK-AM62x-SDK"
version = "1.0.0"

[device.stm32f4]
family = "stm32f4"
model = "STM32F407VGT6"

[device.am62x]
family = "am62x"
model = "ATK-DLAM62xB"
```

**Project Scope Config** (`.fwauto/config.toml`)：

從 User Config 繼承 SDK 和裝置資訊，加入專案特定配置。

```toml
# .fwauto/config.toml - Project Scope

[sdk]
type = "am62x"

[device]
family = "am62x"
model = "ATK-DLAM62xB"

[build]
makefile = ".fwauto/build/Makefile"
target = "build"

[flash]
makefile = ".fwauto/flash/Makefile"
target = "flash"
```

**運作方式**：

1. Init 時列出 User Config 中已配置的 SDK
2. 使用者選擇現有 SDK 或新增 SDK
3. SDK 和裝置資訊儲存到 User Config
4. Project Config 從 User Config 繼承資訊

**SDK 的雙重用途**：

- **Template 識別**：根據 SDK identifier (例如 `stm32f4`, `am62x`) 選擇對應的 build files
- **AI Source Analysis**：提供 SDK BSP 路徑讓 AI 分析 HAL/Driver 程式碼

**真實環境範例**：

- **STM32F4**: Keil 安裝時內建的 STM32 SDK，位於 `C:\Keil_v5\ARM`
- **AM62x**: ATK 廠商提供的 Ubuntu 22.04 VM，SDK 位於 `/home/alientek/ATK-AM62x-SDK`

#### ProjectConfig 類別結構

```mermaid
classDiagram
    class ProjectConfig {
        +Path config_path
        +dict data
        +_load() dict
        +_validate() None
        +build_makefile: str
        +build_target: str
        +flash_makefile: str
        +flash_target: str
    }

    class ConfigError {
        <<exception>>
    }

    ProjectConfig ..> ConfigError: raises
```

**特性**：

- ✅ 預設值機制完善（所有欄位可選）
- ✅ 讀取邏輯清晰（TOML → dict → 屬性）
- ✅ 支援 SDK 識別欄位（`sdk.type` 用於 template 選擇和 AI source analysis）
- ✅ 支援裝置識別欄位（`device.family`, `device.model`）
- ✅ 雙層 Config 架構（User Scope + Project Scope）

**註**：SDK 指的是 Firmware BSP (如 STM32CubeF4)，不是 compiler/toolchain

**相關類別**：

- `UserConfig` - 管理 `~/.fwauto/config.toml`
- `ProjectConfig` - 管理 `.fwauto/config.toml`

**關鍵程式碼位置**：

- [`config.py:40-82`](src/fwauto/config.py:40-82) - `ProjectConfig` 類別
- [`config.py:118-132`](src/fwauto/config.py:118-132) - `create_default_config` 函數

---

### 4. Template 與 Workflow 整合

#### LangGraph 路由機制

```mermaid
graph TD
    START["START"] -->|route_from_start| A{"execution_mode?"}

    A -->|"build"| BUILD["build_node"]
    A -->|"flash"| FLASH["flash_node"]
    A -->|"feat"| AI["ai_brain_node"]

    BUILD -->|"load config"| CONFIG1["ProjectConfig<br/>build_makefile<br/>build_target"]
    FLASH -->|"load config"| CONFIG2["ProjectConfig<br/>flash_makefile<br/>flash_target"]

    CONFIG1 --> EXEC1["execute_make_command"]
    CONFIG2 --> EXEC2["execute_make_command"]

    EXEC1 -->|"success"| END1["END"]
    EXEC1 -->|"error"| AI
    AI --> BUILD

    EXEC2 --> END2["END"]

    style BUILD fill:#90EE90
    style FLASH fill:#87CEEB
    style AI fill:#FFD700
    style CONFIG1 fill:#FFE4B5
    style CONFIG2 fill:#FFE4B5
```

**發現**：

- ✅ Template（makefile）被 `build_node` / `flash_node` 使用
- ✅ 透過 `ProjectConfig` 自動發現 makefile 路徑
- ✅ 錯誤時可觸發 AI Brain 修復循環
- ❌ **系統「知道」用哪個 makefile 靠硬編碼預設值**
- ❌ **無根據板子類型動態選擇 template 的機制**

**關鍵程式碼位置**：

- [`nodes/build.py:21-132`](src/fwauto/nodes/build.py:21-132) - Build node 實作
- [`nodes/flash.py:21-129`](src/fwauto/nodes/flash.py:21-129) - Flash node 實作
- [`utils.py:78-156`](src/fwauto/utils.py:78-156) - `execute_make_command` 函數
- [`graph.py:30-65`](src/fwauto/graph.py:30-65) - 路由函數

---

### 5. 外部系統參考

#### 5.1 CMake Presets - Metadata + 繼承設計

**核心概念**：

```json
{
  "configurePresets": [
    {
      "name": "base",
      "hidden": true,
      "cacheVariables": {...}
    },
    {
      "name": "debug",
      "inherits": "base",
      "description": "Debug build",
      "condition": {"type": "equals", "lhs": "${hostSystemName}", "rhs": "Windows"}
    }
  ]
}
```

**可借鑒的設計**：

- ✅ JSON schema 定義完整 metadata
- ✅ `hidden: true` 支援抽象基礎 template
- ✅ `inherits` 多重繼承避免重複
- ✅ `condition` 系統支援自動選擇

#### 5.2 Cargo Features - 功能開關

**核心概念**：

```toml
[features]
default = ["logging"]
logging = []
advanced = ["logging"]
```

**可借鑒的設計**：

- ✅ Feature 組合式啟用
- ✅ `default` 陣列定義預設功能
- ✅ Feature 間可相互依賴

#### 5.3 Docker Multi-Stage - Target 選擇

**核心概念**：

```dockerfile
FROM base AS development
FROM base AS production
```

```bash
docker build --target development
docker build --target production
```

**可借鑒的設計**：

- ✅ 明確的 target 命名
- ✅ CLI 直接指定 target
- ✅ Stage 可獨立也可組合

---

## Architecture Insights

### 目前架構的優勢

1. **KISS 原則完美實踐**
   - Template 最小化（只有必要檔案）
   - Config 預設值機制（無需冗長配置）
   - Init 流程直接（無複雜互動）

2. **職責分離清晰**
   - Makefile: 統一入口 + 參數傳遞
   - PowerShell Script: 平台特定邏輯
   - Config: 專案配置管理

3. **向後相容性良好**
   - 預設值確保現有專案不受影響
   - 新增欄位不破壞舊配置

### 目前架構的限制

1. **Template 識別缺失**

   ```
   問題：系統不知道「這是 STM32F407 的 template」還是「通用 template」
   影響：無法根據板子類型自動選擇
   ```

2. **使用者定製支援不足**

   ```
   問題：Init 時無法選擇或建立 template
   影響：每個新板子都需要手動修改 templates/
   ```

3. **Metadata 資訊不完整**
   ```
   問題：Config 不記錄 SDK 類型、板子型號
   影響：AI Brain 無法針對特定平台優化提示詞
   ```

### 擴展空間分析

#### 可擴展的地方

1. **Templates 目錄結構**

   ```
   templates/
   ├── boards/
   │   ├── stm32f407/
   │   │   ├── metadata.json
   │   │   ├── build/
   │   │   └── flash/
   │   └── am62x/
   │       ├── metadata.json
   │       ├── build/
   │       └── flash/
   ├── base/
   │   └── stm32-common/
   └── features/
       └── rtos/
   ```

2. **Config Schema 擴展**

   ```toml
   [project]
   name = "my-project"
   template = "stm32f407"  # 記錄使用的 template

   [device]
   family = "stm32f4"
   type = "STM32F407VG"

   [sdk]
   type = "keil"
   version = "5.35"
   path = "C:\\Keil_v5"

   [build]
   makefile = ".fwauto/build/Makefile"
   target = "build"

   [flash]
   makefile = ".fwauto/flash/Makefile"
   target = "flash"
   tool = "st-link"
   ```

3. **Init 流程擴展**

   ```python
   def run_init_wizard(project_root: Path | None = None) -> bool:
       # 1. 列出可用 templates
       templates = discover_templates()

       # 2. 使用者選擇
       selected = prompt_user_select(templates)

       # 3. 詢問客製化資訊
       customization = prompt_customization(selected)

       # 4. 複製 template
       copy_template_files(selected, project_root)

       # 5. 生成 config.toml（包含 metadata）
       create_config(project_root, selected, customization)
   ```

#### 不建議擴展的地方

1. ❌ **Makefile 內部邏輯**
   - 原因：應該保持 Makefile 最小化
   - 替代：複雜邏輯放在 script 中

2. ❌ **FirmwareState 新增過多欄位**
   - 原因：State 應保持精簡
   - 替代：使用 `mode_metadata` 字典擴展

3. ❌ **複雜的條件系統**
   - 原因：過度設計，違反 KISS
   - 替代：明確的 template 選單 + 簡單的 tag 篩選

---

## Code References

| 檔案路徑                                      | 行號    | 說明                   |
| --------------------------------------------- | ------- | ---------------------- |
| `src/fwauto/templates/build/Makefile.minimal` | -       | Build Makefile wrapper |
| `src/fwauto/templates/build/build.ps1`        | 16-94   | Keil 編譯邏輯          |
| `src/fwauto/templates/flash/Makefile.minimal` | -       | Flash Makefile wrapper |
| `src/fwauto/templates/flash/flash.ps1`        | 17-60   | ST-LINK 燒錄邏輯       |
| `src/fwauto/cli_commands/init.py`             | 52-130  | Init 主流程            |
| `src/fwauto/cli_commands/init.py`             | 24-49   | Template 複製函數      |
| `src/fwauto/config.py`                        | 40-82   | ProjectConfig 類別     |
| `src/fwauto/config.py`                        | 118-132 | 生成 config.toml       |
| `src/fwauto/nodes/build.py`                   | 21-132  | Build node             |
| `src/fwauto/nodes/flash.py`                   | 21-129  | Flash node             |
| `src/fwauto/utils.py`                         | 78-156  | execute_make_command   |
| `src/fwauto/graph.py`                         | 30-65   | route_from_start       |

---

## Technical Feasibility

### 方向 1：資料夾結構組織

**可行性**: ⭐⭐⭐⭐⭐

**說明**：

- 可直接在 `templates/` 下建立 `boards/`, `base/`, `features/` 子目錄
- 不破壞現有 `build/`, `flash/` 結構
- 向後相容：保留 `Makefile.minimal` 作為 fallback

**範例**：

```
templates/
├── build/Makefile.minimal      # 保留作為 fallback
├── flash/Makefile.minimal
└── boards/
    ├── stm32f407/
    │   ├── metadata.json
    │   ├── build/Makefile
    │   └── flash/Makefile
    └── am62x/
        ├── metadata.json
        ├── build/Makefile
        └── flash/Makefile
```

### 方向 2：Metadata Schema 設計

**可行性**: ⭐⭐⭐⭐⭐

**說明**：

- 可使用 JSON 或 TOML 格式
- Pydantic 可提供完整的驗證
- 參考 CMake Presets 的 schema 設計

**範例**：

```json
{
  "name": "stm32f407-keil",
  "display_name": "STM32F407 + Keil uVision",
  "description": "STM32F407 開發板，使用 Keil uVision 編譯器",
  "tags": ["hw-f4", "compiler-keil", "platform-windows"],
  "sdk": {
    "type": "keil",
    "min_version": "5.0"
  },
  "device": {
    "family": "stm32f4",
    "series": "STM32F407"
  },
  "files": {
    "build": ["Makefile", "build.ps1"],
    "flash": ["Makefile", "flash.ps1"]
  }
}
```

### 方向 3：Init 流程整合

**可行性**: ⭐⭐⭐⭐

**說明**：

- 需要改寫 `run_init_wizard` 函數
- 加入 template 選單邏輯（使用 Rich 的 `Prompt.ask`）
- 保留現有的「無互動模式」作為快速初始化

**潛在挑戰**：

- 如何處理「沒有合適 template」的情況
- 是否需要「空白 template」或「引導式生成」

### 方向 4：Config 擴展

**可行性**: ⭐⭐⭐⭐⭐

**說明**：

- `ProjectConfig` 設計支援新增 `@property`
- 預設值機制確保向後相容
- 可漸進式加入新欄位

**範例**：

```python
@property
def device_family(self) -> str:
    """Device family, defaults to 'generic'"""
    return self.data.get("device", {}).get("family", "generic")

@property
def sdk_type(self) -> str:
    """SDK type, defaults to 'unknown'"""
    return self.data.get("sdk", {}).get("type", "unknown")

@property
def template_source(self) -> str:
    """Template used for initialization"""
    return self.data.get("project", {}).get("template", "unknown")
```

---

## Historical Context

### 相關的設計決策

1. **為何選擇 Makefile 作為 wrapper？**
   - 參考：[`docs/makefile-design.md`](docs/makefile-design.md)
   - 原因：跨平台統一入口，支援任意 toolchain

2. **為何 config.toml 所有欄位都可選？**
   - 原因：KISS 原則，避免強迫使用者填寫冗長配置
   - 權衡：缺少驗證，但透過預設值確保系統可運作

3. **為何只有 `.minimal` 一個 template？**
   - 原因：初期只支援 STM32 + Keil，無需多版本
   - 現況：即將加入 AM62x，需要擴展機制

---

## Design Decisions (已確認)

基於與使用者的討論，以下決策已確認：

### 1. Template 識別機制的粒度 ✅

**決策**：以 **SDK** 為單位

**理由**：

- SDK (Firmware BSP) 在同一開發環境下是共用的
- 避免每次 init 都重複詢問
- 符合實際工作流程（一個環境多個專案）
- SDK 同時用於：
  - **Template 識別**：選擇對應的 build files
  - **AI Source Analysis**：提供 BSP 路徑讓 AI 分析程式碼

**範例**：`stm32f4`, `am62x`

**注意**：SDK 是指 Firmware BSP，真實範例：

- `stm32f4`: Keil 內建的 STM32 SDK (`C:\Keil_v5\ARM`)
- `am62x`: ATK 提供的 AM62x SDK (`/home/alientek/ATK-AM62x-SDK`)
- Compiler/toolchain 由 Makefile 處理，FWAuto 不需要管理

### 2. 使用者定製的程度 ✅

**決策**：**空白 template + 詳細註解**

**理由**：

- 簡單直接，符合 KISS 原則
- 使用者可自行填寫，不依賴複雜生成邏輯
- 提供清晰的註解指引

### 3. Template 更新機制 ✅

**決策**：`fwauto init --overwrite` 只覆寫 template 相關檔案

**保留**：

- ✅ `.fwauto/logs/` 目錄和內容
- ✅ 其他使用者可能自訂的內容

**覆寫**：

- ⚠️ `.fwauto/build/Makefile` 和相關 scripts
- ⚠️ `.fwauto/flash/Makefile` 和相關 scripts

### 4. Config Scope 架構 ✅

**決策**：建立雙層 Config 架構

**User Scope** (`~/.fwauto/config.toml`)：

- 儲存開發環境共用的 SDK 資訊
- 儲存 SDK 關聯的裝置設定
- 多個專案共用，避免重複詢問

**Project Scope** (`.fwauto/config.toml`)：

- 從 User Scope 複製 SDK 資訊
- 加入專案特定配置（build/flash 設定等）

**Init 流程**（2025-10-23 更新）：

1. **列出選項**：
   - 載入 `~/.fwauto/config.toml`
   - 顯示「已配置的 SDK」列表（含裝置資訊）
   - 提供「新增 SDK」選項（總是存在）

2. **兩條平行路徑**：
   - **路徑 A（使用現有）**：
     - 選擇已配置的 SDK
     - 從 User Config 讀取 SDK 和裝置資訊
     - 零輸入完成初始化

   - **路徑 B（建立新 SDK）**：
     - 選擇「新增 SDK」
     - 列出所有可用的 SDK templates
     - 輸入 SDK 路徑、版本
     - 輸入裝置系列、型號
     - 儲存到 User Config

3. **建立 Project Config**：
   - 複製對應的 template 檔案
   - 生成 `.fwauto/config.toml`（包含 SDK 和裝置資訊）

**關鍵特性**：

- 所有 SDK templates 都是可用的（無分類限制）
- 「新增 SDK」選項總是存在
- User Config 是流程決策點

### 5. Platform 欄位整合 ⏸️

**決策**：**暫不整合** (no idea)

**原因**：需要更多實際使用經驗才能決定整合方式

---

## Open Questions (待探索)

### SDK 類型自動偵測

**問題**：使用者輸入 SDK PATH 後，是否需要自動偵測 SDK 類型？

**潛在方式**：

- 檢查路徑中是否有特定檔案（例如：`UV4.exe` → Keil）
- 或直接詢問使用者選擇

### Template Metadata 格式

**已決策**：使用 TOML

**待確認細節**：

- Metadata 檔案命名（`metadata.toml` or `template.toml`）
- 必填 vs 選填欄位
- 驗證機制（Pydantic schema）

---

## Related Research

此研究為 Makefile 管理系統問題定義的延伸：

- [`.ai/prpi/problems/2025-10-22-makefile-management-system.md`](.ai/prpi/problems/2025-10-22-makefile-management-system.md)

---

## 版本資訊

- **文件版本**：1.1
- **研究方法**：並行 Task 探索 + 外部系統研究 + 實現驗證
- **研究時間**：2025-10-22
- **Git Commit**：2555260
- **Git Branch**：main
