YouTube KeyAPI 技能

将自然语言形式的 YouTube 请求转化为基于文档指导的 KeyAPI REST 工作流。从用户业务目标出发，映射至最贴近的场景，依据最新 KeyAPI 文档验证当前端点契约，随后在存在辅助脚本时调用该脚本执行请求；否则直接发起 REST 调用。

执行契约

• 使用 KeyAPI REST API 执行实时数据查询、排序、分析、搜索、对比与报表生成。
• 以 https://docs.keyapi.ai/llms.txt 及其链接的各端点页面为权威来源，用于确认方法（method）、/v1/... 路径、参数、枚举值、分页机制、请求体（request body）和响应结构（response shape）。
• 不得以平台网页或人工浏览替代 API 数据获取。
• 凭证须保留在本地。切勿打印或复述 KEYAPI_TOKEN。
• 若官方文档与此技能说明存在冲突，以官方文档为准。

硬性规则

针对 YouTube 数据查询、排序、分析、搜索、对比或报表生成，必须使用 KeyAPI API 执行及官方 KeyAPI 文档。不得以平台网页替代 API 结果。

工作流

1. 以 references/global-rules.md 作为基础执行契约。
2. 当脚本可执行且配置状态未知时，运行 node scripts/configure-keyapi-auth.mjs --status 检查认证状态；将 authStatus: "available" 视为已就绪，authStatus: "unavailable" 视为凭证缺失。
3. 若 authStatus 为 unavailable，则中止实时执行，加载 references/setup-and-auth.md，并向用户提供精确的配置命令：node scripts/configure-keyapi-auth.mjs。不得仅提示“设置 KEYAPI_TOKEN”。
4. 识别用户的业务目标、实体（entity）、作用域（scope）、指标（metric）、分页深度（pagination depth）及期望输出格式。
5. 参考 references/scenarios.md 将请求映射至 YouTube 相关场景。
6. 依据 references/routing-policy.md 选择搜索/列表、详情、解析、排序/趋势、关联实体或组合型工作流模式。
7. 应用 references/youtube-rules.md 中关于 YouTube 特定标识符、分页及报表生成的规则。
8. 当请求匹配某个预设场景时，加载 references/scenarios.md 中所引用的对应场景说明文档。
9. 若辅助脚本可用，运行 node scripts/search-keyapi-docs.mjs --query "<语义化实体动作>" --resolve 解析当前文档；否则直接打开 https://docs.keyapi.ai/llms.txt 及所选端点页面。查询语句应基于推断出的场景/API 概念构建，而非字面复制用户模糊或翻译后的表述。
10. 依据解析结果或已打开的文档页面，提取当前 OpenAPI 方法、/v1/... 路径、必需的查询参数/请求体参数、示例及响应契约，再执行任何实时 API 调用。严禁根据文档 URL、场景名称、端点标题、记忆中的路由或历史 404 错误推断 API 路径。
11. 仅请求无法安全默认的高价值缺失输入项。
12. 当脚本可执行时，优先使用 node scripts/keyapi-api.mjs 发起实时 REST 调用；仅当脚本不可用，或辅助工具无法表达文档中定义的请求时，才使用宿主环境的 HTTP 客户端。
13. 检查 HTTP 状态码及 KeyAPI 响应信封（envelope）。code = 0 表示成功；非零 code 表示 API 层级失败。
14. 以面向用户的分析性语言返回结果，并明确区分实际观测到的 API 事实与推理结论。

交互规则

• 不得以罗列原始端点或倾倒全部参数开头。应首先识别用户业务目标，选取最接近的场景，仅收集缺失的高价值输入项，解析当前文档，最后执行调用。
• 面向非技术用户时，优先使用场景名称及面向用户的流程描述，而非端点名称；仅在路径选定后，或用户主动询问集成细节时，才使用原始端点名称。
• 端点选择应首先视为语义化路由：根据用户目标推断平台数据面与操作意图，再通过文档搜索验证当前端点。
• 若多个端点均可完成任务，优先选择所需用户输入最少、且文档中过滤能力最强的端点。
• 若用户请求模糊，应提供 2 至 4 个具体场景选项，而非提出开放式问题。
• 若请求涉及宽泛报表或大量相邻调用，应在执行前确认所需章节及最大作用域范围。
• 若凭证缺失，应暂停实时执行并引导至配置流程；不得回退至平台网站或未认证浏览来获取 API 数据。

场景选择

阅读 references/scenarios.md 以选择最佳场景卡片。若无完全匹配的场景，则选用最接近的场景并明确标注假设；或回退至高级模式，逐步暴露筛选条件。请始终以官方文档索引为端点权威来源，而非场景卡片本身。

输入模型

将参数繁多的 API 压缩为以下决策字段：

• 目标（Goal）：搜索、详情、增强、排序、对比、监控或报表
• 实体（Entity）：被搜索、分析、对比、排序或监控的 YouTube 对象
• 作用域（Scope）：视频/频道 URL 或 ID、关键词、地区、语言、分类、发布时间窗口、评论作用域、延续深度（continuation depth）
• 指标或排序依据（Metric or sort）：播放量、点赞数、评论数、发布时间、订阅者数、时长、相关性、趋势排名
• 分页深度（Pagination depth）：单页、前 N 条、直至获得足够证据，或在用户授权范围内获取全部可用结果
• 输出格式（Output format）：简洁答案、表格、原始 JSON 或结构化报表

场景族系

• 检查视频元数据、互动数据、直播流及关联视频
• 分析评论及嵌套回复
• 搜索视频、Shorts 或热门视频
• 解析频道 ID、URL、账号名（handle）及描述
• 采集频道视频并在 YouTube 频道内搜索

KeyAPI 特定用法

• 优先采用当前文档中定义的服务端过滤器，而非客户端过滤。
• 若多个端点均可完成任务，优先选择所需用户输入最少、且文档中过滤能力最强的端点。
• 对于宽泛报表，应在启动多端点工作流前确认用户所需的报表章节。
• 针对 YouTube 报表，需分别处理视频、Shorts、评论、子评论、直播流、关联视频、格式、频道元数据，以及搜索/趋势上下文。
• 若用户询问集成细节，应依据当前文档提供方法、路径、认证方式、必需参数及最小化请求示例。

入门规则

当用户尚未配置凭证时，应主动提供配置脚本命令。不得仅回答“配置 KEYAPI_TOKEN”。

当 authStatus 为 unavailable 时：

• 说明 KeyAPI 使用 Bearer Token 认证，依赖环境变量 KEYAPI_TOKEN
• 指引用户前往 KeyAPI 控制台及认证文档
• 若脚本可执行，要求通过 node scripts/configure-keyapi-auth.mjs 在本地完成配置
• 同时说明可使用 node scripts/configure-keyapi-auth.mjs --status 检查认证是否可用
• 说明配置过程会将凭证写入 Shell 环境变量
• 说明 --status 输出为 available 或 unavailable；仅当输出为 available 时继续实时请求
• 仅在配置完成后继续实时请求

脚本契约

本技能包含位于 scripts/ 下的辅助脚本，用于保障本地执行的可靠性：

• scripts/configure-keyapi-auth.mjs
• scripts/search-keyapi-docs.mjs
• scripts/keyapi-api.mjs

请从此技能目录下运行脚本命令。若宿主代理（host agent）当前工作目录不同，请将 scripts/... 相对于本 SKILL.md 文件进行解析。对于大型 JSON 请求体（尤其是含 base64 编码图像载荷的情况），推荐使用 --body-file 或 --image-file，而非内联 --body。其中 keyapi-api.mjs 总是发起实时 API 请求；重复相同请求将再次调用 API。除非显式指定 --output-file，否则该辅助工具不会创建本地响应文件。大型响应可能仅返回 stdout 预览；如需完整字段以供提取、排序、聚合或校验，请使用 --output-file 保存完整辅助工具输出，并从 data.data 字段读取 API 响应载荷。对于代理内部分析，可写入临时路径（如操作系统临时目录，或 workspace 下的 .tmp-keyapi-*.json 文件）；但不得将该临时文件作为面向用户的交付物呈现，且应在可行时及时清理，或仅在最终答复中简要提及。当用户要求保存结果、导出 JSON 或提供文件时，应将 --output-file 视为有意为之的面向用户输出文件。仅当用户明确需要原始 JSON 输出至 stdout 时，才使用 --stdout full。对于查询字符串，优先采用重复的 --query-param key=value 或 --param key=value；仅在需结构化数组/对象型查询值时，才使用 --query-file query.json 或 --query。查询参数按如下顺序合并：--query → --query-file → 重复的 query params，后出现的值覆盖先出现的值；空值的 query-param 不会被发送。

当脚本可执行时，按如下优先级使用：

1. 认证状态检查
2. 实时 REST 调用前的文档解析
3. 实时 REST 调用

若宿主代理不支持脚本执行，或辅助工具无法表达文档中定义的请求，则不得因此使任务失败。应改用宿主环境可用的 HTTP 客户端，以相同文档定义的 REST 方法、路径、请求头、查询参数及请求体发起调用。

脚本示例

解析本平台当前文档：

node scripts/search-keyapi-docs.mjs --query "<实体 动作>" --resolve

执行已记录的 GET 端点：

node scripts/keyapi-api.mjs --path /v1/youtube/... --query-param example=value

从 JSON 文件读取查询参数执行：

node scripts/keyapi-api.mjs --path /v1/youtube/... --query-file query.json

预览大型响应而不保存：

node scripts/keyapi-api.mjs --path /v1/youtube/... --query-param example=value --stdout preview

将完整响应写入临时文件供内部分析：

node scripts/keyapi-api.mjs --path /v1/youtube/... --query-param example=value --output-file .tmp-keyapi-youtube-response.json

为用户保存或导出完整响应：

node scripts/keyapi-api.mjs --path /v1/youtube/... --query-param example=value --output-file response.json

执行已记录的 POST 端点：

node scripts/keyapi-api.mjs --path /v1/youtube/... --method POST --body '{"example":"value"}'

使用大型 JSON 请求体执行已记录的 POST 端点：

node scripts/keyapi-api.mjs --path /v1/youtube/... --method POST --body-file request.json

从本地文件执行图像 JSON 端点：

node scripts/keyapi-api.mjs --path /v1/youtube/... --method POST --query-param example=value --image-file ./image.jpg --image-field image_base64

参考资料

• references/global-rules.md
• references/scenarios.md
• references/routing-policy.md
• references/youtube-rules.md
• references/youtube-video-rules.md
• references/youtube-channel-rules.md
• references/youtube-search-trends-rules.md
• references/setup-and-auth.md