feat(cli): add short option aliases for command arguments

Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>

Author: LanternCX

.progress/PROGRESS.md

@@ -40,3 +40,4 @@ abc123d (or TBD)
 | 2026-03-09-4 | 2026-03-09 | Reset scan records and keep only last successful snapshot | `.progress/entries/2026/2026-03-09-4.md` | list, reset-cache, successful-snapshot, runtime-db, cli |
 | 2026-03-11-1 | 2026-03-11 | Add incremental base commit support | `.progress/entries/2026/2026-03-11-1.md` | incremental, git-diff, base-ref, cli, deploy |
 | 2026-03-11-2 | 2026-03-11 | Override using-git-worktrees with project git workflow | `.progress/entries/2026/2026-03-11-2.md` | skills, git-workflow, worktree, override, opencode |
+| 2026-03-11-3 | 2026-03-11 | Add short option aliases for CLI commands | `.progress/entries/2026/2026-03-11-3.md` | cli, argparse, short-options, readme, tests |

.progress/entries/2026/2026-03-11-3.md

@@ -0,0 +1,25 @@
+# 2026-03-11-3
+
+## Date
+2026-03-11
+
+## Title
+Add short option aliases for CLI commands
+
+## Background / Issue
+当前 `mpy-cli` 的参数以长选项为主，日常使用时输入偏长。用户希望为每个现有命令参数补充单字符短选项，同时保持长选项兼容，并让 README 与测试一起同步约束这套映射。
+
+## Actions / Outcome
+- Approach 1: 为所有参数设计全局唯一短选项 -> 可避免跨命令复用，但会引入许多不直观字母，放弃。
+- Approach 2: 按子命令局部复用短选项，并优先使用参数名直觉字母 -> 适合 `argparse` 的子命令模型，保留了 `-m/-p/-y/-n` 等常见写法。
+- Final approach: 先用 TDD 为 CLI 解析新增短参数回归测试，再在 `mpy_cli/cli.py` 中补齐短选项，并同步更新 `README.md` 与 `tests/test_docs_and_ci.py` -> 成功为所有现有参数增加短选项别名，重点解决了 `tree` 中 `--path` 与 `--port` 的冲突，最终采用 `-a/--path` 与 `-p/--port`，全部验证通过。
+
+## Lessons / Refinements
+- 为 `argparse` 子命令扩展短参数时，应以“子命令内无冲突、跨子命令可复用”为优先规则，避免为了全局唯一牺牲可记忆性。
+- README 约束测试应按命令小节校验关键 token/别名对，而不是整行精确匹配，才能同时保证契约强度与文档可维护性。
+
+## Related Commit Message
+TBD
+
+## Related Commit Hash
+TBD

README.md

@@ -180,11 +180,11 @@ python3 -m pip install -e <SOURCE_MPY_CLI_PATH>
 ### `mpy-cli init`
 
 ```bash
-mpy-cli init [--force] [--no-interactive]
+mpy-cli init [-f] [--force] [-n] [--no-interactive]
 ```
 
-- `--force`：覆盖已有 `.mpy-cli.toml` 和 `.mpyignore`。
-- `--no-interactive`：跳过初始化后的交互配置向导。
+- `-f`/`--force`：覆盖已有 `.mpy-cli.toml` 和 `.mpyignore`。
+- `-n`/`--no-interactive`：跳过初始化后的交互配置向导。
 
 ### `mpy-cli config`
 
@@ -208,25 +208,25 @@ mpy-cli config
 ### `mpy-cli plan`
 
 ```bash
-mpy-cli plan [--mode {incremental,full}] [--base BASE] [--port PORT] [--no-interactive] [--yes]
+mpy-cli plan [-m {incremental,full}] [--mode {incremental,full}] [-b BASE] [--base BASE] [-p PORT] [--port PORT] [-n] [--no-interactive] [-y] [--yes]
 ```
 
-- `--mode`：指定同步模式（`incremental` 或 `full`）。
-- `--base`：仅在 `incremental` 模式生效，指定 Git 基准提交；增量集合按“该基准提交 vs 当前工作区”计算。
-- `--port`：指定设备端口（如 `/dev/ttyACM0` 或 `COM3`）。
-- `--no-interactive`：禁用交互提问。
-- `--yes`：保留参数；在 `plan` 中不会触发写入确认流程。
+- `-m`/`--mode`：指定同步模式（`incremental` 或 `full`）。
+- `-b`/`--base`：仅在 `incremental` 模式生效，指定 Git 基准提交；增量集合按“该基准提交 vs 当前工作区”计算。
+- `-p`/`--port`：指定设备端口（如 `/dev/ttyACM0` 或 `COM3`）。
+- `-n`/`--no-interactive`：禁用交互提问。
+- `-y`/`--yes`：保留参数；在 `plan` 中不会触发写入确认流程。
 
 ### `mpy-cli list`
 
 ```bash
-mpy-cli list [--workers N] [--probe-timeout SECONDS] [--scan-mode MODE] [--reset]
+mpy-cli list [-w N] [--workers N] [-t SECONDS] [--probe-timeout SECONDS] [-s MODE] [--scan-mode MODE] [-r] [--reset]
 ```
 
-- `--workers`：并发探测线程数，默认 `8`；当扫描到很多端口时可提升返回速度。
-- `--probe-timeout`：单端口探测超时秒数，默认 `1.0`；慢端口超时后会被跳过，不阻塞全部结果。
-- `--scan-mode`：端口探测策略，支持 `known-first`、`known-only`、`full-only`，默认 `known-first`。
-- `--reset`：先清空之前的扫描记录，再立即执行当前这次 `list`。
+- `-w`/`--workers`：并发探测线程数，默认 `8`；当扫描到很多端口时可提升返回速度。
+- `-t`/`--probe-timeout`：单端口探测超时秒数，默认 `1.0`；慢端口超时后会被跳过，不阻塞全部结果。
+- `-s`/`--scan-mode`：端口探测策略，支持 `known-first`、`known-only`、`full-only`，默认 `known-first`。
+- `-r`/`--reset`：先清空之前的扫描记录，再立即执行当前这次 `list`。
 - 默认会先读取运行时数据库里“上一次扫描成功过”的端口，仅对“成功缓存端口与当前 `mpremote connect list` 交集”做探测；若没有发现设备，再回退到当前可用端口全量探测。
 - 该策略兼容 macOS / Linux / Windows：是否“当前可用”以本次 `mpremote connect list` 结果为准，因此 `COM3` 这类 Windows 端口同样可用。
 - 自动扫描串口，并对选中的端口进行受控并发探测，返回所有可访问的 MicroPython 设备。
@@ -241,97 +241,97 @@ mpy-cli list
 当本机串口很多、默认探测较慢时，可按需调高并发并缩短超时：
 
 ```bash
-mpy-cli list --workers 12 --probe-timeout 1.0
+mpy-cli list -w 12 -t 1.0
 ```
 
 如果你想直接忽略缓存、每次都对当前端口全量探测：
 
 ```bash
-mpy-cli list --scan-mode full-only
+mpy-cli list -s full-only
 ```
 
 如果你想先清空之前的扫描记录，再做一次全新的 list：
 
 ```bash
-mpy-cli list --reset
+mpy-cli list -r
 ```
 
 输出会包含当前探测到的所有可用 MicroPython 设备，例如端口、实现版本、平台与机型信息。
 
 ### `mpy-cli deploy`
 
 ```bash
-mpy-cli deploy [--mode {incremental,full}] [--base BASE] [--port PORT] [--no-interactive] [--yes]
+mpy-cli deploy [-m {incremental,full}] [--mode {incremental,full}] [-b BASE] [--base BASE] [-p PORT] [--port PORT] [-n] [--no-interactive] [-y] [--yes]
 ```
 
-- `--mode`：指定同步模式（`incremental` 或 `full`）。
-- `--base`：仅在 `incremental` 模式生效，指定 Git 基准提交；未提供时默认对比 `HEAD` 与当前工作区。
-- `--port`：指定设备端口。
-- `--no-interactive`：禁用交互提问。
-- `--yes`：跳过执行前确认（包括全量模式二次确认）。
+- `-m`/`--mode`：指定同步模式（`incremental` 或 `full`）。
+- `-b`/`--base`：仅在 `incremental` 模式生效，指定 Git 基准提交；未提供时默认对比 `HEAD` 与当前工作区。
+- `-p`/`--port`：指定设备端口。
+- `-n`/`--no-interactive`：禁用交互提问。
+- `-y`/`--yes`：跳过执行前确认（包括全量模式二次确认）。
 
 推荐用法：
 
 ```bash
-mpy-cli deploy --no-interactive --yes
+mpy-cli deploy -n -y
 ```
 
 进行 `config` 之后直接无交互烧入
 
 ### `mpy-cli upload`
 
 ```bash
-mpy-cli upload [--local LOCAL] [--remote REMOTE] [--port PORT] [--no-interactive] [--yes]
+mpy-cli upload [-l LOCAL] [--local LOCAL] [-r REMOTE] [--remote REMOTE] [-p PORT] [--port PORT] [-n] [--no-interactive] [-y] [--yes]
 ```
 
-- `--local`：本地文件路径（如 `seekfree_demo/E01_demo.py`）。
-- `--remote`：设备目标路径；不传时交互模式默认优先使用“相对 `source_dir` 路径”，若本地文件不在 `source_dir` 下则回退为本地输入路径，可手动修改。
-- `--port`：指定设备端口。
-- `--no-interactive`：禁用交互提问；此时需显式提供 `--local` 和 `--remote`。
-- `--yes`：跳过执行前确认。
+- `-l`/`--local`：本地文件路径（如 `seekfree_demo/E01_demo.py`）。
+- `-r`/`--remote`：设备目标路径；不传时交互模式默认优先使用“相对 `source_dir` 路径”，若本地文件不在 `source_dir` 下则回退为本地输入路径，可手动修改。
+- `-p`/`--port`：指定设备端口。
+- `-n`/`--no-interactive`：禁用交互提问；此时需显式提供 `--local` 和 `--remote`。
+- `-y`/`--yes`：跳过执行前确认。
 
 推荐用法：
 
 ```bash
-mpy-cli upload --local <LOCAL>
+mpy-cli upload -l <LOCAL>
 ```
 
 填写字段 `LOCAL` 指定本地文件路径之后交互式确认远程路径
 
 ### `mpy-cli run`
 
 ```bash
-mpy-cli run [--path PATH] [--port PORT] [--no-interactive] [--yes]
+mpy-cli run [-f PATH] [--path PATH] [-p PORT] [--port PORT] [-n] [--no-interactive] [-y] [--yes]
 ```
 
-- `--path`：设备目标文件路径，语义为相对 `device_upload_dir`。
-- `--port`：指定设备端口。
-- `--no-interactive`：禁用交互提问；此时需显式提供 `--path`。
-- `--yes`：跳过执行前确认。
+- `-f`/`--path`：设备目标文件路径，语义为相对 `device_upload_dir`。
+- `-p`/`--port`：指定设备端口。
+- `-n`/`--no-interactive`：禁用交互提问；此时需显式提供 `--path`。
+- `-y`/`--yes`：跳过执行前确认。
 
 推荐用法：
 
 ```bash
-mpy-cli run --path main.py
+mpy-cli run -f main.py
 ```
 
 若配置 `device_upload_dir = "apps/demo"`，则会执行 `:apps/demo/main.py`。
 
 ### `mpy-cli delete`
 
 ```bash
-mpy-cli delete [--path PATH] [--port PORT] [--no-interactive] [--yes]
+mpy-cli delete [-f PATH] [--path PATH] [-p PORT] [--port PORT] [-n] [--no-interactive] [-y] [--yes]
 ```
 
-- `--path`：设备目标路径，语义为相对 `device_upload_dir`，可为文件或目录。
-- `--port`：指定设备端口。
-- `--no-interactive`：禁用交互提问；此时需显式提供 `--path`。
-- `--yes`：跳过执行前确认。
+- `-f`/`--path`：设备目标路径，语义为相对 `device_upload_dir`，可为文件或目录。
+- `-p`/`--port`：指定设备端口。
+- `-n`/`--no-interactive`：禁用交互提问；此时需显式提供 `--path`。
+- `-y`/`--yes`：跳过执行前确认。
 
 推荐用法：
 
 ```bash
-mpy-cli delete --path obsolete.py
+mpy-cli delete -f obsolete.py
 ```
 
 若配置 `device_upload_dir = "apps/demo"`，则会删除 `:apps/demo/obsolete.py`。
@@ -340,17 +340,17 @@ mpy-cli delete --path obsolete.py
 ### `mpy-cli tree`
 
 ```bash
-mpy-cli tree [--path PATH] [--port PORT] [--no-interactive]
+mpy-cli tree [-a PATH] [--path PATH] [-p PORT] [--port PORT] [-n] [--no-interactive]
 ```
 
-- `--path`：设备目标目录路径，语义为相对 `device_upload_dir`；不传时默认读取 `device_upload_dir` 根目录。
-- `--port`：指定设备端口。
-- `--no-interactive`：禁用交互提问；此时需通过 `--port` 或配置文件提供端口。
+- `-a`/`--path`：设备目标目录路径，语义为相对 `device_upload_dir`；不传时默认读取 `device_upload_dir` 根目录。
+- `-p`/`--port`：指定设备端口。
+- `-n`/`--no-interactive`：禁用交互提问；此时需通过 `--port` 或配置文件提供端口。
 
 推荐用法：
 
 ```bash
-mpy-cli tree --path .
+mpy-cli tree -a .
 ```
 
 若配置 `device_upload_dir = "apps/demo"`，则默认读取 `:apps/demo`；例如 `--path services` 会读取 `:apps/demo/services`。

docs/plans/2026-03-11-cli-short-options-design.md

@@ -0,0 +1,114 @@
+# CLI 短参数同义设计文档
+
+## 背景
+
+当前 `mpy-cli` 的子命令参数以长选项为主，可读性较好，但在高频命令行使用场景下输入偏长。用户希望为每个命令的每个参数补充单字符短选项，同一语义可以同时支持长短两种写法。
+
+## 目标
+
+- 为所有现有子命令参数增加单字符短选项同义。
+- 保持现有长选项行为完全兼容。
+- 允许短选项在不同子命令内复用，不强求全局唯一。
+- 保持 `README.md`、CLI 帮助输出与测试同步。
+
+## 方案对比
+
+### 方案 A（推荐）按参数名直觉分配，子命令内解决冲突
+
+- 优先使用参数名首字母，例如 `--mode -> -m`、`--port -> -p`。
+- 若同一子命令内冲突，再为冲突参数选次优字母。
+- 优点：大多数参数一眼可猜，记忆成本最低。
+- 缺点：少量参数需要非首字母，如 `--no-interactive -> -n`。
+
+### 方案 B 统一按参数类别分配
+
+- 路径类、布尔类、模式类分别使用固定字母集合。
+- 优点：风格整齐。
+- 缺点：不如按参数名直接映射直观，用户仍需额外记规则。
+
+### 方案 C 仅为高频参数补短选项
+
+- 减少冲突与文档维护成本。
+- 缺点：不满足“每个命令的每个参数都增加短选项”的需求。
+
+最终采用方案 A。
+
+## 命令设计
+
+### `init`
+
+```bash
+mpy-cli init [-f|--force] [-n|--no-interactive]
+```
+
+### `list`
+
+```bash
+mpy-cli list [-w|--workers N] [-t|--probe-timeout SECONDS] [-s|--scan-mode MODE] [-r|--reset]
+```
+
+### `plan` / `deploy`
+
+```bash
+mpy-cli plan [-m|--mode {incremental,full}] [-b|--base BASE] [-p|--port PORT] [-n|--no-interactive] [-y|--yes]
+mpy-cli deploy [-m|--mode {incremental,full}] [-b|--base BASE] [-p|--port PORT] [-n|--no-interactive] [-y|--yes]
+```
+
+### `upload`
+
+```bash
+mpy-cli upload [-l|--local PATH] [-r|--remote PATH] [-p|--port PORT] [-n|--no-interactive] [-y|--yes]
+```
+
+### `run`
+
+```bash
+mpy-cli run [-f|--path PATH] [-p|--port PORT] [-n|--no-interactive] [-y|--yes]
+```
+
+### `delete`
+
+```bash
+mpy-cli delete [-f|--path PATH] [-p|--port PORT] [-n|--no-interactive] [-y|--yes]
+```
+
+### `tree`
+
+```bash
+mpy-cli tree [-a|--path PATH] [-p|--port PORT] [-n|--no-interactive]
+```
+
+- `tree` 内 `--path` 与 `--port` 均可能争用 `-p`。
+- 为保证高频串口参数的一致性，保留 `--port -> -p`。
+- `tree --path` 退让为 `-a`，取自 p`a`th 中次优可用字符，虽然不如 `-p` 直觉，但可避免同一子命令歧义。
+
+## 架构与影响面
+
+1. 在 `mpy_cli/cli.py` 的 `build_parser()` 中为每个 `add_argument()` 增加短选项别名。
+2. 参数 `dest`、默认值、行为分支不变，仅扩展 `argparse` 接受的输入形式。
+3. 在 `tests/test_cli.py` 中新增回归测试，覆盖典型短选项解析结果。
+4. 更新 `README.md` 的命令示例与参数总览。
+5. 如 `tests/test_docs_and_ci.py` 对 README/参数文本有同步校验，需要一并更新。
+
+## 错误处理
+
+- 不引入新的业务错误码。
+- 若短选项冲突，问题应在解析器构建阶段暴露，因此实现时需确保同一子命令内唯一。
+- 长选项保持兼容，避免破坏现有脚本或用户习惯。
+
+## 测试策略
+
+- 在 `tests/test_cli.py` 中增加短选项解析测试：
+  - `plan/deploy` 的 `-m/-b/-p/-n/-y`
+  - `list` 的 `-w/-t/-s/-r`
+  - `upload` 的 `-l/-r/-p/-n/-y`
+  - `run/delete/tree` 的冲突参数映射
+- 运行 `tests/test_docs_and_ci.py`，确保 README 与 CLI 定义同步。
+- 运行全量测试，确认短选项扩展没有影响既有行为。
+
+## 验收标准
+
+- 每个现有 CLI 参数都存在一个可用的单字符短选项。
+- 长选项与既有行为保持兼容。
+- 同一子命令内不存在短选项冲突。
+- README、帮助输出、测试全部同步通过。