---
date: 2025-10-11T15:35:57+08:00
researcher: Claude (Sonnet 4.5)
git_commit: 12effa33f51d1669331483ae207186c6e6279f4f
branch: main
repository: fwauto
topic: "文檔更新需求分析與 High Level Design Document 規劃"
tags: [research, documentation, architecture, roadmap]
status: complete
last_updated: 2025-10-11
last_updated_by: Claude (Sonnet 4.5)
---

# Research: 文檔更新需求分析與 High Level Design Document 規劃

**Date**: 2025-10-11T15:35:57+08:00
**Researcher**: Claude (Sonnet 4.5)
**Git Commit**: 12effa33f51d1669331483ae207186c6e6279f4f
**Branch**: main
**Repository**: fwauto

## Research Question

根據最新的 codebase 狀態，分析現有文檔的正確性，並規劃新增 High Level Design Document 和 Roadmap 文檔的架構。

## Summary

經過全面的 codebase 研究，發現：

1. **現有文檔狀態**：部分文檔嚴重過時（README.md、flow-spec.md），需要更新以反映當前實作（錨點模式、移除專案編號）
2. **實作完整度**：核心功能（LangGraph workflow、Makefile 整合、CLI 系統）已完整實作，但部分設計功能未完成（build_output.toml、其他 AI 任務類型）
3. **測試覆蓋**：約 36% 的模組有測試，缺少 CLI、AI Brain、完整工作流程的測試
4. **文檔規劃**：設計了面向開發者的 High Level Design Document 架構和以指令擴展為核心的 Roadmap

## Detailed Findings

### 1. 現有文檔一致性分析

#### 文檔狀態總覽

| 文檔                   | 檔案路徑                      | 狀態        | 問題描述                                         |
| ---------------------- | ----------------------------- | ----------- | ------------------------------------------------ |
| README.md              | `/docs/` 無，在根目錄         | ❌ 嚴重過時 | 包含已移除的專案編號參數、不存在的 migrate 命令  |
| flow-spec.md           | `docs/flow-spec.md`           | ⚠️ 部分過時 | 命令表格包含專案編號、init_project_node 描述不符 |
| makefile-design.md     | `docs/makefile-design.md`     | ✅ 基本正確 | 需標註 Phase 2 未完成（build_output.toml）       |
| make-file-test-flow.md | `docs/make-file-test-flow.md` | ⚠️ 需驗證   | 需確認與實際測試策略一致性                       |
| AGENTS.md              | `AGENTS.md`                   | ✅ 正確     | 開發規範描述正確                                 |

#### 關鍵差異

**README.md** (`README.md:16-48`):

- ❌ `fwauto build 04` → 應為 `fwauto build`
- ❌ `fwauto migrate` → 命令不存在
- ❌ 描述 Legacy 模式 → 已完全改為錨點模式

**flow-spec.md** (`docs/flow-spec.md:142-149`):

- ❌ 命令表格包含專案編號參數
- ❌ init_project_node 描述為「基於 project_number」→ 實際使用 `.fwauto/` 搜尋

### 2. Codebase 實作狀態

#### 核心架構完整度

```mermaid
graph LR
    A[CLI 層] --> B[LangGraph 層]
    B --> C[Nodes 層]
    C --> D[工具層]

    A -->|✅ 完整實作| A1[Typer CLI]
    A -->|✅ 錨點模式| A2[專案搜尋]
    A -->|❌ 缺少測試| A3[測試覆蓋]

    B -->|✅ 完整實作| B1[State 管理]
    B -->|✅ 完整實作| B2[路由邏輯]
    B -->|✅ 完整實作| B3[錯誤恢復]

    C -->|✅ 完整實作| C1[Build/Flash]
    C -->|⚠️ 部分實作| C2[AI Brain]
    C -->|⚠️ 基本測試| C3[Log Node]

    D -->|✅ 完整實作| D1[Makefile 執行]
    D -->|❌ 未實作| D2[build_output.toml]
```

#### 實作狀態表格

| 功能模組           | 實作狀態               | 測試狀態    | 檔案位置                                |
| ------------------ | ---------------------- | ----------- | --------------------------------------- |
| CLI 系統           | ✅ 完整                | ❌ 無測試   | `src/fwauto/cli.py`                     |
| LangGraph Workflow | ✅ 完整                | ⚠️ 基本測試 | `src/fwauto/graph.py`                   |
| Build/Flash Nodes  | ✅ 完整                | ✅ 完整測試 | `src/fwauto/nodes/build.py`, `flash.py` |
| AI Brain Node      | ⚠️ 僅 fix_build_errors | ❌ 無測試   | `src/fwauto/nodes/ai_brain.py`          |
| Log Node           | ✅ 基本功能            | ⚠️ 基本測試 | `src/fwauto/nodes/log.py`               |
| Init Node          | ✅ 完整                | ❌ 無測試   | `src/fwauto/nodes/init.py`              |
| Makefile 整合      | ✅ Phase 1             | ✅ 完整測試 | `src/fwauto/utils.py`                   |
| Prompt 系統        | ⚠️ 部分實作            | ⚠️ 間接測試 | `src/fwauto/prompt_manager.py`          |

### 3. LangGraph 架構發現

#### State 機制

**FirmwareState 結構** (`src/fwauto/state.py:6-71`):

- 總計 19 個欄位
- 分為 7 大類：基礎、編譯、燒錄、重試、命令、日誌、韌體

**冗餘欄位**:

- `project_number` - 存在但完全未使用
- `project_name` - 僅用於顯示，無功能用途

#### 節點與路由

**5 個核心節點**:

| 節點         | 檔案                | 行數 | 主要職責                       |
| ------------ | ------------------- | ---- | ------------------------------ |
| init_project | `nodes/init.py`     | 55   | 向上搜尋 `.fwauto/` 並載入配置 |
| ai_brain     | `nodes/ai_brain.py` | 161  | AI 錯誤修復與程式碼生成        |
| build        | `nodes/build.py`    | 133  | 執行 Makefile build            |
| flash        | `nodes/flash.py`    | 130  | 執行 Makefile flash            |
| log          | `nodes/log.py`      | 211  | Claude Code SDK 日誌分析       |

**6 個路由函數** (`src/fwauto/graph.py`):

1. `route_from_start` (30-64) - 初始路由
2. `route_after_init` (66-84) - 初始化後路由
3. `route_after_build` (86-106) - Build 後路由（含 AI 重試邏輯）
4. `route_after_ai_brain` (108-112) - AI 修復後路由
5. `route_after_flash` (114-121) - Flash 後路由
6. Log 節點直接連接 END

#### AI 重試循環

```mermaid
stateDiagram-v2
    [*] --> Build
    Build --> Flash: success & run mode
    Build --> End: success & build only
    Build --> AIBrain: error & iteration < max_retries
    Build --> End: error & max_retries reached
    AIBrain --> Build: always (驗證修復)
    Flash --> End: always
```

**重試機制** (`graph.py:86-106`):

- 最大重試次數：3 次 (`max_retries`)
- 每次失敗 `iteration += 1`
- AI Brain 總是路由回 Build 驗證修復結果

### 4. Makefile 整合設計

#### 架構圖

```mermaid
graph TD
    A[FWAuto CLI] --> B[build_node]
    A --> C[flash_node]

    B -->|make -f .fwauto/build/Makefile build| D[Build Makefile]
    C -->|make -f .fwauto/flash/Makefile flash| E[Flash Makefile]

    D -->|呼叫| F[Keil / GCC / IAR]
    E -->|呼叫| G[ST-LINK / JLink]

    D -.未實作.-> H[.fwauto/build_output.toml]
    B -.未實作.-> H
```

#### 實作狀態

**✅ 已實作 (Phase 1)**:

- Build/Flash Node 完全透過 Makefile 執行
- 統一的 `execute_make_command()` 工具函數 (`utils.py:78-156`)
- 跨平台支援（Windows/macOS/Linux）
- Timeout 保護（60 秒）
- 完整的輸出捕捉

**❌ 未實作 (Phase 2)**:

- `build_output.toml` 生成與讀取
- `firmware_path` State 欄位追蹤
- `HEX_FILE` 參數傳遞給 flash

**⚠️ 限制**:

- Makefile 模板仍包含硬編碼路徑（Keil, ST-LINK, Git Bash）

### 5. Claude Code SDK 整合

#### 使用模式

**ai_brain_node** (`nodes/ai_brain.py:109-133`):

```python
ClaudeCodeOptions(
    allowed_tools=["Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash"],
    permission_mode="bypassPermissions",
    add_dirs=[stm32_project_root],
    cwd=stm32_project_root
)
```

**log_node** (`nodes/log.py:103-108`):

```python
ClaudeCodeOptions(
    allowed_tools=["Read", "Grep"],  # 限制工具
    permission_mode="bypassPermissions",
    add_dirs=[log_dir],
    append_system_prompt=system_override  # 強制執行模式
)
```

#### Prompt 系統

**已實作的 Prompt** (`prompts/`):

| 檔案                  | 大小  | 用途             | 觸發條件                  |
| --------------------- | ----- | ---------------- | ------------------------- |
| `fix_build_errors.md` | 2.6KB | 編譯錯誤自動修復 | `build_status == "error"` |
| `log.md`              | 524B  | UART 日誌分析    | `execution_mode == "log"` |
| `claude_code.md`      | 39KB  | 參考文件         | 不直接使用                |

**未實作的任務類型** (`ai_brain.py:83-106`):

- `implement_feature` - 實作新功能
- `fix_bug` - 修復 Bug
- `natural_language` - 自然語言任務
- `general_codegen` - 通用程式碼生成

### 6. 測試策略分析

#### 測試架構

**三層測試設計**:

```mermaid
graph TD
    A[Layer 3: E2E 測試] -->|未實作| A1[真實 Keil + ST-LINK]
    B[Layer 2: 整合測試] -->|部分實作| B1[測試 Makefile + 輸出重播]
    C[Layer 1: 單元測試] -->|完整實作| C1[Mock + Fixtures]

    B1 --> B2[tests/integration/]
    C1 --> C2[tests/nodes/]
    C1 --> C3[tests/test_story_*.py]
```

#### 測試覆蓋統計

| 指標           | 數值       |
| -------------- | ---------- |
| 源代碼檔案總數 | 22 個      |
| 有測試的模組   | 8 個 (36%) |
| 測試檔案總數   | 10 個      |
| 測試總數       | 43+ 個     |
| 測試程式碼行數 | 1,357 行   |

#### 測試盲點

**完全缺少測試**:

- CLI 主程式 (`cli.py`)
- Init 命令 (`cli_commands/init.py`)
- 配置管理 (`config.py`)
- Init 節點 (`nodes/init.py`)
- AI Brain 節點 (`nodes/ai_brain.py`)
- Prompt Manager (`prompt_manager.py`)

**測試不足**:

- Log 節點（僅基本測試）
- Graph 完整工作流程
- 錯誤恢復循環

### 7. CLI 命令系統

#### 當前命令

| 命令      | 實作狀態 | 參數                    | 功能               |
| --------- | -------- | ----------------------- | ------------------ |
| `build`   | ✅       | 無                      | 編譯韌體           |
| `flash`   | ✅       | 無                      | 燒錄韌體           |
| `run`     | ✅       | 無                      | 編譯+燒錄          |
| `log`     | ✅       | `<prompt>` `--log-path` | AI 日誌分析        |
| `init`    | ✅       | `[path]`                | 初始化專案         |
| `migrate` | ❌       | -                       | 不存在（文檔誤植） |

#### 錨點模式設計

**專案搜尋機制** (`config.py:84-109`):

```
從當前目錄向上搜尋 .fwauto/ 目錄
類似 Git 的 .git/ 搜尋機制
支援在專案任何子目錄執行命令
```

**優點**:

- 無需記憶專案編號
- 支援多專案環境
- 直覺易用

## Code References

| 檔案路徑                                      | 行號   | 說明                                |
| --------------------------------------------- | ------ | ----------------------------------- |
| `src/fwauto/state.py`                         | 6-71   | FirmwareState 完整定義（19 個欄位） |
| `src/fwauto/graph.py`                         | 30-64  | route_from_start 初始路由邏輯       |
| `src/fwauto/graph.py`                         | 86-106 | route_after_build AI 重試循環       |
| `src/fwauto/nodes/build.py`                   | 73-84  | Makefile 執行呼叫                   |
| `src/fwauto/nodes/ai_brain.py`                | 83-106 | 任務類型分析（含未實作類型）        |
| `src/fwauto/utils.py`                         | 78-156 | execute_make_command 跨平台實作     |
| `src/fwauto/cli.py`                           | 65-221 | 所有 CLI 命令定義                   |
| `src/fwauto/config.py`                        | 84-109 | 錨點模式專案搜尋                    |
| `prompts/fix_build_errors.md`                 | 1-67   | 編譯錯誤修復 prompt                 |
| `prompts/log.md`                              | 1-17   | 日誌分析 prompt                     |
| `tests/nodes/test_build_makefile.py`          | 1-144  | Build 節點單元測試                  |
| `tests/integration/test_build_integration.py` | 1-142  | Build 整合測試                      |
| `docs/flow-spec.md`                           | 1-190  | 流程規格（需更新）                  |
| `docs/makefile-design.md`                     | 1-153  | Makefile 設計文件                   |
| `README.md`                                   | 1-59   | 專案 README（需更新）               |

## Architecture Insights

### 設計模式發現

#### 1. State-First 設計

- 所有節點使用 `{**state, ...}` 增量更新模式
- 符合 LangGraph 最佳實踐
- 狀態不可變性確保可追蹤、可持久化

#### 2. Makefile 抽象層

- 隱藏工具鏈差異
- 提高可移植性
- 簡化新工具鏈支援

**可擴展方向**:

- 目前只需更換 Makefile 即可支援不同工具
- 未來可以透過 Adapter Pattern 進一步抽象

#### 3. 錨點模式

- 類似 Git 的 `.git/` 機制
- 無需全域配置或專案註冊
- 支援多專案並存

#### 4. AI 任務驅動

- 透過 `analyze_task_type` 動態選擇 prompt
- 支援多種任務類型（設計完成，部分實作）
- 可擴展新的 AI 任務

### 技術選型分析

| 技術            | 版本    | 選型理由                               |
| --------------- | ------- | -------------------------------------- |
| LangGraph       | 1.0.0a3 | State-based workflow, 易於管理複雜流程 |
| Claude Code SDK | 0.0.23  | 整合 AI 輔助開發能力                   |
| Typer           | 0.19.2  | 現代化 CLI 框架，自動生成 help         |
| Jinja2          | 3.1.6   | Prompt 模板化，易於維護                |
| UV              | -       | 快速的 Python 套件管理器               |

### 限制與權衡

**當前限制**:

1. 依賴 Alpha 版本的 LangGraph（可能不穩定）
2. Claude Code SDK 極早期版本（0.0.23）
3. Makefile 模板仍有硬編碼路徑
4. 測試覆蓋不足（36%）

**設計權衡**:

1. **簡單 vs 靈活**：選擇簡單（空白 config.toml + 預設值）
2. **通用 vs 專精**：當前專注 STM32，但架構支援通用化
3. **自動 vs 可控**：AI 修復限制在 `USER/` 目錄，確保安全

## 建議文檔架構

### High Level Design Document

**目標讀者**: 開發者（用戶自己）

**章節結構**:

```markdown
1. 系統概述
   - FWAuto 的定位
   - 解決的核心問題
   - 關鍵特性

2. 架構原則
   - KISS 原則體現
   - Makefile 抽象層價值
   - 錨點模式設計

3. 系統架構
   - 整體架構圖
   - LangGraph 工作流程
   - AI 整合策略

4. 關鍵設計決策
   - 技術選型理由
   - 設計權衡考量

5. 擴展點設計
   - 如何新增指令
   - 如何支援新平台
   - 如何自訂 AI 任務

6. 限制與權衡
```

### Roadmap

**核心方向**: 指令擴展 + 通用化

**Phase 1: 指令擴展（短期）**

- `/feat` - 新功能開發
- `/fix` - Bug 修復
- `/pref` - 效能分析

**Phase 2: 通用化支援（中期）**

- 多平台支援（ESP32, Arduino, RISC-V, ARM Cortex-M）
- 多工具鏈支援（GCC, IAR, ARMCC, LLVM）
- 多燒錄工具支援（J-Link, OpenOCD, pyOCD）

**Phase 3: 生態系整合（長期）**

- 開發板配置模板庫
- 硬體在環測試
- 協作功能（共享配置、知識庫）

### 需要更新的現有文檔

| 文檔               | 優先級 | 更新內容                                 |
| ------------------ | ------ | ---------------------------------------- |
| README.md          | 🔴 高  | 移除專案編號、更新命令範例、移除 migrate |
| flow-spec.md       | 🟡 中  | 更新命令表格、init_project_node 說明     |
| makefile-design.md | 🟢 低  | 標註 Phase 2 未完成                      |

## Related Research

相關研究文件（若存在於 `.ai/rpi/` 目錄）可在此列出。

---

**Research completed at**: 2025-10-11T15:35:57+08:00
