142 lines
3.9 KiB
Markdown
142 lines
3.9 KiB
Markdown
# 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`
|