refactor: normalize default CLI interactive flows (#172)

* refactor: unify interactive CLI input handling

* refactor: normalize gh interactive inputs

* refactor: normalize zulip image and chatenv inputs

* refactor: finish remaining interactive cli defaults

* refactor: normalize remaining interactive entrypoints

* docs: align cli interaction guidance

* feat: add pypi and tplogin cli shortcuts

* docs: add cli normalization report

Author: RexWzh

AGENTS.md

@@ -38,6 +38,8 @@ mkdocs serve --no-livereload # 本地预览文档
 - `-i` 强制开启交互，`-I` 强制关闭（参数不全则报错）
 - 参数默认值从环境变量读取，敏感值在提示中自动 mask
 - 所有 CLI 交互统一走 `src/chattool/interaction/`
+- 新 CLI 默认优先使用 `src/chattool/interaction/command_schema.py` 里的 `CommandField` / `CommandSchema` / `CommandConstraint` / `resolve_command_inputs()` / `add_interactive_option()`，不要在每个命令里重复手写缺参判断、TTY 检查和 prompt 流程
+- 对可恢复缺参，避免直接使用 Click 的 `required=True` 或必填位置参数；否则会在 callback 执行前被 Click 拦截，统一交互机制无法运行
 - 进入 interactive 后，补全当前任务相关的关键参数
 - interactive 展示的默认值必须与实际执行一致
 - `-i` 进入当前命令交互流程，`-I` 完全禁用交互

CHANGELOG.md

@@ -7,6 +7,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 ## [Unreleased]
 
 ### Fixed
+- `src/chattool/interaction/` 新增声明式 CLI 输入规范层：统一提供 `CommandField` / `CommandSchema` / `CommandConstraint` / `resolve_command_inputs()` / `add_interactive_option()`，把缺参补问、`-i/-I` 语义、TTY 检查和多字段约束从各命令的重复样板中收口到共享模块；`chattool dns`、`chattool client cert`、`chattool client svg2gif`、`chattool gh`、`chattool zulip`、`chattool image`、`chatenv` 高频 profile/key 命令、`chattool explore arxiv get`、`chattool network ping`、`chattool dns cert-update` 已切到这套机制，并补充了相应 mock CLI 测试与开发文档规范
+- `chattool dns` 现在在交互终端里默认进入命令选择；`chattool dns get` / `set` / `ddns` 缺少必要参数时会自动补问，`-I` 才显式禁用交互并报错；同时 `ddns` 的监控间隔短参数收口为仅保留 `--interval`，避免与统一的 `-i` 交互开关冲突
 - `chattool pypi probe` 现在默认检查正式 `pypi`，收口为更直接的精确项目名可用性检查：名称已占用时直接给出阻塞结论，并补充作者、摘要、链接、最新版本等少量有用信息；不再默认查 `testpypi`，也不再输出一组对决策无帮助的固定状态项
 - `chattool nginx static-root` 的默认站点根目录现从 NAS 风格示例调整为更通用的 `/var/www/example-site`，交互默认值、文档和测试同步更新
 - `chattool setup` 中通过 npm 执行安装或检查时，现会先打印真实的 `npm ...` 命令，方便用户确认当前实际在执行什么

DEVELOP.md

@@ -15,6 +15,8 @@
 - 新能力先落 `tools/<name>/`，再接入 `client/mcp/serve`。
 - CLI 统一 `-i/-I` 与缺参自动交互规则。
 - 所有 CLI 交互统一走 `src/chattool/interaction/`。
+- 新 CLI 默认优先使用 `src/chattool/interaction/command_schema.py` 里的 `CommandField` / `CommandSchema` / `CommandConstraint` / `resolve_command_inputs()` / `add_interactive_option()`，不要在每个命令里重复手写缺参判断、TTY 检查和补问流程。
+- 对可恢复缺参，避免直接使用 Click 的 `required=True` 或必填位置参数；否则命令会在进入 callback 前被 Click 拦截，统一交互机制不会生效。
 - 进入 interactive 后，补全当前任务相关的关键参数。
 - prompt 默认值必须与实际执行一致，敏感值默认脱敏。
 - 任何新增或修改的 CLI 都必须统一满足这些规则，不能只让当前命令局部符合。

README.md

@@ -103,12 +103,15 @@ bot.start()
 ### DNS 管理 (`chattool dns`)
 
 ```bash
+chattool dns
 chattool dns get home.example.com
 chattool dns set home.example.com -v 1.2.3.4
 chattool dns ddns home.example.com --monitor
 chattool dns cert-update -d example.com -e admin@example.com
 ```
 
+交互终端里直接运行 `chattool dns` 会先进入命令选择；`get` / `set` / `ddns` 缺少必要参数时会自动补问，`-I` 才会禁用交互并直接报错。
+
 ### Nginx 配置生成 (`chattool nginx`)
 
 ```bash
@@ -124,17 +127,23 @@ chattool nginx -i  # 交互式选择模板并逐项填写
 ```bash
 chattool image pollinations generate "a cat in space" -o cat.png
 chattool image siliconflow generate "a cute dog" -o dog.png
+chattool image huggingface generate
 ```
 
+交互终端里，各家 `generate` 命令缺少 `prompt` 时会自动补问；`huggingface generate` 缺少 `-o/--output` 也会自动补问。显式传 `-I` 时保持直接报错。
+
 ### 数据探索 (`chattool explore`)
 
 ```bash
 chattool explore arxiv search -p ai4math -n 10
 chattool explore arxiv daily -p math-formalization --days 3
 chattool explore arxiv daily -p math-formalization-weekly --days 7 -v
 chattool explore arxiv get 1706.03762 -v
+chattool explore arxiv get
 ```
 
+交互终端里，`chattool explore arxiv get` 缺少 arXiv ID 时会自动补问。
+
 ### 其他工具
 
 | 工具 | 命令 | 说明 |
@@ -166,8 +175,11 @@ PyPI 发布命令设计草案见 `docs/design/chattool-pypi-cli-design.md`
 ```bash
 chattool pypi init mychat
 chattool pypi init cli-style mycli
+chatpypi mychat
 ```
 
+`chatpypi` 现在是更直接的快捷入口：传入普通首参数时，会自动按 `chattool pypi init <name>` 处理；如果首参数本身就是 `init/build/check/upload/probe` 之一，则保持原样透传给 `chattool pypi`。
+
 默认生成的 `pyproject.toml` 会写入 `requires-python = ">=3.9"`。
 
 `cli-style` 模板会额外生成 `DEVELOP.md`、`setup.md`、`CHANGELOG.md`、`AGENTS.md`、`docs/`、`cli-tests/`、`mock-cli-tests/` 与 `.github/workflows/` 骨架，并默认依赖 `chatstyle` 作为可复用 CLI 运行时。

docs/client.md

@@ -334,7 +334,7 @@ chattool dns set test.example.com -v 1.2.3.4
 chattool dns set -d example.com -r _test -t TXT -v "some-value"
 ```
 **选项:**
-- `-v, --value`: 记录值 (必填)。
+- `-v, --value`: 记录值。交互终端里缺少时会自动补问；显式传 `-I` 时才保持直接报错。
 - `-t, --type`: 记录类型 (默认: `A`)。
 - `--ttl`: TTL 值 (默认: 600)。
 - `-p, --provider`: DNS 提供商 (默认: `aliyun`)。
@@ -345,8 +345,11 @@ chattool dns set -d example.com -r _test -t TXT -v "some-value"
 
 ```bash
 chattool dns cert-update -d example.com -d *.example.com -e admin@example.com
+chattool dns cert-update
 ```
 
+在交互终端里，缺少域名或邮箱时会自动补问；显式传 `-I` 时才会禁用交互并直接报错。
+
 **输出文件结构:**
 证书将保存在 `<cert-dir>/<domain>/` 目录下，包含以下文件：
 - `fullchain.pem`: 完整证书链 (适用于 Nginx/Apache 配置)。
@@ -377,10 +380,11 @@ chattool dns cert-update -d example.com -d *.example.com -e admin@example.com
 #### 申请证书 (`apply`)
 ```bash
 chattool client cert apply -d example.com -d *.example.com --token my-secret-token
+chattool client cert apply
 ```
 **选项:**
-- `-d, --domain`: 域名列表 (必填)。
-- `-e, --email`: 邮箱 (如果配置了 `git config user.email` 则可选，否则必填)。
+- `-d, --domain`: 域名列表。缺少时会在交互终端里自动补问。
+- `-e, --email`: 邮箱。默认优先尝试 `git config user.email`，缺少时会自动补问。
 - `-p, --provider`: DNS 提供商 (可选)。
 - `--secret-id/--secret-key`: 云厂商凭证 (可选)。
 
@@ -393,9 +397,12 @@ chattool client cert list --token my-secret-token
 #### 下载证书 (`download`)
 ```bash
 chattool client cert download example.com -o ./my-certs --token my-secret-token
+chattool client cert download
 ```
 下载指定域名的证书文件 (`cert.pem`, `privkey.pem`, `fullchain.pem`) 到本地目录。
 
+在交互终端里，`download` 缺少 domain 时会自动补问；显式传 `-I` 时保持直接报错。
+
 ---
 
 ## 3. 网络工具 (`network`)
@@ -405,8 +412,11 @@ chattool client cert download example.com -o ./my-certs --token my-secret-token
 ### 3.1 存活扫描 (`network ping`)
 ```bash
 chattool network ping --network 192.168.1.0/24
+chattool network ping
 ```
 
+交互终端里缺少 `--network` 时会自动补问；`-I` 会禁用交互。
+
 ### 3.2 端口扫描 (`network ssh`)
 ```bash
 chattool network ssh --network 192.168.1.0/24 --port 22
@@ -454,6 +464,7 @@ chattool gh pr-list --state open --limit 20
 
 # 查看 PR 详情（含 mergeable / merge state）
 chattool gh pr-view --number 123
+chattool gh pr-view
 
 # 查看 PR 的可合并状态与 CI / checks 状态
 chattool gh pr-check --number 123
@@ -468,6 +479,7 @@ chattool gh job-logs --job-id 68373094563
 
 # 创建 PR
 chattool gh pr-create --base vibe/master --head feature-branch --title "Title" --body "Body"
+chattool gh pr-create
 
 # 评论 PR
 chattool gh pr-comment --number 123 --body "Looks good"
@@ -489,6 +501,8 @@ chattool gh set-token --token github_pat_xxx --save-env
 chattool gh repo-perms --repo owner/repo --token github_pat_xxx
 ```
 
+在交互终端里，`pr-create` / `pr-view` / `pr-check` / `run-view` / `job-logs` / `pr-comment` / `pr-merge` / `pr-update` 缺少关键参数时都会自动补问；显式传 `-I` 才禁用交互并直接报错。
+
 `set-token` 只在当前目录存在 git remote，且 `origin` 指向 GitHub 仓库时生效。它会按仓库路径写入本地 Git HTTPS credential，因此不同仓库可以使用不同 token。
 
 默认情况下，`set-token` 不会改写 `GITHUB_ACCESS_TOKEN`。只有显式传 `--save-env`，才会把 token 写入 `chatenv gh` 对应的 GitHub 配置。
@@ -578,6 +592,10 @@ chattool chatenv cat -t zulip
 # 列出订阅的 streams
 chattool zulip streams
 
+# 缺少 stream/topic 时自动补问
+chattool zulip topics
+chattool zulip topic
+
 # 查看消息（支持过滤）
 chattool zulip messages --stream general --before 20
 
@@ -587,6 +605,8 @@ chattool zulip news --since-hours 24 --stream general --stream announcements
 
 默认输出文件：`zulip-news-YYYYMMDD.md`（当前目录），可用 `--output` 覆盖。
 
+在交互终端里，`topics` / `topic` 缺少关键参数时会自动补问；显式传 `-I` 时保持直接报错。
+
 ---
 
 ## 6. 环境管理 (`env`)
@@ -608,6 +628,14 @@ chattool env get CHATTOOL_DNS_PROVIDER
 
 # 删除配置值
 chattool env unset CHATTOOL_DNS_PROVIDER
+
+# 缺少 key / profile 名时自动补问
+chattool env save -t gh
+chattool env use -t gh
+chattool env delete -t gh
+chattool env get
+chattool env set
+chattool env unset
 ```
 
 **命令详解:**
@@ -617,6 +645,8 @@ chattool env unset CHATTOOL_DNS_PROVIDER
 - `get`: 获取单个配置项的值。
 - `unset`: 删除（置空）单个配置项的值。
 
+在交互终端里，`save/use/delete/get/set/unset/test` 缺少关键参数时都会自动补问；显式传 `-I` 才禁用交互并直接报错。
+
 ---
 
 ## 6. 本地服务器工具 (`serve`)