# 售后宝CLI


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


- **Agent 原生设计**：提供组结构化 Skills，专为 Claude Code 等 AI Agent 设计，经过 agent 兼容性测试
- **覆盖完整核心业务域**：工单、事件、客户、产品、备件、云仓物料、PaaS —— 一个工具管理全部 售后宝 核心资源
- **三层命令架构**：普通用户入口 → `shortcuts` 高级快捷封装 → `service/api` 原始 spec 驱动
- **多环境支持**：钉钉、飞书、独立端、企业微信，统一 CLI 命令，3 分钟内从安装到第一次调用
- **安全内置**：token 优先写入 OS keychain，写操作需显式确认，支持 `--dry-run` 预览


## 能力概览

| 业务域 | 模块 | 命令数 | 主要能力 |
|--------|------|--------|---------|
| **工单** | task | 14 | 搜索、详情、类型查询、字段查询、创建、更新、派发分配、回访满意度查询 |
| **事件** | event | 6 | 搜索、详情、类型查询、字段查询、创建、更新 |
| **客户** | customer | 6 | 客户列表搜索、联系人查询、地址查询、字段查询、创建、更新 |
| **产品** | product | 6 | 产品搜索、按客户查产品、字段查询、目录类型、创建 |
| **备件** | part | 10 | 备件搜索、详情、字段查询、库存查询、个人备件库查询（只读） |
| **云仓物料** | warehouse material | 9 | 物料搜索、详情、字段查询、字段唯一性校验、创建、编辑（含批量）、删除、启停用 |
| **云仓物料服务BOM** | warehouse bom | 9 | BOM搜索、详情、组成物料树查询、创建、编辑、删除、启停用、撤销删除 |
| **云仓物料替换** | warehouse replacement | 10 | 替换搜索、详情、按原始物料查有效替换候选、字段查询、创建（含批量）、编辑、删除、启停用 |
| **PaaS 应用/表单** | paas | 70+ | 自定义表单/业务模块：列出与按名定位表单、字段定义查询与增改、表单数据搜索/详情/创建/保存/删除、流程发起、流程日志|



## 安装

### 通过 npm 安装（推荐）

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


### 安装 Agent Skills

```bash
# 通过 npm 包安装
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
```


## 快速开始（人类用户）

**第一步：登录认证**

```bash
shb-cli auth login
```

CLI 会提示选择登录环境：

```
选择登录环境:
  1. 钉钉 (dingtalk)
  2. 飞书 (lark)
  3. 独立端 (standalone) [默认]
  4. 企业微信 (wecom)
请输入序号或环境名称 [standalone]:
```

选择环境后，浏览器自动打开授权页面，完成授权后凭据自动写入本地 profile。

**第二步：验证状态**

```bash
shb-cli config
```

**第三步：开始使用**

```bash
# 搜索工单列表
shb-cli task search

# 查看工单详情
shb-cli task detail --id <task-id>

# 查询工单类型
shb-cli task type list

# 查询 PaaS 表单内容
shb-cli paas form search --template-biz-id <template-biz-id> --keyword <keyword> --page-size 100
shb-cli paas form search --template-biz-id <template-biz-id> --format-data --fields serialNumber,bizId
```

---

## 快速开始（AI Agent）

当你作为 AI Agent 帮用户使用 shb-cli 时，推荐按如下顺序执行：

```bash
# 1. 安装 Skills
npx skills add https://gitee.com/publink/shb-cli.git -y -g

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

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

# 4. 开始执行业务命令
shb-cli task search
```

> **注意**：作为 Agent 执行时，显式传 `--env` 参数避免卡在交互选择。

---

## Agent Skills

| Skill | 描述 |
|-------|------|
| **shb-cli** | 总入口 skill，处理安装、快速开始、能力总览、命令分层、安全规则和业务 skill 路由。 |
| **shb-shared** | 处理首次安装、登录认证、token 管理、租户切换、权限异常恢复。所有其他 skill 的前置依赖。 |
| **shb-task** | 处理工单搜索、详情、类型与字段查询、创建、更新、派发分配与回访满意度查询。依赖 shb-shared 的认证状态。 |
| **shb-event** | 处理事件搜索、详情、类型与字段查询、创建与更新。依赖 shb-shared 的认证状态。 |
| **shb-customer** | 处理客户搜索、联系人、地址、字段查询与创建。依赖 shb-shared 的认证状态。 |
| **shb-product** | 处理产品搜索、字段查询、目录类型与创建。依赖 shb-shared 的认证状态。 |
| **shb-part** | 处理备件搜索、详情、字段查询、库存查询与个人备件库查询（只读）。依赖 shb-shared 的认证状态。 |
| **shb-warehouse-material** | 处理云仓物料搜索、详情、字段查询与唯一性校验、创建、编辑（含批量）、删除、启停用。依赖 shb-shared 的认证状态。 |
| **shb-warehouse-bom** | 处理云仓物料服务BOM搜索、详情、组成物料树查询、创建、编辑、删除、启停用、撤销删除。依赖 shb-shared 的认证状态。 |
| **shb-warehouse-replacement** | 处理云仓物料替换搜索、详情、按原始物料查有效替换候选、字段查询、创建（含批量）、编辑、删除、启停用。依赖 shb-shared 的认证状态。 |
| **shb-paas** | 处理 PaaS 自定义表单/业务模块（如"寄修"等非工单/客户/产品的菜单）：表单定位、字段定义查询与增改、表单数据查询与增删改、流程发起/日志 shb-shared 的认证状态。 |

Skills 详细说明：

- [`skills/shb-cli/SKILL.md`](./skills/shb-cli/SKILL.md)
- [`skills/shb-shared/SKILL.md`](./skills/shb-shared/SKILL.md)
- [`skills/shb-task/SKILL.md`](./skills/shb-task/SKILL.md)
- [`skills/shb-event/SKILL.md`](./skills/shb-event/SKILL.md)
- [`skills/shb-customer/SKILL.md`](./skills/shb-customer/SKILL.md)
- [`skills/shb-product/SKILL.md`](./skills/shb-product/SKILL.md)
- [`skills/shb-part/SKILL.md`](./skills/shb-part/SKILL.md)
- [`skills/shb-warehouse-material/SKILL.md`](./skills/shb-warehouse-material/SKILL.md)
- [`skills/shb-warehouse-bom/SKILL.md`](./skills/shb-warehouse-bom/SKILL.md)
- [`skills/shb-warehouse-replacement/SKILL.md`](./skills/shb-warehouse-replacement/SKILL.md)
- [`skills/shb-paas/SKILL.md`](./skills/shb-paas/SKILL.md)

---

## 认证命令

### 登录

```bash
# 交互式登录（推荐普通用户）
shb-cli auth login

# 指定环境登录（推荐 Agent 使用）
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 login --no-browser
```

### 查看状态

```bash
shb-cli config
```

### 登出

```bash
shb-cli auth logout
```

### 切换租户（仅 standalone 环境）

```bash
# 交互式切换（先选租户，再输入密码）
shb-cli auth switch-tenant

# 非交互式（脚本/CI 场景）
shb-cli auth switch-tenant --tenant-name <tenant-name> --password <password>

# 仅查看可切换的租户列表
shb-cli auth switch-tenant --list
```



### 输出格式

```bash
shb-cli task search                          # 默认 JSON
shb-cli task search | jq '.content[]'        # 配合 jq 处理
```

### 写操作预览

```bash
shb-cli task create submit --file ./create.json
```

### 查看版本与构建信息

```bash
shb-cli version
shb-cli version --json
```

`version --json` 输出中包含 `build_env`（prod / test），以及 `_notice.update` 字段（如有新版本会为 `true`）。

### Shell 补全

```bash
shb-cli completion bash >> ~/.bashrc
shb-cli completion zsh >> ~/.zshrc
```

---

## 环境说明

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

---

## 安全说明

> ⚠️ **AI Agent 使用风险提示**
>
> 当 AI Agent 以用户身份执行 shb-cli 命令时，存在以下固有风险：
>
> - **模型幻觉**：Agent 可能生成错误的参数或操作意图
> - **不可预测执行**：Agent 的行为路径并非总是可控
> - **Prompt 注入**：恶意内容可能通过 API 响应影响 Agent 行为
>
> **安全建议：**
> - 写操作（创建/更新/删除/部署/审批）执行前，务必让用户确认
> - 复杂 payload 使用 `--file` 或 `--payload-file` 传入，避免命令行拼接
> - 先用 `--dry-run` 预览高风险操作
> - **禁止把 token 写入终端输出或仓库文件**
> - 不要要求普通用户提供 `org-code`、`domain`、`authorize-url` 等底层参数



## 命令组速查

```text
config                              # 查看当前配置与认证状态
auth login|logout|switch-tenant|token-import
task alloc submit|create submit|detail|field common|field list|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
part detail|field list|personal holding|personal search|personal stock-record|
     personal use-record|personal users|search|stock distribution|stock search
warehouse material search|material detail|material field list|
          material field check|material create|material update|
          material update batch|material update status|material delete|
          bom search|bom detail|bom materials|bom create|bom edit|
          bom edit status|bom delete|bom delete materials|bom revert|
          replacement search|replacement detail|replacement by-original|
          replacement field list|replacement field save-fields|
          replacement create|replacement create batch|replacement edit|
          replacement edit enable|replacement delete
paas app forms|template ...|form ...|flow ...   # 表单定位/字段/数据/流程，70+ 子命令，详见 shb-cli paas --help
completion bash|zsh|fish|powershell
version
```