# 文檔更新實施計劃

## Overview

根據研究文件 `.ai/rpi/research/2025-10-11-docs-update-analysis.md` 的分析結果，現有文檔與實際 codebase 存在嚴重不一致。本計劃將修正過時文檔，並新增 High Level Design Document 幫助開發者理解系統架構。

## Current State Analysis

### 文檔狀態

| 文檔 | 狀態 | 主要問題 |
|------|------|---------|
| README.md | ❌ 嚴重過時 | 包含已移除的專案編號參數、不存在的 migrate 命令 |
| flow-spec.md | ⚠️ 部分過時 | 命令表格包含專案編號、init_project_node 描述不符 |
| makefile-design.md | ✅ 基本正確 | 需標註 Phase 2 未完成（build_output.toml） |
| high-level-design.md | ❌ 不存在 | 缺少架構文檔 |

### 實際實作狀態（已驗證）

**✅ 已完整實作**：
- 錨點模式：`.fwauto/` 向上搜尋機制（`config.py:84-109`）
- Makefile 整合：`execute_make_command` 統一執行介面（`utils.py:78-156`）
- CLI 系統：完全移除專案編號參數（`cli.py:65-241`）
- LangGraph 工作流程：State 管理、路由邏輯、AI 重試循環

**❌ 未實作（Phase 2）**：
- `build_output.toml` 生成與讀取
- `firmware_path` State 欄位追蹤

### Key Discoveries

1. **專案編號已完全移除** (`cli.py:65-241`)：
   - 所有命令不再接受專案編號參數
   - 使用錨點模式自動搜尋 `.fwauto/` 目錄

2. **錨點模式完整實作** (`config.py:84-109`, `nodes/init.py:10-54`)：
   - `find_project_root()` 向上搜尋 `.fwauto/` 目錄
   - `init_project_node()` 自動初始化專案

3. **Makefile 整合正確運作** (`utils.py:78-156`, `nodes/build.py:73-84`, `nodes/flash.py:73-84`)：
   - 統一的 `execute_make_command()` 函數
   - 支援 timeout、即時輸出、log 記錄

4. **build_output.toml 未實作**：
   - 搜尋結果：0 個使用位置
   - `firmware_path` State 欄位存在但未被填充

## Desired End State

所有文檔準確反映當前實作狀態，並提供清晰的架構說明文件。

### 驗證方式

1. README.md 的所有命令範例可以正確執行
2. flow-spec.md 的命令表格與 `cli.py` 實作一致
3. makefile-design.md 明確標註未完成功能
4. high-level-design.md 提供完整的架構說明

## What We're NOT Doing

- ❌ 不實作 build_output.toml 功能（此為程式碼變更，非文檔更新）
- ❌ 不創建 Roadmap 文檔（用戶明確表示暫不需要）
- ❌ 不修改任何程式碼
- ❌ 不更新測試相關文檔（make-file-test-flow.md）

## Implementation Approach

遵循 KISS 原則，分兩階段執行：
1. **Phase 1**：快速修正過時文檔，確保基本正確性
2. **Phase 2**：新增架構文檔，提供深入理解

所有變更基於實際 codebase 驗證結果，確保文檔與實作 100% 一致。

---

## Phase 1: 修正過時文檔

### Overview

修正 README.md、flow-spec.md、makefile-design.md 的過時內容，使其與當前實作一致。

### Changes Required

#### 1. README.md

**File**: `README.md`
**Changes**: 移除專案編號參數、移除不存在的 migrate 命令、更新所有命令範例

**需要修正的內容**：

- [x] 1. **Line 16-18**: 移除 legacy 模式說明
   ```markdown
   # 移除這段
   fwauto run 4        # 使用專案編號 (legacy 模式)
   ```

   替換為：
   ```markdown
   fwauto run          # 從當前目錄向上搜尋 .fwauto/
   ```

- [x] 2. **Line 33-36**: 移除所有專案編號範例
   ```markdown
   # 移除這些
   uv run fwauto build 01
   uv run fwauto flash 13
   uv run fwauto run 04
   ```

   替換為：
   ```markdown
   uv run fwauto build
   uv run fwauto flash
   uv run fwauto run
   ```

- [x] 3. **Line 44-49**: 移除 legacy 模式和 migrate 命令
   ```markdown
   # 移除這段
   fwauto build 4      # Legacy 模式：使用專案編號
   fwauto migrate      # 遷移舊專案到 .fwauto/ 結構
   ```

   保留：
   ```markdown
   fwauto build        # 從當前目錄向上搜尋 .fwauto/
   fwauto run          # Build + Flash
   fwauto init         # 初始化新專案
   ```

#### 2. flow-spec.md

**File**: `docs/flow-spec.md`
**Changes**: 更新命令表格、修正 init_project_node 說明

**需要修正的內容**：

- [x] 1. **Line 142-149**: 更新命令表格（移除專案編號欄位）

   現有內容：
   ```markdown
   | 命令 | 說明 | 範例 | 模式 |
   |------|------|------|------|
   | `build` | 編譯指定專案 | `fwauto build 04` | build |
   | `flash` | 燒錄韌體到裝置 | `fwauto flash 04` | flash |
   | `run` | 快速編譯並燒錄 | `fwauto run 05` | run |
   | `log` | 分析 UART 日誌 | `fwauto log "有錯誤嗎?"` | log |
   ```

   修正為：
   ```markdown
   | 命令 | 說明 | 範例 | 模式 |
   |------|------|------|------|
   | `build` | 編譯專案 | `fwauto build` | build |
   | `flash` | 燒錄韌體到裝置 | `fwauto flash` | flash |
   | `run` | 快速編譯並燒錄 | `fwauto run` | run |
   | `log` | 分析 UART 日誌 | `fwauto log "有錯誤嗎?"` | log |
   | `init` | 初始化新專案 | `fwauto init` | - |
   ```

- [x] 2. **Line 150-153**: 移除「必要參數：project_number」說明

   移除：
   ```markdown
   **命令特性**:
   - **必要參數**: `build`, `run` 需要專案編號，`flash` 參數可選
   ```

   修正為：
   ```markdown
   **命令特性**:
   - **錨點模式**: 所有命令自動從當前目錄向上搜尋 `.fwauto/` 目錄
   ```

- [x] 3. **Line 131**: 修正 init_project_node 說明

   現有：
   ```markdown
   | init_project_node | project_root, project_initialized, project_number | 初始化專案路徑和編號，基於 project_number |
   ```

   修正為：
   ```markdown
   | init_project_node | project_root, project_initialized | 使用錨點模式搜尋 .fwauto/ 目錄並初始化專案 |
   ```

#### 3. makefile-design.md

**File**: `docs/makefile-design.md`
**Changes**: 在「實作狀態」章節明確標註 Phase 2 未完成

**需要新增的內容**：

- [x] 在 Line 147 之後新增「實作狀態」章節，包含詳細說明：

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

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

**目前狀態**：
- Build 和 Flash 節點完全依賴 Makefile 的 exit code 判斷成功/失敗
- 無法取得 Makefile 輸出的結構化資訊（如韌體檔案路徑、size 資訊等）
- `firmware_path` State 欄位已定義但未被任何節點填充

**影響**：
- Flash 節點無法自動取得 Build 產生的韌體檔案路徑
- 需要 Makefile 自行管理檔案路徑（目前透過 PROJECT_ROOT 參數實現）

**如需實作 Phase 2**：
1. 修改 build/Makefile，build 完成後寫入 `.fwauto/build_output.toml`
2. 修改 `build_node.py`，讀取 `build_output.toml` 並更新 `firmware_path`
3. 修改 `flash_node.py`，從 State 讀取 `firmware_path` 並傳遞給 flash/Makefile
```

### Success Criteria

#### Automated Verification

- [x] 所有修改的檔案通過 Markdown linting（如果有設定）
- [x] README.md 中的命令範例可以執行：
  ```bash
  # 在有 .fwauto/ 的專案目錄測試
  fwauto build    # cli.py:64
  fwauto flash    # cli.py:101
  fwauto run      # cli.py:138
  fwauto log "test"  # cli.py:175
  ```

#### Manual Verification

- [x] README.md 不再包含專案編號參數或 migrate 命令
- [x] flow-spec.md 命令表格與 `cli.py` 實作一致
- [x] makefile-design.md 清楚標註 Phase 2 未完成狀態
- [x] 所有文檔的命令範例在實際環境中可正確執行

**Implementation Note**: 完成此階段後，暫停並確認所有文檔修正正確無誤再進行 Phase 2。

---

## Phase 2: 創建 High Level Design Document

### Overview

新增 `docs/high-level-design.md`，提供面向開發者的系統架構說明，幫助理解 FWAuto 的設計原則、關鍵決策和擴展點。

### Changes Required

#### 1. 創建 docs/high-level-design.md

**File**: `docs/high-level-design.md` (新檔案)
**Changes**: 創建完整的架構文檔

**文檔結構**：

```markdown
# FWAuto High Level Design

## 1. 系統概述

### 定位
FWAuto 是一個基於 LangGraph 的 STM32 韌體開發自動化系統，透過 AI 輔助實現從程式碼生成、編譯、燒錄到日誌分析的完整閉環。

### 解決的核心問題
- 韌體開發流程繁瑣（編譯 → 燒錄 → 測試 → 修復 → 重複）
- 編譯錯誤修復需要人工介入
- 工具鏈整合複雜（Keil、ST-LINK、各種 SDK）
- 缺少統一的自動化流程

### 關鍵特性
- **AI 驅動的錯誤修復**：自動分析編譯錯誤並嘗試修復
- **錨點模式專案管理**：類似 Git 的 `.fwauto/` 目錄自動搜尋
- **Makefile 抽象層**：隱藏不同工具鏈和平台的差異
- **LangGraph 工作流程**：State-based 流程管理，可追蹤、可恢復

## 2. 架構原則

### KISS 原則體現
- **配置即檔案**：`.fwauto/config.toml` 空白即可，使用預設值
- **約定優於配置**：統一的 Makefile 介面，不需複雜配置
- **單一職責**：每個節點只做一件事

### Makefile 抽象層價值
- 隱藏工具鏈差異（Keil vs GCC vs IAR）
- 支援跨平台（Windows vs Linux）
- 簡化新平台整合（只需提供 Makefile）

### 錨點模式設計
- 類似 Git 的 `.git/` 機制
- 向上搜尋 `.fwauto/` 目錄標識專案根目錄
- 無需全域配置或專案註冊

## 3. 系統架構

### 整體架構圖

(參考 flow-spec.md 的 LangGraph 圖，此處簡化說明)

```
CLI 層 (Typer)
    ↓
LangGraph 層 (State Management + Routing)
    ↓
Nodes 層 (init_project, build, flash, ai_brain, log)
    ↓
工具層 (execute_make_command, Claude Code SDK)
```

### LangGraph 工作流程

**核心組件**：
- **FirmwareState** (19 個欄位)：共享狀態，貫穿整個工作流程
- **5 個核心節點**：init_project, build, flash, ai_brain, log
- **6 個路由函數**：控制工作流程的分支與循環

**AI 重試循環**：
```
Build (失敗) → AI Brain (修復) → Build (驗證)
                    ↑_______________|
                    (最多重試 3 次)
```

**State 更新模式**：
```python
return {**state, "build_status": "success"}  # 增量更新
```

### AI 整合策略

**Claude Code SDK 使用**：
- `ai_brain_node`：允許修改程式碼（Write, Edit, MultiEdit）
- `log_node`：限制為只讀（Read, Grep）

**Prompt 系統**：
- Jinja2 模板化 prompt (`prompts/`)
- 動態任務類型分析 (`analyze_task_type()`)
- 可擴展新的 AI 任務類型

## 4. 關鍵設計決策

### 技術選型理由

| 技術 | 選型理由 |
|------|---------|
| LangGraph | State-based workflow，易於管理複雜流程和恢復機制 |
| Claude Code SDK | 整合 AI 輔助開發能力，支援程式碼讀寫 |
| Typer | 現代化 CLI 框架，自動生成 help 文件 |
| Jinja2 | Prompt 模板化，易於維護和調整 |
| TOML | 配置檔格式，可讀性高且結構化 |

### 設計權衡考量

1. **簡單 vs 靈活**
   - 選擇：簡單（空白 config.toml + 預設值）
   - 理由：降低使用門檻，90% 場景不需自訂配置

2. **通用 vs 專精**
   - 選擇：當前專注 STM32，但架構支援通用化
   - 理由：先做好一個平台，再逐步擴展

3. **自動 vs 可控**
   - 選擇：AI 修復限制在 `USER/` 目錄
   - 理由：確保不會修改到關鍵系統檔案

4. **Exit Code vs TOML**
   - 選擇：Phase 1 僅使用 exit code，Phase 2 加入 TOML
   - 理由：快速實現核心功能，結構化資訊可後續補充

## 5. 擴展點設計

### 如何新增 CLI 命令

1. 在 `cli.py` 新增 `@app.command()` 裝飾的函數
2. 初始化 FirmwareState 並設定 `execution_mode`
3. 呼叫 `run_workflow(state)`

範例：
```python
@app.command()
def my_command():
    state: FirmwareState = {
        "execution_mode": "my_mode",
        # ... 其他欄位
    }
    run_workflow(state)
```

### 如何支援新平台

1. 準備平台專用的 `build/Makefile` 和 `flash/Makefile`
2. 在 `.fwauto/config.toml` 中設定 Makefile 路徑
3. 執行 `fwauto build` 測試

**無需修改 Python 程式碼**。

### 如何自訂 AI 任務

1. 在 `prompts/` 目錄新增 prompt 模板（Jinja2 格式）
2. 在 `ai_brain_node.py` 的 `analyze_task_type()` 新增任務類型判斷
3. 在 `prompt_manager.py` 註冊新的 prompt 檔案

範例：
```python
# ai_brain_node.py
if "optimize" in user_prompt.lower():
    return "optimize_performance"

# prompt_manager.py
def get_prompt(self, task_type: str, state: dict) -> str:
    if task_type == "optimize_performance":
        return self._render_template("optimize.md", state)
```

## 6. 當前限制與權衡

### 技術債務

1. **依賴 Alpha 版本**：
   - LangGraph 1.0.0a3（可能不穩定）
   - Claude Code SDK 0.0.23（極早期版本）

2. **測試覆蓋不足**：
   - 僅 36% 的模組有測試
   - 缺少 CLI、AI Brain、完整工作流程的測試

3. **硬編碼路徑**：
   - Makefile 模板中仍有硬編碼的工具鏈路徑（Keil, ST-LINK）

### 已知限制

1. **build_output.toml 未實作**（Phase 2）：
   - 無法自動傳遞韌體檔案路徑給 flash
   - 需要 Makefile 自行管理檔案位置

2. **單一平台支援**：
   - 目前僅針對 STM32 + Keil 最佳化
   - 其他平台需要準備對應的 Makefile

3. **AI 任務類型有限**：
   - 僅實作 `fix_build_errors` 和 `log_analysis`
   - 其他任務類型（implement_feature, fix_bug 等）已設計但未實作

### 未來改進方向

1. **完成 Phase 2 功能**：
   - 實作 build_output.toml 機制
   - 自動追蹤 firmware_path

2. **擴展測試覆蓋**：
   - 新增 CLI 整合測試
   - 新增 AI Brain 單元測試
   - 新增完整工作流程 E2E 測試

3. **多平台支援**：
   - ESP32, Arduino, RISC-V
   - GCC, IAR, LLVM 工具鏈

## 7. 參考資料

### 相關文檔
- [Flow Specification](./flow-spec.md)
- [Makefile Design](./makefile-design.md)
- [AGENTS.md](../AGENTS.md)

### 外部資源
- [LangGraph Documentation](https://docs.langchain.com/oss/python/langgraph/overview)
- [Claude Code SDK](https://docs.claude.com/en/docs/claude-code/sdk/sdk-python)
- [Typer Documentation](https://typer.tiangolo.com/)

### Code References

| 元件 | 檔案位置 | 說明 |
|------|---------|------|
| FirmwareState | `src/fwauto/state.py:6-71` | 完整 State 定義 |
| 錨點模式搜尋 | `src/fwauto/config.py:84-109` | find_project_root() |
| CLI 命令 | `src/fwauto/cli.py:65-241` | 所有命令定義 |
| Makefile 執行 | `src/fwauto/utils.py:78-156` | execute_make_command() |
| Build 節點 | `src/fwauto/nodes/build.py:10-133` | Build 邏輯 |
| AI Brain 節點 | `src/fwauto/nodes/ai_brain.py:10-161` | AI 修復邏輯 |
| 路由邏輯 | `src/fwauto/graph.py:30-121` | 所有路由函數 |

---

**文檔版本**: v1.0
**最後更新**: 2025-10-11
**維護者**: 開發者自己
```

### Success Criteria

#### Automated Verification

- [x] 新檔案通過 Markdown linting（如果有設定）
- [x] 所有 code reference 的 file:line 正確指向實際程式碼

#### Manual Verification

- [ ] 文檔結構清晰，章節安排合理
- [ ] 所有架構圖和程式碼範例正確無誤
- [ ] 技術選型理由充分且說服力足夠
- [ ] 擴展點設計的範例可實際運作
- [ ] 限制與權衡的描述準確反映現狀
- [ ] 對開發者（自己）理解系統有實質幫助

**Implementation Note**: 此階段完成後，整個文檔更新工作即完成。建議定期（如每次重大功能更新後）回顧並更新此文檔。

---

## Testing Strategy

### Manual Testing Steps

#### 驗證 README.md 正確性
1. 在有 `.fwauto/` 的專案目錄執行所有命令範例
2. 確認所有命令都能正確執行
3. 確認不再有 `migrate` 或專案編號相關的錯誤提示

#### 驗證 flow-spec.md 正確性
1. 對照 `src/fwauto/cli.py` 確認命令表格完全一致
2. 檢查 State 欄位變化說明與 `src/fwauto/state.py` 一致
3. 確認流程圖與 `src/fwauto/graph.py` 路由邏輯一致

#### 驗證 makefile-design.md 正確性
1. 確認 Phase 2 未完成的標註清楚明確
2. 檢查是否有誤導性描述（如描述成已完成）
3. 驗證「如需實作 Phase 2」的步驟合理可行

#### 驗證 high-level-design.md 正確性
1. 檢查所有 code reference 的 file:line 是否正確
2. 驗證架構圖與實際程式碼流程一致
3. 確認擴展點範例可實際運作
4. 檢查技術選型理由與實際使用情況一致

## Performance Considerations

無效能考量，此為純文檔更新工作。

## Migration Notes

無需資料遷移。

## References

- Original research: `.ai/rpi/research/2025-10-11-docs-update-analysis.md`
- CLI implementation: `src/fwauto/cli.py:65-241`
- Config implementation: `src/fwauto/config.py:84-109`
- State definition: `src/fwauto/state.py:6-71`
- Graph routing: `src/fwauto/graph.py:30-121`
