\r \r

Smartbi CLI Skill\r

\r

Summary\r

\r 把用户业务意图映射到唯一 operationKey，并按流程使用 smartbi CLI 完成调用；失败时给可执行修复命令。\r \r operationKey 格式为 ${domain}.${operationId}（如 demo.createOrder、aichat.getAgentItems）。list 输出结果可直接复制作为 describe/call 的参数。\r \r

Triggers\r

\r 当用户描述“业务动作 + 业务对象”，但未显式给出接口名/operationKey（例如“帮我训练模型资源A”“基于模型资源A分析去年销售额”）时触发。\r \r 当用户问及 BI 相关业务操作（分析、训练、指标查询、报表/问句类需求）时，应默认尝试触发本 skill，再通过 discover 流程收敛到唯一 operationKey。\r \r

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

\r

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

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

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

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

文档优先级原则\r

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

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

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

Workflow（摘要）\r

\r

Phase 0（lazy preflight）\r

\r 默认不强制在每个新会话先检查 smartbi-cli 安装/~/.smartbi/config.yaml。\r \r 直接进入 Phase 1（list / discover）。\r \r 当任意一次实际执行 smartbi（任意子命令）时，若出现下列情况，才读取 references/init.md 做补齐与排查：\r \r CLI 不存在（最高优先级，MUST 先于一切）\r \r 若 shell/系统明确提示 找不到 smartbi 可执行文件（例如 command not found、'smartbi' 不是内部或外部命令、is not recognized、ENOENT、退出码 127 等），说明 尚未安装、未在 PATH，或运行中途被卸载。\r \r 此时 MUST：\r \r

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

• 鉴权/凭证：AUTH_FAILED / FORBIDDEN / PROFILE_NOT_FOUND\r
• 服务不可达：NETWORK_TIMEOUT / NETWORK_ERROR / UPSTREAM_UNAVAILABLE\r
• 配置缺失或不合法：INVALID_ARGUMENT 且 hint 指向 Config file not found\r \r 其余错误按 Phase 4 diagnose 流程处理。\r \r

Phase 1（discover）\r

\r

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

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

Phase 2（contract）\r

\r smartbi describe \x3CoperationKey> --agent\r \r 消费字段：callParameterPlan、requestBodySchema、consumes/produces、suggestedCall。\r \r

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

\r describe 完成后，应主动尝试加载关联文档作为理解接口语义的理论依据。\r \r 步骤 1：识别文档来源\r \r | 维度 | 识别方式 | 示例 |\r |------|----------|------|\r | description 中的链接 | 扫描 describe 输出的 description 字段中的 Markdown 链接 | [MDL详情](/docs/specs/tabularmodel/mdl/mdl.md) |\r | requestBodySchema 中的链接 | 沿 $ref 链查找被引用 schema 的 description 中的链接 | schemas.yaml 中组件定义的 description |\r | domain 推断 | 根据 operationKey 所属 domain 推断相关文档目录 | createDataSet → docs/specs/tabularmodel/ |\r | 数据类型推断 | 根据请求体中涉及的核心数据类型推断参考文档 | 含 DataSetMeasure → docs/specs/tabularmodel/mdl/references/measures.md |\r | llmBrief / summary 中的引用 | 检查 describe 输出其他字段中的文档引用 | — |\r \r 步骤 2：加载文档：对识别到的文档路径，执行 smartbi doc \x3Cpath> --agent，将返回的 content 纳入上下文。\r \r 步骤 3：递归穿透：加载的文档内容中包含的引用链接应继续加载，以建立完整理解：\r \r

• 绝对路径链接（以 / 开头）：直接作为 path 传给 smartbi doc\r
• 相对路径链接（不以 / 开头）：基于当前文档路径解析为绝对路径后传给 smartbi doc（如 ../../design/xxx.md → /docs/design/xxx.md）\r
• 外部 URL（https://...）：使用 WebFetch 获取\r
• 导航类文档（如 guide.md）中的目录链接宜优先穿透\r \r 步骤 4：文档优先，schema 兜底：\r
• 文档有定义时，以文档为基准对照理解 schema（文档提供业务含义、枚举值、字段依赖、使用示例，schema 提供结构约束）\r
• 文档不可用或未覆盖的字段，直接使用 requestBodySchema 和 callParameterPlan\r \r 文档引用处理（MUST）：若 description 中包含 Markdown 链接（如 [详情](/docs/specs/demo/test.md) 等引用），MUST 执行：\r

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

Phase 3（execute）\r

\r smartbi call \x3CoperationKey> ... --agent\r \r

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

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

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

请求体构造\r

\r

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

Phase 4（diagnose on failure）\r

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

Output Contract（固定顺序）\r

\r

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

Detail Fetch Policy（按需 RAG）\r

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

参考文件（skill 内部指引）\r

\r

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

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

\r

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