glmocr-formula

GLM-OCR 公式识别技能（glmocr-formula）是智谱 GLM-OCR 的官方技能，用于从图片和 PDF 中识别数学公式并转换为 LaTeX 格式，底层调用智谱 GLM-OCR 版面解析 API。

【用途】该技能适用于从图片或扫描件中提取数学公式、将公式图片转为 LaTeX、识别复杂方程（如积分、求和、矩阵、分数、根式）、解析含公式的论文、教材、试卷等场景。当用户提到“formula OCR”“extract formula”“公式识别”“公式OCR”“提取公式”“图片转LaTeX”等关键词时，可使用该技能。

【主要能力】

复杂公式支持：可处理积分、求和、矩阵、分数、根式等。
LaTeX 输出：公式以 LaTeX 格式输出，可直接用于文档。
行内与独立公式：同时识别行内公式和展示式公式。
混合内容：可处理文字与公式混排的文档。
本地文件与 URL：支持本地文件和远程 URL 两种输入方式。

【使用方式】前置条件：需配置 API Key。脚本通过 ZHIPU_API_KEY 环境变量获取密钥，可与其他智谱技能复用同一个 key。获取 Key 需访问智谱开放平台 API Keys 页面创建或复制。配置方式任选一种：

全局配置（推荐）：在 openclaw.json 的 env.vars 中设置一次，所有智谱技能共享： { "env": { "vars": { "ZHIPU_API_KEY": "你的密钥" } } }
Skill 级别配置：在 openclaw.json 中仅为该技能设置： { "skills": { "entries": { "glmocr-formula": { "env": { "ZHIPU_API_KEY": "你的密钥" } } } } }
Shell 环境变量：在 ~/.zshrc 中添加： export ZHIPU_API_KEY="你的密钥"

命令行用法： python {baseDir}/scripts/glm_ocr_cli.py (--file-url URL | --file PATH) [--output FILE] [--pretty] [--include-raw]

参数说明：

--file-url：必选其一，图片/PDF 的 URL。
--file：必选其一，本地图片/PDF 文件路径。
--output, -o：可选，将结果 JSON 保存到文件。
--pretty：可选，美化 JSON 输出。
--include-raw：可选，在结果字段中包含原始上游 API 响应（仅调试用）。

示例：从 URL 提取：python scripts/glm_ocr_cli.py --file-url "https://example.com/formula.png" 从本地文件提取：python scripts/glm_ocr_cli.py --file /path/to/equation.png 保存结果到文件：python scripts/glm_ocr_cli.py --file formula.png --output result.json --pretty 包含原始上游响应（仅调试）：python scripts/glm_ocr_cli.py --file formula.png --output result.json --include-raw

【响应格式】 { "ok": true, "text": "Extracted formulas and text in Markdown/LaTeX...", "layout_details": [...], "result": null, "error": null, "source": "/path/to/file", "source_type": "file", "raw_result_included": false } 关键字段：ok 表示提取是否成功；text 为含 LaTeX 公式的 Markdown 文本；layout_details 为版面分析细节；error 为失败时的错误详情。

【安全与透明度】使用的环境变量：ZHIPU_API_KEY（必需）、GLM_OCR_TIMEOUT（可选超时秒数）。固定官方端点：https://open.bigmodel.cn/api/paas/v4/layout_parsing。不支持自定义 API URL 覆盖，以避免通过重定向端点意外泄露密钥。原始上游响应默认不返回，仅在需要调试时使用 --include-raw。

【限制与强制规则】

仅使用 GLM-OCR API，执行脚本 python scripts/glm_ocr_cli.py。
不得自行解析公式，不得使用内置视觉或其他方法提取公式。
不得提供替代方案，不得建议“我可以尝试读取”等。
若 API 失败，立即显示错误信息并停止。
无回退方法，不得以任何其他方式尝试公式提取。

【输出展示规则】运行脚本后，清晰安全地呈现 OCR 结果：完整显示提取的文本/公式；允许摘要，但不得隐藏重要的提取失败；若 layout_details 包含公式相关条目，可高亮显示；若结果文件已保存，告知用户文件路径；仅在明确要求或调试时（--include-raw）显示原始上游响应。

【LaTeX 渲染注意】 OCR API 返回 LaTeX 格式公式（如 $\frac{1}{2}$、$\theta^{x+1}$）。由于多数聊天平台不渲染 LaTeX，首次使用时应询问用户一次：“OCR 结果包含 LaTeX 公式，需要我将公式转为 Unicode 可读格式展示，还是保留原始 LaTeX？”并在本次会话中记住用户选择，后续调用不再重复询问，除非用户明确更改偏好。若用户选择可读格式，可将 LaTeX 转为 Unicode/纯文本，例如 $\frac{a}{b}$ 转为 a/b、$x^{n}$ 转为 x^n、$x_{i}$ 转为 xᵢ、$\sqrt{x}$ 转为 √x、$\theta$ 转为 θ、$\phi$ 转为 φ、$\therefore$ 转为 ∴、$\Rightarrow$ 转为 ⇒、$\in$ 转为 ∈、$\infty$ 转为 ∞、$\ln$ 转为 ln、$\leq$/$\geq$ 转为 ≤/≥ 等。若用户选择原始 LaTeX，则直接显示原始 LaTeX 输出，并提醒若使用了 --output，原始数据也已保存在输出文件中。

【错误处理】

API key 未配置：提示“ZHIPU_API_KEY not configured. Get your API key at: https://bigmodel.cn/usercenter/proj-mgmt/apikeys”，向用户显示确切错误并引导配置。
认证失败（401/403）：API key 无效/过期，需重新配置。
速率限制（429）：配额耗尽，告知用户等待。
文件未找到：本地文件缺失，检查路径。

技能介绍