# Help 指令實施計劃

## Overview

實作 `help` 指令，同時支援 CLI 指令（`fwauto help`）和 Chat mode slash command（`/help`）。顯示版本、指令清單、環境資訊和 API key 狀態。

## Current State Analysis

- CLI 使用 Typer 框架（`cli.py`）
- Chat mode slash command 由 `slash_commands.py` 解析，`chat.py` 處理
- 目前 slash command 只支援 `build`, `deploy`, `log`
- 版本定義於 `pyproject.toml:3`
- API key 透過環境變數 `ANTHROPIC_API_KEY` 讀取

## Desired End State

執行 `fwauto help` 或在 chat mode 輸入 `/help` 後，顯示：

```
🚀 FWAuto v0.3.0

📋 支援的指令：
  build     🔨 Build firmware project
  deploy    📥 Deploy firmware to device
  run       ⚡ Run build and deploy
  log       📊 Analyze UART log files
  feat      🚀 AI-assisted feature implementation
  init      🚀 Initialize new project
  help      ❓ Show this help message

💡 直接執行 fwauto（無參數）進入互動模式

🔧 環境資訊：
  Python:   3.12.x
  Platform: linux
  Project:  /path/to/project

🔑 API Key：
  ANTHROPIC_API_KEY: sk-a***xyz (已設定)
```

### 驗證方式

1. `fwauto help` 正確顯示所有資訊
2. Chat mode 中輸入 `/help` 正確顯示所有資訊
3. API key 遮蔽顯示（前 4 字元 + `***` + 後 4 字元）
4. 未設定 API key 時顯示「未設定」

## What We're NOT Doing

- 不修改現有指令的行為
- 不新增 `/run` slash command（已存在於 CLI，chat mode 暫不需要）
- 不顯示 `LANGSMITH_API_KEY`

## Implementation Approach

```mermaid
graph LR
    Phase1["Phase 1<br/>核心函數"] --> Phase2["Phase 2<br/>CLI 指令"]
    Phase2 --> Phase3["Phase 3<br/>Slash Command"]
```

建立共用的 `_get_help_info()` 函數，CLI 和 slash command 都調用此函數。

---

## Phase 1: 核心 Help 函數

### Overview

在 `cli.py` 中建立 `_get_help_info()` 函數，收集並格式化所有資訊。

### Changes Required

#### 1. 新增 `_get_help_info()` 函數

**File**: `src/fwauto/cli.py`

**位置**: 在 `_build_deploy_state()` 函數之前（約 line 28）

**新增內容**:

```python
def _mask_api_key(key: str | None) -> str:
    """Mask API key for display.

    Shows first 4 chars + *** + last 4 chars.
    Example: sk-ant-api03-xxx...xxx -> sk-a***xxxx
    """
    if not key:
        return "未設定"
    if len(key) <= 8:
        return "***"
    return f"{key[:4]}***{key[-4:]}"


def _get_help_info() -> str:
    """Generate help information string.

    Returns formatted help text including:
    - Version
    - Available commands
    - Environment info (Python, platform, project path)
    - API key status (masked)
    """
    import os
    import platform
    import sys
    from importlib.metadata import version

    from .config import find_project_root

    # Get version
    try:
        ver = version("fwauto")
    except Exception:
        ver = "unknown"

    # Get project root
    project_root = find_project_root()
    project_path = str(project_root) if project_root else "不在專案目錄中"

    # Get API key status
    anthropic_key = os.getenv("ANTHROPIC_API_KEY")

    # Build help text
    help_text = f"""🚀 FWAuto v{ver}

📋 支援的指令：
  build     🔨 Build firmware project
  deploy    📥 Deploy firmware to device
  run       ⚡ Run build and deploy
  log       📊 Analyze UART log files
  feat      🚀 AI-assisted feature implementation
  init      🚀 Initialize new project
  help      ❓ Show this help message

💡 直接執行 fwauto（無參數）進入互動模式

🔧 環境資訊：
  Python:   {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}
  Platform: {platform.system().lower()}
  Project:  {project_path}

🔑 API Key：
  ANTHROPIC_API_KEY: {_mask_api_key(anthropic_key)}"""

    return help_text
```

### Success Criteria

#### Automated Verification

- [ ] 型別檢查通過：`uv run pyright src/fwauto/cli.py`
- [ ] Lint 通過：`uv run python -m fwauto.scripts.lint`

#### Manual Verification

- [ ] 函數可正確取得版本號
- [ ] API key 遮蔽邏輯正確

---

## Phase 2: CLI Help 指令

### Overview

在 `cli.py` 中新增 `help` 指令。

### Changes Required

#### 1. 新增 `help` 指令

**File**: `src/fwauto/cli.py`

**位置**: 在 `init` 指令之後（約 line 529）

**新增內容**:

```python
@app.command(name="help")
def help_command():
    """
    ❓ Show help information.

    Displays available commands, version, environment info, and API key status.

    Example:
        fwauto help
    """
    console.print(_get_help_info())
```

### Success Criteria

#### Automated Verification

- [ ] 型別檢查通過：`uv run pyright src/fwauto/cli.py`
- [ ] Lint 通過：`uv run python -m fwauto.scripts.lint`

#### Manual Verification

- [ ] `fwauto help` 正確顯示所有資訊
- [ ] `fwauto --help` 列出 `help` 指令

---

## Phase 3: Chat Mode Slash Command

### Overview

在 `slash_commands.py` 加入 `/help` 支援，並在 `chat.py` 中處理。

### Changes Required

#### 1. 更新 `slash_commands.py`

**File**: `src/fwauto/slash_commands.py`

**變更 1**: 更新 `parse_slash_command()` 中的指令清單（line 46）

```python
# 原本
if command_name not in ["build", "deploy", "log"]:

# 改為
if command_name not in ["build", "deploy", "log", "help"]:
```

**變更 2**: 更新 `parse_command_args()` 函數（約 line 56-81）

```python
def parse_command_args(cmd: SlashCommand) -> dict[str, Any]:
    """Parse slash command arguments into command_args dict."""
    if cmd.name == "build":
        return _parse_build_args(cmd.raw_args)
    elif cmd.name == "deploy":
        return _parse_deploy_args(cmd.raw_args)
    elif cmd.name == "log":
        return _parse_log_args(cmd.raw_args)
    elif cmd.name == "help":
        return {}  # help 不需要參數
    else:
        raise ValueError(f"Unknown command: {cmd.name}")
```

#### 2. 更新 `chat.py` 的 `_handle_slash_command()`

**File**: `src/fwauto/nodes/chat.py`

**位置**: 在 `_handle_slash_command()` 函數中，`else` 分支之前（約 line 303）

**新增**:

```python
        elif cmd.name == "help":
            from ..cli import _get_help_info

            help_text = _get_help_info()
            console.print(help_text)

            # Log command execution
            if cmd_logger:
                cmd_logger.log_command_execution(
                    command="/help",
                    parameters={},
                    status="success",
                    output=help_text,
                )
            return  # help 不需要注入 AI 對話
```

### Success Criteria

#### Automated Verification

- [ ] 型別檢查通過：`uv run pyright`
- [ ] Lint 通過：`uv run python -m fwauto.scripts.lint`
- [ ] 測試通過：`uv run pytest tests/`

#### Manual Verification

- [ ] 啟動 chat mode（`fwauto`），輸入 `/help` 正確顯示資訊
- [ ] `/help` 不會觸發 AI 對話

---

## Testing Strategy

### Unit Tests

不需要新增 unit tests，因為：
- `_get_help_info()` 是簡單的格式化函數
- `_mask_api_key()` 邏輯簡單

### Manual Testing Steps

1. 執行 `fwauto help`，確認顯示正確
2. 設定/取消 `ANTHROPIC_API_KEY`，確認顯示狀態正確
3. 在專案目錄內外執行，確認 Project 路徑顯示正確
4. 啟動 `fwauto`（chat mode），輸入 `/help`，確認顯示正確

---

## References

- Research: `.ai/prpi/research/2025-11-25-help-and-run-cli-commands.md`
- CLI 入口點: `src/fwauto/cli.py`
- Slash commands: `src/fwauto/slash_commands.py`
- Chat node: `src/fwauto/nodes/chat.py`
