any-launcher

配置驱动的通用命令启动器（包装器）。以 llama 系列命令为主要场景，但可包装任意命令。

核心特性

• 配置驱动：执行命令（exec）和所有参数均在配置文件中定义
• 无扩展名限制：配置文件可以是任意文件名，内容符合 TOML 格式即可
• 严格优先级：CLI 参数 > 配置文件 > 默认值
• Profile 机制：单文件多套命名配置，一键切换（dev/prod/staging）
• 子命令支持：通过 subcommand 字段支持固定前缀模式（如 paddleocr ocr、docker compose up）
• 原始透传：-- 之后的参数原样追加，不做任何解析
• 环境变量展开：配置值中支持 ${VAR} 和 $VAR 语法
• dry-run 模式：打印最终命令行，不实际执行
• 跨平台：Windows / Linux / macOS 统一行为（spawn + 信号转发 + 退出码透传）

安装

git clone https://github.com/iamxiaojianzheng/any-launcher
cd any-launcher
go build -o any-launcher .

用法

# 位置参数传配置文件（推荐）
any-launcher server.cfg

# 显式 --config 写法（与上面等效）
any-launcher --config server.cfg

# 覆盖配置文件中的参数
any-launcher server.cfg --port 9090 --n-gpu-layers 50

# 使用命名 Profile
any-launcher models.cfg --profile dev
any-launcher models.cfg --profile prod

# 覆盖 exec 命令本身
any-launcher server.cfg --exec /usr/local/bin/llama-server-cuda

# 覆盖子命令（--subcommand 可多次指定，组成多级子命令）
any-launcher paddle.cfg --subcommand table
any-launcher docker.cfg --subcommand compose --subcommand up

# "--" 之后的参数原样追加到目标命令末尾
any-launcher server.cfg -- --experimental-flag value

# 查看最终命令行，不执行（调试用）
any-launcher server.cfg --profile prod --dry-run

# 纯 CLI 模式（不用配置文件）
any-launcher --exec echo -- hello world

配置文件格式

配置文件为 TOML 格式，文件名无限制（server、prod.cfg、my-config、llama.conf 均可）。

极简配置

# 文件名：server（无扩展名）

[default]
exec         = "llama-server"
model        = "/models/qwen2.5-7b-q4_k_m.gguf"
port         = 8080
host         = "127.0.0.1"
ctx-size     = 4096
n-gpu-layers = 99

多 Profile 配置

将公共参数放在 [default]，各 Profile 只写差异部分：

# 文件名：models.cfg

[launcher]
log_level = "info"   # debug | info | warn | error

# 所有 profile 共享的基础参数
[default]
exec         = "llama-server"
host         = "127.0.0.1"
port         = 8080
ctx-size     = 4096
n-gpu-layers = 99

[profiles.dev]
model        = "${HOME}/models/qwen-0.5b-q4_k_m.gguf"
ctx-size     = 2048
n-gpu-layers = 0

[profiles.prod]
model        = "${LLAMA_MODEL_DIR}/qwen2.5-72b-q5_k_m.gguf"
port         = 8000
host         = "0.0.0.0"
ctx-size     = 8192
api-key      = "${LLAMA_API_KEY}"

[profiles.chat]
exec     = "llama-cli"
model    = "${HOME}/models/qwen-7b.gguf"
ctx-size = 4096

子命令（固定前缀）配置

通过 subcommand 字段在目标命令与 flag 之间插入固定的子命令词。

单级子命令（字符串形式）：

# 包装 paddleocr ocr
[default]
exec       = "paddleocr"
subcommand = "ocr"
image_dir  = "./doc/imgs"
use_gpu    = false

最终执行：paddleocr ocr --image_dir ./doc/imgs

多级子命令（数组形式）：

# 包装 docker compose up
[default]
exec       = "docker"
subcommand = ["compose", "up"]

# 单横线 flag（-d）使用现有键名机制
"-d"         = true
project-name = "myapp"

最终执行：docker compose up -d --project-name myapp

Profile 切换子命令：

[default]
exec       = "paddleocr"
subcommand = "ocr"

[profiles.pps]
subcommand = "pp_structurev3"   # 切换到 pp_structurev3 识别，其余参数继承 default

any-launcher paddle.cfg                    # paddleocr ocr ...
any-launcher paddle.cfg --profile pps   # paddleocr pp_structurev3 ...
any-launcher paddle.cfg --subcommand doc_parser  # paddleocr doc_parser ...（CLI 覆盖）

从 HuggingFace Hub 拉取模型（单横线 flag）

llama.cpp 的 -hf 是单横线 flag。键名以 - 开头时，any-launcher 直接透传，不补 --：

# Profile 名含小数点须用引号
[profiles."qwen3-1.7"]
"-hf"    = "unsloth/Qwen3-1.7B-GGUF:Q4_K_M"
ctx-size = 4096

[profiles."qwen3-0.6"]
"-hf"    = "unsloth/Qwen3-0.6B-GGUF:Q4_K_M"
ctx-size = 2048

# 使用时 profile 名不需要引号
any-launcher models.cfg --profile qwen3-1.7

包装任意命令

# 包装 nginx

[default]
exec   = "nginx"
config = "/etc/nginx/dev.conf"

参数键名规则

配置文件中的键名直接映射到目标命令的 flag，规则如下：

配置键值	生成的 flag	说明
port = 8080	--port 8080	普通键名自动补 -- 前缀
n-gpu-layers = 99	--n-gpu-layers 99	含连字符的键名同样支持
verbose = true	--verbose	bool true → 仅 flag，不带值
verbose = false	（跳过，不生成）	bool false → 完全忽略
"-hf" = "repo:file"	-hf repo:file	键名以 - 开头 → 直接使用，不补 --
"--no-cache" = true	--no-cache	键名以 -- 开头 → 同样直接使用
exec = "..."	（不生成 flag，作为命令名）	保留字
subcommand = "ocr"	（插入命令与 flag 之间）	保留字，支持字符串或字符串数组

优先级说明

配置文件 [default]          层1（最低）
      ↓ 叠加
配置文件 [profiles.xxx]     层2（--profile 指定时）
      ↓ 覆盖
CLI 显式参数               层3（最高）
      ↓ 追加
"--" 后的原始参数           直接追加，不做解析

Profile 叠加语义：profile 中未定义的键保留 [default] 的值，不会被清空。

exec 和 subcommand 同样遵循三层优先级，profile 中定义会完全覆盖 default 中的值，CLI --subcommand 优先级最高。

Tip

关于点号（.）的注意事项： 由于 TOML 语法将 . 视为嵌套键的分隔符，如果你的 Profile 名称包含点号（如 qwen3-1.7），在配置文件中必须使用引号：

[profiles."qwen3-1.7"]
model = "..."

示例

查看 examples/ 目录：

• examples/llama-server - llama-server 基础配置 + -hf 单横线 flag 示例（无扩展名演示）
• examples/multi-profile.cfg - 多 Profile 配置，含含点号 Profile 名和 HuggingFace Hub 拉取模型示例
• examples/any-command - 包装任意命令
• examples/subcommand-test.toml - subcommand 功能演示（字符串/数组写法 + Profile 切换子命令）