smartbi-cli

SKILL.md

---
name: smartbi-cli
description: Trigger on Smartbi BI business asks (训练资源、报表分析、指标/交易统计、大模型问句、先训后查链式意图); map intent to operationKey via 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，立即暂停）

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

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

典型缺项（用于判定，非穷尽）：YAML 未配置 **`baseUrl` 与 `baseUrlEnv` 二者之一**；仅 **`baseUrlEnv`** 但变量未赋值且无 **`baseUrl`** 回落；未配置 `token` 与 `tokenEnv` 二者之一；已配 `tokenEnv` 但进程环境中无对应值；**`serverType` 未配置或配置值与用户实际服务器类型不符**。

## 文档优先级原则

构造 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 定义（见「文档优先级原则」）。