RFC: NeoCode 命令行体验 (CLI UX) 重新设计

[pionxe]

[CLI] 优化交互体验：补齐全局简写习惯与重构适配器命令架构

目标问题

当前 NeoCode CLI 的命令树和参数在整体上表现出良好的一致性（如资源管理使用 ls/rm，服务管理使用 install/status），但在“高频用户肌肉记忆”和“单单词顶层命令架构”方面存在少量体验断层：

1. 全局版本查询缺失：缺乏常用的 -v / --version 全局拦截，用户输入 neocode -v 会报 unknown flag，必须输入 neocode version。
2. 短标识缺失：高频全局参数 --workdir 和模型参数 --model 缺乏符合直觉的单字母别名（-w, -m）。
3. 顶层命令风格破坏：现有的 feishu-adapter 是唯一使用 kebab-case 的顶层命令，既破坏了顶层“单单词名词/动词”的对称美学，也不利于未来接入其他协作平台（如钉钉、企微）的扩展规划。

实现设计

本任务将在不影响现有核心业务链路的前提下，对 CLI 层进行体验调优与结构重构：

1. 统一 Version 习惯：在 internal/cli/root.go 级别支持并拦截 -v / --version 标志，复用 version_command.go 的核心输出逻辑。
2. 补齐高频参数短别名：通过 Cobra 的 *P 方法，为关键参数注册单字母别名。
3. 适配器插件化重构（Breaking Change）：引入统一的 adapter 命令组，将原飞书适配器降级为子命令，即由 neocode feishu-adapter 改为 neocode adapter feishu，为后续构建插件化生态奠定标准。

任务清单

• 构建 adapter 命令组
  • 在 internal/cli 创建 adapter_command.go，定义并注册 adapter 顶层命令。
  • 将原 feishu_adapter_command.go 挂载为 adapter 的子命令。
  • 清理相关的测试用例及调用链路。
• 完善全局 -v / --version 支持
  • 修改 internal/cli/root.go，支持原生的 --version 标志并桥接版本探测逻辑，保证退出状态码与直接执行 neocode version 一致。
• 添加参数短别名
  • 修改 root.go，将 --workdir 注册改为 PersistentFlags().StringP("workdir", "w", ...)
  • 修改 use_command.go，将 --model 注册改为 Flags().StringVarP(&opts.Model, "model", "m", ...)
• 更新周边文档与自动化脚本
  • 更新 README.md 或其他包含 CLI 使用说明的文档（将 feishu-adapter 替换为 adapter feishu）。
• 执行全面回归测试
  • 确保 internal/cli 整体测试覆盖率满足强制 100% 目标。

测试验证

• 正常路径：
  • 执行 neocode -v 和 neocode --version 能正确输出当前版本及升级提示，无报错。
  • 执行 neocode web -w /tmp 能够被正确解析为工作目录。
  • 执行 neocode use openai -m gpt-4 能够成功切换模型。
  • 执行 neocode adapter feishu --help 能够正确拉起适配器的帮助信息。
• 异常分支：
  • 旧命令 neocode feishu-adapter 应优雅地报错或提示命令已变更。

风险与回滚

• 风险：低。主要为 CLI 解析层的路由更改。唯一的破坏性变更（Breaking Change）是 feishu-adapter 的更名，若用户有存量的 Shell/Systemd 启动脚本，升级后会执行失败。
• 回滚：发现不可预期的启动崩溃或 TUI 初始化阻塞时，直接 Revert 对应 PR 的 CLI 修改即可，不涉及持久化状态数据污染。

[phantom5099]

截至时间：2026.05.09
卡点：可能需要新的实现