tier0-cli

name: tier0-cli version: 0.3.2 description: "Tier0 Cloud 平台 CLI 统一入口。涵盖 UNS（Unified Namespace）数据面操作：命名空间浏览、节点读写、历史数据查询、节点增删改；以及 Flow（Node-RED）管理：SourceFlow 协议采集 / EventFlow 业务处理流的创建、部署、画布导入导出。triggers: Tier0, Cloud, UNS, Flow, Node-RED, 命名空间, 数据读写, 设备数据, SourceFlow, EventFlow, 工作流" metadata: requires: bins: ["tier0"] cliHelp: "tier0 help" openclaw: emoji: "☁️" hermes: tags: [api, cloud, uns, namespace, data, flow, nodered]

tier0-cli — Tier0 Cloud Platform CLI

⚠️ 前置条件：必须先安装 tier0 CLI 并完成登录授权，否则无法调用任何 API。

安装与初始化

第 1 步 安装 CLI + Skills（一键）

推荐（跨平台，需要 Node.js >= 16）：

npx @tier0/cli@latest install

一条命令同时安装 tier0 CLI 二进制和 Cursor / Claude Agent Skills。

备选 — macOS / Linux：

curl -sL https://raw.githubusercontent.com/FREEZONEX/Tier0-cli/main/install.sh | bash
# 然后单独安装 Skills：
npx skills add FREEZONEX/Tier0-skill

备选 — Windows (PowerShell)：

Invoke-RestMethod -Uri https://raw.githubusercontent.com/FREEZONEX/Tier0-cli/main/install.ps1 | Invoke-Expression
# 然后单独安装 Skills：
npx skills add FREEZONEX/Tier0-skill

第 3 步 配置（私有化部署必须执行，SaaS 跳过）

tier0 config --base-url https://your-tier0-instance.com

关键约束：先 config 再 login，否则授权 URL 指向错误地址。

⚠️ 变更 base-url 后必须重新登录：如果用户通过 tier0 config --base-url 修改了平台地址（例如从 SaaS 切换到私有化部署，或更换了实例），原有 API Key 对新地址无效，必须重新执行完整的登录流程：

tier0 config --base-url https://new-instance.com
tier0 login   # 或 tier0 config --api-key <新实例的 API Key>

不重新登录直接调用 API 会收到 authentication 错误（exit 3）。

第 4 步 登录授权

方式 A — Agent 已持有 API Key（推荐）：

tier0 config --api-key sk-per-xxxxxx

方式 B — Device Flow（需要用户浏览器配合）：

⚠️ CRITICAL：必须先把授权链接展示给用户，用户在浏览器完成授权后轮询才有意义。跳过此步直接轮询等同于永远超时。

按以下两步执行：

# 第 1 步：获取授权 URL（立即返回，解析 setup_code）
tier0 login --no-wait --json
# 输出: {"status":"authorization_required","verification_url":"...","setup_code":"abc123","expires_in":600}

必须立即把 verification_url 以可点击链接的形式展示给用户，并明确告知用户需要在浏览器中打开该链接完成授权，然后立即执行第 2 步（无需等待用户回复）：

# 第 2 步：开始轮询（每 5 秒检测一次，最多等待 10 分钟）
tier0 login --setup-code <code>
# 用户浏览器授权后自动保存 API Key，轮询结束

说明：第 2 步轮询会阻塞直到用户完成浏览器授权。Agent 无需在两步之间询问用户"是否完成"，但第 1 步的授权链接必须展示，否则用户无从授权，轮询永远不会成功。

语言切换

tier0 config --lang zh   # 切换中文
tier0 config --lang en   # 切换英文（默认）
# 或临时覆盖：
TIER0_LANG=zh tier0 flow list

核心概念

Flow ↔ UNS Topic 关联：Flow 名称（flowName）与 UNS topic 路径通常同名——SourceFlow 负责采集并写入对应 topic，EventFlow 负责订阅并处理该 topic 的数据。 当用户提到某个设备/数据点名称时，它同时对应一个 UNS topic 和一个（或多个）Flow，应同时查询两侧。 ⚠️ 目前 API 尚未提供显式关联字段，topicmeta 接口后续版本将加入关联信息，届时更新此文档。

资源关系

Workspace
├── UNS (Unified Namespace)
│   ├── Plant/                          ← folder（文件夹）
│   │   ├── Line1/                      ← folder
│   │   │   ├── Metric/                 ← folder
│   │   │   │   └── Temperature         ← file（数据点，完整 topic）
│   │   │   │       └── VQT { value: {"temperature":27.5,"unit":"C"},
│   │   │   │                 quality: "Good", timeStamp: 1733382000000 }
│   │   │   └── State/
│   │   │       └── MachineStatus       ← file（数据点）
│   │   └── Line2/
│   │       └── ...
└── Flow
    ├── SourceFlow "Line1-Collector"     ← 同名关联: 采集 → 写入 Plant/Line1/...
    └── EventFlow  "Line1-Processor"     ← 同名关联: 订阅 Plant/Line1/... → 处理

Flow ↔ UNS 名称对应规则（当前版本约定，topicmeta 关联 API 尚在开发中）：

• Flow flowName 与 UNS 路径人为保持同名，如 Line1-Collector 对应路径 Plant/Line1/...
• 遇到名称查询时，必须同时查 tier0 flow list --keyword <name> 和 tier0 uns browse

关键规则：

• browse / search 操作的对象是路径段（文件夹）
• read / write / history 操作的对象是完整 topic（叶子数据点）
• 写入时 value 是符合该 topic 字段定义的对象，不是标量
• 中间路径段（如 Plant/Line1）不能直接 read/write，只能 browse

子技能路由

根据用户意图，必须先读取对应子文档，再执行命令。

UNS — 统一命名空间

路径辨别规则：用户给出的路径若不到叶子节点（如 Plant/Line1），是文件夹，用 browse；完整到数据点（如 Plant/Line1/Metric/Temperature）才能 read/write。 关联提示：用户按名称询问某设备/数据的情况时，UNS topic 和 Flow 通常同名，查完 UNS 后也应查 tier0 flow list --keyword <name>，除非用户明确只需要其中一侧。

Auth / Info — 认证与服务信息

Flow — Node-RED 管理

CRITICAL — 执行 deploy 前 MUST 先读 flow/references/deploy.md，禁止直接盲目调用。 CRITICAL — 执行 delete 前 MUST 先用 tier0 flow get --id <id> 确认 Flow 存在。 CRITICAL — 用户按名称询问 Flow 相关数据时，MUST 同时查询 UNS（browse/read）和 Flow（list/get），因为两者通常同名关联。

任务选路心智模型

根据用户意图选正确命令，避免走错路径：

Windows PowerShell 调用注意

tier0 uns 子命令在 PowerShell 下与其他平台行为一致，通配符需加引号：

tier0 uns browse
tier0 uns read "Plant/+/Metric/Temperature" --json
tier0 uns write --topic Plant/Line1/Metric/Temperature --value '{"temperature":27.5}'
# 复杂 JSON（write/create/update）推荐用 --file
tier0 uns write --file writes.json
tier0 uns create --file structure.json
# 调试模式
tier0 uns browse Plant/Line1 --debug

常用命令速查

# ── UNS ──────────────────────────────────────
# 浏览命名空间
tier0 uns browse
tier0 uns browse Plant/Line1 --max-depth 2

# 读取数据点（value 是对象，包含多个字段）
tier0 uns read Plant/Line1/Metric/Temperature
# 响应: {"value":{"temperature":27.5,"unit":"C","humidity":58.6},"quality":"Good","timeStamp":1733382000000}

# 通配符读取（所有产线温度）
tier0 uns read "Plant/+/Metric/Temperature" --json

# 写入数据点（value 是对象）
tier0 uns write --topic Plant/Line1/Metric/Temperature --value '{"temperature":27.5,"unit":"C","humidity":58.6}'

# 查询历史数据
tier0 uns history factory/line1/sensor/temp --start 1715000000 --end 1715600000

# 创建节点（路径须含 Metric；字段类型写在 --fields）
tier0 uns create --topic Plant/Line1/Metric/Temperature --type topic \
  --fields '[{"name":"value","type":"float","unit":"°C"}]'
tier0 uns create --parent Plant/Line1 --topic Metric/ProductionCount --type topic \
  --fields '[{"name":"value","type":"int"}]'
tier0 uns create --file structure.json

# ── Flow ─────────────────────────────────────
# 列出所有 Flow
tier0 flow list

# 只看 SourceFlow / EventFlow
tier0 flow list --source
tier0 flow list --event

# 创建 Flow
tier0 flow create --name "modbus-collector" --source --desc "Modbus 采集"

# 导出画布到文件
tier0 flow data --id 1 --out flows.json

# 从文件部署画布
tier0 flow deploy --id 1 -f flows.json

UNS 批量接口响应解析规则

适用接口：uns read / uns write / uns history / uns create（批量数据面接口）

这类接口即使部分 topic 失败，HTTP 状态码仍为 200，外层 code 仍为 200，msg 仍为 "success"。必须检查 data.success 和 data.results[i].success 才能判断业务是否真正成功。

HTTP 200 + code:200 + msg:"success"
  └─ data.success: false        ← 整体有失败，不能只看外层
       └─ data.results[i].success: false  ← 具体哪个 topic 失败
            └─ data.results[i].error.code / message

解析规则（伪代码）：

const apiOk = body.code === 200;

// 批量接口：data.success 存在时用它判断整体业务成功
const businessOk =
  typeof body.data?.success === 'boolean'
    ? body.data.success
    : apiOk;

// 还要逐项检查，因为可能部分成功、部分失败
for (const item of body.data?.results ?? []) {
  if (!item.success) {
    // item.topic + item.error.code + item.error.message
  }
}

非批量接口（browse / search / flow list / flow get / info / auth whoami）不含 data.success，直接用外层 code === 200 判断即可。

错误处理

高风险操作协议（exit 10）

flow deploy 和 flow delete 是高风险操作。不带 --yes 时 CLI 退出码为 10，stderr 输出：

{
  "ok": false,
  "error": {
    "type": "confirmation_required",
    "message": "Deploy canvas to Flow 1 — ALL existing Node-RED nodes will be REPLACED...",
    "hint": "add --yes to confirm",
    "risk": { "level": "high-risk-write", "action": "flow deploy" }
  }
}

Agent 处理规则：

1. 检测到 exit code = 10 且 error.type == "confirmation_required"
2. 把 error.risk.action + error.message 展示给用户，明确告知高风险
3. 用户同意 → 原命令末尾追加 --yes 后重试
4. 用户拒绝 → 终止，不得擅自加 --yes

更新提示

CLI 每条命令执行后会在后台检查新版本（每 24 小时实际请求一次），有新版本时：

• JSON 模式：响应中附加 _notice.update 字段
• 普通模式：stderr 输出一行提示

升级命令：

tier0 upgrade