ClawHub

smartbi-cli

API key required
Other

Trigger on Smartbi BI business asks (训练资源、报表分析、指标/交易统计、大模型问句、先训后查链式意图); map intent to operationKey via smartbi CLI.

Install

openclaw skills install smartbi-cli

Smartbi CLI Skill

Summary

把用户业务意图映射到唯一 operationKey，并按流程使用 smartbi CLI 完成调用；失败时给可执行修复命令。

operationKey 格式为 ${domain}.${operationId}（如 demo.createOrder、aichat.getAgentItems）。list 输出结果可直接复制作为 describe/call 的参数。

Triggers

当用户描述“业务动作 + 业务对象”，但未显式给出接口名/operationKey（例如“帮我训练模型资源A”“基于模型资源A分析去年销售额”）时触发。

当用户问及 BI 相关业务操作（分析、训练、指标查询、报表/问句类需求）时，应默认尝试触发本 skill，再通过 discover 流程收敛到唯一 operationKey。

安装、可执行文件与配置（MUST，禁止自由发挥）

  • MUST 仅通过 npm 全局安装 获得可执行命令 smartbi，安装命令与顺序以 references/init.md 的 标准安装 为准（npm install -g @smartbi/cli@latest，随后 smartbi --version）。
  • MUST NOT 使用仓库内脚本、未打包二进制、npx 临时跑包、或其它名称/路径“看起来像 smartbi”的程序代替上述 smartbi。
  • MUST NOT 用 yarn / pnpm / bun 等替代 npm 完成本 skill 规定的全局安装。
  • 初始化 MUST 严格按 references/init.md：先 smartbi init（或按需 smartbi init --print 预览），再按文档编辑 由 init 生成/指向 的配置；不得跳过 init 手写一套未经验证的配置结构。
  • 配置文件 MUST 仅为：默认 ~/.smartbi/config.yaml，或用户在完成 init 后 明确指定 且与本文档一致的 --config <path>。MUST NOT 在系统中搜索、猜测或套用“文件名像 config.yaml / smartbi 配置”的其它文件。

执行前置条件不足时（MUST，立即暂停）

在运行任何会访问 sdk-server 的 smartbi 子命令（list / search / describe / call）之前，若根据当前生效配置（默认 ~/.smartbi/config.yaml，或显式 --config）与进程环境可判定 最小连接条件未满足，则 MUST：

  1. 立即停止后续 Phase；MUST NOT 在缺少可用的 sdk-server 根 URL、缺少鉴权（token / tokenEnv）、或 tokenEnv 对应变量未设置时仍执行上述命令“试探”。
  2. 明确列出缺项，并请用户 选择或提供（至少：baseUrl / baseUrlEnv 二选一且运行时能解析出 sdk-server 根 URL — init 默认仅 baseUrlEnv，须设置对应环境变量或改回字面量 baseUrl；以及 tokenEnv 与 token 二选一及取值方式；若选 tokenEnv，须确认当前环境中该变量已赋值）。
  3. 仅在用户确认配置已按 references/init.md 补齐（或提供可写入的值且经用户授权）后再继续。

典型缺项（用于判定，非穷尽）：YAML 未配置 baseUrl 与 baseUrlEnv 二者之一；仅 baseUrlEnv 但变量未赋值且无 baseUrl 回落；未配置 token 与 tokenEnv 二者之一；已配 tokenEnv 但进程环境中无对应值。

文档优先级原则

构造 call 参数时，应主动获取 docs/specs/ 下的业务文档作为理论依据；文档不可用或未覆盖时，以 schema 定义兜底。

取值优先级：

  1. 文档内容（优先）：字段的业务含义、合法枚举值、字段间依赖关系、完整使用示例
  2. requestBodySchema（兜底）：字段类型、必填/可选、嵌套结构 — 文档不可用或未覆盖时使用
  3. callParameterPlan：参数分组和 CLI 标志映射
  4. suggestedCall：仅供参考的命令行模板

行为指引：

  • 主动获取：构造 call 参数前，主动检查是否存在关联文档并加载（识别方式见 Phase 2 步骤 1）
  • 文档优先，schema 兜底：文档有定义时以文档为准；文档不可用或未覆盖时以 schema 为准
  • 递归穿透：获取到的文档中包含引用链接时，继续加载以建立完整理解（路径解析规则见 Phase 2 步骤 3）

Workflow（摘要）

Phase 0（lazy preflight）

默认不强制在每个新会话先检查 smartbi-cli 安装/~/.smartbi/config.yaml。

直接进入 Phase 1（list / discover）。

当任意一次实际执行 smartbi（任意子命令）时，若出现下列情况，才读取 references/init.md 做补齐与排查：

CLI 不存在（最高优先级，MUST 先于一切）

若 shell/系统明确提示 找不到 smartbi 可执行文件（例如 command not found、'smartbi' 不是内部或外部命令、is not recognized、ENOENT、退出码 127 等），说明 尚未安装、未在 PATH，或运行中途被卸载。

此时 MUST：

  1. 立即停止当前 Phase（含 list/search/describe/call）及任何“猜 operationKey、换路径盲试、用 curl 代替 CLI”等行为。
  2. 立刻读取并遵循 references/init.md 中的 标准安装，在终端实际执行 npm install -g @smartbi/cli@latest，并用 smartbi --version 验证成功后再继续。
  3. 验证通过后，按 references/init.md 的 重装后恢复顺序 处理 smartbi init 与配置（不得口述安装、不得跳过版本验证）。

其他惰性触发（仍读 references/init.md）

  • 鉴权/凭证：AUTH_FAILED / FORBIDDEN / PROFILE_NOT_FOUND
  • 服务不可达：NETWORK_TIMEOUT / NETWORK_ERROR / UPSTREAM_UNAVAILABLE
  • 配置缺失或不合法：INVALID_ARGUMENT 且 hint 指向 Config file not found

其余错误按 Phase 4 diagnose 流程处理。

Phase 1（discover）

  1. 默认先执行 smartbi list --agent（必要时 --verbose），将候选全集交给大模型做语义重排。
  2. 若结果过大，先加 --domain / --service 再次 list 收敛。
  3. 产出 Top-N 候选后，对每个候选调用 smartbi search <operationKey> --verbose --agent 获取详细信息（description、请求/响应 schema、参数等），由大模型基于详细信息做二次筛选以消歧。
  4. 经二次筛选后若仍有多条候选，则让用户选择 operationKey（见 references/discovery.md 模板）。
  5. search 的关键词检索仅作为补充回退手段（例如用户提供了明确关键词锚点时），不再作为默认第一步。

Phase 1 定位约束（MUST）：

  • MUST 默认使用 list 路径定位接口，不得先走 search 作为主路径。
  • MUST 产出 Top-N 后先对每个候选执行 smartbi search <operationKey> --verbose --agent 以获取详细信息辅助选择。
  • MUST 在用户未确认前停在候选阶段，不得直接进入 describe / call。

Phase 2（contract）

smartbi describe <operationKey> --agent

消费字段：callParameterPlan、requestBodySchema、consumes/produces、suggestedCall。

文档加载（优先获取，不可用时兜底）

describe 完成后，应主动尝试加载关联文档作为理解接口语义的理论依据。

步骤 1：识别文档来源

维度识别方式示例
description 中的链接扫描 describe 输出的 description 字段中的 Markdown 链接[MDL详情](/docs/specs/tabularmodel/mdl/mdl.md)
requestBodySchema 中的链接沿 $ref 链查找被引用 schema 的 description 中的链接schemas.yaml 中组件定义的 description
domain 推断根据 operationKey 所属 domain 推断相关文档目录createDataSet → docs/specs/tabularmodel/
数据类型推断根据请求体中涉及的核心数据类型推断参考文档含 DataSetMeasure → docs/specs/tabularmodel/mdl/references/measures.md
llmBrief / summary 中的引用检查 describe 输出其他字段中的文档引用—

步骤 2：加载文档：对识别到的文档路径，执行 smartbi doc <path> --agent，将返回的 content 纳入上下文。

步骤 3：递归穿透：加载的文档内容中包含的引用链接应继续加载，以建立完整理解：

  • 绝对路径链接（以 / 开头）：直接作为 path 传给 smartbi doc
  • 相对路径链接（不以 / 开头）：基于当前文档路径解析为绝对路径后传给 smartbi doc（如 ../../design/xxx.md → /docs/design/xxx.md）
  • 外部 URL（https://...）：使用 WebFetch 获取
  • 导航类文档（如 guide.md）中的目录链接宜优先穿透

步骤 4：文档优先，schema 兜底：

  • 文档有定义时，以文档为基准对照理解 schema（文档提供业务含义、枚举值、字段依赖、使用示例，schema 提供结构约束）
  • 文档不可用或未覆盖的字段，直接使用 requestBodySchema 和 callParameterPlan

文档引用处理（MUST）：若 description 中包含 Markdown 链接（如 [详情](/docs/specs/demo/test.md) 等引用），MUST 执行：

  1. smartbi doc <path> --agent 获取文档内容（path 取链接中的路径，如 /docs/specs/demo/test.md）
  2. 将返回的 content 纳入上下文辅助理解接口语义
  3. 若获取到的文档内容中包含更多引用链接，且对理解当前接口有帮助，应继续递归获取：
    • 绝对路径链接（以 / 开头，如 /docs/design/xxx.md）：直接作为 path 传给 smartbi doc
    • 相对路径链接（不以 / 开头，如 ../../design/xxx.md）：基于当前文档的 URL 路径解析为绝对路径后再传给 smartbi doc（例如 /docs/specs/demo/test.md 中的 ../../design/xxx.md → /docs/design/xxx.md）
  4. 外部 URL（https://...）链接使用 WebFetch 获取
  5. MUST NOT 忽略链接或自行猜测文档内容

Phase 3（execute）

smartbi call <operationKey> ... --agent

参数构造依据（文档优先，schema 兜底）

构造 call 参数时，遵循「文档优先级原则」确定每个字段的值：

  1. 文档有定义时以文档为准：如文档已明确字段的合法枚举值、业务含义、字段间依赖关系或完整示例，直接使用文档中的定义。
  2. 文档不可用或未覆盖时以 schema 为准：降级使用 requestBodySchema 和 callParameterPlan 确定字段类型、必填/可选及嵌套结构。
  3. 仍无法确定的字段：向用户确认，不应自行编造。

请求体构造

  • JSON 请求体必须使用 -d @file.json（MUST，避免跨 shell/OS 转义差异）
  • MUST NOT 使用内联 JSON（如 -d '{"k":"v"}' 或 -d "{\"k\":\"v\"}"）
  • 为本轮 call 新建的 JSON 文件：在 call 流程结束后 MUST 删除（详见 references/call.md「临时请求体文件」）；不得删除用户自带的 @ 文件
  • 写请求重试必须幂等门控（--idempotent 与/或 describe 元数据）

前置条件检测与子任务（MUST）：

  • 执行 call 前，若根据 Phase 2 describe 的 callParameterPlan / requestBodySchema 判定存在依赖其他 smartbi 操作才能获取的参数值（如需要先查询资源 ID、先创建关联对象等），则 MUST 先创建子任务处理前置需求。
  • 子任务内容：再次发动 smartbi-cli 技能，以用户业务意图描述完成该前置操作，获取所需参数值。
  • 前置子任务完成后，将结果填入当前 call 的参数，再继续执行。
  • MUST NOT 跳过前置条件直接调用，也 MUST NOT 用占位值/假值代替。
  • 退出机制（MUST）：子任务链受以下硬限制保护，任一限制触发时 MUST 立即停止自动化流程，执行用户升级流程（详见 references/call.md「前置条件与子任务」）：
    • 深度上限：子任务嵌套深度 ≤ 3（原始 call 为深度 0，每嵌套一层 +1）
    • 数量上限：每个父 call 的直接前置子任务 ≤ 5 个
    • 去重：同一 operationKey + 相同参数意图，在同一调用链（从原始 call 到当前深度的全链路）中已完成的前置操作，不得重复发起，应复用已获取的结果
    • 触发退出时：列出已完成的前置结果 + 未完成的前置条件清单，请用户选择后续操作（直接提供值 / 指定部分继续自动处理 / 跳过非必填项）

Phase 4（diagnose on failure）

失败后 smartbi describe <operationKey> --agent；仍有契约歧义再加 --include-raw-schema

Output Contract（固定顺序）

  1. operationKey
  2. 最终执行命令
  3. 关键结果（status/tid/核心业务字段）
  4. 若失败：单行修复建议 + 下一条可执行命令

Detail Fetch Policy（按需 RAG）

默认只使用本摘要。需要模板/字段映射/检查清单/异常分支时，以及需要加载接口关联文档时，才读取：

参考文件（skill 内部指引）

  • references/init.md
  • references/discovery.md
  • references/describe.md
  • references/call.md
  • references/strategy.md

业务文档（接口语义理解，MUST 按需加载）

  • docs/specs/ 下的所有业务文档：通过 smartbi doc <path> --agent 获取，用于理解接口的完整语义、字段合法值、参数构造约束。
  • 触发时机：Phase 2 识别到文档关联时（见 Phase 2「文档加载与理解」步骤 1）。
  • 递归加载：文档内的引用链接 MUST 穿透加载，直到所有必要信息都已获取。
  • 优先级：业务文档的优先级高于本 skill 的参考文件和 schema 定义（见「文档优先级原则」）。