Docs
控制台

Skills CLI

Scrumball Skills 是一套面向网红营销的 AI Agent Skills。它把用户的自然语言需求映射为可执行的业务任务，再通过明确的 operationId 调用 Scrumball API。

该项目不是单纯的提示词集合。它同时提供：

  • 5 个按业务领域划分的 Agent Skill；
  • 84 个底层 API 操作；
  • 86 个面向业务人员和 AI Agent 的语义任务；
  • 平台支持的社媒数据能力；
  • 统一的初始化、连通性检查、任务发现和演示工具；
  • 每个 Skill 独立的 API 索引、参数说明、返回结构与执行脚本；
  • OpenAPI 规范和机器可读的任务映射。

适用场景包括达人发现、受众匹配、实时数据补充、营销活动监控和 TikTok Shop 电商情报分析。

能力总览

业务领域Skill任务数API 操作数平台主要能力
达人发现influencer-lead-discovery2223YouTube、TikTok、Instagram、跨平台搜索达人/内容、账号信息、相似达人、合作品牌、Hashtag 互动
受众匹配influencer-audience-fit-scoring3835YouTube、TikTok、Instagram地域、语言、年龄、性别、兴趣、互动行为、粉丝真实性、评级
实时补数influencer-realtime-enrichment1010YouTube、TikTok、Instagram实时账号、视频、贴文、Story 及内容详情
活动监控influencer-campaign-monitoring1111YouTube、TikTok、Instagram、跨平台创建、查询、刷新、停止监控任务，获取指标和下载素材
电商情报influencer-commerce-intel55TikTok带货销售、商品、直播、视频广告和商品详情

快速接入

初始化

初始化工具会询问网关地址、API Key、可选鉴权前缀和超时时间，将其写入 .env，并默认调用 /api/ping。

bash
npx skills add scrumball/skills

验证

bash
python3 scripts/scrumball_cli.py doctor

成功时应返回：

json
{
  "ok": true
}

查找任务

bash
python3 scripts/scrumball_cli.py tasks --search creator

预览调用

bash
python3 scripts/scrumball_cli.py demo \
  --task lead.find-tiktok-creators \
  --param query=nike \
  --dry-run

执行调用

确认任务、参数和目标环境后，移除 --dry-run：

bash
python3 scripts/scrumball_cli.py demo \
  --task lead.find-tiktok-creators \
  --param query=nike

Skills 安全与生产使用建议

凭证管理

  • 不要将 .env 或真实 API Key 提交到代码仓库；
  • 在生产环境中使用密钥管理服务或 CI/CD Secret；
  • 不要在日志、报错、Prompt 或业务报告中输出完整 API Key；
  • 为开发、测试和生产环境使用不同的凭证；
  • 定期轮换 API Key，并遵循最小权限原则。

调用安全

  • 首次运行任务时先使用 --dry-run 检查映射和参数；
  • 不要把文档示例值当成真实用户输入；
  • 对创建、刷新和停止监控任务增加确认与审计；
  • 对批量调用增加并发、重试和超时控制；
  • API 速率限制与配额以实际 Scrumball 网关策略为准，不应在客户端自行假设；
  • 跨平台比较时应提示口径差异，避免将不同平台指标直接等价。

数据质量

  • 实时接口无数据时，可重试一次并记录降级结果；
  • 缺少某个受众维度时可继续评分，但必须降低置信度；
  • 搜索无结果时一次只放宽一个筛选条件，并记录变化；
  • 监控数据存在延迟时，应明确标注数据新鲜度；
  • 业务结论应同时保留原始标识、调用时间和 operationId，便于审计。

常见问题排查

问题或报错常见原因处理方式
SCRUMBALL_BASE_URL is required未配置网关地址补充 .env 中的 SCRUMBALL_BASE_URL
SCRUMBALL_API_KEY is required未配置 API Key补充 .env 中的 SCRUMBALL_API_KEY
Missing required ...缺少 Query 或 Body 必填字段查看任务追问或对应 request-response.md
Unknown operationId拼写错误或使用了错误 Skill执行该 Skill 的 list 命令
HTTP 401 / 403API Key、鉴权前缀或权限错误检查 Key、SCRUMBALL_AUTH_PREFIX 和网关权限
HTTP 404网关地址、接口路径或目标资源错误检查 SCRUMBALL_BASE_URL、operationId 和标识字段
Network error / DNS 错误网关不可达、VPN 或 DNS 问题使用 doctor 检查，并确认网络环境
请求超时网关响应慢或超时设置过小适当提高 SCRUMBALL_TIMEOUT_SECONDS，并记录重试
返回为空标识错误、数据尚未收录或实时采集失败校验平台标识，重试一次并提供降级说明
任务映射不一致新增或重命名操作后未同步任务表执行 check-task-map --strict 并更新映射