Qi CLI

qi-cli 是一个用 **奇语（Qi）**写的命令行框架，方向参考了 spf13/cobra：

• 命令树
• 子命令
• 局部参数
• 持久参数（走 clap global，自动继承到子命令）
• 自动帮助
• 前置 / 后置 / 持久前置 / 持久后置执行钩子

底层参数解析继续复用 标准库.命令行，上层则提供更接近 Cobra 的命令组织方式。

📘 AI 辅助：本项目带 SKILL.md，可作为 agent skill 安装，让 AI 助手准确生成 qi-cli 代码。

项目结构

• CLI.qi：导出入口
• 模型.qi：应用 / 命令 / 参数 / 上下文类型
• 构建.qi：创建应用、命令、参数，以及命令树组装
• 上下文.qi：在处理函数里读取参数和标志
• 执行.qi：把命令树编译成原生命令行对象并完成分发

核心 API

• 创建应用("工具箱")
• 创建命令("问候")
• 创建参数("名字")
• 应用添加命令
• 命令添加子命令
• 应用添加参数
• 命令添加参数
• 参数长名 / 参数短名 / 参数帮助 / 参数默认值 / 参数标志 / 参数持久
• 命令执行 / 命令前置执行 / 命令后置执行 / 命令持久前置执行 / 命令持久后置执行
• 值 / 整数值 / 标志 / 存在值
• 执行(应用值)

用法示例

包 主程序;

导入 标准库.输入输出;
导入 CLI::{
    创建应用, 创建命令, 创建参数, 执行,
    应用简介, 应用添加命令,
    命令简介, 命令执行, 命令添加参数,
    参数帮助, 参数默认值,
    值
};

函数 执行问候(上下文值: 上下文) : 整数 {
    输入输出::打印行("你好，" + 值(上下文值, "名字") + "！");
    返回 0;
}

函数 入口() {
    变量 应用值: 应用 = 创建应用("工具箱");
    应用值 = 应用简介(应用值, "一个简单的 CLI");

    变量 问候命令: 命令 = 创建命令("问候");
    问候命令 = 命令简介(问候命令, "向某个人打招呼");
    问候命令 = 命令执行(问候命令, 执行问候);

    变量 名字参数: 参数 = 创建参数("名字");
    名字参数 = 参数帮助(名字参数, "要问候的名字");
    名字参数 = 参数默认值(名字参数, "世界");
    问候命令 = 命令添加参数(问候命令, 名字参数);

    应用值 = 应用添加命令(应用值, 问候命令);
    执行(应用值);
}

运行示例

先编译：

cargo run -q -p qi-compiler -- compile qi-cli/examples/工具箱.qi -o /tmp/qi_cli_toolbox

再运行：

/tmp/qi_cli_toolbox 问候 小李
/tmp/qi_cli_toolbox 服务 --端口 9001
/tmp/qi_cli_toolbox 用户 添加 小王

复杂示例

examples/ 还有几个组合标准库的真实场景示例，可以直接 qi run 跑：

示例	主要演示	子命令
工具箱.qi	命令树、持久参数、钩子	问候 / 服务 / 用户 添加
文件管理.qi	文件 IO + 加密模块	信息 / 哈希 / 备份 / 写入 / 追加
HTTP客户端.qi	HTTP 模块、httpie 风格	获取 / 发送 / 更新 / 删除 / 状态
待办.qi	持久 JSON 状态、字符串切分	添加 / 列表 / 完成 / 删除 / 清空
系统信息.qi	操作系统 + 网络 + 加密组合	概览 / 环境 / 设置 / 网络 / 哈希字符串
AI助手.qi	集成 qi-harness 调 DeepSeek	问 / 流 / 翻译 / 总结

跑 AI 示例需要先 export QI_LLM_KEY=sk-...。

当前边界

第一版先把这些能力做稳：

• 命令树和子命令
• 局部参数
• 持久参数继承
• 帮助输出
• 别名
• 前置 / 后置执行钩子

还没做的：

• shell completion
• 文档生成
• 隐藏命令 / 废弃命令
• 参数分组
• 自动脚手架生成器