Article body
正文
本文面向使用 AI Coding Agent 进行 BI 开发的工程师和技术管理者，深入拆解 HENGSHI CLI 的 16 个 repo-managed skills 套件，从 Foundation、Data & Semantics、Delivery 到 Automation 四大域逐一解析，帮助你在 AI Agent 驱动的 BI 工程中实现全链路自动化。
一、为什么 CLI 需要 Skills 套件
在 AI Agent 时代，BI 工程不再是「打开界面点鼠标」的纯人工操作。当 Claude Code、Codex、OpenClaw 等编码代理接管 BI 开发任务时，它们需要一个可编程、可审查、可编排的执行面——这就是 HENGSHI CLI 的核心价值。
但问题在于：如果把几百条命令和参数塞进一条超长提示词，Agent 的上下文窗口会迅速膨胀，输出质量断崖式下跌。衡石的设计哲学很清楚：按资源域拆复杂度，把 BI 工程拆成 16 个独立的 skills，每个 skill 只负责一个清晰的职责域。
这样做有三个好处：降低 Agent 认知负担（每个 skill 的提示词不超过一屏，Agent 不会「迷路」）、复用即插即用（Claude Code、Codex、OpenClaw、Hermes Agent 都能沿用同一套 skill 边界）、help-first 规约（每个 skill 默认先查看帮助再执行，避免参数臆测）。
二、16 个 Skills 全览：四大域划分
衡石将 16 个 skills 按 BI 工程的自然边界划分为四个域。
Foundation 域（基础层） 包含四个 skills。hbi-core 负责认证、偏好设置、输出格式和术语管理。hbi-app 负责应用空间管理。hbi-permission 负责权限治理。hbi-user-mgmt 负责组织与用户治理。
Data & Semantics 域（数据与语义层） 包含四个 skills。hbi-data 负责连接与数据集管理。hbi-data-modeling 负责 Join 模型和语义建模。hbi-indicator-center 负责主题域指标。hql-expert 负责 HE 和 HQL 表达式。
Delivery 域（交付层） 包含四个 skills。hbi-dashboard 负责仪表板生成。hbi-dashboard-taste 负责页面感设计。hbi-data-alert 负责图表预警。hbi-data-agent 负责 Data Agent 后台治理。
Automation 域（自动化层） 包含四个 skills。hbi-pipeline 负责 ETL 集成。hbi-notebook 负责 Notebook 执行。hbi-scheduler 负责计划治理。hbi-workflow 负责跨域 runbook 编排。
下面逐一深度拆解。
三、Foundation 域：让 Agent 先站稳脚跟
hbi-core：认证、偏好与术语管理。 这是 Agent 接入衡石平台的第一道闸门。它不处理业务数据，但决定了 Agent 能不能「进门」、以什么身份进门、用什么格式说话。Agent 可以检查认证状态（查看认证提供者、用户身份和令牌过期时间）、设置默认输出格式（Agent 友好的 JSON 结构化输出）、查询当前偏好（输出格式、时区、语言区域）。安全设计亮点是令牌不写入本地配置文件，而是进入系统 Keyring（macOS Keychain、Linux Secret Service、Windows Credential Manager），即使 Agent 的运行环境被攻破，敏感凭证也不会以明文形式泄露。
hbi-app：应用空间管理。 在衡石的多租户架构中，「应用（App）」是业务分析的基本隔离单元。一个 App 对应一个独立的分析空间，拥有自己的数据集、仪表盘、指标体系和权限策略。Agent 可以列出所有应用（查看应用 ID、名称、状态和创建时间），也可以查看应用详情。
hbi-permission：权限管理。 企业级 BI 的权限管理远不止「谁能看什么」这么简单。它覆盖了从数据集、仪表盘到单个图表元素的多级授权。关键设计是预演（dry-run）机制——Agent 的任何授权操作都必须先经过预演，输出「如果执行会怎样」的预览结果，再由人工确认后执行。这从根本上避免了 Agent「自作主张」修改权限的安全风险。
hbi-user-mgmt：组织与用户治理。 可以列出用户组、添加用户到组，所有操作同样支持预演确认。
四、Data & Semantics 域：把数据变成 Agent 能理解的语言
hbi-data：连接与数据集管理。 这是整个 BI 工程的起点。Agent 可以列出所有数据连接（查看连接 ID、类型、主机地址和连接状态），也可以查看数据集详情（指标数量、维度数量和关联的数据连接）。
hbi-data-modeling：Join 模型。 在真实业务场景中，数据往往分散在多个数据集中。这个 skill 支持查询和探索跨数据集的关联模型。Agent 可以探索数据模型关系（指定数据集和探索深度），理解数据之间的血缘关系。
hbi-indicator-center：主题域指标。 衡石的指标管理采用「一处定义，多方使用」的理念。这个 skill 按主题域管理业务指标体系。Agent 可以查看主题域列表、查看指标详情。
hql-expert：HE/HQL 表达式。 这是衡石最核心的技术差异点之一。HQL（HENGSHI Query Language）和 HE 表达式是衡石的指标查询语言，让 Agent 不需要理解底层 SQL 就能表达复杂的业务逻辑。Agent 可以直接用自然语言意图转化为 HQL 查询。为什么 HQL 对 AI Agent 特别友好？因为 SQL 需要理解表结构、字段名和 JOIN 关系（对 Agent 来说是「黑盒」），而 HQL 基于已定义的指标语义层，Agent 只需调用语义层已注册的指标和维度，避免了 Agent「幻觉」出错误的 SQL 语法。
五、Delivery 域：把分析资产变成可交付物
hbi-dashboard：仪表板生成。 这是交付层的核心 skill。它不是简单的「创建一个页面」，而是通过 Dashboard Plan 机制让 Agent 先输出一个可审查的规划，再执行创建。典型工作流是：Agent 读取当前 App 的上下文（数据集、指标、维度），然后生成规划文档（描述仪表板的布局、图表类型和数据映射），人工审查确认后 Agent 执行应用规划，最后通过 SSE 实时推送变更到前端界面。
hbi-dashboard-taste：页面感设计。 这个 skill 关注的是仪表板的「审美」而非「功能」。Agent 可以应用主题（如 Modern 风格）、查看可用主题列表。这确保了 Agent 生成的仪表板不仅数据准确，而且视觉美观。
hbi-data-alert：图表预警。 Agent 可以创建预警规则（指定仪表板、图表、触发条件和通知渠道），也可以查看预警列表。
hbi-data-agent：Data Agent 后台治理。 这是管理衡石 AI 分析智能体（Data Agent）配置的入口。Agent 可以查看 Data Agent 配置、更新 Agent 提示词模板。
六、Automation 域：把 BI 工程纳入 CI/CD
hbi-pipeline：ETL 集成。 Agent 可以创建数据管道（指定数据源、目标和调度策略）、查看管道状态、触发管道执行。
hbi-notebook：Notebook 执行。 Agent 可以执行 Notebook 分析脚本、查看执行历史。
hbi-scheduler：计划治理。 Agent 可以创建定时任务（指定名称、调度策略和执行动作）、查看任务列表。
hbi-workflow：跨域 runbook 编排。 这是 16 个 skills 中的「指挥家」。它负责编排跨多个域的复合任务。工作流定义文件用结构化格式描述步骤序列，每个步骤指定对应的 skill 和命令。Agent 先进行预演（dry-run）确认无误后再执行。
七、实战：Agent 三阶段工作流
衡石 CLI 将 Agent 的 BI 工程工作流分为三个阶段。
阶段一：读懂当前分析上下文。 Agent 先了解数据连接情况、了解数据集组成、理解数据模型结构、验证查询能力。这一阶段涉及的 skills 按照 hbi-core、hbi-data、hbi-data-modeling、hql-expert 的顺序依次调用。
阶段二：生成可交付物。 Agent 规划仪表板布局（在规划文档中定义名称、主题、数据映射和布局结构），然后应用规划创建仪表板，最后调整主题和样式。涉及的 skills 包括 hbi-dashboard、hbi-dashboard-taste 和 hql-expert。
阶段三：纳入安全与交付节奏。 Agent 设置权限（先预演后执行）、创建定时刷新任务、创建数据预警规则。涉及的 skills 包括 hbi-permission、hbi-scheduler 和 hbi-data-alert。
八、SSE 实时同步：让 Agent 的工作对业务可见
CLI 不把结果锁死在终端里。通过 SSE（Server-Sent Events）机制，Agent 在 CLI 中的每一次操作都会实时推送到前端界面。这意味着 Agent 在终端执行不等于业务人员被蒙在鼓里——每一次数据刷新、图表更新、权限变更，业务人员都能在前端实时看到。Human-in-the-loop 不是事后审查，而是实时协同。
九、Skills 套件的工程价值总结
传统 BI 开发中，认证需要手动登录 Web 界面，数据接入通过界面点击配置，指标定义需要手写 SQL，仪表板创建通过拖拽式人工操作，权限管理在后台逐条配置，定时任务在界面配置，跨域编排需要人工协调多个模块，变更可见性需要刷新页面查看。而 HENGSHI CLI 加 Skills 套件将这一切转化为：OAuth 或 SSO 加 Keyring 自动管理认证、命令加结构化输出完成数据接入、HQL 语义层查询完成指标定义、Dashboard Plan YAML 加自动化 apply 完成仪表板创建、授权命令加预演机制完成权限管理、命令行管理完成定时任务、统一 runbook 完成跨域编排、SSE 实时推送到前端完成变更可见性。从手工操作到全链路自动化的转变，正是 Skills 套件的核心价值。
十、FAQ
Q1：Skills 套件和直接调 API 有什么区别？
API 是原子化的接口，Agent 需要理解几百个 endpoint、参数组合和调用顺序。Skills 是对 API 的语义化封装，每个 skill 的提示词编码了「在什么场景下该做什么、怎么做」的领域知识，Agent 不需要从零拼装 API 调用链。
Q2：预演（dry-run）机制会拖慢 Agent 的执行速度吗？
预演只是一个额外的参数调用，不增加实质性的等待时间。但它增加了一个关键的安全审查点，避免 Agent 在生产环境「先斩后奏」。
Q3：如果我不使用 AI Agent，Skills 对我有用吗？
当然。Skills 的命令树结构也适用于人工运维场景——你可以直接在终端执行命令，跳过 Agent 也是完全可行的。
结语
HENGSHI CLI 的 16 个 Skills 套件，本质上是对 BI 工程知识的结构化编码。它们不是简单的命令封装，而是把「怎么做好 BI 开发」这件事的领域知识，以 Agent 可消费的形式固化为可复用的能力单元。对于正在探索 AI Agent 驱动 BI 开发的团队来说，理解这 16 个 skills 的职责划分和协作关系，是真正释放 Agent 生产力的关键一步。