# Grok Vision

> grok-vision：借 grok 的眼睛

- Skill: `phaseddd/grok-vision` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add phaseddd/grok-vision`
- Raw SKILL.md: https://api.skillmd.com/api/skills/phaseddd/grok-vision/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: phaseddd (https://skillmd.com/u/phaseddd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/phaseddd/grok-vision

---


# grok-vision：借 grok 的眼睛

图片/视频视觉分析交给 grok 原生视觉能力：图片走 API 内联（最轻）或本地 grok CLI 降级，视频走 API 文件上传链路（无降级）。

触发：`paths` 限定的目录内（demos、.vision）自动生效；其他地方手动 `/grok-vision <图片或视频路径> [问题]` 兜底。用户给了文件路径/公网 URL 和关注点后，按下面流程执行。

## 调用（bash，统一走脚本）

```bash
node ${CLAUDE_SKILL_DIR}/scripts/grok-vision.mjs image --file a.png --file b.png --prompt '用中文回答：两页对齐是否一致'
node ${CLAUDE_SKILL_DIR}/scripts/grok-vision.mjs image --file a.png --prompt '核对布局' --detail high
node ${CLAUDE_SKILL_DIR}/scripts/grok-vision.mjs video --file demo.mp4 --prompt 't=0s 黑场 → t=1s 标题浮现 → t=2.5s 完成态，评估节奏'
node ${CLAUDE_SKILL_DIR}/scripts/grok-vision.mjs convert input.webm output.mp4
node ${CLAUDE_SKILL_DIR}/scripts/grok-vision.mjs check
```

- 脚本路径用环境注入的 skill 目录变量（Claude Code：`${CLAUDE_SKILL_DIR}`；其他环境无此变量时，从技能目录用相对路径 `scripts/grok-vision.mjs`）
- `--prompt` 用 bash 单引号包裹；prompt 超长/含引号/多行时写入临时文件改用 `--prompt-file <文件>`
- `image` 默认传 `detail=high`（对齐 xAI 示例）；与 `--model` 一样仅用 CLI `--detail high|low|auto` 覆盖
- `--json` 输出单行 JSON；退出码：0 成功 / 1 参数与文件 / 2 凭据 / 3 网络与超时 / 4 大小与格式 / 5 上游 API 错误
- `check` 默认只要求凭据就绪（exit 0），grok CLI/ffmpeg 为 optional（缺了仅通道 C/convert 不可用，按输出的 `ready`/`unavailable` 调整路由）；完整栈自检用 `check --strict`
- allowed-tools 已预批 mjs/ffmpeg/grok；若仍弹权限请向用户反馈，勿自行放宽规则

## 路由决策

- jpg/jpeg/png ≤20MiB → `image`；mp4 ≤50MB → `video`
- gif/webm → `convert` 转 mp4（视频）或 jpg（动图抽帧）→ 对应通道；仅格式转换，零缩放零裁剪
- 图片 >20MiB → 先报告用户 → 默认尝试通道 C（grok CLI 本地读图，无 20MiB 限制）→ 或经用户同意 `convert` 压缩后走 `image`
- 公网图片 URL → `image --file` 直接收 URL；公网视频 URL → 先下载为本地 mp4 再走 `video`（脚本不内置下载）
- PDF 不支持，不触发
- 收到 401 / 退出码 2 → 请用户检查 `GROK_API_KEY` 或先跑 `grok -p 'hi'` 刷新登录态 → 重试；仍 401 才降级通道 C（C 读同一份凭据，先刷新是必要前置）
- `image` 失败（网络/403/超限/格式）→ 降级通道 C；`video` 失败无降级，错误原样转达

## 意图组织

- **意图结构保留**：用户原话逐字传给 grok，不分类、不转译；澄清只补缺口，不改写意图
- **澄清协议**（最多两轮，用环境的提问机制澄清，一次一问、选项带推荐）：
  - 第一轮：请求含模糊评价词（"好不好看"）或验证类请求未给目标值/参考图时，问关注维度（整体观感 / 视觉细节 / 动效与节奏 / 风格一致性）
  - 第二轮：仍存在多种合理输出形式时，问形式（一句话结论 / 逐项清单 / 对照表）
  - 两轮后用户未改选 → 用默认方案立即执行，绝不追加；事实类信息（文件存在/大小/格式）一律脚本自查，不占用提问
- 锚点类验证（颜色/尺寸/对齐）：用户给目标值与关注点 → 原样传 grok 逐项核对
- 无锚点评价（风格/氛围）：给背景与关注点即可，评价完全交给 grok；用户要求客观/挑刺时 prompt 末尾加"优先指出问题与改进点"
- 动效/时间线类问题按阶段描述关注点（`t=0s 黑场 → t=1s 标题浮现 → t=2.5s 完成态`）；非时序类问题（内容/台词/人物识别）不必套时间线格式
- OCR/文字提取：直接要求 grok 提取并标注位置；参考图对照：图并列传入，prompt 说明谁是谁（如"图1 设计稿，图2 实现截图"）
- `video` 分析后服务端文件即删，追问同一视频需重新上传（`--keep` 除外）
- 需要中文回答时在 prompt 末尾加"用中文回答"

## 凭据与隐私

- 凭据三级链，只由脚本内部读取，模型不接触 token 字符串；禁止打印凭据、Authorization 头、请求体：
  1. 环境变量 `GROK_API_KEY`（xAI 控制台长期 API key，推荐）→ 最高优先级
  2. `~/.grok/auth.json`（grok CLI 登录态，`GROK_HOME` 可覆盖；精确匹配 `https://auth.x.ai::` 前缀；expires_at 预留 60s）
  3. 都没有 → 脚本报错并引导两种方式，不假设已装 grok-build
- 本地图片/视频会上传 x.ai 服务端，仅走用户自己的账号与凭据

## 通道 C：grok CLI 降级（仅图片）

```bash
grok -p --prompt-file <prompt.txt> --yolo
```

- 仅当 `image` 子命令失败或图片 >20MiB 时使用；grok 报错（超限、解码失败、权限）→ 错误原样转达，不自己猜原因
- prompt 一律写临时文件走 `--prompt-file`（不进 argv，防进程列表暴露）；需要程序化取字段时加 `--output-format json`
- 不加 `--max-turns` 等护栏参数：grok 自己决定跑多少回合；`--yolo` 免确认执行工具，不加会被权限询问卡住

## 跨 harness 说明

本技能遵循 Agent Skills 开放标准（agentskills.io），Claude Code 与 Codex 均可使用：

- SKILL.md frontmatter 的 `paths`/`allowed-tools`/`argument-hint` 是 Claude Code 扩展字段，其他环境忽略不报错（只认 `name`/`description`）
- 隐式调用开关对照：Claude Code `disable-model-invocation: true` ⇄ Codex `agents/openai.yaml` 的 `policy.allow_implicit_invocation: false`（本技能用 `paths` 限定激活范围，未设此开关）
- 提问机制对照：Claude Code `AskUserQuestion` ⇄ Codex `request_user_input`（契约差异：Codex 需 id 字段、1~5 问、无 multiSelect、Other 需显式）
- 脚本本身零依赖纯 Node，任意环境可直接 `node scripts/grok-vision.mjs ...` 运行

## Gotchas

- Windows 下 PowerShell `-Form` 上传视频服务端见 0 字节（历史坑，已由脚本 FormData+Blob 消除）
- Windows 重定向 stdout 是 GBK 非 UTF-8（脚本 Node 原生 UTF-8 输出，已根除）
- grok CLI `--yolo` 官方别名 `--always-approve`；`-p` 长形式是 `--single`
- Files API 官方上限 50MB（48MB 是第三方误报）；上传带 `expires_after=3600` TTL 兜底，删除失败也不留服务端垃圾

## 不变量

- 不替 grok 做任何预测性限制（分析深度、处理方式都由它决定）
- grok 报错原样转达，不自己猜原因
- 通道 C 是降级不是主路
- 凭据每次现取，不缓存、不打印