grok-oauth-router

name	grok-oauth-router
description	统一使用 Grok 完成聊天、推理、X 搜索、图片生成、视频生成、文本转语音、语音转文字和代理接入的能力路由技能。只要用户明确说“用 Grok”“走 Grok OAuth”“用 xAI/Grok 做某件事”，或者上下文明显要求把任务交给 Grok 处理时，就应该触发本技能。遇到未登录、令牌失效、需要先完成 OAuth 再恢复原任务、或需要区分 entitlement 拒绝与重新登录时，也必须使用本技能。

Grok OAuth Router

任务定义

这个技能的目标不是单纯解释 Grok OAuth，也不是只把模型切换到 Grok。

你的职责是把用户的“用 Grok 做 X”转换成一个可执行的完整流程：

1. 判断用户要用的是哪一种 Grok 能力。
2. 判断当前是否已经具备可复用的 Grok OAuth。
3. 如果还没有，则先走 OAuth。
4. 保存凭据以供后续复用。
5. 恢复并继续执行用户原始任务。

默认使用用户自己的 OAuth。

默认坚持 OAuth-first。不要静默退回 API key 模式。只有在用户明确允许时， 才把 API key 作为异常回退路径。

何时触发

当出现下面这些情况时，应当触发本技能：

• 用户明确说“用 Grok 做……”
• 用户明确说“走 Grok OAuth”
• 用户明确说“用 xAI / Grok 来处理这个任务”
• 用户希望统一通过 Grok 完成聊天、搜索、图片、视频、语音或转写能力
• 用户当前任务已经表明必须优先使用 Grok，而不是其他 provider

高频示例：

• 用 Grok 总结这个仓库
• 用 Grok 去 X 上搜大家怎么评价这个发布
• 用 Grok 生成一张图
• 用 Grok 生成一个短视频
• 用 Grok 把这段话读出来
• 用 Grok 把这段录音转成文字
• 用 Grok 的代理接口给别的工具使用

能力分类

先把用户任务归类到以下内部模式之一：

• chat
• x_search
• image_gen
• video_gen
• tts
• stt
• proxy

归类原则：

• 没有明确媒体或工具诉求时，默认按 chat 处理
• 提到 X / Twitter / 推文 / 线程 / 社交反应时，优先考虑 x_search
• 提到生成图片、海报、概念图、插画、渲染时，优先考虑 image_gen
• 提到生成视频、动画、图生视频时，优先考虑 video_gen
• 提到朗读、配音、语音播报时，优先考虑 tts
• 提到转录、转写、语音识别、字幕时，优先考虑 stt
• 提到 OpenAI-compatible、代理端点、给别的工具接入时，优先考虑 proxy

执行流程

始终按下面的顺序处理：

1. 先识别原始任务

不要一看到 Grok 就只讨论认证。先提炼出用户真正想完成的任务。

你需要在内部保留一个简短的“原始任务摘要”，用于认证完成后的自动续跑。

2. 检查 OAuth 状态

优先复用已有的 Grok OAuth 状态。检查重点包括：

• 是否已有已保存的 xAI OAuth 状态
• access token 是否存在
• token 是否仍可用
• 是否已经进入需要重新登录的状态
• 是否属于 entitlement / tier 被拒绝，而不是普通登录失效

如果 OAuth 已可用，就直接继续执行原始任务。

3. 没有 OAuth 时先认证

如果没有可用 OAuth，就先完成认证，再继续任务。

认证模式优先级：

• 本地桌面环境：使用浏览器 loopback 回调
• SSH / 远程环境：使用远程 listener + 本地端口转发
• 浏览器型远端环境：使用手动粘贴 callback 的方式

认证完成后要做两件事：

• 保存凭据，供未来 Grok 任务复用
• 自动恢复原始任务，而不是停在“登录成功”

4. 把任务路由到正确能力面

认证通过后，按能力类型继续：

• chat 用 Grok 作为主模型完成聊天、推理、分析、总结、工具调用等任务

• x_search 优先使用 Grok 的 X 搜索能力，而不是泛化成普通网页搜索

• image_gen 路由到 Grok 图片生成能力

• video_gen 路由到 Grok 视频生成能力

• tts 路由到 Grok 文本转语音能力

• stt 路由到 Grok 语音转文字能力

• proxy 路由到 Grok 兼容代理能力

5. 自动续跑原任务

认证只是前置步骤，不是结果。

认证成功后，直接继续执行原始任务，不要要求用户重复说一遍“刚才那个任务”。

错误处理规则

必须区分两类问题：

需要重新登录

这类问题通常意味着：

• 本地没有可用 OAuth
• refresh token 失效
• token 过期且无法正常刷新
• 需要重新完成浏览器授权

遇到这种情况时，应该把重点放在“先完成认证，再自动恢复原任务”。

entitlement / tier 被拒绝

这类问题不是简单重新登录就能解决的。

当判断为 entitlement、tier、allowlist 或 API 权限被拒绝时：

• 不要把它误报成“重新登录即可解决”
• 明确告诉用户这是账号权限层面的拒绝
• 默认不要静默切到 API key
• 只有在用户明确允许时，才讨论 API key 回退方案

能力面与模型不匹配

如果某个 Grok 模型不支持 x_search 或某个工具能力：

• 明确指出问题在“模型能力不匹配”
• 优先切换到支持该能力的 Grok 模型
• 不要把这类问题误判为 OAuth 失败

用户交互规则

与用户沟通时遵守下面的规则：

• 把用户目标放在前面，不要把认证当主角
• 认证需要用户配合时，用简短说明解释下一步
• 认证完成后，主动继续执行原任务
• 不要默认让用户在 OAuth 和 API key 之间做开放式选择
• 只有在真正存在风险分叉时，才向用户确认

如果认证会打断当前执行，应当明确保留原始任务语义，例如：

• “我先帮你完成 Grok OAuth，完成后继续用 Grok 搜 X 上的讨论。”
• “我先把 Grok 登录状态准备好，然后继续用 Grok 生成图片。”

参考文档使用方式

优先按需读取以下文档：

• ./grok-skill-routing-plan.md 用于理解整体设计目标、路由边界和运行时状态机

• ./capability-matrix.md 用于确认当前 Grok 能力面和路由范围

• ./oauth-flow.md 用于理解 OAuth 的用户路径、本地 / SSH / manual-paste 分支，以及恢复原任务的要求

• ./constraints-and-risks.md 用于判断哪些情况属于能力限制、上游变化或路由风险

• ./hermes-grok-oauth-parameter-observations.md 只在需要研究兼容性细节时读取。这里记录的是 Hermes 当前可观察到的参数、 固定值和行为特征，用于兼容性判断，而不是稳定不变的官方契约。

关于 Hermes 参数与值

需要理解下面这个边界：

• 这个技能的目标是让用户用自己的 OAuth 使用 Grok 的全部能力
• Hermes 当前使用的参数、值和请求形状，是兼容性观察输入
• 不要把这些参数和值包装成对用户的表层概念
• 不要把“复制 Hermes”本身当成用户目标

在真正需要分析兼容性问题时，再去查阅参数观察文档。

输出要求

当任务完成时：

• 先给出 Grok 任务结果
• 再简短说明是否进行了 OAuth 复用或新认证

当任务被认证阻塞时：

• 明确说明正在为哪个原始 Grok 任务做前置认证
• 保留原始任务摘要
• 认证完成后自动继续

当任务被 entitlement 阻塞时：

• 明确这是权限 / tier 问题
• 不要误导用户反复重新登录

示例

示例 1：聊天任务

用户：用 Grok 帮我总结这个仓库的核心架构。

你的处理：

1. 识别为 chat
2. 检查是否已有 Grok OAuth
3. 如果没有，先完成认证
4. 认证成功后，继续总结仓库架构

示例 2：X 搜索任务

用户：用 Grok 去 X 上搜一下大家对 Grok 新功能的反应。

你的处理：

1. 识别为 x_search
2. 检查 OAuth
3. 必要时先完成认证
4. 再继续用 Grok 的 X 搜索能力完成任务

示例 3：图像任务

用户：用 Grok 生成一张复古未来主义风格的产品海报。

你的处理：

1. 识别为 image_gen
2. 检查 OAuth
3. 必要时先认证
4. 再继续生成图片，而不是停在登录说明