# Kuaishou Assistant

> 快手数据助手、快手热榜、快手内容研究、作品研究、作品详情、评论分析、评论回复分析、达人数据和达人作品。覆盖 Kuaishou / Kwai short-video research，来自 GuaiKei 社媒数据助手。

- Skill: `why20261/kuaishou-assistant` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add why20261/kuaishou-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/why20261/kuaishou-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: why20261 (https://skillmd.com/u/why20261)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/why20261/kuaishou-assistant

---


# 快手数据助手 (KuaiShou Assistant)

> ✨ **一句话价值主张**：快手数据助手、快手热榜、快手内容研究、作品研究、作品详情、评论分析、达人数据和达人作品。覆盖 Kuaishou / Kwai short-video research。输入关键词就能搜到快手实时作品数据，通过快手作者就能获取KOL的作品列表，通过作品链接就能抓取作品评论。当用户需要搜索快手作品、获取快手最多点赞视频、查找快手热门内容、查询快手作品数据时使用。

## 1. 🛠️ 技能概述

这是一款专注于**快手数据挖掘**的工具。它能够穿透快手的公开数据层，为你提供深度的**竞品监控**、**趋势预测**和**KOL 筛选**服务。无论你是内容创作者、品牌营销人员还是市场分析师，都能通过此工具获取决策支持。

**🔥核心优势**

> - 安全: 无需登录你的快手账号，不担心风控风险 / 封号问题
> - 强大: 一次可获取最多1W条数据，技能内置批量操作，使用简单方便
> - 全面: 各功能出参数据全面，可见及有价值数据都会返回
> - 灵活: 支持多维度筛选、批量操作、多格式导出
> - 轻量: 无需部署服务，Node.js 一键运行
> - 实用: 日志自动归档，适配营销报告 / 内容策划场景

## 2. ✅ 什么时候应该调用这个技能（AI 触发条件）

🎯 出现以下任一信号时优先调用本技能：

- 用户明确提到要查 **快手** 内容（含「快手」「Kuaishou」「短视频」等词）。
- 用户要做 **关键词搜索视频**、**爆款选题调研**、**竞品监控**、**评论洞察**、**博主作品追踪**。
- 用户提供了快手关键词、视频链接（`short-video/...`）或博主主页链接（`profile/...`），希望拿到结构化数据。
- 用户后续还要基于结果继续做总结、对比、筛选、报告生成。

### 🚫 不要在这些场景误调用

- 用户只是想写文案、改标题、生成脚本，但并未要求查询快手公开数据。
- 用户查询的平台不是快手，例如抖音、小红书、B站、微博。
- 用户要求获取私密内容、登录态数据、隐藏数据或非公开信息。
- 用户既没有提供关键词，也没有提供可识别的快手视频链接/主页链接，且任务目标仍不明确。

如果意图不明确，先追问，不要盲目执行命令。

## 3. 🚧 能力边界

本技能当前只覆盖 3 类能力：

1. **关键词搜索**：按关键词搜索快手视频。
2. **博主作品监控**：根据博主主页链接或 user_id 获取其公开作品列表。
3. **视频评论获取**：根据视频链接单独获取该视频的评论数据，便于做评论洞察与观点分析。

🛑 本技能不负责：

- 登录快手账号
- 发布内容、互动、点赞、评论、关注
- 获取私密或非公开数据
- 代替用户做营销策略判断

它的职责是先把数据拿回来，再交给上层流程去分析、整理或生成结论。

## 4. 🔀 调用路由规则

> **Note:** 请先通过 [快手作品搜索技能官网](https://www.guaikei.com) 开通TOKEN，配置环境变量 `GUAIKEI_API_TOKEN` 后才能正常运行。

根据用户输入的关键信号，路由到对应脚本：

| 用户输入 / 意图              | 调用脚本                          | 必填输入               | 典型结果                               |
| ---------------------------- | --------------------------------- | ---------------------- | -------------------------------------- |
| 查某个关键词的快手视频       | `scripts/kuaishou/search-cli.js`  | `keyword`              | 视频列表、作者信息、互动信息、跳转链接 |
| 看某个快手博主最近发布了什么 | `scripts/kuaishou/post-cli.js`    | 博主主页 URL / user_id | 博主公开作品列表                       |
| 看某篇快手视频的评论数据     | `scripts/kuaishou/comment-cli.js` | 视频 URL               | 该视频的评论内容、评论者信息、互动数据 |

### 🧭 路由细则

- 用户给的是 **关键词**，没有链接：走 **关键词搜索**。
- 用户给的是 `https://www.kuaishou.com/short-video/...` 或 `3x...` 视频ID，走 **视频评论获取**。
- 用户给的是 `https://www.kuaishou.com/profile/...` 或纯数字 `user_id`：走 **博主作品监控**。
- 如果用户同时给出多个目标，按用户目标拆分执行，不要把不同意图硬塞进一次命令。

## 5. 🧺 输入收集规则

执行前先收集足够输入，避免无效调用。

### 5.1 🔍 关键词搜索

至少要确认：

- `keyword`：搜索关键词，建议 2-50 个字符。

可选参数：

- `sort`：排序规则，`0` 综合排序，`1` 最新发布，`2` 最多点赞。
- `time`：发布时间，`0` 全部，`1` 近一日，`7` 近一周，`30` 近一月。
- `duration`：视频时长，`0` 全部，`1` 1分钟以内，`2` 1-5分钟，`3` 5分钟以上。
- `limit`：返回数量，范围 `1-10000`，默认 `10`。

如果用户只说“帮我看看最近趋势”，优先补问：关键词是什么？

### 5.2 📡 博主作品监控

至少要确认：

- `url`：快手博主主页链接，或博主 `user_id`（纯数字也可）。

可选参数：

- `sort`：排序方式，`0` 最新，`1` 最热（默认）。
- `limit`：返回作品数量上限，`0–10000`；**为 `0` 时仅返回博主基础信息与互动数据**，不返回作品列表。

适用链接示例：

- `https://www.kuaishou.com/profile/xxx`
- `123456`（博主 user_id）

如果用户给的是视频详情链接，不要误走博主脚本，先说明需要主页链接或 user_id。

### 5.3 💬 视频评论获取

至少要确认：

- `url`：快手视频链接，或视频 ID（`3x...`）。

可选参数：

- `limit`：评论数量上限，`1–10000`；不传时默认 `10`。

适用链接示例：

- `https://www.kuaishou.com/short-video/xxx`
- `3xxxx`（视频 ID）

如果用户给的是博主主页链接，不要误走评论脚本，先指出链接类型不匹配。

**👉 详细选项说明**, 可参阅 [完整选项说明](references/options.md)

## 6. 📜 执行原则

### 6.1 ❓ 缺少必要输入时

- 没有关键词：先追问关键词。
- 没有链接：先追问视频链接或博主主页链接 / user_id。
- 链接类型不明确：先确认这是视频还是博主主页。
- 没有 `GUAIKEI_API_TOKEN`：提醒用户先配置环境变量，再执行。

不要在缺关键输入时硬调命令。

### 6.2 📤 输出原则

执行完成后，优先返回：

- 本次执行的目标
- 关键参数
- 结构化 JSON 结果（含 `status`：`success` / `empty` / `error`）
- 如果有必要，再补充一小段摘要说明

适合继续衔接的后续动作包括：选题汇总、高赞视频对比、评论观点聚类、竞品内容风格总结、博主发文节奏分析、报告与表格生成。

### 6.3 🩹 失败处理原则

出现以下情况时，应明确向用户说明原因：token 未配置或无效、链接不合法或类型错误、搜索结果为空、接口返回异常、网络或超时问题。**失败时不要编造数据，不要把空结果当成成功结论。**

## 7. 🚀 对 WorkBuddy / OpenClaw 更友好的使用方式（AI 调用约定）

为了提升识别准确率与执行成功率，Agent 请遵循：

1. **先路由后执行**：仅凭「关键词 / profile 链接 / short-video 链接」三类信号选择脚本，路径一律用 `scripts/kuaishou/...`。
2. **缺参先追问**：`keyword`、`url` 任一缺失或链接类型不清时，不要执行，先向用户澄清。
3. **不编造数据**：`status` 非 `success` 时如实反馈 `error_code`，不要拼装假结果。
4. **只取最后一份 JSON**：脚本失败时通过 `process.stdout.write(..., () => process.exit(1))` 异步写出后退出，消费方需等进程退出再读完整 stdout，且只解析最后一份带 `status` 的 JSON。

优先采用的自然语言触发示例：

- 帮我搜一下快手里"具身智能"的高赞视频
- 分析这条快手视频评论区都在讨论什么
- 看看这个快手博主最近 20 条作品主要发什么内容
- 监控"具身智能"最近一周的内容趋势

如果用户表达比较笼统（如"帮我做快手竞品分析"），优先把任务拆成两步：先确认关键词 / 竞品链接 / 博主主页，再调用对应脚本拿回数据。

## 8. 📦 环境与依赖

- 运行环境：Node.js 16.14.0+
- 系统兼容：Windows / Linux / macOS
- 必需环境变量：`GUAIKEI_API_TOKEN`
- 官方入口：<https://www.guaikei.com>
- 详细参数说明：见 `references/options.md`
- 更新记录：见 `references/changelog.md`

## 9. 🛡️ 合规与使用限制

- 仅处理快手**公开数据**，不涉及登录态与隐私。
- 不支持私密、隐藏或需要登录态的数据。
- 不应将返回数据用于违规分发或违法用途。
- 本技能会依赖第三方 API 服务，请在使用前确认数据外发与授权范围。

## 10. 🚫 反模式与常见问题 FAQ

> 本章帮助你自行判断「是不是用错了」以及「报错时怎么处理」。结构化结果都带 `status` 和 `error_code` 字段，下游请**先按 `status` 分支**，再参考 `error_code`。

### 10.1 🚫 反模式

- **链接类型错配**：把 `profile/...` 传给 `comment-cli.js`，或把 `short-video/...` 传给 `post-cli.js`。
- **缺关键输入就硬跑**：没有 `keyword`、没有 `url`，或链接类型不明确时，先追问。
- **传脏链接**：带前后空格、用 `http://`（非 `https://`）的链接会被拒绝；需要时先 trim、`http→https` 归一。
- **`limit` 超限被静默降级**：上限 `10000`，写成 `> 10000` 会被静默降到 `10`。
- **把空结果当成功 / 编造数据**：失败 JSON 的 `status` 是 `"error"`（或 `"empty"`），`results` 为 `null`；只有成功时 `results` 才有数据。
- **关键词喂 emoji / 纯符号**：会被清洗成空串，触发「关键词无效」拦截。

### 10.2 ❓ 常见问题 FAQ

**Q1. 报错 `error_code: 401` 或 `403` 怎么办？**

> 含义：`GUAIKEI_API_TOKEN` 未配置或无效。自查：①确认运行环境里 `export GUAIKEI_API_TOKEN=...` 已注入当前进程；②token 须为十六进制字符串，核对是否有空格/换行；③是否已过期，去 guaikei.com 重新开通。

**Q2. 报错 `error_code: 429` 怎么办？**

> 含义：触发频率限制。降低调用频率、减小 `--limit`、或稍后重试。

**Q3. 报错 `error_code: 500 / 502 / 503` 等服务端错误怎么办？**

> 含义：第三方 API 临时故障。等 1–2 分钟重试；持续出现再联系支持，并附上 `skill_metadata.execution_time` 与请求参数。

**Q4. 报错 `error_code: ERRCODE_xxx` 怎么办？**

> 含义：业务层错误（HTTP 200 但 `errcode !== 0`），常见如「视频已删除 / 不存在 / 无权限」。换一条确认仍存在的链接；该错误不会随重试变好。

**Q5. 报错 `error_code: ETIMEDOUT` 或 `UNKNOWN` 怎么办？**

> 含义：网络超时或无法解析响应。检查本机网络/代理；确认能访问 guaikei.com；重试一次。

**Q6. `--limit 0` 在博主作品里是什么意思？**

> 含义：仅返回博主**基础信息与互动数据**，不返回作品列表。仅 `post-cli.js` 支持；`comment-cli.js` 的 `--limit` 要求 `>= 1`。

**Q7. 命令一启动就退出、没输出数据？**

> 自查：多半是 `GUAIKEI_API_TOKEN` 未通过校验（见 Q1）。运行前先 `echo $GUAIKEI_API_TOKEN` 确认变量已注入。

**Q8. 搜索返回空、但退出码不是 0？**

> 含义：`search-cli.js` 把「无结果」视为失败（退出码 1）。换更宽泛的关键词、放宽 `--time` / `--duration`，或确认关键词不是被清洗成空串的符号。

**Q9. 设了 `--limit 10000` 却只拿到 10 条？**

> 含义：`limit` 写成了超过 `10000` 的值，被静默降到默认 `10`。确认 `--limit` 是 `1–10000` 之间的整数。

**Q10. 下游程序解析 stdout 失败 / `Unexpected end of JSON input`？**

> 自查：失败输出经 `process.stdout.write(..., () => process.exit(1))` 异步写出后会退出；请确保消费方**等进程退出后再读完整 stdout**，且只取最后一份 JSON。

## 11. 🎧 支持信息

如需开通 token 或获得使用支持，可优先通过官网处理：

- 官网：[快手搜索作品数据获取技能官网](https://www.guaikei.com)

如需人工支持，可联系开发者：

- 微信：`13395823479`（备注：快手技能）