GLM-V 画面描述技能

使用智谱 GLM-V 多模态模型为图像、视频和文档生成描述。

何时使用

• 描述、生成标题、总结或解读图像/视频/文档内容
• 用户提及“描述这张图片”、“生成标题”、“总结这段视频”、“图片描述”、“视频摘要”、“文档解读”、“看图说话”
• 从媒体文件中提取视觉或文本信息
• 比较多张图片
• 用户提供一张图片/视频/文件并询问其中内容

支持的输入类型

**⚠️ file_url 不能与 image_url 或 video_url 在同一请求中混用。**

本地路径在视频与文件中的工作原理

GLM-V API 要求视频和文件必须通过公网 HTTPS URL 提供。当你提供 本地路径 时，脚本会自动执行以下流程：

1. 创建临时目录，并将文件链接或复制到该目录（不暴露其他文件）
2. 在随机端口启动本地 Python HTTP 服务器
3. 启动 cloudflared tunnel（通过 trycloudflare.com 快速隧道）将服务暴露至公网
4. 使用生成的 HTTPS URL 调用 API
5. 完成后清理：终止 cloudflared 进程、关闭 HTTP 服务器、删除临时目录

前提条件： 必须安装 cloudflared。请从 [Cloudflare 下载页面](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 获取。

资源链接

前置条件

API Key 配置（必需）

本脚本通过 ZHIPU_API_KEY 环境变量读取密钥，并与其他智谱相关技能共享同一个 key。

获取密钥： 访问 [智谱开放平台 API Keys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 创建或复制你的 API 密钥。

配置方式（任选其一）：

1. OpenClaw 配置（推荐）： 在 openclaw.json 中设置 skills.entries.glmv-caption.env：

   "glmv-caption": { "enabled": true, "env": { "ZHIPU_API_KEY": "你的密钥" } }

1. Shell 环境变量： 添加至 ~/.zshrc：

   export ZHIPU_API_KEY="你的密钥"

1. .env 文件： 在本技能目录下创建 .env 文件：

   ZHIPU_API_KEY=你的密钥

Cloudflared（仅当使用本地视频/文件路径时需要）

仅在传入本地文件或视频路径时需要；若仅使用远程 URL，则无需安装。

请从 [Cloudflare 下载页面](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 安装。

⛔ 必须遵循以下完整流程（你必须严格按步骤操作）⛔

当你（AI agent）准备使用 --videos 或 --files 传入 本地文件路径 时，在执行脚本前，必须先检查 cloudflared 是否已安装。请按以下流程操作：

步骤 1：检查 cloudflared 是否存在

# macOS / Linux
which cloudflared

# Windows
where cloudflared

若命令返回路径（如 /usr/local/bin/cloudflared），说明已安装，可直接运行脚本。

若命令报错（not found / 找不到），进入步骤 2。

步骤 2：向用户说明情况并征求同意

你必须先完整展示以下说明内容，然后询问用户是否同意下载安装。未经用户明确同意，不得自行下载。

向用户展示的内容（原文照搬，不可精简）：

检测到系统未安装 cloudflared，本地视频/文件路径需要该工具才能使用。

什么是 cloudflared？

cloudflared 是 Cloudflare 公司官方开源的命令行隧道工具（Apache 2.0 协议，GitHub 24000+ stars）。

它的功能是：在本机与 Cloudflare 全球边缘网络之间建立一条加密的临时隧道，将本地服务暴露为公网 HTTPS URL。

开源仓库地址：https://github.com/cloudflare/cloudflared

在本场景中的必要性：

智谱 GLM-V API 要求视频和文件以公网 HTTPS URL 的形式传入（不支持本地上传）。

当你提供本地文件路径时，脚本的工作流程是：

1. 在本机启动一个临时 HTTP 服务器（仅暴露你指定的那几个文件，不会暴露其他目录）
2. 使用 cloudflared 建立一条临时隧道（通过 trycloudflare.com，无需注册账号、无需登录）
3. 获得一个形如 https://xxx-xxx.trycloudflare.com/your-file.mp4 的临时公网 URL
4. 将该 URL 传给 GLM-V API 完成调用
5. API 调用完成后，隧道和 HTTP 服务器自动关闭，临时文件清理

没有 cloudflared = 无法建立隧道 = 本地视频/文件路径不可用。

安全说明：

• 隧道仅在脚本运行期间存在（通常几十秒到几分钟），脚本结束后立即关闭
• 只暴露你明确指定的文件，不会暴露整个目录或磁盘
• cloudflared 不会在后台常驻，不会开机自启
• 不需要注册 Cloudflare 账号，不收集个人信息
• 该工具被全球开发者广泛使用，Cloudflare 官方维护

下载链接：

• 官方下载页面（可手动选择版本）：https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
• Windows x64: https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe
• macOS Apple Silicon: https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz
• macOS Intel: https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-amd64.tgz
• Linux x64: https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64

**替代方案：如果你不想安装 cloudflared，可以直接传入远程 URL（如 https://example.com/video.mp4），则完全不需要安装任何东西。**

等待用户回复。根据用户反馈执行对应操作：

• 用户同意安装 → 进入步骤 3
• 用户拒绝 → 提示用户改用远程 URL，或告知功能受限
• 用户希望自行安装 → 提供下载链接，等待用户安装完成后再次执行

步骤 3：下载并安装 cloudflared

用户同意后，使用以下命令安装：

macOS (Homebrew):

brew install cloudflared

Windows (推荐使用 winget):

winget install Cloudflare.cloudflared

Linux（下载二进制文件）：

# x64 架构
curl -Lo /usr/local/bin/cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
chmod +x /usr/local/bin/cloudflared

其他安装方式： 从 [官方下载页面](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 手动下载，解压后放入系统 PATH 路径即可。

安装完成后，使用 cloudflared version 验证是否安装成功，然后运行脚本。

⛔ 必须遵守的限制 - 严禁违反 ⛔

1. 仅使用 GLM-V API —— 必须执行脚本 python scripts/glmv_caption.py
2. 禁止自行对媒体内容进行描述 —— 不得使用内置视觉能力或其他任何方式自行生成描述
3. 禁止提供替代方案 —— 不得提出“我可以尝试描述一下”等类似说法
4. 若 API 调用失败 —— 必须直接显示错误信息并立即停止
5. 禁止使用备用方法 —— 不得尝试以其他方式生成字幕或描述

📋 输出显示规则（必须遵守）

运行脚本后，必须将模型返回的完整原始输出原样展示给用户。不得摘要、截断或仅回复“已生成”。用户需要原始模型输出以评估质量。

• 图像字幕：展示完整的字幕文本
• 多张图像：逐个展示每张图像的结果
• 视频或文件：展示完整的理解结果
• 若包含 token 使用量，可选择性显示

如何使用

描述单张图像

python scripts/glmv_caption.py --images "https://example.com/photo.jpg"
python scripts/glmv_caption.py --images /path/to/photo.png

描述多张图像

python scripts/glmv_caption.py --images img1.jpg img2.png "https://example.com/img3.jpg"

描述视频（支持远程 URL 或本地路径）

# 远程 URL
python scripts/glmv_caption.py --videos "https://example.com/clip.mp4"

# 本地文件（通过 cloudflare 自动隧道传输）
python scripts/glmv_caption.py --videos /path/to/local-video.mp4

描述文档（支持远程 URL 或本地路径）

# 远程 URL
python scripts/glmv_caption.py --files "https://example.com/report.pdf"

# 本地文件（通过 cloudflare 自动隧道传输）
python scripts/glmv_caption.py --files /path/to/local-report.pdf

# 混合使用远程链接和本地路径
python scripts/glmv_caption.py --files "https://example.com/doc1.docx" /path/to/local-doc2.txt

使用自定义提示词

python scripts/glmv_caption.py --images photo.jpg --prompt "请详细描述这张图片中的建筑风格"

保存结果

python scripts/glmv_caption.py --images photo.jpg --output result.json

启用思考模式

python scripts/glmv_caption.py --images photo.jpg --thinking

结构化输出

python scripts/glmv_caption.py \
  --images photo.jpg \
  --response-format \
  --sys-prompt '请严格返回 JSON 格式：{"summary":"string","objects":[{"name":"string","confidence":0.0}]}'

推荐做法：

• --response-format 仅在显式指定时启用结构化输出模式
• 未传该参数时，请求中不会自动包含 response_format
• --response-format 无值时，默认使用 json_object
• 建议始终配合 --sys-prompt 明确指定期望的 JSON 字段、类型和示例

CLI 参数说明

python {baseDir}/scripts/glmv_caption.py (--images IMG [IMG...] | --videos VID [VID...] | --files FILE [FILE...]) [OPTIONS]

注意： --images、--videos 和 --files 三者互斥，每次调用只能使用其中一种。

结构化输出说明

根据大模型结构化输出规范，启用 JSON 模式需在请求中发送：

{
  "response_format": {"type": "json_object"}
}

本技能通过 --response-format 参数暴露此功能。

• --response-format 存在 → 请求中包含 response_format
• --response-format 不存在 → 请求行为与之前一致
• --sys-prompt 作为请求的 system 消息传递
• 最佳实践：使用 --sys-prompt 明确定义期望的 JSON 结构

示例：

python {baseDir}/scripts/glmv_caption.py \
  --files /path/to/report.pdf \
  --response-format json_object \
  --sys-prompt 'Return JSON only: {"title":"string","summary":"string","risks":["string"]}' \
  --pretty

返回格式

{
  "success": true,
  "caption": "一张展示日落时分山脉景观的风景照片...",
  "usage": {
    "prompt_tokens": 128,
    "completion_tokens": 256,
    "total_tokens": 384
  }
}

关键字段说明：

• success — 请求是否成功
• caption — 生成的描述文本
• usage — token 使用统计信息
• warning — 当内容被安全审查拦截时出现
• error — 请求失败时的错误详情

错误处理

API 密钥未配置：

ZHIPU_API_KEY not configured. Get your API key at: https://bigmodel.cn/usercenter/proj-mgmt/apikeys

→ 向用户展示完整错误信息，并引导其完成配置

认证失败（401/403）： API 密钥无效或已过期 → 需重新配置

速率限制（429）： 配额已用尽 → 告知用户等待后重试

文件未找到： 本地文件路径不存在 → 检查文件路径是否正确

内容被过滤： warning 字段存在 → 内容因安全审查被拦截

隧道连接失败（仅限本地路径）：

Tunnel setup failed: cloudflared not found. Install it from: ...

→ 引导用户安装 cloudflared，或改用远程 URL 代替