Redant 命令行框架

Redant 是一个用于构建大型 Go 命令行程序的框架，提供命令树、选项系统、中间件链、帮助系统与多格式参数解析能力。

文档导航

README 仅保留“快速上手 + 能力入口”。详细设计与流程请跳转：

• 总索引：docs/INDEX.md
• 使用速览：docs/USAGE_AT_A_GLANCE.md
• 架构设计：docs/DESIGN.md
• MCP 指南：docs/MCP.md
• WebTTY 指南：docs/WEBTTY.md
• 评估报告：docs/EVALUATION.md
• 变更记录：.version/changelog/README.md

核心能力

• 命令树与可控子命令继承（支持嵌套）
• 选项多来源配置（命令行、环境变量、默认值）
• 中间件链式编排
• 自动帮助信息与全局标志
• 多格式参数解析（位置参数、查询串、表单、JSON）
• Busybox 风格 argv0 调度（软链接命令入口）
• MCP 工具暴露（将命令树映射为 Model Context Protocol Tools）
• Web 控制台（web 子命令）：可视化选择命令、填写 Flags/Args、查看调用过程与执行结果
• 可视化命令（viz / doc）：Mermaid 图生成与交互式文档站

仓库范围说明

• 当前 redant 仓库聚焦 CLI 框架核心能力（命令树、Flag/Args 解析、中间件、帮助系统、MCP/Web/WebTTY）。
• agentline、copilot-demo 及相关示例已迁移到独立项目维护（fastgit 侧），不再作为本仓库内置模块继续演进。
• 如需 Agent 交互与 Copilot 集成演示，请在迁移后的项目中使用对应目录与示例。

快速开始

第一步：最小命令

只需一个 Command + Handler，3 行核心代码即可跑起：

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/pubgo/redant"
)

func main() {
    cmd := redant.Command{
        Use:   "echo <text>",
        Short: "输出传入文本",
        Handler: func(ctx context.Context, inv *redant.Invocation) error {
            if len(inv.Args) == 0 {
                return fmt.Errorf("缺少文本参数")
            }
            fmt.Fprintln(inv.Stdout, inv.Args[0])
            return nil
        },
    }

    if err := cmd.Invoke().WithOS().Run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

第二步：添加标志

通过 Options 声明标志，支持命令行、环境变量、默认值三种来源：

var upper bool
cmd := redant.Command{
    Use:   "echo <text>",
    Short: "输出传入文本",
    Options: redant.OptionSet{
        {
            Flag:        "upper",
            Shorthand:   "u",
            Description: "输出大写",
            Value:       redant.BoolOf(&upper),
        },
    },
    Handler: func(ctx context.Context, inv *redant.Invocation) error {
        // upper 已由框架自动解析
        fmt.Fprintln(inv.Stdout, inv.Args[0])
        return nil
    },
}

第三步：加子命令

用 Children 挂载子命令。标志默认不继承，需显式设置 Inherit: true 才会向子命令下沉：

root := redant.Command{
    Use:   "app",
    Short: "我的 CLI 工具",
    Children: []*redant.Command{
        {
            Use:   "greet <name>",
            Short: "打招呼",
            Handler: func(ctx context.Context, inv *redant.Invocation) error {
                fmt.Fprintf(inv.Stdout, "Hello, %s!\n", inv.Args[0])
                return nil
            },
        },
    },
}

root.Options = redant.OptionSet{
    // 显式允许子命令继承
    {Flag: "verbose", Value: redant.BoolOf(new(bool)), Inherit: true},
}

更多进阶用法（中间件、结构化响应、MCP/Web 集成）见 docs/USAGE_AT_A_GLANCE.md。

常用能力速览

参数与标志

• 子命令支持空格路径与冒号路径（如 app repo commit / app repo:commit）。
• 参数支持位置参数、query、form、JSON 四种形态。
• 推荐写法：app <command> [flags...] [args...]。

常用全局标志：

• --help, -h
• --list-commands（根命令）
• --list-flags（根命令）

详细解析规则见：docs/USAGE_AT_A_GLANCE.md。

Web 调试界面

app web
app web --addr 127.0.0.1:18080 --open=false

Web 控制台支持可视化填写 flags/args，并展示 curl 与多行 CLI 调用过程。更多说明见：docs/USAGE_AT_A_GLANCE.md。

WebTTY 本地终端

app webtty
app webtty --addr 127.0.0.1:18081 --open=false

webtty 提供最简本地 Web 终端能力（WebSocket + PTY），并支持文件上传/下载。详细接口与迭代路线见：docs/WEBTTY.md。

交互式文档站

app doc                           # 启动交互式文档站（类 Swagger UI）
app doc --addr 127.0.0.1:18081 --open=false

doc 命令从命令树自动生成交互式文档站，包含命令搜索、参数/选项表格与 Mermaid 图渲染。

Richline 交互终端（可选挂载）

若你的应用挂载了 cmds/richlinecmd，可通过以下方式进入交互终端：

app richline

当前 richline 界面支持：

• 状态栏：IDLE / RUNNING / OUTPUT_SCROLL
• 焦点提示：focus=INPUT / OUTPUT
• 输出区滚动状态：显示 offset/rows
• 快捷切换：Ctrl+O 在输入区与输出滚动区之间切换，并给出显式切换提示

MCP 集成

app mcp list
app mcp list --format text
app mcp serve --transport stdio

MCP 输入/输出协议、Schema 规则与排查建议见：docs/MCP.md。

LLM / Agent 集成

Redant 内建多层 LLM 友好接口，便于 AI Agent 发现和调用命令：

能力	入口	说明
命令树文档	app llms-txt	输出 Markdown 格式命令树（命令、参数、选项、响应类型）
MCP 工具映射	app mcp serve	将命令树自动暴露为 MCP Tools（含 inputSchema / outputSchema）
MCP 资源	redant://<app>/llms.txt	完整命令树文档资源
MCP 资源	redant://<app>/help/<tool>	单命令 Markdown 帮助
MCP 资源	redant://<app>/schema/<tool>	单命令 JSON Schema（input + output）
MCP Prompts	<app>-overview	全局命令概览提示模板
MCP Prompts	use-<tool>	单命令调用指南提示模板
Agent Hints	Metadata 字段	标记命令只读/幂等/危险等语义，映射到 tool description

Agent Hints 用法示例：

cmd := &redant.Command{
    Use:   "delete",
    Short: "Delete a resource.",
    Metadata: map[string]string{
        "agent.destructive":          "true",
        "agent.requires-confirmation": "true",
    },
    Handler: deleteHandler,
}

示例目录

按学习路径推荐顺序：

阶段	示例	说明
入门	example/echo	最小命令（Handler + Flag + 中间件）
基础	example/globalflags	全局标志与环境变量回退
基础	example/env-test	环境变量配置示例
进阶	example/args-test	四种参数形态（位置/query/form/JSON）
进阶	example/unary	结构化响应（ResponseHandler）
进阶	example/stream-interactive	交互流（ResponseStreamHandler）
综合	example/demo	子命令树 + 多模块集成
综合	example/fastcommit	全功能展示（Web/MCP/Viz/Doc）

开发与维护

• 文档入口：docs/INDEX.md
• 变更记录：.version/changelog/README.md

许可证

本项目采用 MIT 许可证，详见 LICENSE。