Skill: wahsonleung/smartbi-cli (version 1.1.0)

--- 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 --tmpl` 获取占位符模板），再按文档补齐配置；不得跳过 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；不得试探执行。 2. **分步向用户索要**（一次一个问题），全部获取后后台生成配置文件，用户无需感知中间过程： - **先问 Smartbi 地址**，用户提供后设 `serverType: smartbi` - 用户无法提供 Smartbi 地址时，告知可提供 SDK Server 地址作为替代；高级用户可声明 `sdkserver: http://xxx` 直接设 `serverType: sdk-server` - **再问个人令牌** - 两项都拿到后，后台执行 `smartbi init --tmpl` 获取占位符模板 → 替换占位符 → 写入 `~/.smartbi/config.yaml`，然后仅告知用户"配置已写入" - 详细流程与替换规则见 `references/init.md`「生成配置文件」 3. 全部补齐后再继续。 **`serverType` 取值约束（MUST）**：`serverType` 只能是 `sdk-server` 或 `smartbi`，不得使用其他变体（`Smartbi`、`smartbi-server`、`sdk_server`、`sdkServer` 等均无效）。 典型缺项：`baseUrl` 缺失/为空；`token` 缺失/为占位值（如 `your-api-token`）；`serverType` 不在 `[sdk-server, smartbi]` 内。 ## 文档优先级原则 构造 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`，将候选全集交给大模型做语义重排。 2. 若结果过大，先加 `--domain` / `--service` 再次 `list` 收敛。 3. 若候选唯一且语义明确匹配 → 直接向用户确认该 `operationKey`，进入 Phase 2。不要继续 search。 4. 若存在多条疑似候选无法区分 → 仅对难以区分的候选调用 `smartbi search <operationKey> --verbose --agent` 获取详细信息以消歧。MUST NOT 对所有 Top-N 逐个 search。 5. `search` 的关键词检索仅作为补充回退手段（例如用户提供了明确关键词锚点时），不作为默认第一步。 Phase 1 定位约束（MUST）： - MUST 默认使用 `list` 路径定位接口，不得先走 `search` 作为主路径。 - `search --verbose` 仅用于消歧，不得对每个候选盲目执行。 - 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`（`--agent` 仅影响 stderr 错误格式，stdout 为原始文档文本），将 stdout 输出纳入上下文。 **步骤 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`；`--agent` 仅影响 stderr 错误格式，stdout 为原始文档文本） 2. 将 stdout 输出的文档文本纳入上下文辅助理解接口语义 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 定义（见「文档优先级原则」）。


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)