openclaw/human-ai-collab

人机协作台（Human-AI Collaboration）

功能简介

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

• 理解自然语言指令：直接描述需求，如「帮我找50个美国做服装的客户」
• 智能任务拆解：自动识别目标数量、行业、地区、执行周期等参数
• 多员工协作：根据任务类型自动分配对应职能员工
  • AiWa：客户挖掘（找客户、行业客户等）
  • Frank：邮件销售
  • Fran：电话销售
  • Lisa：短信销售
• 自动提交任务：调用 KocGo API 提交任务，后台异步执行
• 定时查询结果：任务提交后 8 分钟自动查询并推送结果
• 生成 xlsx 报表：客户数据自动生成带样式的 Excel 文件返回

---

前置条件：获取 API Key

1. 访问 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": "判断描述中是否明确提及每日/每天/周期性，如果提及则返回'周期性任务'，未提及则返回'定额任务'"
}

解析结果字段：

• totalTarget：目标数量（数字）
• employeeList：参与员工逗号字符串，如 "AiWa" 或 "AiWa,Frank"
• language："中文" 或 "英文"
• taskName：任务名称
• executionMode："定额任务" 或 "周期性任务"（接口参数：定额=1，周期=2）

---

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

参数构建规则：

• taskName：来自 Step 1
• taskDescription：用户原始输入
• executionMode：定额任务=1，周期性任务=2
• AiWa 参数中：
  • 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} 你可以告诉我「再查一次」，我会立即重新查询。

---

实现方式

• AI 分析：直接在当前对话中用 LLM 完成，分析时告知用户正在处理
• HTTP 请求：使用 exec 工具调用 curl
• 定时等待：使用 cron(action=add) 设置 8 分钟后触发的 systemEvent
• xlsx 生成：使用 exec 调用 Python 脚本

---

依赖

• Python 3（系统自带）
• openpyxl：python3 -m pip install openpyxl --user --break-system-packages
• 生成脚本：~/.openclaw/workspace/skills/human-ai-collab/scripts/format_customers.py

---

错误处理

• KOCGO_API_KEY 未设置：提示用户前往 https://staging.kocgo.vip 注册登录后新建 API Key，配置环境变量后再使用
• POST 接口返回非 200：展示错误信息，提示检查参数或稍后重试
• GET 接口 data 为空：提示任务可能仍在执行，给出 taskId 供用户告知「再查一次」
• Python 脚本执行失败：直接以文字列表格式返回客户数据，不中断流程
• 网络请求失败：展示 curl 错误信息