qi-cli 快速开始：用奇语写 Cobra 风格命令行工具

包 主程序;

导入 标准库.输入输出 作为 IO;
导入 CLI::{ 创建应用, 应用简介, 应用执行, 执行 };

函数 根执行(上下文值: 上下文) : 整数 {
    IO.打印行("待办清单 CLI —— 用 --help 查看所有命令");
    返回 0;
}

函数 入口() {
    变量 应用值: 应用 = 创建应用("待办");
    应用值 = 应用简介(应用值, "一个用 qi-cli 写的待办清单工具");
    应用值 = 应用执行(应用值, 根执行);
    执行(应用值);  // 解析 argv 并分发
}

$ qi run 待办.qi
待办清单 CLI —— 用 --help 查看所有命令

函数 执行添加(上下文值: 上下文) : 整数 {
    变量 标题: 字符串 = 值(上下文值, "标题");
    IO.打印行("已添加待办: " + 标题);
    返回 0;
}

// 在 入口() 里：
变量 添加命令: 命令 = 创建命令("添加");
添加命令 = 命令简介(添加命令, "添加一条待办");
添加命令 = 命令执行(添加命令, 执行添加);
应用值 = 应用添加命令(应用值, 添加命令);

函数 执行添加(上下文值: 上下文) : 整数 {
    变量 标题: 字符串 = 值(上下文值, "标题");
    变量 优先级: 整数 = 整数值(上下文值, "优先级", 3);  // 带默认值
    IO.打印行("已添加待办: " + 标题 + "（优先级 " + 整数转字符串(优先级) + "）");
    如果 (标志(上下文值, "紧急") == 1) {       // 读布尔开关，0/1
        IO.打印行("  -> 标记为紧急");
    }
    返回 0;
}

// 位置参数：必需
变量 标题参数: 参数 = 创建参数("标题");
标题参数 = 参数帮助(标题参数, "待办标题（位置参数）");
标题参数 = 参数必需(标题参数);
添加命令 = 命令添加参数(添加命令, 标题参数);

// 带值 flag：--优先级 / -p，有默认值 3
变量 优先级参数: 参数 = 创建参数("优先级");
优先级参数 = 参数长名(优先级参数, "优先级");
优先级参数 = 参数短名(优先级参数, "p");
优先级参数 = 参数默认值(优先级参数, "3");
添加命令 = 命令添加参数(添加命令, 优先级参数);

// 布尔标志：--紧急
变量 紧急参数: 参数 = 创建参数("紧急");
紧急参数 = 参数长名(紧急参数, "紧急");
紧急参数 = 参数标志(紧急参数);
添加命令 = 命令添加参数(添加命令, 紧急参数);

变量 详细参数: 参数 = 创建参数("详细");
详细参数 = 参数长名(详细参数, "详细");
详细参数 = 参数短名(详细参数, "v");
详细参数 = 参数帮助(详细参数, "输出详细日志");
详细参数 = 参数标志(详细参数);
详细参数 = 参数持久(详细参数);          // 关键：继承到所有子命令
应用值 = 应用添加参数(应用值, 详细参数);

添加命令 = 命令添加别名(添加命令, "a");
列表命令 = 命令添加别名(列表命令, "ls");

// 持久前置钩子：执行前根据 --详细 打印路径
函数 全局前置(上下文值: 上下文) : 整数 {
    如果 (标志(上下文值, "详细") == 1) {
        IO.打印行("[详细] 即将执行: " + 命令路径(上下文值));
    }
    返回 0;
}

// 列表命令的局部前置/后置钩子
函数 列表前置(上下文值: 上下文) : 整数 {
    IO.打印行("--- 待办列表开始 ---");
    返回 0;
}
函数 列表后置(上下文值: 上下文) : 整数 {
    IO.打印行("--- 待办列表结束 ---");
    返回 0;
}

// 挂钩子（在 入口() 里）
添加命令 = 命令持久前置执行(添加命令, 全局前置);
列表命令 = 命令前置执行(列表命令, 列表前置);
列表命令 = 命令后置执行(列表命令, 列表后置);

变量 配置命令: 命令 = 创建命令("配置");
配置命令 = 命令简介(配置命令, "管理配置");

变量 设置命令: 命令 = 创建命令("设置");
设置命令 = 命令执行(设置命令, 执行配置设置);
// 两个必需位置参数：键、值
变量 键参数: 参数 = 参数必需(创建参数("键"));
设置命令 = 命令添加参数(设置命令, 键参数);
变量 值参数: 参数 = 参数必需(创建参数("值"));
设置命令 = 命令添加参数(设置命令, 值参数);

配置命令 = 命令添加子命令(配置命令, 设置命令);
应用值 = 应用添加命令(应用值, 配置命令);

$ qi run 教程_快速开始.qi -- 添加 "写教程" --优先级 1 --紧急
已添加待办: 写教程（优先级 1）
  -> 标记为紧急

$ qi run 教程_快速开始.qi -- a "买菜" -v
[详细] 即将执行: 待办 添加
已添加待办: 买菜（优先级 3）

$ qi run 教程_快速开始.qi -- 列表 --标签 工作
--- 待办列表开始 ---
1. 写 qi-cli 教程（优先级 1）
2. 跑通示例（优先级 2）
（已按标签过滤: 工作）
--- 待办列表结束 ---

$ qi run 教程_快速开始.qi -- 配置 设置 主题 暗色
配置已更新: 主题 = 暗色

$ qi run 教程_快速开始.qi -- --help
演示 qi-cli 的根命令、子命令、局部/持久参数、别名与执行钩子。

Usage: 教程_快速开始 [OPTIONS] [COMMAND]

Commands:
  添加    添加一条待办
  列表    列出所有待办
  配置    管理配置
  help  Print this message or the help of the given subcommand(s)

Options:
  -v, --详细     输出详细日志
  -h, --help    Print help (see a summary with '-h')
  -V, --version Print version

示例:
待办 添加 "写教程" --优先级 1
待办 列表 --标签 工作
待办 配置 设置 主题 暗色

$ qi run 教程_快速开始.qi -- 添加 --help
添加一条待办

Usage: 教程_快速开始 添加 [OPTIONS] <标题>

Arguments:
  <标题>  待办标题（位置参数）

Options:
  -p, --优先级 <优先级>  1-5，越小越重要 [default: 3]
  -v, --详细         输出详细日志
      --紧急         标记为紧急
  -h, --help       Print help

$ qi run 教程_快速开始.qi -- --version
待办 1.0.0

$ qi run 教程_快速开始.qi -- 添加
error: the following required arguments were not provided:
  <标题>

Usage: 教程_快速开始 添加 <标题>

For more information, try '--help'.