# Cliet Finder 简明使用说明

这份文档只讲两件事：

1. 平台管理员怎么管理客户和 `clientKey`
2. 客户怎么把一句话交给 agent，直接唤起 skill

---

## 1. 一张图看全流程

```text
+---------------------------+
| 平台管理员后台            |
| 新增客户 / 生成 clientKey |
+-------------+-------------+
              |
              v
+---------------------------+
| 把 clientKey 发给客户     |
+-------------+-------------+
              |
              v
+---------------------------+
| 客户把 key 配给 Agent      |
| (workflow input_data)     |
+-------------+-------------+
              |
              v
+---------------------------+
| Agent 唤起 client-finder   |
| 先扩展关键词再执行流程      |
+-------------+-------------+
              |
              v
+---------------------------+
| 返回客户列表/联系人数据     |
+---------------------------+
```

---

## 2. 平台管理员使用说明（简单版）

### 2.1 你要做的事

1. 新增客户公司信息
2. 给这个客户配置专属 `HOOK_URL`（用于完成/失败回调）
3. 给这个客户生成 `clientKey`
4. 把 `clientKey` 发给客户
5. 如泄露，立即吊销并重发新 key

### 2.2 页面功能（ASCII 示意）

```text
+------------------------------------------------------------------+
| Skill Token 管理                                                  |
+------------------------------------------------------------------+
| [新增客户]                                                        |
| 客户名: ______  联系人: ______  公司名: ______  备注: ______      |
| [保存]                                                            |
+------------------------------------------------------------------+
| 客户列表                                                          |
| Client A | HOOK_URL: https://.../a | [生成Key] [复制] [吊销]     |
| Client B | HOOK_URL: https://.../b | [生成Key] [复制] [吊销]     |
+------------------------------------------------------------------+
```

### 2.3 管理建议

- 一个客户一把 key，便于计费和关系维护。
- key 只在安全渠道发放。
- key 泄露就吊销，不要继续复用。

---

## 3. 客户使用说明（给 Agent）

### 3.1 客户只需要准备两项

- `client_key`（平台给你的）
- 你的业务需求（例如：`coffee in US`）

说明：`HOOK_URL` 已在平台端绑定到该 `clientKey`，客户端运行时无需再配置。

### 3.2 给 agent 的标准文案（可直接复制）

```text
请使用 client-finder skill 帮我找美国客户。

要求：
1) 查询词：coffee
2) 国家：US
3) 输出字段：公司名、网站、联系人邮箱、推荐触达理由
4) 先做关键词扩展，再执行查找
5) 如果流程失败，请返回失败原因和建议下一步

我会在 workflow 的 input_data 里提供 client_key，请按技能流程自动执行。
```

### 3.3 workflow 入参示例（给接入同学）

```json
{
  "instruction": "[skill:client-finder] 帮我找美国 coffee 客户",
  "input_data": {
    "client_key": "sk_xxx.yyy",
    "query": "coffee",
    "country": "us"
  }
}
```

建议：`client_key` 仅通过 workflow payload 下发，不要写死在仓库文件或长期环境变量。

---

## 4. 常见问题（非技术版）

### Q1: 一个 skill 可以给多个客户用吗？

可以。每个客户用自己的 `clientKey` 即可。

### Q2: 客户需要懂 API 吗？

不需要。客户只要给 agent 需求文案 + `clientKey`。

### Q3: 失败会扣费吗？

正常设计下，失败会回滚，不做最终扣费。

### Q4: 扩展失败会自动改用原始关键词吗？

会。当前策略是“扩展失败回退原始关键词 A 再执行”，提高流程可完成率。

---

## 5. 技术同学最少必知（可选）

- 管理端路径：`/auth/skill-credit/*`
- skill 执行路径：`/ecom/cold-outreach/run-flow`