---
name: shb-cli
version: "1.1.0"
description: "当用户需要安装、配置、快速上手 shb-cli，或需要判断应使用哪个 SHB 业务 skill/命令层级时触发。提供售后宝 CLI 的安装、认证、能力总览、Agent 调用顺序、命令分层、安全规则和业务 skill 路由。"
metadata:
  cliHelp: "shb-cli --help"
---

# shb-cli

售后宝通用命令行工具，面向人类用户与 AI Agent。当前覆盖工单、客户、产品、备件、云仓物料、PaaS 应用等核心业务域，提供 80+ 命令与 11 个 Agent Skills。

本技能是 shb-cli 的总入口：先完成安装与认证，再按用户目标路由到具体业务 skill。

## 何时使用

- 用户首次安装、升级、验证 `shb-cli`。
- 用户需要快速开始使用售后宝 CLI。
- 用户不知道该用哪个 `shb-*` skill。
- 用户需要理解命令层级、输出格式、安全规则或环境选择。
- 用户要让 AI Agent 自动操作售后宝系统。

## 能力概览

<!-- gen:modules:capabilities:begin -->
| 业务域 | Skill | 主要能力 |
| --- | --- | --- |
| 共享基础 | `shb-shared` | 登录认证、状态检查、token 管理、租户切换、权限异常恢复 |
| 工单 | `shb-task` | 搜索、详情、类型查询、字段查询、创建、更新、派发分配、回访满意度查询 |
| 事件 | `shb-event` | 搜索、详情、类型查询、字段查询、创建、更新 |
| 客户 | `shb-customer` | 客户搜索、联系人、地址、字段查询、客户创建 |
| 产品 | `shb-product` | 产品搜索、字段查询、目录类型、产品创建 |
| 标签 | `shb-label` | 跨模块智能标签（智能标签分组）查询，供工单/客户/产品的标签过滤搜索使用 |
| 备件 | `shb-part` | 备件搜索、详情、字段查询、库存查询、个人备件库查询（只读） |
| 云仓物料 | `shb-warehouse-material` | 物料搜索、详情、字段查询、字段唯一性校验、创建、编辑（含批量）、删除、启停用 |
| 云仓物料服务BOM | `shb-warehouse-bom` | 物料服务BOM搜索、详情、组成物料树查询、创建、编辑、删除、启停用、撤销删除 |
| 云仓物料替换 | `shb-warehouse-replacement` | 物料替换搜索、详情、按原始物料查有效替换候选、字段查询、创建（含批量）、编辑、删除、启停用 |
| PaaS 应用/表单 | `shb-paas` | 应用、模板、流程、表单数据、应用数据、外部分享 |
<!-- gen:modules:capabilities:end -->

## 安装

### 从 npm 安装

```bash
npm install -g @publink-ai/cli
```

### 从源码构建

需要 Go 1.26+。

```bash
git clone https://gitee.com/publink/shb-cli.git
cd shb-cli
make build        # 生产构建
make build-test   # 测试构建，走 pubapp.shb.ltd
```

### 安装 Agent Skills

```bash
# 安装整个仓库的 skills
npx skills add https://gitee.com/publink/shb-cli.git -y -g

# 本地仓库调试
npx skills add . -y -g

# 只安装指定 skill
npx skills add . --skill shb-cli --skill shb-shared --skill shb-task -y -g
```

安装完成后，重启 Agent 工具让 skills 生效。

## 快速开始

### 人类用户

```bash
# 1. 交互式登录
shb-cli auth login

# 2. 查看当前配置与认证状态
shb-cli config

# 3. 开始使用
shb-cli task search
shb-cli task detail --id <task-id>
shb-cli task type list
```

### AI Agent

Agent 执行时显式传 `--env`，避免卡在交互选择。

```bash
# 1. 确认可执行文件可用
shb-cli version --json

# 2. 发起登录。后台执行时提取授权链接发给用户
shb-cli auth login --env <environment> --no-browser

# 3. 用户完成浏览器授权后验证状态
shb-cli config

# 4. 进入业务命令
shb-cli task search
```

`environment` 可选值：

| 环境 | 说明 | 域名 | 支持切换租户 |
| --- | --- | --- | --- |
| `dingtalk` | 钉钉集成 | `shb3144.eapps.dingtalkcloud.com` | 否 |
| `lark` | 飞书集成 | `cloud.shb.ltd` | 否 |
| `standalone` | 独立端 | `cloud.shb.ltd` | 是 |
| `wecom` | 企业微信集成 | `cloud.shb.ltd` | 否 |

## 认证

推荐路径：

```bash
shb-cli auth login --env <environment>
shb-cli config
```

常用命令：

```bash
shb-cli auth login --env dingtalk
shb-cli auth login --env lark
shb-cli auth login --env standalone
shb-cli auth login --env wecom
shb-cli auth logout
shb-cli auth switch-tenant --list
shb-cli auth switch-tenant --tenant-name <tenant-name> --password <password>
```

`shb-cli config` 输出中应确认：

- `authenticated: true`
- `valid: true`

遇到 401、`token is empty`、`valid: false`，切到 `shb-shared` skill 处理认证恢复。

## Skill 路由

先读 `shb-shared`，再读具体业务 skill。

业务域优先级:

<!-- gen:modules:routing:begin -->
- 用户明确说"paas/PaaS/PASS",或提到某个表单/菜单名(含仍在用"应用/应用数据"这类说法)时,统一优先进入 PaaS 表单逻辑(按表单/菜单名定位),不再区分"应用"与"表单"(对应技能 `shb-paas`)。
- 明确说"工单"、"事件"、"客户"、"产品"、"备件"、"云仓/物料"、"BOM/物料服务BOM"、"物料替换"时,分别优先进入`shb-task`(工单)、`shb-event`(事件)、`shb-customer`(客户)、`shb-product`(产品)、`shb-part`(备件)、`shb-warehouse-material`(云仓物料)、`shb-warehouse-bom`(云仓物料服务BOM)、`shb-warehouse-replacement`(云仓物料替换)。注意区分:事件与工单是两个独立模块,事件可转为工单,但"事件"相关请求走事件技能,不要按工单处理;物料(云仓)与备件是两个独立业务系统,不要混用;物料服务BOM与物料替换是物料主数据下两个互不相关的子概念,不要混淆,物料主数据/物料服务BOM/物料替换分别由独立技能覆盖,按用户意图选择对应技能。
- 未明确业务域但问"表单数据"或某个名称"有多少数据/多少条/记录数"时,优先按 PaaS 表单/菜单名探测;命中后进入 `shb-paas`,未命中再根据上下文选择其他业务域。
<!-- gen:modules:routing:end -->

<!-- gen:modules:readorder:begin -->
| 用户目标 | 读取顺序 |
| --- | --- |
| 安装、登录、状态检查、租户切换 | `shb-cli` -> `shb-shared` |
| 搜索/查看/创建/更新/派发工单、查询回访满意度 | `shb-cli` -> `shb-shared` -> `shb-task` |
| 搜索/查看/创建/更新事件 | `shb-cli` -> `shb-shared` -> `shb-event` |
| 搜索客户、联系人、地址、创建客户 | `shb-cli` -> `shb-shared` -> `shb-customer` |
| 搜索产品、字段、目录、创建产品 | `shb-cli` -> `shb-shared` -> `shb-product` |
| 查询标签列表、按标签过滤工单/客户/产品搜索 | `shb-cli` -> `shb-shared` -> `shb-label` |
| 搜索/查看备件、备件字段、备件库存、个人备件库 | `shb-cli` -> `shb-shared` -> `shb-part` |
| 搜索/查看/创建/编辑/删除云仓物料 | `shb-cli` -> `shb-shared` -> `shb-warehouse-material` |
| 搜索/查看/创建/编辑/删除云仓物料服务BOM | `shb-cli` -> `shb-shared` -> `shb-warehouse-bom` |
| 搜索/查看/创建/编辑/删除云仓物料替换记录 | `shb-cli` -> `shb-shared` -> `shb-warehouse-replacement` |
| 操作 PaaS 应用、模板、流程、表单，或查询表单数据/应用数据 | `shb-cli` -> `shb-shared` -> `shb-paas` |
<!-- gen:modules:readorder:end -->

## 命令分层

shb-cli 提供三层调用入口：

1. 普通业务命令：`shb-cli task search`、`shb-cli customer list`，适合日常操作。
2. 快捷命令：`shb-cli task task-search`、`shb-cli task task-detail`，适合 Agent 快速完成高频任务。
3. Spec/API 命令：`shb-cli service ...`、`shb-cli api ...`，适合调试、复杂 payload 和底层接口访问。

默认优先使用普通业务命令；需要高级封装时使用挂在各业务命令下的 shortcut 子命令(如 `task task-search`、`paas apps`)；需要底层能力时再使用 `service/api`。

## 输出与调试

```bash
shb-cli task search                       # 默认 JSON
shb-cli task search | jq '.content[]'     # 配合 jq 处理
shb-cli version
shb-cli version --json
shb-cli completion zsh >> ~/.zshrc
```

`version --json` 输出中包含 `build_env`（`prod` / `test`）和 `_notice.update`。当 `_notice.update: true` 时，建议用户更新：

```bash
npm update -g @publink-ai/cli
```

## 写操作安全

- 创建、更新、删除、部署、审批、派发等写操作执行前，先取得用户明确确认。
- 复杂 payload 使用 `--file` 或 `--payload-file`，减少命令行 JSON 拼接错误。
- 支持 `--dry-run` 的命令优先预览请求。
- token 属于敏感凭证，输出、日志、仓库文件里都应保持脱敏。
- 普通用户路径只需要 `auth login` 与 `config`，底层 `org-code`、`domain`、`authorize-url` 参数用于调试和兼容场景。

## 命令速查

<!-- gen:modules:commands:begin -->
```text
config
auth login|logout|switch-tenant|token-import
task alloc submit|create submit|detail|field common|field list|review dynamic|
     review fields|review init|review search|search|task-detail|task-search|
     type list|update submit
event create submit|detail|field list|search|type list|update submit
customer address list|create|field list|linkman search|list|update submit
product catalog field list|catalog list|create|field list|list-link-customer|
        search
label list
part detail|field list|personal holding|personal search|personal stock-record|
     personal use-record|personal users|search|stock distribution|stock search
warehouse bom create|bom delete materials|bom detail|bom edit status|
          bom materials|bom revert|bom search|material create|material delete|
          material detail|material field check|material field list|
          material search|material update batch|material update status|
          replacement by-original|replacement create batch|replacement delete|
          replacement detail|replacement edit enable|replacement field list|
          replacement field save-fields|replacement search
paas app forms|flow approve|flow attribute|flow back-to-me|flow batch-transfer|
     flow buttons|flow countersign|flow deploy|flow get|flow log|
     flow log-progress|flow log-pure-form|flow pause|flow redeploy|flow resume|
     flow start|flow urge|flow version condition|flow version condition-new|
     flow version create|flow version current|flow version delete|
     flow version edit|flow version enable|flow version list|flow-buttons|
     flow-log|form api-request|form batch-get|form batch-update|
     form batch-with-flow-log|form create|form delete|form delete-phone|
     form finish-content|form formula-value|form get|form get-for-print|
     form get-sn|form outer-get-field-setting|form outer-get-setting|
     form outer-list-phone|form reset-pwd|form save|form save-field-setting|
     form save-phone|form save-setting|form search|form share|
     form start-content|form switch|form-share|template add-fields|
     template all-apps|template all-list|template all-list-v2|
     template all-node-fields|template attachment-fields|template back-gray|
     template check-state|template create|template delete|template fields|
     template fields-by-template|template get|template have-data-templates|
     template node-fields|template process-forms|template product-fields|
     template related-fields|template related-text|template required|
     template save-fields|template select-info|template sms-fields|
     template-fields
completion bash|fish|powershell|zsh
version
```
<!-- gen:modules:commands:end -->

## References

<!-- gen:modules:references:begin -->
- [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md) —— 认证、配置、租户与共享安全规则
- [`../shb-task/SKILL.md`](../shb-task/SKILL.md) —— 搜索、详情、类型查询、字段查询、创建、更新、派发分配、回访满意度查询
- [`../shb-event/SKILL.md`](../shb-event/SKILL.md) —— 搜索、详情、类型查询、字段查询、创建、更新
- [`../shb-customer/SKILL.md`](../shb-customer/SKILL.md) —— 客户搜索、联系人、地址、字段查询、客户创建
- [`../shb-product/SKILL.md`](../shb-product/SKILL.md) —— 产品搜索、字段查询、目录类型、产品创建
- [`../shb-label/SKILL.md`](../shb-label/SKILL.md) —— 跨模块智能标签（智能标签分组）查询，供工单/客户/产品的标签过滤搜索使用
- [`../shb-part/SKILL.md`](../shb-part/SKILL.md) —— 备件搜索、详情、字段查询、库存查询、个人备件库查询（只读）
- [`../shb-warehouse-material/SKILL.md`](../shb-warehouse-material/SKILL.md) —— 物料搜索、详情、字段查询、字段唯一性校验、创建、编辑（含批量）、删除、启停用
- [`../shb-warehouse-bom/SKILL.md`](../shb-warehouse-bom/SKILL.md) —— 物料服务BOM搜索、详情、组成物料树查询、创建、编辑、删除、启停用、撤销删除
- [`../shb-warehouse-replacement/SKILL.md`](../shb-warehouse-replacement/SKILL.md) —— 物料替换搜索、详情、按原始物料查有效替换候选、字段查询、创建（含批量）、编辑、删除、启停用
- [`../shb-paas/SKILL.md`](../shb-paas/SKILL.md) —— 应用、模板、流程、表单数据、应用数据、外部分享
<!-- gen:modules:references:end -->