用途
GLM-OCR 手写体识别技能用于从图片和 PDF 中识别手写文字，底层调用智谱 GLM-OCR 版面解析 API。适用于以下场景：从手写笔记、信件或文档中提取文字；将手写内容转换为可编辑文本；识别手写与印刷混排的内容；读取手写公式、标签或批注。当用户提到“handwriting OCR”“recognize handwriting”“手写识别”“手写体OCR”“识别手写字”等关键词时，可触发该技能。
主要能力
- 多风格支持：可处理多种手写风格，包括连笔和印刷体。
- 多语言支持：支持中文、英文以及中英混排的手写内容。
- 混排内容识别：可识别同时包含手写和印刷文字的文档。
- 输入方式灵活：支持本地文件和远程 URL 两种来源。
- 结果输出：识别文本以 Markdown 格式返回，可保存为 JSON 文件，并可选输出版面分析细节。
使用方式
前置条件：配置 API Key
脚本通过 ZHIPU_API_KEY 环境变量获取密钥，可与其他智谱技能复用同一个 key。获取密钥请访问智谱开放平台 API Keys 页面创建或复制。配置方式任选一种：
- 全局配置（推荐）：在 openclaw.json 的 env.vars 中设置一次，所有智谱技能共享：
{
"env": {
"vars": {
"ZHIPU_API_KEY": "你的密钥"
}
}
}
- 技能级配置：在 openclaw.json 中仅为该技能设置：
{
"skills": {
"entries": {
"glmocr-handwriting": {
"env": {
"ZHIPU_API_KEY": "你的密钥"
}
}
}
}
}
- Shell 环境变量：在 ~/.zshrc 中添加：
export ZHIPU_API_KEY="你的密钥"
如果已为其他智谱技能（如 glmocr、glmv-caption、glm-image-generation）配置过 key，它们共享同一个 ZHIPU_API_KEY，无需重复配置。
命令行调用
从 URL 识别：
python scripts/glm_ocr_cli.py --file-url "https://example.com/handwriting.jpg"
从本地文件识别：
python scripts/glm_ocr_cli.py --file /path/to/notes.png
保存结果到文件：
python scripts/glm_ocr_cli.py --file notes.png --output result.json --pretty
包含原始上游响应（仅调试）：
python scripts/glm_ocr_cli.py --file notes.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：必选其一，图片/PDF 的 URL。
- --file：必选其一，图片/PDF 的本地文件路径。
- --output, -o：可选，将结果 JSON 保存到文件。
- --pretty：可选，美化 JSON 输出。
- --include-raw：可选，在 result 字段中包含原始上游 API 响应（仅调试用）。
响应格式
{
"ok": true,
"text": "Recognized handwritten text in Markdown...",
"layout_details": [...],
"result": null,
"error": null,
"source": "/path/to/file",
"source_type": "file",
"raw_result_included": false
}
关键字段：ok 表示识别是否成功；text 为提取的 Markdown 文本（用于展示）；layout_details 为版面分析细节；error 为失败时的错误详情。
输出展示规则
运行脚本后，应清晰、安全地呈现 OCR 结果：完整展示提取的手写文本（text）；允许摘要，但不得隐藏重要的提取失败信息；若结果文件已保存，告知用户文件路径；仅在明确要求或调试时（--include-raw）展示原始上游响应。
安全与透明度
- 使用的环境变量：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 失败，显示错误信息并立即停止。
- 无回退方法，不得以任何其他方式尝试手写识别。
错误处理
- API key 未配置：提示“ZHIPU_API_KEY not configured. Get your API key at: https://bigmodel.cn/usercenter/proj-mgmt/apikeys”，向用户展示确切错误并引导配置。
- 认证失败（401/403）：API key 无效或过期，需重新配置。
- 速率限制（429）：配额耗尽，告知用户等待。
- 文件未找到：本地文件缺失，检查路径。