Metadata-Version: 2.4
Name: moxagy
Version: 0.0.2
Summary: MoxAgy CLI Application
Author: Morgan Chen
Author-email: tetsuhou@gmail.com
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: pyyaml
Requires-Dist: moxtools>=0.9.7rc5
Provides-Extra: gui
Requires-Dist: streamlit; extra == "gui"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MoxAgy 使用者操作手冊

- **Author:** Morgan Chen
- **Version:** v0.0.2
- **Last Updated:** 2026-07-06

## 1. 專案概述 (Project Overview)
MoxAgy 是一個基於 Agentic AI 架構開發的軟體開發自動化 CLI 工具。它提供了標準化、模組化的指令列介面，支援透過 YAML 設定檔與 AI Agent 技術進行程式碼審查、自動重構、API 文件生成、CLI 專案腳手架建立等自動化檔案處理任務。

- **支援的平台與環境**：
  - **作業系統**：Windows & Linux
  - **Python 版本**：Python 3.11, Python 3.12 (CP311 & CP312)

## 2. 🛠️ 環境準備 (Prerequisites)
- **必要套件**：
  本專案依賴 `click`、`pyyaml` 以及內部工具包 `moxtools`。
  ```bash
  pip install click pyyaml
  ```
  *(註：請確保 `moxtools` 已正確安裝於您的 Python 環境中)*

  - **Web GUI 支援 (選用)**：若要使用 Web GUI 相關指令，需額外安裝 `streamlit`：
    ```bash
    pip install streamlit
    ```
    （或在本地開發模式下執行 `pip install -e .[gui]`）

- **安裝 MoxAgy CLI**：
  安裝成功後，即可在終端機直接使用 `mox-agy` 命令。
  - **從 PyPI 安裝（推薦）**：
    ```bash
    pip install moxagy
    ```
  - **本地開發模式安裝**（可編輯模式 Editable Mode）：
    請在專案根目錄下執行以下指令：
    ```bash
    pip install -e .
    ```

- **環境變數 / 設定檔**：
  - **除錯模式**：可透過 `--debug` 參數或設定 `PYCLI_DEBUG=1` 來啟用全域除錯模式。
  - **YAML 設定檔**：各子指令支援讀取 YAML 格式的設定檔。若無指定，會自動掃描當前目錄下的設定檔引導使用者選擇。

- **yaml 設定檔說明**:
  以 `manual-gen` (原 `pymanual`) 為例，其預設設定檔內容如下，支援使用模型簡稱（如 `gemini-3.5-flash-m` 等），預設輸出路徑變更為 `./gen-docs`：
  ```yaml
  config:
    output_dir: "./gen-docs"
    default_model: "gemini-3.5-flash-m"
    backup_model:
      - "gemini-3.5-flash-l"
  ```

  以 `readme-gen` (原 `pycli-readme`) 為例，其預設設定檔內容如下，支援指定任務的 Goal、Skill 與 Template 設定檔路徑，現已支援 Python PyCLI 與 C MCU 專案雙模式：
  ```yaml
  config:
    output_dir: "./"
    goal_path: "_agy/goal/pycli-readme-goal.yaml"
    skill_path: "_agy/skill/pycli-readme-expert.yaml"
    template_path: "template/pycli_readme_template.md"
    default_model: "gemini-3.5-flash-m"
    backup_model:
      - "gemini-3.5-flash-l"
  ```

  以 `md2html` 為例，其預設設定檔內容如下，支援自訂輸入路徑、輸出路徑、圖片 Base64 嵌入與浮水印設定：
  ```yaml
  config:
    input_path: "./"
    output_path: "./"
    embed_images: true
    watermark_enable: false
    watermark_text: "CONFIDENTIAL"
  ```

  以 `html-index` 為例，其預設設定檔內容如下，支援文件標題與描述、下載連結，以及索引文件之標題、檔案名稱與描述（並具備自動偵測 moxdoc 以替換為 https://moxdoc.pages.dev/ 文件 URL 的功能，且固定輸出路徑為當前目錄 "./"）：
  ```yaml
  document_title: "[Project Name] Documentation"
  document_description: "Welcome to the [Project Name] documentation. Please select a document below to explore the details."
  download_link: "package.zip"

  document1_title: "[template_doc]"
  document1_file: "template_doc.html"
  document1_description: "[Brief description of the document's purpose and contents.]"
  ```

  - **模型簡稱對照說明**：
    - `gemini-3.5-flash-l` = Low (輕量低耗能)
    - `gemini-3.5-flash-m` = Medium (預設平衡版)
    - `gemini-3.5-flash-h` = High (高精準效能)
    - `gemini-3.1-pro-l` = Gemini 3.1 Pro (Low)
    - `gemini-3.1-pro-h` = Gemini 3.1 Pro (High)
    - `claude-sonnet-4.6-t` = Claude Sonnet 4.6 (Thinking)
    - `claude-opus-4.6-t` = Claude Opus 4.6 (Thinking)
    - `gpt-oss-120b-m` = GPT-OSS 120B (Medium)

## 3. 🚀 執行方式 (Execution Guide)

### 基本指令
透過主命令 `mox-agy` 作為進入點，執行各項子功能：

| 參數 | 短指令 | 型態 | 預設值 | 說明 |
| :--- | :--- | :--- | :--- | :--- |
| `--config` | `-c` | Path | 無 | 指定 YAML 設定檔路徑（若不接參數值，則自動掃描並引導選擇） |
| `--generate-config` | 無 | Flag | False | 生成對應子指令的預設設定檔模板 |
| `--debug` | 無 | Flag | False | 啟用全域除錯模式 |
| `--model` | `-m` | String | 無 | 指定欲使用的 AI 模型（支援簡稱，如 `gemini-3.5-flash-m`） |
| `--output-dir` | `-o` | Path | 無 | 指定輸出的目標目錄（支援之子指令：`manual-gen`, `bash-script`, `template-gen`, `md2html`） |

> [!NOTE]
> 若執行子指令時未帶 any 參數（例如 `mox-agy manual-gen`），系統將自動以預設設定（Default settings）直接執行。

### 預期結果
- **CLI 模式**：執行後將在終端機顯示處理進度與 AI 分析結果，並在完成後輸出成功訊息。
- **檔案輸出**：例如生成設定檔時，將在當前目錄產生 `config_manual_gen_template.yaml` 等設定檔模板。

### 📋 子指令功能說明 (Sub-commands Overview)
MoxAgy 提供了以下核心子指令與指令群組來自動化您的開發流程：

| 子指令 | 功能簡介 | 詳細說明與用途 |
| :--- | :--- | :--- |
| **`start`** | 啟動 Agy TUI | 自動下載與載入設定，並將 `agy-commands.yaml` 同步轉換至 `.agents/` 技能與 `AGENTS.md` 工作區規則中，再以沙盒模式（`--sandbox`）啟動 Agy 的互動式終端機（TUI）交談介面。支援以 `-m` / `--model` 指定模型。 |
| **`template-gen`** | 樣板生成 | 根據選取的參考檔案（如 Python, C, Markdown）與使用者需求，自動生成相應的程式碼或文件樣板。預設輸出至 `./gen-template`，支援以 `-o` / `--output-dir` 自訂輸出目錄。 |
| **`bash-script`** | 自動化 Bash 腳本 | 根據需求描述自動生成 Shell 腳本，並自動給予執行權限（`chmod +x`）供後續執行。生成過程透過本地暫存檔傳遞，避免 Windows 命令行長度限制。預設輸出至 `./gen-bash`，支援以 `-o` / `--output-dir` 自訂輸出目錄。 |
| **`commit-push`** | 自動化 Git 提交 | 自動偵測未追蹤檔案並引導暫存，比對 `git diff`（寫入暫存檔以避開 Windows 命令行長度限制）後透過 AI 生成 Commit 訊息，經確認後自動進行暫存、提交及推送，並自動執行 `git-log-status` 顯示紀錄。具備 AI 失敗時的 Model Retry 與智慧備用模型輪替機制。 |
| **`pycli-add-feature`** | 新增專案功能 | 為既有的 PyCLI 專案引進新的功能子命令，自動調整檔案與 click 進入點結構。 |
| **`pycli-new-project`** | 建立新專案 | 基於標準 MoxAgy 範本，快速初始化並生成全新的 Python CLI 專案腳手架結構。 |
| **`readme-gen`** (原 `pycli-readme`) | README 生成與更新 | 自動偵測版號、讀取 Git Diff，並透過 AI 增量更新或重新生成 README.md 說明文件。支援 Python PyCLI 與 C MCU 專案雙模式。更新與重構過程透過本地暫存檔傳遞，避免 Windows 命令行長度限制。更新完成後支援互動式選擇發布與建置流程（可調用 `wheel-tool` 執行發布與建置動作，或僅修改 `setup.py` 版號）。 |
| **`pycli-refactor`** | 程式碼自動重構 | 引入專案 API 手冊對指定的 Python 腳本進行安全、語意完整且自動覆寫的程式重構。AI 產出之重構程式碼與 CLI 註冊碼會先寫入暫存檔再套用，避免 Windows 命令行長度限制。 |
| **`manual-gen`** (原 `pymanual`) | API/流程手冊生成 | 自動掃描原始碼中的函式、類別宣告或執行流程，解析其註解並彙整輸出為 Markdown 格式的手冊。支援 5 種手冊類型（AI Python API、Python API、Python User Manual、Python Flow Manual、C Flow Manual）。預設輸出至 `./gen-docs`，支援以 `-o` / `--output-dir` 參數自訂輸出目標資料夾。 |
| **`md2html`** | Markdown 轉 HTML | 將從 Notion 匯出的 Markdown 檔案轉換為精美的 HTML 網頁。支援 Notion 與 GitHub 風格的 CSS、圖片 Base64 嵌入與浮水印設定，且可自動於 Author 下方插入 [TOC] 目錄。現亦整合 Mermaid.js 支援以渲染圖表，並優化表格、Blockquote 等樣式排版與連續多餘空行清理。支援指定單一檔案（`-f`）或自訂輸出目錄（`-o`）。 |
| **`html-index`** | 產生 HTML 索引頁面 | 讀取 YAML 設定檔自動比對並產出 HTML 格式的索引網頁（固定輸出至當前目錄）。支援將本機最新版本檔案打包為 ZIP 壓縮檔、自動比對檔名更新最新版本，並可自動偵測實體檔案路徑中包含 `moxdoc` 的網址並置換為 `https://moxdoc.pages.dev/` 前綴。此外，支援互動選取未記載檔案加入索引並回寫設定檔。 |
| **`gui`** (指令群組) | 啟動 Web GUI | 啟動各獨立工具的網頁圖形化介面（基於 Streamlit）。例如 `gui new-pycli-project` |

## 4. 📝 使用範例 (Examples)

### 範例一：生成設定檔模板
在開始使用某子功能（如 API 手冊生成）前，先產生設定檔以便自訂：
```bash
mox-agy manual-gen --generate-config
```

### 範例二：自動尋找並選擇設定檔執行
輸入 `-c` 選項但不帶 any 參數，系統將自動搜尋並讓您選擇設定檔：
```bash
mox-agy manual-gen -c
```

### 範例三：使用特定設定檔執行核心邏輯
自訂 `config_manual_gen_template.yaml` 後，指定該設定檔執行：
```bash
mox-agy manual-gen --config config_manual_gen_template.yaml
```

### 範例四：指定模型執行
若想臨時切換模型，可使用 `-m` 指定模型簡稱執行：
```bash
mox-agy manual-gen -m gemini-3.5-flash-h
```

### 範例五：直接執行（未帶 any 參數）
若無需指定 any 選項，可直接呼叫子指令，系統將會載入預設的設定值直接執行：
```bash
mox-agy manual-gen
```

### 範例六：自動偵測並生成/更新 README.md (readme-gen)
- **產生 `readme-gen` 設定檔模板**：
  ```bash
  mox-agy readme-gen --generate-config
  ```
- **使用預設設定直接執行**：
  ```bash
  mox-agy readme-gen
  ```
  *(註：執行後系統會自動在執行前檢查 Git 工作區狀態（必須為 Clean），偵測 `setup.py` 版號或現有 README，引導您選擇發佈版本類型（正式版/RC 版）並計算下一版版號，再讀取 Git Diff 進行增量更新（支援 Python PyCLI 與 C MCU 專案雙模式）。更新成功後，您可以透過互動式選單選擇是否使用 `wheel-tool` 進行 GitHub 發布、CICD 或 Local Build)*

### 範例七：指定輸出目錄生成手冊 (manual-gen)
- **指定輸出至 `./manual` 目錄**：
  ```bash
  mox-agy manual-gen -o ./manual
  ```

### 範例八：將 Notion 匯出的 Markdown 轉換為 HTML (md2html)
- **產生 `md2html` 設定檔模板**：
  ```bash
  mox-agy md2html --generate-config
  ```
- **轉換特定 Markdown 檔案並指定輸出目錄**：
  ```bash
  mox-agy md2html -f my_document.md -o ./html-outputs
  ```
- **直接轉換特定 Markdown 檔案（跳過互動式選擇）**：
  ```bash
  mox-agy md2html -f my_document.md
  ```
- **互動式選取並進行批次轉換**（不帶 file 參數）：
  ```bash
  mox-agy md2html
  ```

### 範例九：啟動網頁圖形化介面 (gui)
- **啟動專案初始化腳手架 GUI 介面**：
  ```bash
  mox-agy gui new-pycli-project
  ```

### 範例十：啟動 Agy TUI 並指定欲使用的 AI 模型 (start)
- **指定高精準度效量模型啟動 TUI交談介面**：
  ```bash
  mox-agy start -m gemini-3.5-flash-h
  ```

### 範例十一：自動產生/更新 HTML 說明文件索引 (html-index)
- **產生 `html-index` 設定檔模板**：
  ```bash
  mox-agy html-index --generate-config
  ```
- **以預設/自訂設定執行生成網頁索引**：
  ```bash
  mox-agy html-index
  ```
  *(註：執行後系統會讀取設定檔，比對當前目錄下符合的實體文件，自動將其最新版本（忽略版本後綴）打包為指定 ZIP 檔案，更新/清空下載連結，並提示是否有未記載檔案需互動式選取加入索引，自動偵測並置換路徑中含有 `moxdoc` 的實體檔案 URL，最後更新回寫設定檔並於當前目錄產出 `index.html`)*

## 5. 📅 版本更新紀錄 (Change Log)

### v0.0.2 (2026-07-06)
- **`html-index` 簡化與智慧偵測**：
  - 移除 `html-index` 子指令的 `-o` / `--output-dir` 參數與設定檔中的 `output_path`，將輸出路徑固定為當前目錄 `"./"`。
  - 移除設定檔中的 `base_url` 設定，改為自動偵測實體檔案路徑中包含 `moxdoc` 的 URL，並自動替換前綴為 `https://moxdoc.pages.dev/`。
  - 簡化 `sys.argv` 預處理與 click 選項以配合上述參數的移除。
- **程式碼重構與規則規範**：
  - 於 `pycli-refactor.yaml`、`agy-commands.yaml` 與 `pycli-expert.yaml` 新增 Cython 相容的 API 回傳值接收規範。
  - 限制呼叫複數回傳值 API 時以索引 (index) 接收，禁止使用解包 (unpacking)。
- **模板與文件更新**：
  - 於 `python_user_manual_template.md` 模板新增使用者範例目錄結構說明。
  - 新增 `html-index` 功能的專屬使用者手冊（`manual/Python_User_Manual_html_index.md`）。

### v0.0.2rc5 (2026-07-05)
- **`readme-gen` 錯誤修正與優化**：
  - 修正 `diff_content` 未在 `is_refactor` 條件外初始化可能導致的錯誤。
  - 調整內部 `subprocess.run` 參數排版為單行，優化程式碼結構與可讀性。

### v0.0.2rc4 (2026-07-03)
- **`readme-gen` (原 `pycli-readme`) 升級與 C MCU 專案雙模式支援**：
  - 子指令重構更名為 `readme-gen`，全面支援 Python PyCLI 與 C MCU 專案雙模式。
  - 新增 C MCU 專案的專屬 Goal (`c-mcu-readme-goal.yaml`)、Skill (`c-mcu-readme-expert.yaml`) 與模板 (`c_mcu_project_readme_template.md`)。
  - 實作執行 README 處理前檢查 Git 工作區狀態，若非 clean 狀態或偵測失敗則安全中斷以防資料遺失。
  - 自動偵測與優化專案資訊（如從 `setup.py` 偵測名稱/作者）以及從現有 `README.md` 自動解析作者與專案名稱。
  - 優化版本號選取流程，引導使用者確認正式版或 RC 版號；並於 Git 相關 subprocess 呼叫中強制設定 UTF-8 編碼以提高相容性。
- **全新 `html-index` 子指令**：
  - 新增 `html-index` 功能，自動掃描目錄並讀取 YAML 設定檔生成精美的 HTML 文件索引頁 (`index.html`)。
  - 支援自動將最新版本的非 yaml 檔案打包為指定 zip 檔案，並自動更新下載連結。
  - 提供互動式終端機選單，引導使用者將未在設定檔中記載的實體檔案加入網頁索引，並可即時輸入顯示標題與描述，將變更自動回寫至設定檔中。
  - 自動比對檔名版本（忽略 `-vX.Y.Z` 或 `_vX.Y.Z` 後綴）以確保索引與打包內容均為最新版本。
- **其他優化與修正**：
  - 於 `agy-commands.yaml` 新增 `/ffile`（查詢檔案並載入）、`/cmt-key`（新增關鍵步驟註解）等輔助與 slash 指令。
  - 規範 `flow-manual.yaml` 等設定檔路徑，禁止使用 `file:///` 格式之絕對路徑連結。
  - 移除 C/Python 程式碼流程範本中多餘的模組連結，使輸出更精簡。

### v0.0.2rc3 (2026-06-29)
- **`manual-gen` 功能擴充與 Python 流程 analysis 優化**：
  - 新增對「Python 程式流程說明手冊 (Python Flow Manual)」的支援（共支援 5 種手冊類型），並配置專屬的 Goal (`flow-manual.yaml`)、Skill (`flow-manual-expert.yaml`) 與 Template (`python_code_flow_template.md`)。
  - 針對 Python Flow 模式進行 Prompt 優化，加入對 async/await、類別/資料模型設計、裝飾器控制流與 Exception Handling 的專屬分析要求，並加強特定任務欄位與範本對照（如 `{{python_source_filepath}}` 與 `{{algorithm_or_feature_name}}`）。
- **`md2html` 轉換器升級與圖表渲染支援**：
  - 新增對 **Mermaid 圖表** 的渲染支援（基於 `mermaid.js` 10.9.1 CDN 載入），自動將 markdown-it 生成 of mermaid code blocks 轉換為 Mermaid 辨識 of div 容器並還原 HTML 實體以正常顯示。
  - 介面視覺排版美化：優化 GitHub Style 表格樣式、引用區塊 (Blockquote) 邊框樣式，以及縮減清單項目邊距。
  - 檔名建構優化：修正檔名後綴處理邏輯，使用 `Path.stem` 取得純檔名，避免轉換時產生 `.md.html` 雙副檔名的問題。
  - 轉換逆節調整：移除 Notion 匯出屬性後自動清理連續 3 個以上的換行符，保持排版緊湊；並於 `md2html -h` 幫助訊息中新增 `md2html -f` 快速轉換範例。

### v0.0.2rc2 (2026-06-29)
- **Windows 平台相容性與命令長度優化**：
  - 重構 `run_agy`，加入 Windows 平台的 shell=True 機制與換行符過濾，解決 `agy` 找不到或命令被截斷的問題。
  - 將 `commit-push` (git diff)、`pycli-refactor` (重構程式碼) 以及 `bash-script` 的 AI 讀取與生成過程改為透過本地暫存檔（如 `_agy/current-diff.txt`、`_agy/generated-commit.txt`、`_agy/generated-readme.md` 等）傳遞，徹底解決 Windows 下 command line 長度限制與字元跳脫問題，並在任務完成後自動清理暫存檔。
- **Agy 指令同步機制與 TUI 擴充**：
  - 新增 `sync_agy_commands_to_agents` 通用 API，將 `agy-commands.yaml` 自動轉換並同步至 `.agents/skills/{name}/SKILL.md` 與 `.agents/AGENTS.md` (Workspace Rules)。
  - `start` 指令在啟動前會自動調用同步 API 更新工作區規則，並以 `--sandbox` 啟動 Agy TUI，且新增 `-m` / `--model` 選項以支援手動指定模型。
- **Click 參數解析與工具列別名呼叫優化**：
  - 為 `cli.py` 與 `md2html.py` 新增 sys.argv 預處理，防止點選項（如 `-c`, `-o`) 未帶參數時 click 報錯，提升使用者體驗。
  - 新增 `cmd_utils.run_alias_cmd_via_bash_interactive` 通用 API，改以 `bash -i -c` 執行 `wheel-tool` 及 `git-log-status` 等 CLI 別名，保證 Windows/Linux 的環境變數與別名一致性。
- **`manual-gen` 與 `pycli-readme` 功能微調**：
  - `pycli-readme` 設定檔與載入機制新增 `template_path` (預設為 `template/pycli_readme_template.md`)。
  - 模型名稱對照表 (resolve_model_name) 新增更多可用模型，包含 `gemini-3.1-pro-l/h`、`claude-sonnet-4.6-t`、`claude-opus-4.6-t` 與 `gpt-oss-120b-m` 等。

### v0.0.2rc1 (2026-06-26)
- **`manual-gen` 重構與更名**：原 `pymanual` 重構更名為 `manual-gen`，全面更新內部類別、日誌、CLI 指令名稱與 `config_manual_gen_template.yaml` 範本。預設輸出路徑變更為 `./gen-docs`。
- **手冊功能擴充**：`manual-gen` 新增對程式流程說明手冊（Flow Manual）與 C 語言流程分析的支援，並在檔案掃描時自動排除 `.venv` 目錄。
- **全新 `md2html` 子指令**：支援將 Notion 匯出的 Markdown 批次或指定單一檔案（`-f`）轉換為 HTML，支援圖片嵌入與浮水印設定，且可自訂輸出目錄。
- **全新 `gui` 指令群組**：支援使用 Streamlit 啟動網頁圖形化介面，首波推出 `gui new-pycli-project` 以引導快速初始化專案。
- **智慧型 Model Retry 與智慧輪替**：為 `commit-push` 引進 AI 呼叫失敗時的 Model Retry 與 `backup_model` 智慧型備用模型輪替機制。
- **`commit-push` 清理與優化**：移除不合適的 `output_dir` 相關設定與屬性，最佳化 commit 訊息生成流程與 Windows 相容性。
- **輸出目錄選項與路徑標準化**：
  - 將全域設定與資源路徑統一重新命名為 `_agy` (如 `_agy/goal`, `_agy/skill`)。
  - `template-gen` 預設輸出路徑調整為 `./gen-template`。
  - `bash-script` 預設輸出路徑調整為 `./gen-bash`，並新增 `-o` / `--output-dir` 參數。
- **Agy TUI 快捷指令擴充**：TUI 互動交談模式中新增 `/ssfile`（設定系統參考檔）與 `/ref`（設定參考文件）等 slash 快捷指令。

### v0.0.2rc0 (2026-06-24)
- **新增 `pycli-readme` 子指令**：自動偵測 `setup.py` 版號，引導使用者選擇發佈版本類型（正式版/RC 版）並計算下一版版號，再透過 Git Diff 增量更新或重新生成 `README.md` 文件。
- **支援自訂 `pymanual` 輸出路徑**：`pymanual` 子指令新增 `-o` / `--output-dir` 選項，供使用者手動指定產出 API 手冊的目標資料夾。
- **`commit-push` 暫存優化**：新增未追蹤檔案（untracked files）的偵測機制，並在確認後引導使用者自動執行 `git add .`。
- **`template-gen` 錯誤處理優化**：强化來源目錄與檔案存在性檢查，提升執行穩定性。
- **命名與相容性修正**：微調 `pycli-add-feature` 的內部變數命名邏輯，將連字號 `-` 取代為底線 `_`。

### v0.0.1 (2026-06-23)
- **簡化模型名稱支援**：引進模型名稱簡稱對照表（`gemini-3.5-flash-m` = Medium, `gemini-3.5-flash-l` = Low, `gemini-3.5-flash-h` = High），支援於 CLI 及 YAML 中快速指定。
- **異常容錯處理**：若輸入的模型無法成功識別，系統將會輸出警告日誌 `⚠️` 並自動 Fallback 至預設的 `"Gemini 3.5 Flash (Medium)"`。
- **指令幫助功能升級**：為各個子指令新增 `Features` 功能點英文清單，並更新 `-c` 選項說明。
- **文檔結構精簡**：移除未開發的 GUI/Streamlit 與陳舊參數（如 `--direct`），貼合目前實作狀態。
