Guaikei Kuaishou Hashtag Video Fetcher

按关键词搜索快手视频、抓取博主公开作品和评论，返回结构化JSON数据，支持竞品监控和趋势洞察。

guaikei快手话题视频采集

✨ 一句话价值主张：无需登录快手账号，按关键词搜索视频、抓取博主公开作品、拉取视频评论，返回结构化 JSON 数据，帮你做爆款选题、竞品监控、KOL 筛选、评论舆情与趋势洞察。

1. 这个技能能做什么

一款专注快手公开数据挖掘的命令行技能。它穿透快手公开数据层，提供竞品监控、趋势预测、KOL 筛选三类决策支持，适合内容创作者、品牌营销人员、MCN 机构与市场分析师。

• 安全：不登录快手账号，无封号/风控风险。
• 强大：单次最多可拉取 1 万条数据，内置批量能力。
• 全面：各接口出参数据完整，可见且高价值字段均返回。
• 灵活：多维筛选、批量操作、结构化 JSON 输出，便于下游汇总或生成报告。
• 轻量：Node.js 一键运行，无需部署服务。

2. 什么时候该用它（AI 触发条件）

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

• 用户明确要查快手内容（含「快手」「Kuaishou」「ks」）。
• 用户要做关键词搜视频、爆款选题调研、竞品监控、评论洞察、博主作品追踪。
• 用户提出快手数据类诉求：快手数据采集 / 快手数据分析 / 快手舆情监控 / 快手涨粉调研 / 快手竞品对标。
• 用户提供了快手关键词、视频链接（short-video/...）或博主主页链接（profile/...），想要结构化数据。
• 用户后续还要基于结果做总结、对比、筛选、报告生成。

3. 什么时候不该用它（防误触发）

• 用户只是想写文案、改标题、生成脚本，并未要求查询快手公开数据。
• 用户查的平台不是快手（抖音、小红书、B站、微博等）。
• 用户要求获取私密内容、登录态数据、隐藏数据或非公开信息。
• 用户既无关键词、也无可识别的快手链接，且任务目标仍不明确——先追问，不要硬跑。

4. 能力边界

本技能覆盖 3 类能力，职责是先把数据拿回来，再交给上层流程分析：

能力	作用
关键词搜索	按关键词搜索快手视频
博主作品监控	按博主主页链接或 user_id 获取公开作品列表
视频评论获取	按视频链接单独拉取评论，做评论洞察与观点分析

🛑 不负责：登录快手账号；发布、互动、点赞、评论、关注；获取私密或非公开数据；代替用户做营销策略判断。

5. 调用路由规则

Note: 运行前需先开通 GUAIKEI_API_TOKEN 并配置为环境变量（官网 https://www.guaikei.com），否则无法调用接口。

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

路由细则

• 给的是关键词无链接 → 关键词搜索。
• 给的是 short-video/... 或 3x... 视频 ID → 视频评论获取。
• 给的是 profile/... 或纯数字 user_id → 博主作品监控。
• 多个目标并存时按意图拆分执行，不要硬塞进一次命令。

6. 输入收集规则

执行前先收集足够输入，缺关键参数不要硬跑。

6.1 关键词搜索（search-cli.js）

必填：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

6.2 博主作品监控（post-cli.js）

必填：url（主页链接，或纯数字 user_id）。 可选：

• sort：0 最新 / 1 最热（默认）
• limit：0–10000；为 0 时仅返回博主基础信息与互动数据，不返回作品列表

示例：https://www.kuaishou.com/profile/xxx、123456

6.3 视频评论获取（comment-cli.js）

必填：url（视频链接，或视频 ID 3x...）。 可选：

• limit：1–10000，不传默认 10

示例：https://www.kuaishou.com/short-video/xxx、3xxxx

链接类型不匹配时先指出，不要误走脚本。完整参数见 references/options.md。

7. 执行与输出原则

• 缺参先追问：keyword、url 缺失或链接类型不清时，先向用户澄清；无 GUAIKEI_API_TOKEN 时先提醒配置。
• 只取最后一份 JSON：脚本失败时通过 process.stdout.write(..., () => process.exit(1)) 异步写出后退出，消费方需等进程退出再读完整 stdout，且只解析最后一份带 status 的 JSON。
• 空结果也算失败：search-cli.js 把"无结果"视为失败（退出码 1）。关键词太窄或喂了 emoji/符号被清洗成空串时易触发，换更宽泛关键词或放宽 --time/--duration 即可。
• 输出结构：执行后优先返回——本次目标、关键参数、结构化 JSON（含 status：success/empty/error）、必要时一段摘要。
• 不编造数据：status 非 success 时如实反馈 error_code，不要把空结果当成成功结论。
• 可衔接下游：选题汇总、高赞对比、评论聚类、竞品风格总结、博主发文节奏分析、报告与表格生成。

优先触发示例：

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

8. 错误处理与失败应对

出现以下情况时明确说明原因，失败 JSON 带 status 与 error_code，下游先按 status 分支：

现象	含义 / 处理
401 / 403	token 未配置或无效：确认环境变量已注入、为十六进制无空格、未过期
429	触发频率限制：降频、减小 --limit、稍后重试
500/502/503	第三方 API 临时故障：等 1–2 分钟重试
ERRCODE_xxx	业务错误（HTTP 200 但 errcode!==0），如视频已删除/无权限，换确认存在的链接
ETIMEDOUT / UNKNOWN	网络超时：检查网络/代理，确认能访问 guaikei.com 后重试

9. 环境与依赖

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

10. 合规与使用限制

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

11. 反模式（自查清单）

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

12. 支持信息

• 官网（开通 token / 使用支持）：https://www.guaikei.com
• 人工支持：微信 13395823479（备注：快手技能）