输出格式

每个uip命令都会在标准输出上发出单个结构化信封。无论您是在终端中读取信封、将其输入jq ，还是从管道中使用，信封都具有相同的架构。有四种格式以不同方式呈现该信封： json （默认值）、 table 、 yaml和plain 。使用--output在其之间切换，并使用--output-filter进行筛选。

信封

成功：

{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    {
      "Key": "9f2b3c…-…",
      "Name": "Shared",
      "Path": "Shared",
      "Type": "Standard"
    }
  ]
}

失败：

{
  "Result": "ValidationError",
  "Message": "Unknown option '--folder-pth'. Did you mean '--folder-path'?",
  "Instructions": "Run 'uip or folders list --help' to see valid options.",
  "Log": "/var/log/uip/2026-04-24.log"
}

字段：

• Result — 结果类别。成功时，为Success ；失败时为Failure 、 ConfigError 、 AuthenticationError 、 ValidationError或TimeoutError 。直接映射到退出代码。
• Code — 特定于命令的成功标识符。在主要版本（ FolderList 、 SolutionPack 、 JobStarted 、 SkillsInstall等）中保持稳定。
• Data — 命令的有效负载。形状是特定于命令的；有关确切字段，请参阅每个命令的参考页面。
• Message 、 Instructions — 失败时显示。Message是人类可读的错误； Instructions告诉用户或操作员要执行的操作。
• Context — 可选的失败详细信息（HTTP 状态、请求 ID 等）。
• Log — 当--log-file处于活动状态时，表示日志文件的路径，包含在每个信封中。

信封本身在次要版本中保持稳定。Data的形状视命令而定，并且可以不断发展 — 请参阅版本控制和稳定性。

四种格式

JSON（默认）

uip or folders list

{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    { "Key": "9f2b3c…", "Name": "Shared", "Path": "Shared", "Type": "Standard" },
    { "Key": "a4b8f1…", "Name": "Finance", "Path": "Finance", "Type": "Standard" }
  ]
}

选择默认值是因为它可由任何 JSON 使用者（ jq 、 --output-filter 、脚本、AI 智能体）解析，并且在各个版本中具有确定性。在终端中，其读取效果良好；如需获得打印美观的表格，请切换到--output table 。

表格

uip or folders list --output table

Key         Name       Path      Type
9f2b3c…     Shared     Shared    Standard
a4b8f1…     Finance    Finance   Standard

在真实终端中设置颜色和边框（当标准输出不是 TTY 时，不显示颜色）。每个命令都会选取它认为对表格视图最有用的列，但不一定显示Data中的每个字段。对于完整的字段集，请使用 JSON 或 YAML。

不解析表格输出。列宽、边框甚至列集都可能在 Minor 版本之间发生变化。它仅供人类阅读。

YAML

uip or folders list --output yaml

Result: Success
Code: FolderList
Data:
  - Key: 9f2b3c…
    Name: Shared
    Path: Shared
    Type: Standard
  - Key: a4b8f1…
    Name: Finance
    Path: Finance
    Type: Standard

与json相同的信封的文本 YAML 序列化。如果您的工具更喜欢 YAML（Ansible、Kubernetes 清单、某些 CI 平台），或者您通过目视比较两次运行并发现 YAML 更容易扫描，则此方法非常有用。

plain

uip or folders list --output plain

Data[0].Key=9f2b3c…
Data[0].Name=Shared
Data[0].Path=Shared
Data[0].Type=Standard
Data[1].Key=a4b8f1…
Data[1].Name=Finance
Data[1].Path=Finance
Data[1].Type=Standard

每行一个path=value 。路径是信封中点符号的类似 JMES 路径的密钥。可方便用于没有jq的计算机上的 Shell 循环：

uip or folders list --output plain | grep -E '\.Name=' | cut -d= -f2

使用 --output-filter 进行筛选

--output-filter接受JMESPath表达式。系统会在格式化之前在完整信封上运行，因此筛选器输出会继承--output生成的格式。

一些常见模式：

# just the Data array
uip or folders list --output-filter "Data"

# project specific fields
uip or folders list --output-filter "Data[*].{name: Name, path: Path}"

# count
uip or folders list --output-filter "length(Data)"

# first match
uip or folders list --all --name Shared --output-filter "Data[0]"

# flat list of names
uip or folders list --output-filter "Data[*].Name" --output plain

在命令运行之前，格式错误的表达式会以ValidationError退出（退出代码3 ），因此即使输入错误也不会浪费一次 API 调用。请参阅全局选项 — --output-filter ，了解完整标记。

流分离

--output仅控制标准输出。无论格式如何，所有其他形式的输出都将发送到STDERR ：

• 日志行（ --log-level控制的内容）。
• 进度指示器（微调框、工具自动安装期间的下载栏）。
• 主机在检测到无效标志时呈现的错误文本。

这意味着管道可以将干净输出捕获到文件中，而不会丢失诊断信息：

uip or folders list > folders.json 2> uip.log

在 CI 中，单独对其进行重定向，以使日志可搜索，而无需从数据流中去除 ANSI 或进度工件。

颜色和 TTY 检测

仅当标准输出是交互式终端 ( isTTY ) 时， table格式才会发出 ANSI 颜色代码。当您通过管道连接到文件或另一个流程，或在禁用 TTY 的 CI 运行程序中运行时，表格输出为纯文本，不包含转义代码。目前没有用于强制打开或关闭颜色的标志 — 这取决于 TTY 检测。

其他格式（ json 、 yaml 、 plain ）从不发出颜色。

选择格式

Use case	建议的格式
在终端中读取	--output table
脚本编写（ jq 、Shell 管道）	--output json (默认)
Ansible/Kubernetes 集成	--output yaml
grep- 友好的平面输出，不包含 jq	--output plain
AI 编码智能体	--output json （默认）使用--output-filter进行聚焦提取
在步骤之间传递值的 CI 管道	--output json 带有--output-filter或--output plain （对于简单情况）

另请参阅

• 全局选项— --output 、 --output-filter 、 --log-level和--log-file标志。
• 退出代码— 从Result映射到流程退出代码。
• 脚本模式— CI 中的重试、轮询和安全 JSON 提取。
• 版本控制和稳定性— 在 semver 中，“稳定的 JSON 信封”意味着什么。