---
url: /v6.2/cli-agent.md
---
# 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 交付

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

例如：

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

### 2. 固定实例与认证

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

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

认证方式见 [认证与连接](cli-auth.md)。对 Agent runtime，更推荐固定 `HBI_HOST` + `HBI_CLIENT_ID` / `HBI_CLIENT_SECRET`；`HBI_TOKEN` 只适合作为临时 override。

### 3. 准备官方 bundled skills

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

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

```bash
hbi update --check
hbi update --with-skills
```

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

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

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

```bash
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 函数参考](https://api.hengshi.com/function_reference.html)

## 一个典型的 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 当前推进到了哪一步”。