言令：命令行解析

言令（yanxu-cli）1.0.0 是纯言序的声明式命令行解析库。它处理已经由宿主分词的 argv，支持长短选项、组合短开关、类型转换、位置参数、子命令、帮助和确定性上下文补全，但不会执行 shell 文本或业务操作。

版本与安装

yanbao add 言令 \
  --git https://github.com/yanxulang/yanxu-cli.git \
  --rev v1.0.0 \
  --version '^1.0'

[依赖]
言令 = { git = "https://github.com/yanxulang/yanxu-cli.git", 修订 = "v1.0.0", 版 = "^1.0" }

提交生成的 言序.lock，固定公开标签对应的修订与内容校验。

核心能力：声明并解析命令

引「包:言令」为 言令；

定 程序 为 言令.命令（「构建器」，「构建言序项目」）；

程序.加开关（「verbose」，「v」，「输出详细日志」）
    .加默认选项（「jobs」，「j」，「数量」，「数」，「并行数量」，4）
    .加多值选项（「feature」，「f」，「能力」，「文」，「启用能力」）
    .加参数（「入口」，「入口文件」，真）
    .加余项（「文件」，「其余文件」）；

定 尝试：典 为 程序.尝试解析（
    【「-v」，「--jobs=8」，「主.yx」，「附加.yx」】
）；

若 尝试【「成功」】 则
    定 结果：典 为 尝试【「结果」】；
    言 结果【「选项」】【「jobs」】；
    言 结果【「参数」】【「入口」】；
否则
    言 尝试【「错误详情」】【「代码」】；
    言 尝试【「帮助文」】；
终

真实命令行使用 解析当前或尝试解析当前。库只返回数据，不打印帮助、不选择退出码，也不调用业务逻辑。

声明接口与值类型

取值类型支持：

• 文：保留 argv 原文；
• 数：按 JSON 数字语法解析，拒绝逻辑、空和容器；
• 理：接受 true/false、1/0和真/假；
• JSON：恢复任意合法 JSON 值。

支持的选项形式包括 --name value、--name=value、-n value、-nvalue、组合短开关和显式 --终止。真实声明的 --no-color优先于合成否定语法。

长名和值名须为 1–128 字，不能以连字符开头，也不能含空白、控制符或等号。短名为空或单个有效字符；help、帮助和短名 h由内建帮助保留。

子命令与结果模式 v1

定 根 为 言令.命令（「包」，「管理依赖」）
    .加开关（「verbose」，「v」，「详细输出」）；

定 添加 为 言令.命令（「add」，「添加依赖」）
    .加开关（「dev」，「d」，「开发依赖」）
    .加参数（「包」，「包名」，真）；

根.加子命令（添加）；

定 结果：典 为 根.解析（【「-v」，「add」，「-d」，「http」】）；
言 结果【「子结果」】【「参数」】【「包」】；

普通解析结果固定包含：

• 模式版本：当前为 1；
• 命令路径与命令；
• 帮助与帮助文；
• 当前层的选项与参数；
• 子命令与下一层子结果。

尝试解析固定返回 模式版本/成功/结果/错误/错误详情/帮助文六个键。程序应按错误详情.代码分支；完整消息可以改进，不是兼容协议。

必需位置参数必须先于可选参数，余项必须最后且只能有一个。同一命令不能同时声明必需根位置参数与子命令；可选位置参数或余项可以与子命令并存，但两者是互斥入口。

解析配置与补全

按配置解析、按配置解析当前、尝试按配置解析和按配置补全接受这些逻辑覆盖：

未知配置键或非逻辑值会失败，不会静默忽略。

定 补全：典 为 程序.补全（【「--jo」】）；
言 补全【「命令路径」】；
言 补全【「上下文」】；
言 补全【「候选」】；

补全把最后一个元素视为正在输入的前缀；刚输入空格时，外层适配器应追加空文。它只理解 argv 词元，不拆分引号和转义，不读取文件系统，也不执行候选。

资源、权限与安全边界

言令无第三方依赖，不申请文件、网络、监听、环境、进程或原生扩展权限。规格快照、默认容器和解析结果都会深复制，调用方修改返回值不会回写命令声明。

已知限制与安全责任

• 言令不是 shell：不展开引号、变量、通配符或命令替换，也不执行参数。
• 位置参数统一为文字；路径安全、权限、业务类型和授权必须在解析后另行验证。
• 帮助、错误和补全可能回显名称、说明或参数片段，不能把秘密写入规格说明或默认值。
• 补全候选仍须由适配器按目标 shell 正确转义，不能直接拼成命令执行。
• 命令对象包含可变声明状态，构建完成后应按只读方式共享；库不提供并发修改协调。

项目链接

• GitHub 仓库
• 言令 1.0.0 Release