人机协作台（Human-AI Collaboration）

---

name: human-ai-collab

description: 人机协作台技能。用户输入自然语言销售指令，AI自动分析拆解任务参数，调用 KocGo 平台接口提交任务，等待后查询 AiWa 挖掘客户数据，生成 xlsx 文件并返回。触发场景：用户说「帮我找客户」「挖掘XXX行业客户」「找XXX个客户」「提交任务」等与客户挖掘、销售任务相关的指令。需要提前配置环境变量 KOCGO_API_KEY。

---

# 人机协作台（Human-AI Collaboration）

功能简介

人机协作台是基于 KocGo 平台的智能销售任务助手，能够：

- **AiWa**：客户挖掘（找客户、行业客户等）

- **Frank**：邮件销售

- **Fran**：电话销售

- **Lisa**：短信销售

---

前置条件：获取 API Key

1. 访问 [https://staging.kocgo.vip](https://staging.kocgo.vip) 注册并登录账号

2. 登录后进入「设置」或「API 管理」页面

3. 新建 API Key，复制以 `sk-` 开头的密钥

4. 在 OpenClaw 中配置环境变量：

KOCGO_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxx

> 所有 API 请求头需携带：`X-Api-Key: $KOCGO_API_KEY`

> API Base URL：`https://staging.kocgo.vip/stage-api`

---

完整执行流程

Step 1：第一轮 AI 分析（任务拆解）

用以下 prompt 分析用户指令，严格返回 JSON，不含任何额外文字：

根据【指令】描述，Json格式返回数据
不需要多余的描述，不要过度解读，没有提及的内容请不要擅自理解，识别结果除了Json数据其他文字不要出现
规则如下：
{
  "totalTarget": "提取描述中提及的数量（无单位纯数字）",
  "employeeList": "首先将描述按逗号、顿号等分隔符拆分成多个子任务，然后为每个子任务匹配对应员工：挖掘客户职能（AiWa）：匹配任何包含'找'、'行业'、'客户'等与客户挖掘相关的描述，以及没有明确匹配其他职能的单子任务；邮件销售职能（Frank）：匹配包含'邮件'、'发邮件'等关键词；电话销售职能（Fran）：匹配包含'电话'、'打电话'、'电话销售'等关键词；短信销售职能（Lisa）：匹配包含'短信'、'发短信'等关键词。如果拆分后只有一个子任务且没有匹配上员工，则默认匹配挖掘客户职能（AiWa）。最后汇总所有匹配到的员工名称组成一个逗号拼接的字符串并返回（去重）",
  "language": "判断描述中是否明确提及国家或地区，若提及了国家或地区但和中国没有关联则返回'英文'，其他情况返回'中文'",
  "taskName": "根据描述总结出一个简洁的任务名称",
  "executionMode": "判断描述中是否明确提及每日/每天/周期性，如果提及则返回'周期性任务'，未提及则返回'定额任务'"
}

解析结果字段：

---

Step 2：第二轮 AI 分析（仅当 employeeList 包含 AiWa）

用以下 prompt 对同一用户指令做第二轮分析，严格返回 JSON：

根据【指令】描述，Json格式返回数据，其中数值部分用字符串输出
涉及数值规则仅处理描述中明确出现的数字和比较词，最小值规则：'X以上'=X，'X以下'=空，'X左右'=X；最大值规则：'X以上'=空，'X以下'=X，'X左右'=X
涉及七大洲和国家：如果提及了详细某些国家，七大洲则不用去识别；如果没提及国家则去识别有没有提及七大洲
涉及地址：如果是中国地址原文放入，如果是非中国的地址则以英文放入
不需要多余的描述，不要过度解读，没有提及的内容请不要擅自理解，识别结果除了Json数据其他文字不要出现
规则如下：
{
  "keywordList": "提取描述中的核心名词作为关键词，排除七大洲、国家、地址类关键词。如果是'找X'格式的描述，提取'X'作为关键词。同时添加相关的中文同义词和英文对应词，所有关键词用英文逗号分隔（如：服装,clothing）",
  "continent": "明确提及的七大洲，多个用英文逗号分隔（如：亚洲,欧洲）",
  "country": "明确提及的国家，多个用英文逗号分隔（如：中国,英国）",
  "countryCodeList": "对应国家的ISO代码，多个用英文逗号分隔（如：CN,GB）",
  "address": "明确提及的国家层级之下的详细地址（如：浙江省杭州市）；拆分为一级地址（省）、二级地址（市）、三级地址（区县镇），把一二三级有效地址通过逗号拼接返回（如：浙江宁波 返回 浙江,宁波）",
  "employeeNumberRangeStart": "只有当描述中明确提及员工数量并使用'员工X人以上/以下/左右'等范围描述时，按最小值规则提取；否则为空字符串",
  "employeeNumberRangeEnd": "只有当描述中明确提及员工数量并使用'员工X人以上/以下/左右'等范围描述时，按最大值规则提取；否则为空字符串",
  "storeNumberRangeStart": "只有当描述中明确提及门店数量并使用'门店X家以上/以下/左右'或'X家门店以上/以下/左右'等范围描述时，按最小值规则提取；否则为空字符串。单纯的'找X家门店'属于目标数量不在此提取",
  "storeNumberRangeEnd": "只有当描述中明确提及门店数量并使用'门店X家以上/以下/左右'或'X家门店以上/以下/左右'等范围描述时，按最大值规则提取；否则为空字符串。单纯的'找X家门店'属于目标数量不在此提取",
  "industryList": "根据以上字段推断行业分类，多个用英文逗号分隔（如：服装,数码,家居）"
}

---

Step 3：构建并提交任务

**接口：** `POST https://staging.kocgo.vip/stage-api/ai/presetEmployee/submitTask`

**请求头：**

Content-Type: application/json
X-Api-Key: $KOCGO_API_KEY

**参数构建规则：**

- `totalTarget`：定额模式下填 Step 1 的 totalTarget，周期模式下为 null

- `incrementalTarget`：必填，两种模式下均填 Step 1 的 totalTarget（不可为 null）

- `upperLimitTarget`：填 Step 1 的 totalTarget

- `keywordList`：Step 2 的 keywordList 拆分成数组

- `continent`：Step 2 的 continent（无则 null）

- `country`：Step 2 的 country（无则 null）

- `countryCodeList`：Step 2 的 countryCodeList 拆分成数组（无则 null）

- `addressObjList`：根据 Step 2 的 address 构建，无则 `[{"type":1,"province":"","city":"","county":"","address":""}]`

- `industryList`：Step 2 的 industryList 拆分成数组

**请求体示例：**

{
  "collaborationSubmitTaskParam": {
    "taskName": "挖掘美国客户",
    "taskDescription": "我是做口红的工厂，帮我挖掘美国的客户",
    "executionMode": 1,
    "employeeParams": {
      "AiWa": {
        "totalTarget": 10,
        "incrementalTarget": 10,
        "upperLimitTarget": 10,
        "keywordList": ["口红", "lipstick"],
        "continent": null,
        "country": "美国",
        "countryCodeList": ["US"],
        "addressObjList": [{"type": 1, "province": "", "city": "", "county": "", "address": ""}],
        "industryList": ["化妆品", "美妆"]
      }
    },
    "sourceSettings": null
  },
  "completed": true
}

**成功响应：**

{"msg": "<taskId>", "code": 200}

提取 `msg` 字段作为 `taskId`。

提交成功后，告知用户：

> 任务已提交！任务名：{taskName}，目标数量：{totalTarget}，任务ID：{taskId}。AiWa 正在后台挖掘客户，将在 8 分钟后自动查询结果...

---

Step 4：设置 8 分钟后自动查询

任务提交成功后，使用 `cron` 工具设置一次性定时任务，8 分钟后自动触发查询：

{
  "action": "add",
  "job": {
    "name": "aiwa-query-{taskId前8位}",
    "schedule": { "kind": "at", "at": "{当前时间+8分钟的ISO8601字符串，如2026-03-19T15:00:00+08:00}" },
    "sessionTarget": "main",
    "wakeMode": "now",
    "payload": {
      "kind": "systemEvent",
      "text": "人机协作台提醒：请立即查询 AiWa 客户数据并返回给用户。taskId={taskId}，任务名：{taskName}，目标数量：{totalTarget}。调用 GET https://staging.kocgo.vip/stage-api/ai/customerPoolDetail/listByTaskId?taskId={taskId} 查询结果并格式化返回。"
    },
    "deleteAfterRun": true
  }
}

`schedule.at` = 当前时间 + 480 秒，ISO8601 格式，含时区（如 `+08:00`）。

cron 触发后，systemEvent 注入 main session，agent 收到后立即执行 Step 5。

---

Step 5：生成 xlsx 并返回给用户

查询完成后**必须主动回复用户**，根据结果分两种情况：

**情况一：有数据（data 非空）**

1. 将完整 API 响应 JSON 传给脚本生成 xlsx 文件：

python3 ~/.openclaw/workspace/skills/human-ai-collab/scripts/format_customers.py '<完整响应JSON>' '/tmp/aiwa_{taskId前8位}.xlsx'

脚本成功后输出文件路径（如 `/tmp/aiwa_a32f78c4.xlsx`）。

2. 根据当前 channel 决定如何返回文件：

**飞书（feishu）：** 直接发送文件

message(action=send, channel="feishu", to="{user_open_id}", path='/tmp/aiwa_{taskId前8位}.xlsx', caption='✅ AiWa 挖掘完成！任务：{taskName}，共 {N} 位客户。')

**Telegram / WhatsApp：** 直接发送文件

message(action=send, channel="telegram", path='/tmp/aiwa_{taskId前8位}.xlsx', caption='✅ AiWa 挖掘完成！任务：{taskName}，共 {N} 位客户。')

**webchat 或其他不支持文件的 channel：** 告知用户文件路径

> ✅ xlsx 文件已生成：`/tmp/aiwa_{taskId前8位}.xlsx`，共 {N} 位客户。

> 请从服务器下载该文件，或配置飞书/Telegram 等 channel 以支持直接发送文件。

3. 同时以文字形式展示前5条预览：

序号. 👤 {personName}（{position}）
   🏢 公司：{companyName}
   🏭 行业：{industry}
   📧 邮箱：{email}
   📱 手机：{phone}
   💬 WhatsApp：{whatsapp}
   🔗 LinkedIn：{linkedin}

社媒字段若为 null 则整行不显示。超过5条附上：`...共 {N} 位，完整数据见 xlsx 文件`

**情况二：data 为空或 code 非 200**

> 8 分钟已到，已查询任务结果。暂未获取到客户数据，任务可能仍在执行中。

> 任务ID：{taskId}

> 你可以告诉我「再查一次」，我会立即重新查询。

---

实现方式

---

依赖

---

错误处理