Expand description
§xyz-rust — One definition, three interfaces
一次定义（入参 struct + 校验 + 每渠道细节），一个二进制自动讲三种接口：
CLI 子命令、HTTP REST 服务（带 OpenAPI 文档）与 MCP 工具服务器
（官方 Rust SDK rmcp）。运行模式由库自行判断。
use xyz_rust::{define, CliHints, HTTPHints, XyzArgs};
use xyz_rust::errs;
#[derive(XyzArgs)]
struct AddArgs {
#[xyz(desc = "用户名", required, cli = "positional", http = "path")]
name: String,
#[xyz(desc = "年龄", default = "18")]
age: i32,
}
fn add(_ctx: &xyz_rust::Ctx, in_: &AddArgs) -> errs::Result<String> {
Ok(format!("{} is {}", in_.name, in_.age))
}
fn main() {
define::<AddArgs, String, _, _>("user.add", add)
.summary("添加用户")
.cli(CliHints { usage: "add <name>".into(), ..Default::default() })
.http(HTTPHints { method: "POST".into(), path: "/users/{name}".into(), ..Default::default() })
.run(); // 注册 + 派发 + exit — 整个程序就这一条链
}进程级默认注册表背后的派生器：Main 派发默认注册表并内部调用
std::process::exit，因此 main 里写的清理代码不会在它们之后执行。需要
defer 清理、自定义退出码、多个注册表或嵌入派发器时，用显式注册表的
run / run_config 版本，它们只返回退出码。
没有任何注册命令的注册表是静默 no-op：派发器直接退出 0，什么都不打印。
模式探测：
<app> [命令] ... -> CLI 前端（子命令、flag、位置参数、-h / -v）
<app> mcp stdio|http -> MCP 前端（官方 SDK；--versions 钉定协议版本；sse 随
2026-07-28 修订从官方 Rust SDK 移除，报错退出）
<app> serve [--addr ...] -> HTTP 前端（REST + /openapi.json + /mcp）
<app> （无参数）| help -> 总览（列出三种形态与命令表）模式关键词默认为 serve / mcp / help 且是保留的顶层名字；两者都可经
Config.modes 重命名。派发在 dispatch 模块，配置类型在
config，内置参数解析在 builtins，总览渲染在 overview，流式
构建器在 builder。
Re-exports§
pub use ctx::Ctx;pub use errors as errs;pub use builder::Builder;pub use builder::Definable;pub use builder::define;pub use config::Capabilities;pub use config::Config;pub use config::ModeWords;pub use dispatch::main as main_entry;pub use dispatch::main_config;pub use dispatch::run;pub use dispatch::run_config;pub use errors::Error;pub use errors::Kind;pub use lang::XyzLang;pub use lang::set as set_lang;pub use lang::t;pub use lang::tf;pub use registry::Registry;pub use spec::CliFieldHint;pub use spec::CliHints;pub use spec::Entry;pub use spec::FieldMeta;pub use spec::HTTPFieldHint;pub use spec::HTTPHints;pub use spec::MCPFieldHint;pub use spec::MCPHints;pub use spec::Schema;pub use spec::XyzArgs;pub use spec::XyzField;pub use version::set_version;pub use version::version;pub use chrono;pub use serde;pub use serde_json;
Modules§
- blocks
- 内容块结果（spec §12.7）：handler 可以返回
Blocks而不是纯 JSON 值。 - builder
- builtins
- cli
- config
- ctx
- dispatch
- errors
- httpapi
- lang
- logx
- mcp
- overview
- registry
- spec
- termx
- termx 探针（Go termx 的 Rust 对应物）：CLI 格式轴（§10.7）与保留的 样式轴（§10.7a）共享的终端/环境探测叶模块。
- version
Macros§
- errorf
- 返回带格式化消息的分类错误：
errs::errorf!(errs::Kind::NotFound, "user {} not found", name) - log_
debug - log_
error - log_
info - log_
warn
Structs§
- EnvContext
- 环境上下文快照（现象 §14 item7 的
Env()访问器）。
Functions§
- env
- 一次取齐语言/交互式/颜色抑制（spec §14 item7）。
- interactive
- 进程主输出是否交互式（TTY）。这是格式轴（§10.7）与保留的样式轴 （§10.7a）共享的同一探针接缝。
- language
- 当前界面语言（spec §14 item7）：进程级语言槽（
--xyz.lang> Config > 环境检测 > en，§15.5）。 - language_
from_ ctx - 请求上下文携带的界面语言（spec §11.7）；未绑定时回退进程语言
（Go
xyz.LanguageFromCtx(ctx)的对应物）。 - no_
color - 颜色是否被环境抑制（
NO_COLOR非空或TERM=dumb；§10.7a 保留样式轴 的输入，先以访问器形式暴露）。