---
name: sophnet-customer-management
description: >
  客户管理助手：支持上传 Excel/CSV/Markdown 客户表创建客户库，使用自然语言创建字段、添加客户、
  查询筛选、修改删除客户，并生成生日/到期/跟进提醒。当用户要管理客户资料、导入客户名单、
  查询某月生日客户、查 30 天内到期客户、修改客户信息、导出客户数据时使用。
---

# 客户管理助手

这个 skill 面向“成长型小微企业主”的轻量客户管理场景。优先用对话驱动，但所有关键写操作都要经过结构化命令和必要确认。

## 关键原则

- 先预览、后写入：导入文件时，先做预览，再让用户确认写入。
- 删除和批量修改必须确认：不要在重名或模糊命中时直接执行。
- 统一使用 Python CLI：所有确定性操作通过 `uv run --project "{baseDir}" python -m customer_mgmt_cli ...` 执行。
- 数据以 SQLite 为主：客户库主数据默认写到用户运行环境配置中的数据库路径；JSON/Markdown 只作为预览、中间结果和展示格式。

## 首次使用初始化

- 第一次使用本 skill 时，先初始化运行时配置文件：`${HOME}/.config/sophnet-customer-management/config.env`。
- 配置文件中至少保存：
  - `CUSTOMER_MGMT_DB_PATH=<sqlite绝对路径>`
- 如果用户没有指定数据库路径，则默认写为：`${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`
- 初始化方式：
  - 第一次调用 CLI 时，如果显式传了 `--db`，CLI 会自动把该路径写入 `config.env`
  - 如果没有传 `--db` 且 `config.env` 还不存在，CLI 会自动创建 `config.env` 并写入默认路径
- 后续使用本 skill 时：
  - 默认先读取 `${HOME}/.config/sophnet-customer-management/config.env`
  - 从 `CUSTOMER_MGMT_DB_PATH` 获取 SQLite 路径
  - 因此后续命令默认不必重复传 `--db`
- 这样即使后续卸载或替换 skill 目录，默认客户数据仍然保留在用户配置目录，不会跟随 skill 一起被删除。

### 首次初始化操作规范

- 当 agent 判断这是用户第一次使用本 skill，或当前环境中还不存在 `${HOME}/.config/sophnet-customer-management/config.env` 时，应把本轮视为“首次初始化 + 当前请求”两步一起完成，而不是单独把初始化抛给用户。
- 默认策略：
  - 不额外追问数据库路径
  - 直接采用默认路径 `${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`
  - 首次 CLI 调用后自动落盘 `config.env`
- 只有在用户明确提出“数据库放到别的位置”“想自己指定路径”“多套客户库分开存”等要求时，才改为显式传 `--db <custom_path>`。
- 初始化完成后，agent 在回复中可顺带告知一次数据库位置，但不要每次都重复强调。
- 后续同一 skill 内的命令默认不再传 `--db`，除非本轮任务明确要求切换数据库。

### 首次初始化示例对话

#### 示例 1：用户第一次直接开始用

用户：

```text
帮我建一个客户表，先有姓名、手机号、生日、微信、备注。
```

agent 内部执行思路：

- 先检查 `${HOME}/.config/sophnet-customer-management/config.env` 是否存在。
- 若不存在，则认定为首次使用。
- 不必先打断用户去确认数据库路径，直接使用默认路径 `${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`。
- 执行首次 CLI 调用；CLI 会自动创建：
  - `${HOME}/.config/sophnet-customer-management/config.env`
  - `${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`
- 然后继续执行本次真实任务，例如：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  schema evolve --json '{"labels":["微信"]}'
```

agent 对用户的推荐回复风格：

```text
我先帮你初始化客户库，并按默认位置保存，后续都会自动复用这份客户库。
这次会先创建基础客户表，并补一个“微信”字段。
```

#### 示例 2：用户明确指定数据库位置

用户：

```text
这个客户库不要放默认位置，放到 /data/business/customer_a.sqlite3。
```

agent 内部执行思路：

- 识别为“用户显式指定路径”。
- 本次调用必须显式带上 `--db /data/business/customer_a.sqlite3`。
- CLI 执行后，会把该路径写入 `${HOME}/.config/sophnet-customer-management/config.env`。
- 后续若无新的指定，就默认继续使用这个路径。

示例命令：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  --db /data/business/customer_a.sqlite3 \
  schema inspect
```

#### 示例 3：后续再次使用

用户：

```text
查一下这个月过生日的客户。
```

agent 内部执行思路：

- 默认先读取 `${HOME}/.config/sophnet-customer-management/config.env`
- 取出 `CUSTOMER_MGMT_DB_PATH`
- 直接执行查询，不再重新询问数据库路径

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  customer query --json '{"birthday_month":3,"limit":20}'
```

## 可处理的输入

- 自然语言：
  - “添加客户张三，电话 138xxxx”
  - “查一下 3 月过生日的客户”
  - “把张三的电话改成 139xxxx”
  - “帮我建一个客户表，字段有姓名、电话、生日、备注”
- 文件：
  - `.xls`
  - `.xlsx`
  - `.csv`
  - `.md`

## 文件导入流程

### Step 1：定位文件

用户上传文件后，优先在当前 agent 工作路径（working directory）下的 `media/inbound/` 中寻找最新文件；
若用户直接给了路径，则直接使用该路径。

### Step 2：预览导入

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  import file --path "<file_path>"
```

- 读取返回 JSON 里的 `summary`
- 向用户展示：
  - 待导入客户数
  - 待导入业务记录数
  - 新增字段数
  - 异常与告警
- 仅当用户确认后再执行真正写入

### Step 3：确认后写入

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  import file --path "<file_path>" --commit
```

## 自然语言创建字段

当用户要求“建一个客户表”或“新增某个字段”时，抽取字段名称，然后执行：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  schema evolve --json '{"labels":["微信","孩子生日","最近消费"]}'
```

先向用户解释将新增哪些字段，再执行。

查看当前字段：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  schema inspect
```

## 新增客户

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  customer add --json '{
    "name":"张三",
    "primary_phone":"13800138000",
    "birthday":"1988-03-18",
    "tags":["VIP"],
    "notes":"老客户",
    "dynamic_fields":{"微信":"zhangsan88","喜欢项目":"补水"}
  }'
```

## 查询客户

按姓名/手机号查：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  customer query --json '{"name":"张三","limit":10}'
```

查本月生日：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  customer query --json '{"birthday_month":3,"limit":20}'
```

查 30 天内到期：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  customer query --json '{"due_within_days":30,"limit":20}'
```

返回结果中会带 Markdown 预览，可直接展示给用户。

## 修改客户

更新前先查，确认命中唯一客户后再执行：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  customer update \
  --match-json '{"name":"张三"}' \
  --updates-json '{"primary_phone":"13900139000","dynamic_fields":{"孩子生日":"2018-03-01"}}'
```

## 删除客户

删除必须二次确认：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  customer delete --match-json '{"name":"张三"}'
```

## 提醒

先规划提醒，再决定是否真正注册到 OpenClaw cron。

规划生日和到期提醒：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  reminder plan --json '{"kinds":["birthday","due_date"]}'
```

确认后创建提醒：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  reminder schedule --json '{"kinds":["birthday","due_date"]}'
```

单个客户跟进提醒：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  reminder plan --json '{"follow_up":{"match":{"name":"张三"},"date":"2026-03-20"}}'
```

## 导出

优先导出 CSV，必要时再导出 XLSX：

```bash
uv run --project "{baseDir}" python -m customer_mgmt_cli \
  export file --output "{baseDir}/data/customers_export.csv"
```