---
name: shb-customer
version: "1.1.0"
description: "当用户提到客户相关操作时触发，包括：搜索/查找/查看客户、我的客户/我负责的客户/某负责人的客户/我创建的客户、某个客户的信息/联系人/地址、新建/创建客户、更新/修改/编辑客户、查询客户字段定义。通过 shb-cli 操作客户列表搜索、联系人查询、地址查询、字段定义查询、客户创建和客户更新。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli customer --help"
---

# customer (v1.1)

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md)，其中包含 profile 初始化、环境选择、OAuth2 登录、token 导入、租户切换、安全规则。所有 customer 命令都依赖 `shb-shared` 描述的认证状态。**

## Core Concepts

- **Customer（客户）**：售后宝 客户档案，标识为 `id`。
- **Linkman（联系人）**：客户下的联系人，通过 `customerId` 关联，标识为 `id`。
- **Address（地址）**：客户下的地址，通过 `customerId` 关联，标识为 `id`。
- **Field（字段）**：客户表单的字段定义，包含系统字段（`isSystem=1`）和自定义字段（`isSystem=0`），自定义字段值存于 `attribute` 中。
- **SerialNumber（客户编号）**：客户的唯一业务编号，创建时可校验唯一性。
- **CustomerManager（客户负责人）**：
  - 搜索过滤时用 JSON body 字段 `customerManager`（值为 userId）——**不是 `managerId` / `manager`**
  - 创建时用 flag `--manager-id <userId>`

## Important Notes

### 面向用户的输出措辞（禁止回显接口字段名与内部机制）

**CRITICAL** — 以下两类内容**只供你内部使用，禁止出现在给用户的回复里**：

1. **接口/JSON 字段名**：`total`、`pages`、`page`、`rows`、`columns`、`id`、`customerId`、`serialNumber`、`customerManager`、`isSystem`、`attribute` 等，一律转成自然语言。  
   例：「total 为 189」→「共 189 个客户」；「pages=3」→「总共 3 页」；「customerManager=xxx」→「客户负责人：张三」。
2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（分页、数量判断、全量拉取、字段裁剪、截断重试）都是后台实现细节，**回复里绝不出现，也不要解释你用了什么命令/参数、怎么取的数**，换种说法也不行。直接给结果。
3. **实体的 UUID 值**：客户、联系人、地址等实体的 `id` / `customerId`（形如 `0f384496-694b-11f1-...` 的 UUID）只供你内部串联后续调用（如拿客户 id 再查地址），**绝不输出给用户**——不是不写字段名 `id` 就行，那串 UUID **值本身**也不能出现在回复里。向用户复述实体时只说**名称** + 电话、**客户编号**（`serialNumber`，如 `CUS20260605001`）等有业务含义的信息。  
   反例（禁止）：「客户: 林林科技 (ID: 0f384496-…)，地址: 安徽…(ID: 3b03…)」；正例：「林林科技（编号 CUS20260605001）的地址：安徽省安庆市大观区大观园」。
4. **自定义字段（`attribute`）的显示**：`attribute` 对象的 key 是 `fieldName`（如 `field_xxx`、`customerLevel`），**绝不能直接拿这个 key 显示给用户**。展示前用 `customer field list` 取字段定义，按 `fieldName` 匹配出对应的「显示名」（中文字段名），给用户看「中文字段名：值」；匹配不到的字段宁可不展示，也不要把英文 key 抛给用户。用 `--format-data` 输出时 CLI 已按字段元数据转换，一般无需自行映射。

此规则适用于所有 customer 子命令（list / linkman / address / field / create / update）。

### 命令分层

- **`shb-cli customer <subcommand>`** —— 客户模块主入口，推荐路径。

> ⚠️ **`customer search` 不存在**。搜索客户一律用 `shb-cli customer list`（即使没有加任何筛选参数，也是 list，不是 search）。不要类比 `task search` 写成 `customer search`。

### 输出格式

所有命令支持全局 `--output` / `-o` 标志：

```bash
shb-cli customer list -o json    # 默认，完整 pretty JSON
shb-cli customer list -o table   # 表格格式
shb-cli customer list -o yaml    # YAML 格式
```

### 写操作安全

- `customer create` 和 `customer update submit` 是写操作，执行前确认用户明确要求创建/更新。
- 创建前默认会对 `serialNumber`（客户编号）做唯一性校验；使用 `--force` 可跳过。
- 自定义字段值通过 `--attr` 以 JSON 对象传入，系统字段直接使用对应 flag。
- **更新客户优先使用 `--data` / `--file`**：quick flags 只发送用户提供的字段，未提供字段可能被清空；建议先 `customer list` 拿到完整当前数据，修改后用 `--data` 提交，见 `shb-customer-update.md` 推荐工作流。

## API Resources

**CRITICAL — 执行任何 customer 子命令前，必须先用 skill 工具加载对应 reference 文档，再执行命令：**

| 操作 | 必须先加载 |
|------|-----------|
| 搜索/查询客户列表（`customer list`） | [`references/shb-customer-search.md`](references/shb-customer-search.md) |
| 查询客户联系人（`customer linkman search`） | [`references/shb-customer-linkman.md`](references/shb-customer-linkman.md) |
| 查询客户地址（`customer address list`） | [`references/shb-customer-address.md`](references/shb-customer-address.md) |
| 查询客户字段定义（`customer field list`） | [`references/shb-customer-field.md`](references/shb-customer-field.md) |
| 创建客户（`customer create`） | [`references/shb-customer-create.md`](references/shb-customer-create.md) |
| 更新客户（`customer update submit`） | [`references/shb-customer-update.md`](references/shb-customer-update.md) |

同一会话中每个 reference 只需加载一次。

## 权限与安全

- 只读命令：`list`、`linkman search`、`address list`、`field list`。
- 写命令：`create`、`update submit`。不要在未确认用户意图时执行。
- 可见和可写范围 = 当前 profile 用户在 SHB 后端的权限范围。

## 排错

- 401 / `token is empty` → 回到 `shb-shared` 技能重新认证。
- `--name is required` → 创建时未传 `--name`，该字段必填。
- `--lm-phone or --lm-email is required` → 创建时联系电话或邮箱至少填一个。
- `serialNumber ... 已存在` → 客户编号重复，换一个编号或加 `--force` 跳过校验。
- 列表为空但无错误 → 检查筛选条件是否过严，尝试去掉筛选或扩大 `--page-size`。

## References

- [`references/shb-customer-search.md`](references/shb-customer-search.md) —— 客户搜索
- [`references/shb-customer-linkman.md`](references/shb-customer-linkman.md) —— 客户联系人查询
- [`references/shb-customer-address.md`](references/shb-customer-address.md) —— 客户地址查询
- [`references/shb-customer-field.md`](references/shb-customer-field.md) —— 客户字段定义查询
- [`references/shb-customer-create.md`](references/shb-customer-create.md) —— 客户创建
- [`references/shb-customer-update.md`](references/shb-customer-update.md) —— 客户更新