Skip to content

fix(cli): show help for subcommands missing arguments - #428

Merged
x-lixu merged 2 commits into
QwenAudio:mainfrom
kevin9327:fix-cli-subcommand-help
Sep 17, 2026
Merged

x-lixu merged 2 commits into
QwenAudio:mainfrom
kevin9327:fix-cli-subcommand-help

Conversation

@kevin9327

Copy link
Copy Markdown
Contributor

变更说明

现象:对需要位置参数的子命令查看帮助时,CLI 直接报错退出,而不是显示帮助:

$ qwenaudio install --help
qwenaudio: install 缺少后台名称(可选:opencode、openclaw、qoder、qwen、minimax、kimi、hermes、codebuddy、codex、claude、deepseek、pi、acp)
$ qwenaudio skill --help
qwenaudio: skill 需要子命令(可选:install、list、remove、update)
$ qwenaudio config set --help
qwenaudio: config set 需要 --realtime-model
$ qwenaudio gateway revoke --help
qwenaudio: gateway revoke 需要设备 ID

qwenaudio tui --helpqwenaudio --help 可以正常显示帮助。

原因parseArguments() 先消费子命令的位置参数并执行“缺少参数”“选项只适用于某命令”等校验,--help 只在后面的循环里记录为 options.help。校验提前抛错时,launcher 永远到不了 if (options.help) 分支。launcher 已经把任何带 --help / -h 的调用视为只读命令,说明帮助本应在参数不完整时也可用。

修复:保持原有解析与校验逻辑不变,外层在解析抛错且参数中包含 --help / -h、命令本身合法时,返回 { command, help: true },由 launcher 显示帮助。未请求帮助时仍报告原来的错误;未知命令带 --help 仍报“未知命令”。

验证

本机 Windows 11,Node 24.17.0。

新增测试 shows help for subcommands that otherwise require arguments,覆盖上述四个子命令,并确认不带 --helpinstall 与带 --help 的未知命令仍然报错。

修复前:

✖ shows help for subcommands that otherwise require arguments
  Error: install 缺少后台名称(可选:opencode、openclaw、qoder、qwen、minimax、kimi、hermes、codebuddy、codex、claude、deepseek、pi、acp)
      at parseArguments (file:///.../cli/src/arguments.mjs:255:11)

修复后:

  • node --test cli/test/arguments.test.mjs(21 通过)
  • 实际运行 node cli/bin/qwenaudio.mjs install --help 等四个命令均输出帮助并以 0 退出
  • npm test(根目录与 server 工作区 1467 项:1464 通过、2 跳过、1 失败;其余工作区 899 项:882 通过、17 跳过、0 失败。唯一失败的 server/test/frontend-notes.test.mjs 跨进程文件锁用例只在 Windows 整轮高负载下超时,与本改动无关:单独连续运行 3 次均通过,且在未改动的 upstream/main 上整轮运行两次也复现一次同样的超时)
  • npm run lint
  • npm run build
  • 行为变化已补充测试

兼容性与安全

  • 未提交密钥、用户数据、日志或内部地址
  • 用户可见行为已更新 CHANGELOG;无配置或依赖变化
  • 仅影响带 --help / -h 且原本会解析失败的 CLI 调用;launcher 已按只读方式加载这类调用的环境,不涉及网络、权限、持久化或进程管理。回滚:还原本 PR。

🤖 Generated with Claude Code

kevin9327 and others added 2 commits September 13, 2026 22:19
Subcommand validation ran before --help was honored, so commands such as
`qwenaudio install --help` printed a missing-argument error instead of
the help text. Fall back to help when parsing fails for a known command
that explicitly asks for it; other errors are reported unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

@x-lixu x-lixu left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

感谢修复子命令帮助入口。已验证四类缺参帮助调用以 0 退出,普通缺参和未知命令仍报错;本地参数测试和代码检查通过,更新 main 后的各平台 CI 也已通过,审查通过。

@x-lixu
x-lixu merged commit 987ec83 into QwenAudio:main Sep 17, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants