Table of Contents

Cli——命令行

KernLab.Loom.Cli:[CommandGroup]/[Command] 标注一次,编译期生成三件套——CLI 解析器(Run/RunAsync)、 HTTP 执行代理(TryHandleAsync 单一入口 + 编译期路由表)、JSON I/O 契约。无 Handler 派发层。

可运行 sample:samples/Cli/Commands(解析)、samples/Cli/HttpProxy(HTTP 代理)、samples/Cli/Completion(补全候选)。

从零跑通

[CommandGroup("traffic", Description = "流量管理")]
public sealed class TrafficCommands
{
    [Command("list", Description = "列出规则")]
    public Task<int> List([CommandOption("--filter")] string? filter = null, CancellationToken ct = default) => ...
}

// 生成 TrafficCommandsCli —— 直接当命令行入口
int exit = await TrafficCommandsCli.RunAsync(args);

一个方法标注一次 → 命令行解析、HTTP 代理、JSON 契约三件套同时生成。

声明命令

[CommandGroup("traffic", Description = "流量管理", DefaultExitCode = 2)]
public sealed class TrafficCommands
{
    [Command("list", Description = "列出规则")]
    public Task<int> List(
        [CommandOption("--filter", ShortName = 'f')] string? filter = null,
        [CommandOption("--all")] bool all = false) => ...;

    [Command("create", Description = "新建")]
    public Task<int> Create([CommandBody] CreateRequest body, CancellationToken ct = default) => ...;

    [Command("delete", Description = "删除", Confirm = true)]      // 执行前确认(生成 -y/--yes)
    public Task<int> Delete([CommandArg("id")] Guid id) => ...;
}

绑定形态:

标注 绑定
[CommandArg("id")] 位置参数(按声明序)
[CommandOption("--name")] 命名选项(--name value / --flag bool / ShortName)
[CommandBody] JSON 请求体(HTTP 代理形态;CLI 下从 stdin 读)
[CommandError] 错误码 → 输出映射
组级 Options 组级全局选项(#144——沿嵌套链对子命令可见)

方法返回 Task<int> = 退出码;组可嵌套([CommandGroup] 内再放组 → 逐级路径匹配)。

生成物

生成物 用途
<Root>Cli.g.cs Run/RunAsync(解析→绑定→直调)、WriteHelp、CompleteNext(补全候选)、CommandPaths
<Root>Http.g.cs TryHandleAsync 单一入口 + 编译期路由表(HTTP 执行代理)
<Root>JsonContext / <Root>JsonResults JSON 序列化契约(AOT 安全)

多根组互不知晓——聚合归宿主(首 token switch / 首段路由分发)。

诊断

KLSG054-067:路径冲突/非法命令名/参数未标注/不可绑定形态/GET 带 body/标注宿主非法/参数名占用保留前缀/组选项与子命令冲突等——全默认 Error。

明示不做(诚实边界)

能力 状态 理由
互斥组 / 必选选项组(Group/RequiresAny) 不做 绑定面已足够表达常见 CLI;组语义需运行期交叉校验层,v1 明示边界
shell 补全脚本生成(bash/zsh/powershell) 不做 CompleteNext 候选 API 供宿主补全循环消费;脚本模板留后续