cli: one command per verb, per-family dispatch; experiment train/test scripts

[vividf]

Stacked PR 9/15 — ⬅ #18 | #20 ➡

Stack(base pr-stack-base = 7e35d97):#11 → #12 → #13 → #14 → #15 → #16 → #17 → #18 → #19 → #20(CenterPoint 全功能點)→ #21 → #25 → #22 → #23 → #24(= 開發 branch HEAD,逐位元一致)。合併由下而上,每合一層把下一層 base retarget。

這個 PR 是什麼

CLI:一個動詞一個命令(train/deploy/quantize/test/create-dataset),由 config 路徑前綴(tasks/ vs experiments/)分派到 family 實作——不管什麼模型,命令長得一樣。

設計決策

• dispatch 表:(command, family) → entrypoint module,lazy import(CLI 啟動不載重模組)。
• 啟動速度是被測試守護的契約:test_importing_cli_does_not_import_mlflow_or_hydra。config-family prefix 常數因此單一來源在輕量的 utils/cli/helpers.py(曾在 cli.py/runtime.py 重複定義正是為了避開重 import;現在單源 + 約束寫在定義處)。Review 時別把它們搬回 runtime.py。
• completion callbacks 獨立在 cli/completion.py(每種可補全參數一個有 docstring 的 wrapper;候選發現在 helpers)。
• scripts rename:multi_task_{train,test}.py → experiment_{train,test}.py(family 通用化)。

逐檔導覽

• cli/cli.py:命令定義、OptionFirstTyperCommand(空 token 也給 option 補全)、dispatch、session 管理命令。
• cli/completion.py:補全 wrappers。
• cli/runtime.py:重量級 runtime(hydra compose、entrypoint 執行)。
• utils/cli/helpers.py:補全候選發現、prefix 常數。
• tests/cli/test_cli.py:60+ 測試(dispatch、補全、session、啟動 import 契約)。

檔案清單(點開)

autoware_ml/cli/cli.py 403 +++++++--------------
autoware_ml/cli/completion.py 118 ++++++
autoware_ml/cli/runtime.py 42 ++-
.../{multi_task_test.py experiment_test.py} |
.../{multi_task_train.py experiment_train.py} |
autoware_ml/tests/cli/test_cli.py 64 +++-
autoware_ml/utils/cli/helpers.py 13 +-
docs/contributing/adding-models.md 7 +-
docs/user-guide/cli.md 47 ++-
zensical.toml 1 +

Review checklist

• dispatch 表可讀性;新增 family 的步驟是否自明。
• 已知:tests/cli 有 2 個既有失敗(session/completion 環境相關,base 就存在,非本 stack 引入)。

🤖 Generated with Claude Code