glmocr-formula

用途

glmocr-formula 是智谱 GLM 系列技能之一，专门用于从图像和 PDF 中识别数学公式，并输出 LaTeX 格式。它通过调用智谱 GLM-OCR 版面解析 API（layout parsing）完成识别，适合需要把公式图片或扫描文档转成可编辑 LaTeX 代码的场景。

主要能力

复杂公式支持：可处理积分、求和、矩阵、分式、根式等复杂数学表达式。
LaTeX 输出：公式以 LaTeX 格式返回，可直接用于文档写作。
行内与独立公式：同时识别行内公式和展示样式公式。
混排内容：可处理同时包含文字与公式的文档。
输入来源：支持本地文件与远程 URL。
版面解析：响应中包含 layout_details 版面分析信息。

使用方式

前置条件：配置 API Key

脚本从环境变量 ZHIPU_API_KEY 读取密钥，可与其它智谱技能复用同一个 key。可在智谱开放平台 API Keys 页面创建或复制密钥。配置方式任选一种：

全局配置（推荐）：在 openclaw.json 的 env.vars 中设置一次，所有智谱技能共享：

{
  "env": {
    "vars": {
      "ZHIPU_API_KEY": "你的密钥"
    }
  }
}

Skill 级别配置：仅对本技能设置：

{
  "skills": {
    "entries": {
      "glmocr-formula": {
        "env": {
          "ZHIPU_API_KEY": "你的密钥"
        }
      }
    }
  }
}

Shell 环境变量：在 ~/.zshrc 中添加：

export ZHIPU_API_KEY="你的密钥"

如果已为其他智谱 skill（如 glmocr、glmv-caption、glm-image-generation）配置过 key，它们共享同一个 ZHIPU_API_KEY，无需重复配置。

命令行调用

从 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

CLI 参数

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

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

响应格式

{
  "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 为失败时的错误信息。

适用场景

从图片或扫描件中提取数学公式
将公式图片转为 LaTeX 格式
识别复杂方程、积分、矩阵
解析含公式的科研论文、教材、试卷
用户提到「公式 OCR」「提取公式」「公式识别」「图片转 LaTeX」等关键词时

限制与安全约束

必须使用 GLM-OCR API，即执行 python scripts/glm_ocr_cli.py。
禁止自行解析公式，不得用内置视觉或其他方法提取公式。
不得提供替代方案（例如「我可以试着读一下」）。
API 失败时直接显示错误并停止，不采用任何回退方法。
使用的环境变量：ZHIPU_API_KEY（必需）、GLM_OCR_TIMEOUT（可选超时秒数）。
固定官方端点 https://open.bigmodel.cn/api/paas/v4/layout_parsing，不支持自定义 API URL 覆盖，以避免密钥被重定向端点泄露。
原始上游响应默认不返回，仅在需要调试时使用 --include-raw。

输出展示与 LaTeX 渲染

完整显示提取出的文本/公式（text）。
允许摘要，但不得隐藏重要的提取失败信息。
若 layout_details 包含公式相关条目，可高亮显示。
若结果文件已保存，告知用户文件路径。
仅在明确要求或调试时显示原始上游响应（--include-raw）。
OCR API 返回 LaTeX 格式公式（如 $\frac{1}{2}$、$\theta^{x+1}$）。由于多数聊天平台不渲染 LaTeX，首次使用时应询问用户：需要将公式转为 Unicode 可读格式，还是保留原始 LaTeX？并记住该选择，后续调用不再重复询问，除非用户明确更改偏好。

用户选择可读格式时，将 LaTeX 转为 Unicode/纯文本，例如：

$\frac{a}{b}$ → a/b
$x^{n}$ → x^n
$x_{i}$ → xᵢ
$\sqrt{x}$ → √x
$\theta$ → θ
$\phi$ → φ
$\therefore$ → ∴
$\Rightarrow$ → ⇒
$\left{ \begin{array}{l} ... \end{array} \right.$ → ⎧ line1 ⎨ line2 ⎩
$\textcircled{1}$ → ①
$\in$ → ∈
$\infty$ → ∞
$\ln$ → ln
$\leq$ / $\geq$ → ≤ / ≥

用户选择保留原始 LaTeX 时，直接展示原始输出，并提醒如使用了 --output，原始数据同样保存在输出文件中。

错误处理

API key 未配置：提示 ZHIPU_API_KEY not configured，引导至 https://bigmodel.cn/usercenter/proj-mgmt/apikeys 配置。
认证失败（401/403）：API key 无效或过期，需重新配置。
限流（429）：配额耗尽，提示用户等待。
文件未找到：本地文件缺失，需检查路径。