FineBI 主技能

这个文件是 finebi-skills 包的主技能入口。它负责先识别用户目标，再路由到合适的子技能，而不是把所有场景的细节流程都堆在一个文件里。

运行前提

finebi-skills 依赖外部 CLI：

• 必须先安装 finebi-cli
• 必须能在终端里直接执行 finebi-cli
• 必须配置 FineBI 访问所需环境变量

推荐安装方式：

npm install -g finebi-cli

常见配置方式

有两种常见方式可以让 finebi-skills 读到 FineBI 配置：

1. 单独使用 finebi-cli

• 运行 finebi-cli init
• 配置会写入 ~/.finebi-cli/.env
• 之后可以在任意目录使用 finebi-cli

1. 在 OpenClaw 等宿主工具中使用

• 用户可以直接把 FINEBI_BASE_URL、FINE_ACCESS_TOKEN 配置到宿主工具自己的 .env
• 如果宿主在启动 finebi-cli 时会自动带上这些环境变量，skill 就可以直接复用它们
• 这种情况下不一定需要单独运行 finebi-cli init

启动检查

在进入任何子技能流程之前，先做下面的检查：

1. 检查 finebi-cli 是否可执行。
2. 检查 FINEBI_BASE_URL 是否已配置。
3. 检查认证信息是否已配置，例如 FINE_ACCESS_TOKEN。

如果 finebi-cli 不可用：

• 不要继续执行后续 workflow
• 先明确提示用户安装 finebi-cli

如果环境变量缺失：

• 不要伪造连接结果
• 先提示用户完成 FineBI 连接配置

什么时候先用主技能

当用户要做下面这些事情时，先命中这个主技能：

• 查找并分析看板、组件和指标
• 生成日报、周报、月报或经营分析文档
• 监控阈值并转成任务或提醒
• 把 FineBI 数据同步到外部表格系统

子技能索引

| 子技能 | 目录 | 处理场景 |

| --- | --- | --- |

| dashboard-briefing | skills/dashboard-briefing | 看板摘要、群播报、定时简报 |

| report-to-doc | skills/report-to-doc | 看板导出、分析报告、文档沉淀 |

| alert-to-task | skills/alert-to-task | 阈值监控、异常检测、任务创建 |

| sync-to-bitable | skills/sync-to-bitable | 数据同步到飞书多维表格 |

路由规则

路由到 dashboard-briefing

当用户提到以下意图时优先路由：

• “给我生成日报/周报摘要”
• “把经营看板同步到群里”
• “做一个定时播报”
• “先发一条测试卡片看看”

路由到 report-to-doc

当用户提到以下意图时优先路由：

• “把这个看板整理成文档”
• “导出 PDF 后做分析报告”
• “给我一份经营分析稿”
• “把图表和结论沉淀成文档”

路由到 alert-to-task

当用户提到以下意图时优先路由：

• “低于阈值就告警”
• “异常时自动建任务”
• “监控库存、销量、回款”
• “命中条件后通知负责人”

路由到 sync-to-bitable

当用户提到以下意图时优先路由：

• “同步到飞书多维表格”
• “按主键增量更新”
• “覆盖整张表”
• “定时把数据灌到 bitable”

全局约束

• 先确认 finebi-cli 和 FineBI 环境可用，再执行业务流程。
• 先定位数据对象，再执行动作。数据对象可能是 dashboard、dataset、subject、widget。
• 看板问答、指标解释和组件取数场景，必须先按 references/dashboard-question-answer-flow.md 执行。
• 只要后续流程需要看板的id dashboardId，必须先按 references/dashboard-id-resolution-flow.md 判断来源并解析 id。
• 定位仪表板时，默认先从挂出目录或已发布入口查找，再从“我的分析”查找。
• 调用 get-entry-tree 读取目录树时，应优先使用 -k 过滤，避免拉取过大的目录树响应。同时注意get-entry-tree 的响应结果中的templateId禁止作为 dashboardId 使用。
• export-dashboard-excel 获取仪表板中所有组件完整数据。
• 只有用户明确要求某个具体组件、图表或指标卡的数据时，才进入组件取数链路。
• 组件取数必须先用 resolve-dashboard-widgets 获取可取数组件候选，再调用 get-widget-data。
• 先拿到 FineBI 的真实输出，再做摘要、判断、告警、写文档或同步。
• 复核 FineBI Excel 导出内容时，必须用 read_only=False 打开工作簿检查真实单元格内容。
• 禁止伪造指标、趋势、负责人、任务状态、导出结果和同步结果。
• 禁止仅凭 read-only 模式下的 max_row、max_column 或首行预览判断 Excel “无数据”或“只有表头”。
• 禁止通过自写 JS、Python、浏览器自动化、抓包或猜 HTTP 接口等方式绕过 finebi-cli 查找 dashboardId、widgetId 或数据。
• 如果 CLI 链路无法定位目标，必须停止并澄清或报告“缺少 CLI 能力”，不要自建替代链路。
• 如果目标对象不唯一，必须先澄清，不能跳步。
• 如果子技能匹配已经明确，直接按子技能流程继续，不要在主技能里重复展开细节。

公共参考

• CLI 命令与契约：references/cli-command-map.md
• 看板问答取数链路：references/dashboard-question-answer-flow.md
• 仪表板 id 解析：references/dashboard-id-resolution-flow.md
• 仪表板组件取数：references/dashboard-widget-data-flow.md
• 数据集查找与预览：references/dataset-search-and-preview-flow.md
• 路由与拆分约定：references/skill-routing.md

无匹配时的降级策略

如果用户目标不能明确落到某一个子技能：

1. 先判断更像“看板消费”还是“数据集处理”。
2. 如果更像看板消费场景，优先走 dashboard-briefing。
3. 如果更像数据搬运或落库场景，优先走 sync-to-bitable。
4. 如果仍然不明确，只追问一个关键问题，不要一次追问多个问题。