Scrumball Skills

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-discovery`	22	23	YouTube、TikTok、Instagram、跨平台	搜索达人/内容、账号信息、相似达人、合作品牌、Hashtag 互动
受众匹配	`influencer-audience-fit-scoring`	38	35	YouTube、TikTok、Instagram	地域、语言、年龄、性别、兴趣、互动行为、粉丝真实性、评级
实时补数	`influencer-realtime-enrichment`	10	10	YouTube、TikTok、Instagram	实时账号、视频、贴文、Story 及内容详情
活动监控	`influencer-campaign-monitoring`	11	11	YouTube、TikTok、Instagram、跨平台	创建、查询、刷新、停止监控任务，获取指标和下载素材
电商情报	`influencer-commerce-intel`	5	5	TikTok	带货销售、商品、直播、视频广告和商品详情

快速接入

初始化

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

验证

成功时应返回：

{
  "ok": true
}

查找任务

预览调用

执行调用

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

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` / `403`	API Key、鉴权前缀或权限错误	检查 Key、`SCRUMBALL_AUTH_PREFIX` 和网关权限
HTTP `404`	网关地址、接口路径或目标资源错误	检查 `SCRUMBALL_BASE_URL`、`operationId` 和标识字段
`Network error` / DNS 错误	网关不可达、VPN 或 DNS 问题	使用 `doctor` 检查，并确认网络环境
请求超时	网关响应慢或超时设置过小	适当提高 `SCRUMBALL_TIMEOUT_SECONDS`，并记录重试
返回为空	标识错误、数据尚未收录或实时采集失败	校验平台标识，重试一次并提供降级说明
任务映射不一致	新增或重命名操作后未同步任务表	执行 `check-task-map --strict` 并更新映射

能力总览#

快速接入#

初始化#

验证#

查找任务#

预览调用#

执行调用#

Skills 安全与生产使用建议#

凭证管理#

调用安全#

数据质量#

常见问题排查#