---
date: 2025-11-25T16:30:00+08:00
researcher: Claude
git_commit: 8c753cba87aece3b4baad4d5e7a95806011694ae
branch: help_and_run
repository: FWAuto
topic: "新增 /help 和 /run CLI 指令研究"
tags: [research, cli, typer, help, run]
status: complete
last_updated: 2025-11-25
last_updated_by: Claude
---

# Research: 新增 /help 和 /run CLI 指令研究

**Date**: 2025-11-25T16:30:00+08:00
**Researcher**: Claude
**Git Commit**: 8c753cba87aece3b4baad4d5e7a95806011694ae
**Branch**: help_and_run
**Repository**: FWAuto

## Research Question

新增兩個新的 CLI 指令：
1. `/help` - 顯示支援的指令和使用方式，額外顯示 API key（部分遮蔽）和 fwauto 版本
2. `/run` - 執行 `/build` + `/deploy` 的動作

## Summary

| 發現項目 | 結果 |
|---------|------|
| `/run` 指令 | **已存在** (`cli.py:290-378`) |
| CLI 框架 | Typer |
| 版本定義位置 | `pyproject.toml:3` (version = "0.3.0") |
| API Key | 環境變數 `ANTHROPIC_API_KEY`（由 claude-agent-sdk 自動讀取） |
| 現有指令數量 | 7 個 (build, deploy, run, log, feat, chat, init) |

**關鍵發現**：`/run` 指令已經存在於 codebase 中，不需要新增。只需實作 `/help` 指令。

## Detailed Findings

### CLI 架構

```mermaid
graph TD
    main["main()"] --> checkArgs{"len(sys.argv) == 1?"}
    checkArgs -->|Yes| chatMode["_enter_unified_chat_mode()"]
    checkArgs -->|No| typerApp["app() - Typer CLI"]

    typerApp --> build["build"]
    typerApp --> deploy["deploy"]
    typerApp --> run["run"]
    typerApp --> log["log"]
    typerApp --> feat["feat"]
    typerApp --> chat["chat"]
    typerApp --> init["init"]
```

**入口點**：`src/fwauto/cli.py:604-610`

```
main() → 無參數時進入 chat mode，否則由 Typer 處理指令
```

### 現有指令清單

| 指令 | 位置 | 說明 |
|-----|------|------|
| `build` | `cli.py:170-204` | 編譯韌體專案 |
| `deploy` | `cli.py:207-287` | 部署韌體到裝置 |
| `run` | `cli.py:290-378` | **Build + Deploy（已存在）** |
| `log` | `cli.py:381-421` | 分析 UART logs |
| `feat` | `cli.py:424-464` | AI 輔助功能實作 |
| `chat` | `cli.py:467-508` | 互動式對話 |
| `init` | `cli.py:511-528` | 初始化新專案 |

### /run 指令實作分析

`/run` 指令已完整實作於 `cli.py:290-378`：

- 支援 `--binary-args` / `-ba` 參數
- 支援 `--scenario` / `-s` 參數
- 設定 `execution_mode: "run"` 和 `mode_metadata: {"deploy_after_build": True}`
- Graph routing 在 `graph.py:54` 和 `graph.py:78` 將 `run` 路由到 `build` node
- Build 成功後，`route_after_build()` 在 `graph.py:94` 檢測到 `run` mode 並路由到 `deploy`

### 版本資訊位置

| 項目 | 位置 | 值 |
|-----|------|-----|
| 版本號 | `pyproject.toml:3` | `version = "0.3.0"` |
| 套件名稱 | `pyproject.toml:2` | `name = "fwauto"` |

**讀取方式**：可使用 `importlib.metadata.version("fwauto")` 取得

### API Key 配置

**發現**：FWAuto 使用環境變數管理 API keys，不在配置檔中存儲

| 環境變數 | 用途 | 使用位置 |
|---------|------|---------|
| `ANTHROPIC_API_KEY` | Claude API | claude-agent-sdk 自動讀取 |
| `LANGSMITH_API_KEY` | LangSmith tracing | `langsmith_config.py:15` |

**API Key 遮蔽顯示建議**：
- 顯示前 4 字元 + `***` + 後 4 字元
- 例如：`sk-a****xyz`

### Graph Routing 機制

```mermaid
graph LR
    START --> routeFromStart{"route_from_start()"}

    routeFromStart -->|"mode=build"| buildNode["build"]
    routeFromStart -->|"mode=run"| buildNode
    routeFromStart -->|"mode=deploy"| deployNode["deploy"]

    buildNode --> routeAfterBuild{"route_after_build()"}

    routeAfterBuild -->|"success + run mode"| deployNode
    routeAfterBuild -->|"success + build mode"| END_NODE["END"]
    routeAfterBuild -->|"failed + can retry"| aiBrain["ai_brain"]

    deployNode --> END_NODE
```

**關鍵路由邏輯**（`graph.py:89-96`）：
- `run` mode 在 build 成功後自動路由到 deploy
- 透過 `mode_metadata.deploy_after_build` 或 `execution_mode == "run"` 判斷

## Code References

| 檔案路徑 | 行號 | 說明 |
|---------|------|------|
| `src/fwauto/cli.py` | 17-23 | Typer app 定義 |
| `src/fwauto/cli.py` | 170-204 | build 指令 |
| `src/fwauto/cli.py` | 207-287 | deploy 指令 |
| `src/fwauto/cli.py` | 290-378 | **run 指令（已存在）** |
| `src/fwauto/cli.py` | 604-610 | main 入口點 |
| `src/fwauto/graph.py` | 52-59 | routing_map（run → build） |
| `src/fwauto/graph.py` | 89-96 | route_after_build（run mode → deploy） |
| `pyproject.toml` | 3 | 版本定義 |
| `src/fwauto/langsmith_config.py` | 15 | LANGSMITH_API_KEY 讀取 |

## Architecture Insights

### Typer CLI 模式

FWAuto 使用 Typer 框架，指令定義模式：

```
@app.command()
def command_name(...):
    """Docstring 作為 help 說明"""
    ...
```

Typer 內建提供 `--help` 參數，但沒有獨立的 `help` 子指令。

### State 驅動的 Workflow

CLI 指令透過建立 `FirmwareState` 並傳入 `run_workflow()` 執行：
1. CLI 建立初始 state（包含 `execution_mode`, `command` 等）
2. Graph 根據 state 路由到對應 node
3. Nodes 執行任務並更新 state

### 配置層級

```mermaid
graph TD
    env["環境變數"] --> sdk["claude-agent-sdk"]
    userConfig["~/.fwauto/config.toml"] --> projectConfig["ProjectConfig"]
    projectConfig --> deployment["deployment 設定"]
```

API Key 不在任何配置檔中，只透過環境變數傳遞。

## Open Questions

1. **help 指令的互動模式整合**：
   - 在 unified chat mode（無參數啟動）中，使用者可能也會想要 `/help`
   - 是否需要在 chat mode 中支援 `/help` slash command？

2. **版本資訊的額外內容**：
   - 除了版本號和 API key，是否需要顯示其他資訊？
   - 例如：Python 版本、平台資訊、當前專案路徑等

3. **API Key 檢測範圍**：
   - 目前發現 `ANTHROPIC_API_KEY` 和 `LANGSMITH_API_KEY`
   - 是否有其他需要顯示的 API key？

