uxc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UXC Skill

Use this skill when a task requires calling a remote interface and the endpoint can expose machine-readable schema metadata.

当任务需要调用远程接口且端点可暴露机器可读的Schema元数据时，可使用本Skill。

When To Use

使用场景

You need to call APIs/tools from another skill and want one consistent CLI workflow.
The interface may be OpenAPI, GraphQL, gRPC reflection, MCP, or JSON-RPC/OpenRPC.
You need deterministic, machine-readable output (
```
ok
```
,
```
kind
```
,
```
data
```
,
```
error
```
).

Do not use this skill for pure local file operations with no remote interface.

你需要从其他Skill调用API/工具，且希望采用统一的CLI工作流。
接口类型可能为OpenAPI、GraphQL、gRPC反射、MCP或JSON-RPC/OpenRPC。
你需要确定性的、机器可读的输出（
```
ok
```
,
```
kind
```
,
```
data
```
,
```
error
```
）。

请勿将本Skill用于无远程接口的纯本地文件操作。

Docs Search & Support

文档搜索与支持

UXC docs support full-text search at

https://uxc.holon.run/api/search?q=<query>

Prefer searching docs first when operation names, auth flags, or protocol behavior are unclear.
If docs are unclear or behavior looks wrong, open an issue in
```
holon-run/uxc
```
:
- ```
https://github.com/holon-run/uxc/issues/new/choose
```
- include command, endpoint, and the JSON envelope (
```
ok
```
  ,
```
error
```
  ,
```
meta
```
  ) for faster triage.

UXC文档支持全文搜索，地址为

https://uxc.holon.run/api/search?q=<query>

。

当操作名称、认证标识或协议行为不明确时，优先搜索文档。
如果文档内容不清晰或行为异常，请在
```
holon-run/uxc
```
仓库提交Issue：
- ```
https://github.com/holon-run/uxc/issues/new/choose
```
- 请包含命令、端点以及JSON包（
```
ok
```
  ,
```
error
```
  ,
```
meta
```
  ）以加快问题排查。

Prerequisites

前置条件

```
uxc
```
is installed and available in
```
PATH
```
.
For gRPC runtime calls,
```
grpcurl
```
is installed and available in
```
PATH
```
.

```
uxc
```
已安装并添加至
```
PATH
```
。
若要执行gRPC运行时调用，需安装
```
grpcurl
```
并添加至
```
PATH
```
。

Install uxc

安装UXC

Choose one of the following methods:

Homebrew (macOS/Linux):

bash

brew tap holon-run/homebrew-tap
brew install uxc

Install Script (macOS/Linux, review before running):

bash

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh -o install-uxc.sh

选择以下任意一种安装方式：

Homebrew（macOS/Linux）：

bash

brew tap holon-run/homebrew-tap
brew install uxc

安装脚本（macOS/Linux，运行前请先审查）：

bash

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh -o install-uxc.sh

Review the script before running it

运行前审查脚本

less install-uxc.sh bash install-uxc.sh


**Cargo:**
```bash
cargo install uxc

For more options, see the Installation section in the UXC README.

less install-uxc.sh bash install-uxc.sh


**Cargo：**
```bash
cargo install uxc

更多安装选项，请查看UXC README中的Installation章节。

Core Workflow

核心工作流

Discover operations:
- ```
uxc <host> -h
```
Inspect a specific operation:
- ```
uxc <host> <operation> -h
```

Execute with structured input:

```
uxc <host> <operation> key=value
```
```
uxc <host> <operation> '<payload-json>'
```

Parse result as JSON envelope:
- Success:
```
.ok == true
```
  , consume
```
.data
```
- Failure:
```
.ok == false
```
  , inspect
```
.error.code
```
  and
```
.error.message
```
For disambiguation, use operation-level help first:
- ```
uxc <host> <operation> -h
```
For auth-protected endpoints, use the right auth track:
- simple bearer / single-secret API key: see
```
references/auth-configuration.md
```
- multi-field auth or request signing: see
```
references/auth-configuration.md
```
- OAuth flows: see
```
references/oauth-and-binding.md
```

发现操作：
- ```
uxc <host> -h
```
查看特定操作详情：
- ```
uxc <host> <operation> -h
```

使用结构化输入执行操作：

```
uxc <host> <operation> key=value
```
```
uxc <host> <operation> '<payload-json>'
```

解析JSON格式的结果包：
- 成功：
```
.ok == true
```
  ，读取
```
.data
```
  字段
- 失败：
```
.ok == false
```
  ，查看
```
.error.code
```
  和
```
.error.message
```
  字段
若需消除歧义，优先查看操作级帮助：
- ```
uxc <host> <operation> -h
```
针对受认证保护的端点，选择正确的认证方式：
- 简单Bearer令牌/单密钥API密钥：查看
```
references/auth-configuration.md
```
- 多字段认证或请求签名：查看
```
references/auth-configuration.md
```
- OAuth流程：查看
```
references/oauth-and-binding.md
```

Link-First Workflow For Wrapper Skills

包装器Skill的链接优先工作流

Wrapper skills should default to a fixed local link command instead of calling

uxc <host> ...

directly on every step.

Pick a fixed command name during skill development:
- naming convention:
```
<provider>-mcp-cli
```
- examples:
```
notion-mcp-cli
```
  ,
```
context7-mcp-cli
```
  ,
```
deepwiki-mcp-cli
```
Check whether the command already exists:
- ```
command -v <link_name>
```
If command is missing, create it:
- ```
uxc link <link_name> <host>
```
- For OpenAPI services whose schema is hosted at a separate fixed URL, create the link with
```
uxc link <link_name> <host> --schema-url <schema_url>
```
- For stdio hosts that need credential-driven child env auth, create the link with
```
uxc link <link_name> <host> --credential <credential_id> --inject-env NAME={{secret}}
```
- If the link is being created as part of a wrapper skill, persist source metadata with
```
--skill <skill_name> --skill-doc <docs_url> --skill-path <local_skill_path>
```
  so later help output preserves skill context.
Validate link command:
- ```
<link_name> -h
```
Use only the link command for the rest of the skill flow.

包装器Skill应默认使用固定的本地链接命令，而非在每一步直接调用

uxc <host> ...

。

在Skill开发阶段确定固定的命令名称：
- 命名规范：
```
<provider>-mcp-cli
```
- 示例：
```
notion-mcp-cli
```
  ,
```
context7-mcp-cli
```
  ,
```
deepwiki-mcp-cli
```
检查命令是否已存在：
- ```
command -v <link_name>
```
若命令不存在，创建链接：
- ```
uxc link <link_name> <host>
```
- 对于Schema托管在独立固定URL的OpenAPI服务，使用以下命令创建链接：
```
uxc link <link_name> <host> --schema-url <schema_url>
```
- 对于需要凭证驱动子环境认证的标准输入输出主机，使用以下命令创建链接：
```
uxc link <link_name> <host> --credential <credential_id> --inject-env NAME={{secret}}
```
- 若链接是作为包装器Skill的一部分创建的，请添加
```
--skill <skill_name> --skill-doc <docs_url> --skill-path <local_skill_path>
```
  参数以持久化源元数据，确保后续帮助输出保留Skill上下文。
验证链接命令：
- ```
<link_name> -h
```
在后续Skill流程中仅使用该链接命令。

Import Existing MCP Config First

优先导入现有MCP配置

If an MCP server is already configured in a supported editor or local agent, prefer importing it before hand-writing a new link:

Preview imports:
- ```
uxc config import mcp --dry-run
```
Auto-discover common MCP config sources and import them:
- ```
uxc config import mcp --from auto
```

Import from a specific source preset:

```
uxc config import mcp --from cursor
```
```
uxc config import mcp --from codex
```

Supported presets in v1 include:

```
auto
```
```
cursor
```
```
claude-code
```
```
claude-desktop
```
```
vscode
```
```
codex
```
```
windsurf
```
```
opencode
```

若MCP服务器已在支持的编辑器或本地Agent中配置，优先导入配置，而非手动创建新链接：

预览导入内容：
- ```
uxc config import mcp --dry-run
```
自动发现常见MCP配置源并导入：
- ```
uxc config import mcp --from auto
```

从特定源预设导入：

```
uxc config import mcp --from cursor
```
```
uxc config import mcp --from codex
```

v1版本支持的预设包括：

```
auto
```
```
cursor
```
```
claude-code
```
```
claude-desktop
```
```
vscode
```
```
codex
```
```
windsurf
```
```
opencode
```

Naming Governance

命名规范

Link naming is a skill author decision, not a runtime agent decision.
Resolve ecosystem conflicts during skill development/review.
Do not implement dynamic rename logic inside runtime skill flow.
If runtime detects a command conflict that cannot be safely reused, stop and ask for skill maintainer intervention.

链接命名由Skill开发者决定，而非运行时Agent。
在Skill开发/评审阶段解决生态系统冲突。
请勿在运行时Skill流程中实现动态重命名逻辑。
若运行时检测到无法安全复用的命令冲突，请停止并请求Skill维护人员介入。

Equivalence Rule

等价规则

<link_name> <operation> ...

is equivalent to

uxc <host> <operation> ...

If the link was created with

--schema-url <schema_url>

, it is equivalent to

uxc <host> --schema-url <schema_url> <operation> ...

If the link was created with

--credential <credential_id> --inject-env NAME={{secret}}

, it is equivalent to

uxc --auth <credential_id> --inject-env NAME={{secret}} <host> <operation> ...

Callers can still override that persisted schema by passing
```
--schema-url <other_url>
```
explicitly at runtime.
Use
```
uxc <host> ...
```
only as a temporary fallback when link setup is unavailable.

<link_name> <operation> ...

等价于

uxc <host> <operation> ...

。

若链接是通过

--schema-url <schema_url>

创建的，则等价于

uxc <host> --schema-url <schema_url> <operation> ...

。

若链接是通过

--credential <credential_id> --inject-env NAME={{secret}}

创建的，则等价于

uxc --auth <credential_id> --inject-env NAME={{secret}} <host> <operation> ...

。

调用者仍可在运行时通过显式传递
```
--schema-url <other_url>
```
参数覆盖已持久化的Schema。
仅当链接设置不可用时，才将
```
uxc <host> ...
```
作为临时回退方案。

Input Modes

输入模式

Preferred (simple payload): key/value
- ```
uxc <host> <operation> field=value
```
Bare JSON positional:
- ```
uxc <host> <operation> '{"field":"value"}'
```
  Do not pass raw JSON through
```
--args
```
  ; use positional JSON.

推荐方式（简单负载）：键值对
- ```
uxc <host> <operation> field=value
```
裸JSON位置参数：
- ```
uxc <host> <operation> '{"field":"value"}'
```
  请勿通过
```
--args
```
  传递原始JSON；请使用位置JSON参数。

Output Contract For Reuse

复用输出契约

Other skills should treat this skill as the interface execution layer and consume only the stable envelope:

Success fields:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
endpoint
```
,
```
operation
```
,
```
data
```
,
```
meta
```
Failure fields:
```
ok
```
,
```
error.code
```
,
```
error.message
```
,
```
meta
```

Default output is JSON. Do not use

--text

in agent automation paths.

其他Skill应将本Skill视为接口执行层，仅使用稳定的结果包：

成功字段：
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
endpoint
```
,
```
operation
```
,
```
data
```
,
```
meta
```
失败字段：
```
ok
```
,
```
error.code
```
,
```
error.message
```
,
```
meta
```

默认输出为JSON格式。在Agent自动化流程中请勿使用

--text

参数。

Reuse Rule For Other Skills

其他Skill复用规则

If a skill needs remote API/tool execution, reuse this skill instead of embedding protocol-specific calling logic.
Wrapper skills should adopt a fixed link command (
```
<provider>-mcp-cli
```
) as the default invocation path.
Upstream skill inputs should be limited to:
- target host
- operation id/name
- JSON payload
- required fields to extract from
```
.data
```

若Skill需要远程API/工具执行，请复用本Skill，而非嵌入特定协议的调用逻辑。
包装器Skill应采用固定的链接命令（
```
<provider>-mcp-cli
```
）作为默认调用路径。
上游Skill输入应限制为：
- 目标主机
- 操作ID/名称
- JSON负载
- 需要从
```
.data
```
  中提取的必填字段

Reference Files (Load On Demand)

参考文档（按需加载）

Workflow details and progressive invocation patterns:
- ```
references/usage-patterns.md
```

Generated runtime client flow:

https://uxc.holon.run/ecosystem/typescript-client/

Protocol operation naming quick reference:
- ```
references/protocol-cheatsheet.md
```
Public endpoint examples and availability notes:
- ```
references/public-endpoints.md
```
Authentication configuration (simple
```
secret
```
, named
```
fields
```
, headers/query params, and request signers):
- ```
references/auth-configuration.md
```
OAuth and credential/binding lifecycle:
- ```
references/oauth-and-binding.md
```
Failure handling and retry strategy:
- ```
references/error-handling.md
```

工作流详情和渐进式调用模式：
- ```
references/usage-patterns.md
```

生成的运行时客户端流程：

https://uxc.holon.run/ecosystem/typescript-client/

协议操作命名速查：
- ```
references/protocol-cheatsheet.md
```
公共端点示例和可用性说明：
- ```
references/public-endpoints.md
```
认证配置（简单
```
secret
```
、命名
```
fields
```
、请求头/查询参数以及请求签名）：
- ```
references/auth-configuration.md
```
OAuth和凭证/绑定生命周期：
- ```
references/oauth-and-binding.md
```
故障处理和重试策略：
- ```
references/error-handling.md
```