kalopilot

KaloPilot — TikTok 电商数据助手

这项技能可让你通过 KaloPilot AI Agent 查询 TikTok Shop 数据。KaloPilot 可使用 20 多种专用工具，覆盖所有 TikTok Shop 地区的商品、店铺、创作者、视频、直播和类别。

身份验证

令牌以纯文本形式存储在 ~/.kalopilot/token 中。如果令牌缺失，首次请求会失败并显示明确的错误——这是首次使用时的正常情况。

如果缺少令牌，不要只说“我需要一个令牌”。请引导用户获取令牌：

1. 前往 kalodata.com/pilot 并登录。
2. 在侧边栏左下角，点击 Connect OpenClaw（“技能安装教程”）。
3. 在打开的 OpenClaw Integration Guide 对话框中，复制 Current Account Token 下方的字符串——一串较长的十六进制字符，例如 89e7f60c...5be6b9。
4. 将令牌粘贴到这里，你会替他们保存。

用户提供令牌后，将其保存（此操作也会创建目录并限制权限）：

mkdir -p ~/.kalopilot && echo -n "<token>" > ~/.kalopilot/token && chmod 600 ~/.kalopilot/token

随后确认令牌已保存，并立即重试用户最初的问题——不要让他们再问一次。

在提示用户之前，检查是否已配置令牌：

[ -s ~/.kalopilot/token ] && echo "configured" || echo "missing"

如果用户报告身份验证错误（401 / 无效令牌），保存的令牌可能已过期——请按照相同步骤引导他们获取新的 Current Account Token，并使用上面的命令覆盖文件。

API 端点

此技能使用异步提交 + 轮询流程。提交后会立即返回 task_id；随后 Agent 会在服务端运行直至完成。你可以通过短请求轮询结果，因此无需保持连接打开——无论分析耗时多久，都不会受到网关空闲超时的影响。

POST https://www.kalodata.com/api/pilot/skill/ext/v1/chat/async/submit
GET  https://www.kalodata.com/api/pilot/skill/ext/v1/chat/async/result?task_id=<id>
Authorization: Bearer <token>

发起请求

使用 scripts/pilot.sh 管理查询。该脚本会处理令牌加载、任务提交和轮询——无需后台进程，也不会产生过期文件。

响应时间取决于复杂度：

• 简单查询（单维度查找，例如“美国热门商品”）：约 1 分钟
• 复杂查询（跨维度、诊断、对比）：2–3 分钟
• 非常复杂的查询（带报告的多步骤分析）：数分钟（无最长超时时间）

步骤 1 — 提交查询：

bash <skill-path>/scripts/pilot.sh query "<user question>"

使用 task_id 进行后续提问：

bash <skill-path>/scripts/pilot.sh query "<user question>" "<task_id>"

这会立即返回 task_id（并保存供下一步使用）。如果额度不足或令牌无效，你会立即在此处收到错误。请告知用户分析正在进行。

步骤 2 — 轮询结果：

根据查询复杂度进行轮询：

• 简单查询 → 45 秒后首次轮询
• 复杂查询 → 90 秒后首次轮询
• 当 status 为 running 时，每隔 30 秒再次轮询，直到状态改变

bash <skill-path>/scripts/pilot.sh result

每次调用都会以 JSON 格式返回当前状态。查看 data.status：

• running → 仍在处理中；等待后再次轮询。
• completed → 结果字段（text、report，等等）已填充；呈现这些内容。
• error → 显示 data.error.message。
• cancelled → 任务已取消。

result 会轮询步骤 1 中的同一个 task_id；传入明确的 task_id 参数即可轮询指定任务。

多轮对话

首次请求会在响应中返回 task_id。针对同一主题的后续提问，始终重复使用该 task_id——这样 KaloPilot 就能保留对话上下文，从而理解“第一个”或“和昨天对比”等指代。

示例流程：

1. 首条消息：{"query": "美国热门商品有哪些？"} → 响应包含 "task_id": "abc123"
2. 后续提问：{"query": "第一名的销售趋势怎么样？", "task_id": "abc123"}
3. 再次追问：{"query": "对比一下英国市场", "task_id": "abc123"}

当用户切换到明显不同的主题时，不带 task_id，重新开始。

响应格式

所有异步响应均封装在 { "success", "data", "message", "code" } 中。 你需要关注的字段位于 data 下。

提交（query）：

{ "success": true, "data": { "task_id": "abc123", "status": "submitted" } }

运行中轮询（result）：

{ "success": true, "data": { "task_id": "abc123", "status": "running" } }

完成后轮询（result）：

{
  "success": true,
  "data": {
    "task_id": "abc123",
    "status": "completed",
    "message_id": "456",
    "text": "The main analysis text...",
    "report": "# Detailed Report\n\n...",
    "report_url": "https://www.kalodata.com/...",
    "token_usage": {...},
    "credits_consumed": 10
  }
}

如何显示响应

仅当 data.status 为 completed 时才显示内容。然后从 data 中读取：

1. 显示 text 字段——这是主要分析内容。
2. 如果 report 不为 null，也一并显示（它是包含表格和结构化数据的 Markdown 报告）。
3. 如果 report_url 不为 null，将其显示为可点击链接，让用户可以在浏览器中打开完整报告，例如“查看完整报告：[链接]”。重要：必须原样复制 API 响应中的 report_url 值。切勿构造、猜测或伪造此 URL——URL 中的 task_id 和 tool_call_id 参数是由服务器生成的唯一值，无法推断。如果响应中没有 report_url 或其值为 null，则不要显示任何链接。
4. 在末尾注明消耗的积分，例如“（消耗了 10 积分）”。

错误响应

有两种形式：

• 请求被拒绝（例如积分不足、令牌无效——由 query 返回）：success 为 false，并包含顶层 message 和 code。
• 任务失败（由 result 返回）：data.status 为 error，并包含 data.error.message。

常见情况：

• 积分不足：告知用户需要在 KaloData 充值。
• 需要会员资格：转达相应消息——部分数据需要更高等级的套餐。
• 其他错误：直接显示错误消息。

用户可以询问的内容

KaloPilot 覆盖所有 TikTok Shop 区域（US、UK、ID、MY、TH、VN、PH、SG、MX、DE、IT、FR、ES、BR、JP）的以下维度：

• 商品：排名、销售趋势、价格分析、爆款商品、卖点分析、评论/评价分析、图片搜索（通过照片查找相似商品）
• 店铺：店铺排名、营收、商品组合、增长指标
• 创作者/网红：表现、GMV、粉丝分析、合作数据、创作者搜索
• 视频：爆款商品视频、互动指标、转化分析、视频脚本提取
• 直播：直播销售数据、观看人数指标、直播期间的商品表现
• 类目：市场规模、增长趋势、竞争格局、按关键词搜索类目
• 用户的收藏：查看已保存/关注的商品、店铺、创作者、视频和视频脚本
• URL 查询：粘贴 TikTok、KaloData、Shopee 或 Lazada 链接以获取实体详情
• KaloData 常见问题：关于如何使用 KaloData 本身的问题
• 会员与定价：套餐详情和定价信息
• 跨维度分析：例如，“美国美妆类目中，哪些创作者带来的销量最高？”

如需了解各维度对应的详细工具参数、筛选条件和排序选项，请阅读相关参考文件：

维度	参考文件
商品	references/products.md
店铺	references/shops.md
创作者	references/creators.md
视频	references/videos.md
直播	references/livestreams.md
类目	references/categories.md
收藏、URL 查询、常见问题、积分	references/utilities.md

仅阅读与用户问题相关的参考文件，无需全部加载。

示例查询

店铺诊断 — KaloPilot 将自动获取行业基准，与顶级竞争对手进行比较，并生成诊断报告：

“帮我诊断一下这个店铺 https://kalodata.com/shop/xxx，分析它的优劣势”

按价格区间选品 — 查询多个价格区间并进行比较：

“美国 Beauty 类目 $20-50 和 $50-100 价格带分别有哪些爆款？对比一下各价格带的竞争格局”

视频脚本分析 — 提取表现最佳视频的脚本，并按时间线进行拆解：

“帮我提取美国 Pet Supplies 类目近7天收入最高的5个视频脚本，总结爆款套路”

达人发现 — 查找符合特定条件的达人：

“帮我找美国 Beauty 类目粉丝10万-50万、互动率高的达人，按带货收入排序”

多轮深入分析：

用户：“英国市场 Electronics 类目近30天表现怎么样？” 用户：“前三名的店铺分别是谁？详细对比一下” 用户：“第一名的店铺用了哪些达人？分析达人结构”

重要规则

• 用户的问题可以使用任何语言，KaloPilot 会自动处理多语言查询。
• 如果查询含糊不清，按原样转发即可。KaloPilot 会提出澄清问题或采用合理的默认值。
• 切勿根据自己的知识回答 TikTok 数据问题，务必通过 API 查询。只有 KaloPilot 拥有最新的市场数据。
• 切勿捏造数据。如果 API 调用失败，请如实说明。