Agent 接入与 skills

CLI 不是替代 Agent，而是给 Agent 一个稳定的命令入口

HENGSHI CLI 同时适合人工终端和 Agent 集成。本页重点讲的是：当你准备把 CLI 接入 OpenClaw 或其他 Agent 运行时，怎样让执行路径更稳定、更可审查。

推荐心智模型如下：

层级	作用
人	提需求、审结果、确认风险边界
Agent	理解任务、拆步骤、决定调用哪类能力
skills	把领域经验沉淀成可复用的标准流程
HENGSHI CLI	真正执行读取、预演、创建、更新、授权等动作

为什么 Agent 适合走 CLI

• 结构化输出稳定：json / yaml 更适合 Agent 读写
• 命令边界明确：比让 Agent 临时拼 API 更安全
• 可预演：高风险写动作可以先 --dry-run
• 易于复用：本地、CI、自动化任务和 Agent 运行时都能沿用同一套命令
• 可审查：执行链更容易落日志、回放与追责

官方 skills 的定位

HENGSHI CLI 会与官方 bundled skills 一起交付。官方 skills 通常覆盖这几类高频能力域；面向使用者说明时，推荐同时写 skill 名称和它负责的能力范围：

• hbi-core：认证、配置、输出、术语规则
• hbi-data、hbi-data-modeling、hbi-pipeline、hbi-notebook：连接、数据集、建模、执行与指标
• hbi-dashboard、hbi-dashboard-taste、hbi-app：规划、布局、元素配置与应用页面
• hbi-permission、hbi-user-mgmt：查询、授权、回收与组织治理
• hbi-workflow：跨域编排与顺序控制

skills 的价值主要体现在三点：

1. 先读什么，再写什么
2. 什么动作必须 --dry-run
3. 结果应该如何结构化回传给人或其他系统

推荐接入步骤

1. 先保证运行时里已经完成 CLI 交付

获取方式与安装后验证见 安装与升级。如果你在给团队或客户环境准备 Agent runtime，建议统一固定 CLI 版本和安装入口，而不是让每个运行时各自手工安装。

例如：

curl -fsSL https://download.hengshi.com/cli/install.sh | sh

2. 固定实例与认证

export HBI_HOST="<你的-hengshi-sense-实例>"

HBI_HOST 可以直接写裸 host，也支持像 platform.hengshi.org/bi 这样的二级路径；省略 scheme 时 CLI 会先探测 https://，失败后再试 http://。

认证方式见 认证与连接。对 Agent runtime，更推荐固定 HBI_HOST + HBI_CLIENT_ID / HBI_CLIENT_SECRET；HBI_TOKEN 只适合作为临时 override。

3. 准备官方 bundled skills

当前官方 skills 会随 CLI 一起提供，推荐直接通过 installer 安装，而不是在运行时里再单独拼一套分发逻辑。

如果你已经装好 CLI，推荐优先直接用内置更新命令来同步 CLI 或刷新官方 skills：

hbi update --check
hbi update --with-skills

如果当前安装还不是 updater-managed，再回退到 installer 路径补装或刷新官方 skills：

curl -fsSL https://download.hengshi.com/cli/install.sh | sh -s -- --with-skills

如果你明确知道目标 Agent，也可以在安装时直接写入对应运行时：

curl -fsSL https://download.hengshi.com/cli/install.sh | sh -s -- --with-skills --agent openclaw
curl -fsSL https://download.hengshi.com/cli/install.sh | sh -s -- --with-skills --agent github-copilot

不指定 --agent 时，installer 会按 bundled supported-agents.tsv 自动探测本机已存在的 Agent 配置目录。

4. 约束 Agent 的默认执行策略

建议把下面这些规则写进 Agent 提示或运行时约束：

1. 先读状态，再做写动作
2. 能 --dry-run 的命令先 --dry-run
3. 优先使用 --output json 或 --output yaml
4. 不要自己拼 HENGSHI 私有 API
5. 遇到高风险授权、删除、配置更新时，先把计划返回给人确认
6. 了解 HQL 表达式：构造 data-model query、metric 或 measure 参数时，HQL 支持聚合函数、时间函数和条件逻辑，完整列表见 HQL 函数参考

一个典型的 Agent 执行模式

例如让 Agent “帮我给一个销售应用新建驾驶舱并授权给指定同事”，推荐的执行顺序通常是：

1. 读取应用与数据集上下文
2. 确认目标 dashboard 是否已存在
3. 创建 dashboard
4. 新增图表或其他元素
5. 先 --dry-run 预演授权动作
6. 人确认后再真正授权

这类顺序控制，正是 skills 最适合沉淀的部分。

推荐做法

如果你准备把 CLI 正式纳入 Agent runtime，建议优先遵循下面这些做法：

1. 固定 CLI 版本和 bundled skills 交付方式，避免不同环境各跑一套
2. 默认使用 json 或 yaml 输出，减少 Agent 二次解析成本
3. 对授权、删除、系统配置更新这类动作，坚持先 --dry-run
4. 把 HBI_HOST（或当前保存的本机默认 host）、认证方式和关键命令结果写入运行日志

给 Agent 的输出建议

让 Agent 使用 CLI 时，建议要求它把结果至少整理成下面三类信息：

• 做了什么：执行了哪些读取、预演、写入动作
• 看到什么：关键命令返回了什么结构化结果
• 还缺什么：哪些动作因为权限、上下文或确认流程尚未继续

这样团队成员看到的就不只是一串原始终端输出，而能直接理解“Agent 当前推进到了哪一步”。