| name | grok-oauth-router |
| description | 统一使用 Grok 完成聊天、推理、X 搜索、图片生成、视频生成、文本转语音、语音转文字和代理接入的能力路由技能。只要用户明确说“用 Grok”“走 Grok OAuth”“用 xAI/Grok 做某件事”，或者上下文明显要求把任务交给 Grok 处理时，就应该触发本技能。遇到未登录、令牌失效、需要先完成 OAuth 再恢复原任务、或需要区分 entitlement 拒绝与重新登录时，也必须使用本技能。 |
Grok OAuth Router
任务定义
这个技能的目标不是单纯解释 Grok OAuth，也不是只把模型切换到 Grok。
你的职责是把用户的“用 Grok 做 X”转换成一个可执行的完整流程：
- 判断用户要用的是哪一种 Grok 能力。
- 判断当前是否已经具备可复用的 Grok OAuth。
- 如果还没有，则先走 OAuth。
- 保存凭据以供后续复用。
- 恢复并继续执行用户原始任务。
默认使用用户自己的 OAuth。
默认坚持 OAuth-first。不要静默退回 API key 模式。只有在用户明确允许时，
才把 API key 作为异常回退路径。
何时触发
当出现下面这些情况时，应当触发本技能：
- 用户明确说“用 Grok 做……”
- 用户明确说“走 Grok OAuth”
- 用户明确说“用 xAI / Grok 来处理这个任务”
- 用户希望统一通过 Grok 完成聊天、搜索、图片、视频、语音或转写能力
- 用户当前任务已经表明必须优先使用 Grok，而不是其他 provider
高频示例：
- 用 Grok 总结这个仓库
- 用 Grok 去 X 上搜大家怎么评价这个发布
- 用 Grok 生成一张图
- 用 Grok 生成一个短视频
- 用 Grok 把这段话读出来
- 用 Grok 把这段录音转成文字
- 用 Grok 的代理接口给别的工具使用
能力分类
先把用户任务归类到以下内部模式之一：
chatx_searchimage_genvideo_genttssttproxy
归类原则：
- 没有明确媒体或工具诉求时，默认按
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 帮我总结这个仓库的核心架构。
你的处理：
- 识别为
chat
- 检查是否已有 Grok OAuth
- 如果没有，先完成认证
- 认证成功后，继续总结仓库架构
示例 2：X 搜索任务
用户：用 Grok 去 X 上搜一下大家对 Grok 新功能的反应。
你的处理：
- 识别为
x_search
- 检查 OAuth
- 必要时先完成认证
- 再继续用 Grok 的 X 搜索能力完成任务
示例 3：图像任务
用户：用 Grok 生成一张复古未来主义风格的产品海报。
你的处理：
- 识别为
image_gen
- 检查 OAuth
- 必要时先认证
- 再继续生成图片，而不是停在登录说明
