---
date: 2025-10-14T22:04:14+08:00
researcher: Claude (via Claude Code)
git_commit: 990ffcf0619a4d96096fa3bf2850d81057861d62
branch: main
repository: fwauto
topic: "/feat Codegen 功能架構研究"
tags: [research, codebase, feat-codegen, ai-brain, langgraph, architecture]
status: complete
last_updated: 2025-10-14
last_updated_by: Claude
---

# Research: /feat Codegen 功能架構研究

**Date**: 2025-10-14T22:04:14+08:00
**Researcher**: Claude (via Claude Code)
**Git Commit**: 990ffcf0619a4d96096fa3bf2850d81057861d62
**Branch**: main
**Repository**: fwauto

---

## Research Question

為 `/feat` 功能（AI 協助新功能開發）的實作提供完整的架構分析，通過研究現有 codebase 來理解：

1. **AI Brain Node 架構** - 作為 feat_codegen node 的參考模板
2. **State 與 Graph Routing** - 如何擴展 State 和整合到現有閉環
3. **Prompt Template 系統** - Prompt 設計模式和變數傳遞
4. **CLI 整合模式** - 命令註冊和參數處理方式
5. **現有閉環機制** - build → ai_brain → build 的閉環設計

---

## Summary

### 核心發現

通過並行分析 5 個核心元件，發現 FWAuto 採用 **高度模組化的 LangGraph 架構**，為 `/feat` 功能提供了良好的擴展基礎：

**架構特點**：

1. ✅ **統一的 AI Brain Node 模式** - 使用 Template Method + Strategy Pattern，可直接複用
2. ✅ **靈活的 State 驅動路由** - 透過 `execution_mode` 和 `mode_metadata` 控制流程
3. ✅ **強大的自動修復閉環** - `iteration` + `max_retries` 機制成熟穩定
4. ✅ **Template-based Prompt 系統** - Jinja2 + Platform Config 支援多平台
5. ✅ **清晰的 CLI 整合層** - Typer + State 初始化模式一致

**技術可行性**：

- **預估工作量**: 約 4-5 天（新增 CLI 命令 + AI Brain 整合 + Prompt Template）
- **程式碼變更**: ~85 行新程式碼 + 1 個 prompt 檔案
- **風險等級**: 低（完全複用現有架構，無破壞性變更）

### 關鍵建議方向

**最小可行實作 (MVP)**:

```
fwauto feat "加入蜂鳴器功能"
  ↓
CLI 初始化 State (execution_mode="feat")
  ↓
route_from_start → ai_brain (識別為 "implement_feature")
  ↓
載入 prompts/implement_feature.md → 執行 Claude Code SDK
  ↓
route_after_ai_brain → build (自動編譯驗證)
  ↓
build 失敗 → ai_brain (fix_build_errors) → build (自動修復閉環)
  ↓
build 成功 → flash (mode_metadata.flash_after_build=True)
```

**複用現有閉環的優勢**:

- AI 生成的代碼自動接入 `build → ai_brain → build` 閉環
- 編譯錯誤自動修復（已有 regression test 驗證）
- 無需額外實作 feat_node，直接使用 ai_brain + task type 切換

---

## Detailed Findings

### 1. AI Brain Node 架構分析

#### 1.1 核心設計模式

**Template Method Pattern**:

```mermaid
flowchart TB
    A["ai_brain_node(state)"] --> B["Pre-processing<br/>(Logging)"]
    B --> C["Core Logic<br/>(async run_ai_brain)"]
    C --> D["Post-processing<br/>(State Update + Logging)"]
    D --> E["Return Updated State"]

    C --> C1["1 analyze_task_type()"]
    C1 --> C2["2 prompt_manager.get_prompt()"]
    C2 --> C3["3 get_ai_options()"]
    C3 --> C4["4 Claude Code SDK query()"]
    C4 --> C5["5 Collect responses"]
```

**關鍵發現**:

- Node 函數遵循固定的生命週期：input log → start → execute → update → output log
- 所有 AI 任務統一透過 `analyze_task_type()` 分派到不同 prompt template
- Claude Code SDK 使用 async generator pattern 實現 streaming 輸出

#### 1.2 Task Type 分派機制

**檔案**: [`src/fwauto/nodes/ai_brain.py:83-106`](src/fwauto/nodes/ai_brain.py#L83-L106)

```mermaid
flowchart TD
    Start["analyze_task_type(state)"] --> Check1{"build_errors 存在？<br/>且 build_status == 'error'"}
    Check1 -->|是| T1["fix_build_errors"]
    Check1 -->|否| Check2{"execution_mode<br/>== 'feat'?"}
    Check2 -->|是| T2["implement_feature"]
    Check2 -->|否| Check3{"execution_mode<br/>== 'fix'?"}
    Check3 -->|是| T3["fix_bug"]
    Check3 -->|否| Check4{"execution_mode<br/>== 'natural'?"}
    Check4 -->|是| T4["natural_language"]
    Check4 -->|否| T5["general_codegen"]

    T1 --> Load["載入 prompts/{task_type}.md"]
    T2 --> Load
    T3 --> Load
    T4 --> Load
    T5 --> Load
```

**優先順序**:

1. **Build errors** (最高) - 立即修復編譯錯誤
2. **Feature mode** - 實作新功能 (⚠️ 目前 prompt 缺失)
3. **Fix mode** - 修復 bug (⚠️ 目前 prompt 缺失)
4. **Natural mode** - 自然語言任務
5. **Default** - 通用程式碼生成

#### 1.3 Claude Code SDK 配置模式

**檔案**: [`src/fwauto/nodes/ai_brain.py:109-133`](src/fwauto/nodes/ai_brain.py#L109-L133)

| 配置項            | 值                                                               | 用途                     |
| ----------------- | ---------------------------------------------------------------- | ------------------------ |
| `allowed_tools`   | `["Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash"]` | 白名單控制可用工具       |
| `permission_mode` | `"bypassPermissions"`                                            | 跳過權限檢查（開發環境） |
| `add_dirs`        | `[project_root]`                                                 | 動態增加專案目錄存取     |
| `cwd`             | `project_root`                                                   | 設定工作目錄             |

**對比 log.py 的配置**:

- `allowed_tools`: 更少（只有 `["Read", "Grep"]`）
- `append_system_prompt`: log 有額外系統提示

#### 1.4 可擴展性分析

**新增 Task Type 的擴展流程**:

1. 在 `prompts/` 建立 `{new_task}.md`
2. 在 `analyze_task_type()` 新增判斷邏輯
3. 確保 State 有必要欄位

**對於 feat 功能**:

- ✅ 無需建立新 node，直接使用 ai_brain
- ✅ 只需新增 `execution_mode="feat"` 判斷
- ✅ 建立 `prompts/implement_feature.md`

---

### 2. State 與 Graph Routing 分析

#### 2.1 FirmwareState 結構

**檔案**: [`src/fwauto/state.py:6-77`](src/fwauto/state.py#L6-L77)

| 分類           | 欄位             | 用途                | feat 相關               |
| -------------- | ---------------- | ------------------- | ----------------------- |
| **專案設定**   | `user_prompt`    | 使用者輸入/命令描述 | ✅ Feature 描述         |
|                | `project_root`   | 專案根目錄          | ✅ SDK cwd 參數         |
|                | `platform`       | 平台識別碼          | ✅ Prompt 變數          |
| **Build 狀態** | `build_status`   | 編譯狀態            | ✅ 決定是否進入修復閉環 |
|                | `build_errors`   | 錯誤訊息列表        | ✅ 傳給 AI 修復         |
|                | `build_log`      | 完整編譯 log        | ✅ Prompt 變數          |
| **重試機制**   | `iteration`      | 當前重試次數        | ✅ 控制閉環退出         |
|                | `max_retries`    | 最大重試次數        | ✅ Prompt 顯示進度      |
| **CLI 控制**   | `execution_mode` | **核心路由欄位**    | ✅ **feat 的關鍵**      |
|                | `mode_metadata`  | 擴展參數            | ✅ `flash_after_build`  |

**總計**: 20 個欄位，12 個與 AI 相關，2 個控制路由

**關鍵發現**:

- `execution_mode` 決定進入哪個 node
- `mode_metadata` 調整流程細節（如是否需要初始化、是否自動 flash）
- State 採用 `TypedDict`，變更時需考慮向後相容

#### 2.2 Graph Routing 流程

**檔案**: [`src/fwauto/graph.py:15-180`](src/fwauto/graph.py#L15-L180)

```mermaid
graph TB
    START([START])
    END([END])

    init[init_project]
    ai[ai_brain]
    build[build]
    flash[flash]
    log[log]

    START -->|route_from_start| route1{檢查<br/>execution_mode}

    route1 -->|error/help/verify| END
    route1 -->|需要初始化<br/>且 require_project=true| init
    route1 -->|build/run/feat| build
    route1 -->|flash| flash
    route1 -->|log| log

    init -->|route_after_init| route2{檢查<br/>execution_mode}
    route2 -->|build/run/feat| build
    route2 -->|flash| flash
    route2 -->|log| log

    build -->|route_after_build| route3{檢查<br/>build_status}
    route3 -->|success<br/>且 flash_after_build| flash
    route3 -->|success<br/>且 build-only| END
    route3 -->|error<br/>且 iteration < max_retries| ai
    route3 -->|error<br/>且 達到 max_retries| END

    ai -->|route_after_ai_brain| build

    flash -->|route_after_flash| END
    log --> END

    style ai fill:#f9f,stroke:#333,stroke-width:4px
    style build fill:#bbf,stroke:#333,stroke-width:2px
```

**Routing 決策邏輯**:

| 函數                   | 決策因素                                                       | 可能路徑               |
| ---------------------- | -------------------------------------------------------------- | ---------------------- |
| `route_from_start`     | `execution_mode`, `mode_metadata.require_project`              | init → build/flash/log |
| `route_after_build`    | `build_status`, `iteration`, `mode_metadata.flash_after_build` | flash / ai_brain / END |
| `route_after_ai_brain` | 無條件                                                         | **總是返回 build**     |
| `route_after_flash`    | 無條件                                                         | END                    |

**閉環核心設計**:

- `build` 失敗 + `iteration < max_retries` → `ai_brain`
- `ai_brain` **總是**返回 `build` 重新驗證
- 形成 `build → ai_brain → build` 循環

#### 2.3 feat 功能的整合點

**新增 execution_mode**:

```python
# src/fwauto/state.py
execution_mode: Annotated[
    Literal["build", "flash", "run", "log", "feat", "error"] | None,  # ← 新增 "feat"
    "Workflow execution mode set by Typer CLI",
]
```

**更新 routing_map**:

```python
# src/fwauto/graph.py:53-58
routing_map = {
    "build": "build",
    "run": "build",
    "flash": "flash",
    "log": "log",
    "feat": "ai_brain",  # ← 新增：直接進入 ai_brain
}
```

**關鍵方向**:

- `feat` mode 可以直接路由到 `ai_brain`，無需建立獨立 node
- AI Brain 會透過 `analyze_task_type` 識別為 `"implement_feature"`
- 自動接入現有閉環：生成代碼 → build → (失敗) → ai_brain (fix) → build → (成功) → flash

---

### 3. Prompt Template 系統分析

#### 3.1 PromptManager 架構

**檔案**: [`src/fwauto/prompt_manager.py`](src/fwauto/prompt_manager.py)

```mermaid
flowchart LR
    A["ai_brain_node"] --> B["analyze_task_type()"]
    B -->|task_type| C["prompt_manager.get_prompt()"]
    C --> D["_build_variables(state)"]
    D --> E["System Vars<br/>(cwd, username, timestamp)"]
    D --> F["Platform Config<br/>(platform_config)"]
    D --> G["State Variables<br/>(** state)"]
    E --> H["Jinja2 Environment"]
    F --> H
    G --> H
    H --> I["載入 prompts/{task_type}.md"]
    I --> J["template.render(**variables)"]
    J --> K["渲染後的 Prompt"]
```

**核心特性**:

1. **Jinja2 Template Engine** - 支援變數插值和控制結構
2. **StrictUndefined** - 變數缺失時立即報錯，避免靜默失敗
3. **Platform-driven** - 透過 `platform_config` 動態產生約束條件
4. **檔案命名規則** - `{task_type}.md` 直接對應

#### 3.2 現有 Templates 清單

| Template 檔案          | Task Type           | 狀態        | 用途                   |
| ---------------------- | ------------------- | ----------- | ---------------------- |
| `fix_build_errors.md`  | `fix_build_errors`  | ✅ 已存在   | 自動修復編譯錯誤       |
| `log.md`               | N/A (direct)        | ✅ 已存在   | UART log 分析          |
| `implement_feature.md` | `implement_feature` | ❌ **缺少** | feat 功能的關鍵 prompt |
| `fix_bug.md`           | `fix_bug`           | ❌ 缺少     | Bug 修復               |
| `natural_language.md`  | `natural_language`  | ❌ 缺少     | 自然語言任務           |
| `general_codegen.md`   | `general_codegen`   | ❌ 缺少     | 通用程式碼生成         |

#### 3.3 Prompt 設計模式

**成功的 Template 結構** (基於 `fix_build_errors.md` 分析):

```markdown
# 1. 角色定義

你是 {{platform_config.name}} 韌體開發專家，**任務: [明確描述]**

# 2. 專案上下文

- 專案路徑: {{project_root}}
- 平台: {{platform}}
- 工作目錄: {{cwd}}

# 3. 任務資訊

[Task-specific context]

- User prompt: {{user_prompt}}
- 相關 state 變數

# 4. 約束條件 (Platform Config 驅動)

🚫 禁止: {% for dir in platform_config.forbidden_dirs %}...
✅ 允許: {% for dir in platform_config.allowed_dirs %}...

# 5. 執行步驟

1. 分析...
2. 檢查...
3. 執行...

# 6. 執行觸發 (SDK 模式)

**立即開始執行** / "Do this NOW"
```

**關鍵發現**:

- **Platform Config 動態約束** - 禁止/允許目錄由配置集中管理
- **SDK 執行模式** - 使用命令式語氣，明確指示「立即執行」
- **迭代感知** - 顯示 `{{iteration}}/{{max_retries}}` 進度
- **完整上下文** - 提供 `build_log` 等完整資訊供 AI 分析

#### 3.4 Template 變數完整清單

**所有 templates 可用的變數** = System + Platform + State:

| 分類         | 變數                    | 來源                    | 範例值                |
| ------------ | ----------------------- | ----------------------- | --------------------- |
| **System**   | `cwd`                   | `os.getcwd()`           | `/home/kent/...`      |
|              | `username`              | `os.getenv()`           | `kent`                |
|              | `os_name`               | `platform.system()`     | `Linux`               |
|              | `timestamp`             | `datetime.now()`        | `2025-10-14 22:04:14` |
| **Platform** | `platform`              | `state["platform"]`     | `stm32_keil`          |
|              | `platform_config`       | `get_platform_config()` | `PlatformConfig` dict |
| **State**    | 所有 FirmwareState 欄位 | `**state`               | 直接存取              |

**關鍵發現**:

- State 變數透過 `**state` 展開，所有欄位直接可用
- `platform_config` 包含 `name`, `forbidden_dirs`, `allowed_dirs`, `stop_conditions`
- Jinja2 StrictUndefined 確保變數安全

#### 3.5 feat 功能的 Prompt 設計方向

**建議 `implement_feature.md` 結構**:

```markdown
你是 {{platform_config.name}} 韌體開發專家，**任務：實作新功能**

## 專案環境

- 專案路徑: {{project_root}}
- 平台: {{platform}}

## 功能需求

{{user_prompt}}

## 允許修改的目錄

{% for dir in platform_config.allowed_dirs -%}

- `{{dir}}/`
  {% endfor %}

## 絕對禁止

{% for dir in platform_config.forbidden_dirs -%}

- **不可修改**: `{{dir}}/`
  {% endfor %}

## 執行步驟

1. 分析需求並理解功能目標
2. 檢查現有代碼結構
3. 設計實作方案
4. 使用 Edit/Write 工具實作功能
5. 確保符合 {{platform_config.name}} 規範

**立即開始實作功能**
```

---

### 4. CLI 整合模式分析

#### 4.1 Typer 命令註冊模式

**檔案**: [`src/fwauto/cli.py`](src/fwauto/cli.py)

```mermaid
flowchart TB
    A["@app.command()"] --> B["def command_name(args)"]
    B --> C["顯示命令訊息<br/>(console.print)"]
    C --> D["建立 FirmwareState"]
    D --> E["設定 execution_mode"]
    D --> F["設定 mode_metadata"]
    D --> G["設定 command_args"]
    E --> H["run_workflow(state)"]
    F --> H
    G --> H
    H --> I["create_firmware_graph()"]
    I --> J["workflow.stream(state)"]
    J --> K["迭代處理 events"]
    K --> L["顯示進度"]
```

**命令結構對比**:

| 命令              | 參數                   | execution_mode | mode_metadata                 | 進入點                   |
| ----------------- | ---------------------- | -------------- | ----------------------------- | ------------------------ |
| `build`           | 無                     | `"build"`      | `None`                        | build                    |
| `run`             | 無                     | `"run"`        | `{"flash_after_build": True}` | build → flash            |
| `log`             | `prompt`, `--log-path` | `"log"`        | `{"require_project": False}`  | log (skip init)          |
| **`feat`** (建議) | `prompt`               | `"feat"`       | `{"flash_after_build": True}` | ai_brain → build → flash |

#### 4.2 State 初始化模式

**所有命令的 boilerplate**:

```python
state: FirmwareState = {
    "user_prompt": "...",           # 命令特定
    "project_root": "",             # init_project_node 填入
    "project_initialized": False,
    "build_status": "pending",      # 預設值
    "build_errors": [],
    "build_log": "",
    "flash_status": "pending",
    "flash_errors": [],
    "flash_log": "",
    "iteration": 0,
    "max_retries": 3,
    "execution_mode": "...",        # 命令特定
    "command": "...",               # 命令名稱
    "command_args": {...},          # 命令參數
    "mode_metadata": {...},         # 命令 metadata
    "command_error": None,
    "log_file_path": None,
    "log_analysis_result": None,
    "firmware_path": None,
    "platform": "stm32_keil",       # 預設平台
}
```

**關鍵發現**:

- 所有命令使用統一的 State 結構（boilerplate code 較多）
- `execution_mode` 和 `mode_metadata` 是兩大控制維度
- `command_args` 透過 dict 傳遞參數給 Node（無 type safety）

#### 4.3 feat 命令的建議實作

```python
@app.command()
def feat(prompt: str = typer.Argument(..., help="Feature description")):
    """
    🚀 AI-driven feature implementation.

    Automatically implements new firmware features with AI assistance.

    Example:
        fwauto feat "加入蜂鳴器，發出 3 秒長音後 1 秒斷音"
    """
    console.print(f"[cyan]🚀 Implementing feature: {prompt}[/cyan]")

    state: FirmwareState = {
        "user_prompt": prompt,
        "project_root": "",
        "project_initialized": False,
        "build_status": "pending",
        "build_errors": [],
        "build_log": "",
        "flash_status": "pending",
        "flash_errors": [],
        "flash_log": "",
        "iteration": 0,
        "max_retries": 3,
        "execution_mode": "feat",  # ← 新 mode
        "command": "feat",
        "command_args": {"feature_prompt": prompt},
        "mode_metadata": {"flash_after_build": True},  # ← 自動驗證
        "command_error": None,
        "log_file_path": None,
        "log_analysis_result": None,
        "firmware_path": None,
        "platform": "stm32_keil",
    }

    run_workflow(state)
```

---

### 5. 現有閉環機制分析

#### 5.1 閉環完整流程

**檔案**: [`src/fwauto/graph.py:86-112`](src/fwauto/graph.py#L86-L112)

```mermaid
sequenceDiagram
    participant START
    participant build as Build Node
    participant route as route_after_build
    participant ai as AI Brain
    participant route2 as route_after_ai_brain
    participant END

    START->>build: 執行編譯

    build->>route: build_status, iteration

    alt Build 成功
        route->>END: 成功，進入 flash 或結束
    else Build 失敗 & iteration < max_retries
        route->>ai: 進入 AI 修復
        ai->>ai: analyze_task_type()<br/>("fix_build_errors")
        ai->>ai: 載入 fix_build_errors.md<br/>(build_errors, build_log)
        ai->>ai: 執行 Claude Code SDK<br/>(Edit 工具修復代碼)
        ai->>route2: AI 完成
        route2->>build: **總是返回 build** 驗證修復
        build->>route: iteration++
        Note over route: 檢查 iteration < max_retries
    else Build 失敗 & iteration >= max_retries
        route->>END: 達到重試上限
    end
```

#### 5.2 重試控制機制

**初始化**: `iteration=0`, `max_retries=3`

**Iteration 累加位置**:

- **Build Node** 失敗時: `iteration + 1` ([`build.py:109, 121, 131`](src/fwauto/nodes/build.py#L109))
- **AI Brain** 失敗時: `iteration + 1` ([`ai_brain.py:159`](src/fwauto/nodes/ai_brain.py#L159))

**重試判斷邏輯**:

```python
if current_iteration < max_retries:  # 0,1,2 < 3
    return "ai_brain"
else:
    return "end"  # iteration=3, 停止
```

**實際執行次數**: `max_retries + 1` = 4 次嘗試

#### 5.3 AI Brain 與 Build 的協作

**關鍵設計**:

1. `ai_brain` 成功後 `build_status` 設為 `"success"`
2. `route_after_ai_brain` **總是**返回 `"build"`
3. Build Node 重新編譯驗證修復結果
4. 失敗時 `iteration++`，繼續閉環或結束

**為什麼總是返回 build？**

- AI 執行成功 ≠ 修復成功
- 必須透過實際編譯驗證代碼正確性
- 失敗時再次進入修復閉環

#### 5.4 feat 功能的閉環整合

**完整流程**:

```
fwauto feat "加入蜂鳴器"
  ↓
route_from_start (execution_mode="feat") → ai_brain
  ↓
analyze_task_type() → "implement_feature"
  ↓
載入 prompts/implement_feature.md → 生成代碼
  ↓
route_after_ai_brain → build (驗證生成代碼)
  ↓
build 失敗? → ai_brain (fix_build_errors) → build
  ↓
build 成功 → flash (mode_metadata.flash_after_build=True)
```

**關鍵優勢**:

- AI 生成的代碼自動進入編譯驗證
- 編譯錯誤自動接入修復閉環（復用現有 `fix_build_errors.md`）
- 無需額外邏輯處理失敗情況

---

## Code References

### 核心檔案位置

| 檔案路徑                                                       | 關鍵行號 | 說明                              |
| -------------------------------------------------------------- | -------- | --------------------------------- |
| [`src/fwauto/nodes/ai_brain.py`](src/fwauto/nodes/ai_brain.py) | 24-161   | AI Brain Node 完整實作            |
| [`src/fwauto/nodes/ai_brain.py`](src/fwauto/nodes/ai_brain.py) | 83-106   | `analyze_task_type()` 任務分派    |
| [`src/fwauto/state.py`](src/fwauto/state.py)                   | 6-77     | FirmwareState TypedDict 定義      |
| [`src/fwauto/graph.py`](src/fwauto/graph.py)                   | 15-180   | LangGraph workflow 定義           |
| [`src/fwauto/graph.py`](src/fwauto/graph.py)                   | 30-64    | `route_from_start()` 路由邏輯     |
| [`src/fwauto/graph.py`](src/fwauto/graph.py)                   | 86-106   | `route_after_build()` 閉環核心    |
| [`src/fwauto/graph.py`](src/fwauto/graph.py)                   | 108-112  | `route_after_ai_brain()` 固定路由 |
| [`src/fwauto/prompt_manager.py`](src/fwauto/prompt_manager.py) | 31-61    | `get_prompt()` Template 載入      |
| [`src/fwauto/prompt_manager.py`](src/fwauto/prompt_manager.py) | 63-86    | `_build_variables()` 變數建構     |
| [`src/fwauto/cli.py`](src/fwauto/cli.py)                       | 64-222   | Typer CLI 命令定義                |
| [`src/fwauto/cli.py`](src/fwauto/cli.py)                       | 27-62    | `run_workflow()` Workflow 觸發    |
| [`src/fwauto/platforms.py`](src/fwauto/platforms.py)           | 16-32    | PLATFORMS dict 配置               |
| [`prompts/fix_build_errors.md`](prompts/fix_build_errors.md)   | 1-70     | 編譯錯誤修復 Prompt               |
| [`prompts/log.md`](prompts/log.md)                             | 1-20     | Log 分析 Prompt                   |

---

## Architecture Insights

### 設計模式發現

#### 1. **Template Method Pattern** (Node 生命週期)

所有 Node 遵循相同的執行流程:

```
Pre-processing (Logging) → Core Logic → Post-processing (State Update + Logging) → Return
```

優點:

- 統一的日誌記錄
- 標準化的錯誤處理
- 易於測試和維護

#### 2. **Strategy Pattern** (Task Type 切換)

透過 `analyze_task_type` 動態選擇 Prompt Strategy:

```
State → analyze_task_type() → task_type → prompts/{task_type}.md
```

優點:

- 新增任務類型無需修改 Node 邏輯
- Prompt 和代碼邏輯解耦
- 支援多種 AI 任務場景

#### 3. **State-Driven Routing** (LangGraph 路由)

完全基於 State 欄位決定流程:

- `execution_mode`: 決定主要路徑
- `mode_metadata`: 調整流程細節
- `build_status` + `iteration`: 控制閉環

優點:

- 無需在 Node 內部處理路由邏輯
- State 完整記錄執行歷史
- 易於追蹤和 debug

#### 4. **Platform-Driven Configuration** (多平台支援)

透過 `platform_config` 動態產生約束:

```jinja2
{% for dir in platform_config.forbidden_dirs %}
- **不可修改**: `{{dir}}/`
{% endfor %}
```

優點:

- 新增平台只需在 `platforms.py` 增加配置
- Prompt 邏輯與平台細節解耦
- 統一的安全約束管理

### 架構整合圖

```mermaid
flowchart TB
    subgraph CLI["CLI Layer (cli.py)"]
        Cmd["Typer Commands<br/>@app.command()"]
        InitState["初始化 FirmwareState<br/>(execution_mode, mode_metadata)"]
    end

    subgraph Workflow["LangGraph Layer (graph.py)"]
        Start["START Node"]
        RouteS["route_from_start()"]
        RouteB["route_after_build()"]
        RouteA["route_after_ai_brain()"]
    end

    subgraph Nodes["Node Layer"]
        InitNode["init_project_node"]
        AINode["ai_brain_node"]
        BuildNode["build_node"]
        FlashNode["flash_node"]
        LogNode["log_node"]
    end

    subgraph AI["AI Processing"]
        Analyze["analyze_task_type()"]
        PM["PromptManager"]
        SDK["Claude Code SDK"]
    end

    subgraph Templates["Prompt Templates"]
        T1["fix_build_errors.md"]
        T2["implement_feature.md<br/>(待建立)"]
    end

    subgraph Platform["Platform Config"]
        PC["platforms.py<br/>PLATFORMS dict"]
    end

    Cmd --> InitState
    InitState --> Start
    Start --> RouteS

    RouteS --> InitNode
    RouteS --> AINode
    RouteS --> BuildNode
    RouteS --> LogNode

    BuildNode --> RouteB
    RouteB --> AINode
    RouteB --> FlashNode

    AINode --> Analyze
    Analyze --> PM
    PM --> T1
    PM --> T2
    PM --> PC
    PM --> SDK

    AINode --> RouteA
    RouteA --> BuildNode

    FlashNode --> End([END])
    LogNode --> End

    style AINode fill:#f9f,stroke:#333,stroke-width:4px
    style T2 fill:#ffc,stroke:#f66,stroke-width:2px,stroke-dasharray: 5 5
```

---

## Technical Feasibility

### feat 功能實作的可行性評估

#### 預估工作量

| 任務                   | 預估時間   | 說明                                                        |
| ---------------------- | ---------- | ----------------------------------------------------------- |
| **1. State 擴展**      | 0.5 天     | 新增 `"feat"` 到 `execution_mode` Literal                   |
| **2. CLI 命令**        | 0.5 天     | 建立 `@app.command() def feat()`                            |
| **3. Graph 路由**      | 0.5 天     | 在 `routing_map` 新增 `"feat": "ai_brain"`                  |
| **4. AI Brain 整合**   | 0.5 天     | 在 `analyze_task_type` 新增 `elif execution_mode == "feat"` |
| **5. Prompt Template** | 1-2 天     | 建立 `prompts/implement_feature.md`<br/>調整和測試 prompt   |
| **6. 整合測試**        | 1-2 天     | 測試完整流程，確保閉環正常                                  |
| **總計**               | **4-5 天** | 開發時間                                                    |

#### 程式碼變更規模

**新增程式碼**:

- State 定義: **1 行** (新增 `"feat"` literal)
- CLI 命令: **~30 行** (`@app.command() def feat()`)
- Graph 路由: **1 行** (routing_map 新增)
- AI Brain: **2 行** (`elif execution_mode == "feat"`)
- Prompt: **1 個新檔案** (`prompts/implement_feature.md`)
- 測試: **~50 行** (驗證流程)

**總計**: **~85 行新程式碼** + **1 個 prompt 檔案**

#### 風險評估

| 風險                | 等級 | 緩解措施                                                          |
| ------------------- | ---- | ----------------------------------------------------------------- |
| **Prompt 設計不當** | 中   | 參考 `fix_build_errors.md` 結構<br/>使用 platform_config 限制範圍 |
| **無限循環**        | 低   | 依賴現有 `iteration` + `max_retries` 機制                         |
| **State 過度膨脹**  | 低   | 只新增 1 個 mode，不新增 state 欄位                               |
| **AI 質量問題**     | 中   | 自動接入修復閉環，編譯錯誤會自動修正                              |
| **破壞現有功能**    | 極低 | 完全複用現有架構，無修改核心邏輯                                  |

**風險總評**: **低風險**，架構完全支援擴展，無破壞性變更

---

## Historical Context (from .ai/prpi)

### 相關歷史文件

- `.ai/prpi/problems/2025-10-14-feat-codegen.md` - 問題定義與決策驗證
  - 確認 `/feat` 是規劃好的必做功能
  - 技術方向: 簡化版（codegen → build → flash）
  - 預估時間: 4-5 天開發
  - 核心擔憂: 擔心做錯方向，而非技術困難

---

## Open Questions

### 需要進一步探索的問題

1. **Prompt 質量驗證** (重要性: 高)
   - 問題: Claude 生成 STM32 韌體代碼的實際質量如何？
   - 建議: Phase 1 快速測試驗證（使用簡單案例如蜂鳴器）
   - 參考: 現有 `fix_build_errors.md` 的修復成功率

2. **State 欄位擴展需求** (重要性: 中)
   - 問題: 是否需要新增 `feature_spec` 或其他欄位？
   - 建議: 初期不新增，使用 `user_prompt` 和 `command_args` 即可
   - 原則: 遵守「State 屬性保持最小化」原則

3. **多輪對話需求** (重要性: 低)
   - 問題: 是否需要 `/chat` 對話式互動？
   - 建議: 初期不實作，簡化版 `/feat` 使用單次 AI 調用
   - 未來: 可擴展為 research → plan → implement 完整流程

4. **Platform Config 擴展** (重要性: 低)
   - 問題: 不同韌體功能類型是否需要不同的約束？
   - 建議: 初期使用統一的 `allowed_dirs` 和 `forbidden_dirs`
   - 未來: 可在 `platform_config` 新增功能類型特定配置

---

## 總結與建議

### 關鍵發現

1. **架構高度模組化** - 所有元件（AI Brain, State, Graph, Prompt, CLI）都有清晰的職責和介面
2. **擴展機制成熟** - 透過 `execution_mode`, `task_type`, `mode_metadata` 實現靈活控制
3. **閉環設計穩固** - `iteration` + `max_retries` + 自動修復提供可靠的錯誤處理
4. **Prompt 系統靈活** - Jinja2 + Platform Config 支援多平台和複雜邏輯
5. **CLI 整合簡潔** - Typer + State 初始化模式一致且易於擴展

### 實作建議方向

**Phase 1: MVP (2-3 天)**

- 新增 `execution_mode="feat"` 支援
- 建立基本的 `prompts/implement_feature.md`
- 在 AI Brain 新增 `analyze_task_type` 判斷
- CLI 註冊 `feat` 命令

**Phase 2: 整合測試 (1-2 天)**

- 測試完整流程（feat → build → ai_brain → build → flash）
- 調整 prompt 提升生成質量
- 驗證閉環修復機制

**Phase 3: 優化 (可選)**

- 根據實測結果優化 prompt
- 考慮是否需要新增 State 欄位
- 文件更新

### 技術決策建議

**建議採用的方案**:

- ✅ `/feat` 直接路由到 `ai_brain`（無需新 node）
- ✅ 使用 `task_type="implement_feature"` 切換 prompt
- ✅ 設定 `mode_metadata.flash_after_build=True` 自動驗證
- ✅ 複用現有閉環處理編譯錯誤

**不建議的方案**:

- ❌ 建立獨立的 `feat_node`（增加複雜度）
- ❌ 新增必填 State 欄位（破壞性變更）
- ❌ 實作 research → plan → verify 完整流程（時間不足）

### 差異化價值

**為什麼 /feat 是差異化功能？**

- **自動閉環**: AI 寫完 → 自動編譯 → 失敗自動修復 → 再編譯 → 自動燒錄
- **vs Copilot/Cursor**: 只能寫代碼，後續需要手動編譯、改錯、燒錄
- **深度整合**: Keil + LangGraph + 韌體專業知識，難以複製

**Demo 話術建議**:

> "市面上 Copilot/Cursor 能幫寫代碼，但寫完還是要手動編譯、手動改錯。我們的差異化是：AI 寫完 → 自動編譯 → 失敗自動修復 → 再編譯 → 自動燒錄，完整閉環。這需要深度整合 Keil + LangGraph + 韌體專業知識，別人做不到。"

---

**研究完成時間**: 2025-10-14T22:04:14+08:00
**預估實作時間**: 4-5 天
**風險等級**: 低
**技術可行性**: 高 ✅
