图像 OCR — 本地 AI PC（Windows · GLM-OCR · llama.cpp Vulkan）

模型: ggml-org/GLM-OCR-GGUF (Q8_0, HuggingFace / hf-mirror)

推理引擎: llama-server (llama.cpp Vulkan 预编译版本，HTTP API)

SKILL_VERSION: 1.0.0

目录结构（自动创建或用户指定）

<OCR_DIR>\                        ← 自动选择的磁盘或用户指定路径（例如 C:\image-ocr 或 D:\image-ocr）
├── llama.cpp\                    ← llama-server.exe 及相关二进制文件
└── models\
    └── GLM-OCR-GGUF\
        ├── GLM-OCR-Q8_0.gguf        ← 主模型 (~950 MB)
        └── mmproj-GLM-OCR-Q8_0.gguf ← 视觉投影层 (~484 MB，必需)

Python 辅助脚本（位于此 SKILL.md 旁边）：

⚠️ 安装前注意事项 — 安全与合规说明

此技能将在您的系统上执行以下操作。请在授予自主执行权限前仔细审查。

操作	来源	风险等级
下载并解压 llama-server.exe 及相关二进制文件	github.com/ggml-org/llama.cpp 发布页	中等 — 执行下载的二进制文件
下载模型文件（总计约 1.5 GB）	HuggingFace（huggingface.co）或 ModelScope（modelscope.cn）	低 — 大文件下载
自动安装 Miniforge（若未检测到 Python）	github.com/conda-forge/miniforge	中等 — 静默安装 Python 至 %USERPROFILE%\miniforge3
创建目录并在磁盘上写入文件	仅限本地文件系统	低

凭证信息：GLM-OCR 模型（ggml-org/GLM-OCR-GGUF）为公开可获取，无需身份验证。若您使用私有或受保护的 HuggingFace 模型，可能需要在运行下载命令前设置 $env:HUGGINGFACE_TOKEN —— 此技能不会自动请求或存储任何令牌。

信任来源：请在继续前确认信任以下地址：

• https://github.com/ggml-org/llama.cpp/releases
• https://huggingface.co/ggml-org/GLM-OCR-GGUF
• https://github.com/conda-forge/miniforge（仅当触发 Miniforge 自动安装时）

若您更倾向于手动控制每一步而非授予自主执行权限，请逐行运行 SKILL.md 中的 PowerShell 命令。

依赖项：模型文件通过 Python 的 huggingface_hub（hf download）或 modelscope 下载。若未安装 Python，第 2 步将自动安装 Miniforge（无需管理员权限）。

⚠️ AI 助手操作指引

1. 一次只执行一条命令；等待输出完成后再继续下一步。
2. 出现错误时立即停止；参考文末的故障排查表。
3. 所有路径请用双引号包裹。
4. <OCR_DIR> 是经过预检后确定的绝对工作目录路径。
5. 唯一目标：识别图像内容并返回文本结果。

执行流程（不可跳过步骤）：

预检：检查工作目录 + llama.cpp + 模型文件            → 状态值
步骤 1：检查 Python（PYTHON_OK/MISSING）                  → PYTHON_OK
       安装 / 更新 llama.cpp（仅当缺失时）                → LLAMA_OK
步骤 2：下载模型（仅当缺失时）                            → MODEL_OK
步骤 3：通过 Python 调用 llama-server.exe HTTP API 运行推理 → 返回结果

进度提示：每个步骤开始前会进行公告，例如：🔍 预检：正在检查环境…

⚠️ 在 Windows 上使用 Bash.exe（Git Bash / WSL）

如果 AI 助手使用的终端是 bash.exe（而非 PowerShell 或 CMD），通过 $env:OCR_DIR（PowerShell）或 set OCR_DIR=（CMD）设置的环境变量将无法被从 bash 启动的 Python 脚本识别。这是导致“找不到 llama.cpp / 模型”错误的最常见原因。

当前解决方案

所有脚本均使用 _ocr_cfg.py，该文件按以下顺序解析 OCR_DIR：

1. 环境变量 OCR_DIR —— 仅在 bash 中正确 export 后生效
2. **.ocr_dir 配置文件** —— 由 preflight_workdir.py 自动创建于脚本所在目录

**只要 preflight_workdir.py 曾经运行过一次（无论从哪个 shell），后续所有脚本都将自动找到 OCR 目录**，无需手动设置环境变量。

若使用 bash.exe，请确保：

# 切换至脚本所在目录 —— 此操作会生成 .ocr_dir 配置文件
cd /path/to/local-image-ocr-aipc
python preflight_workdir.py       # 写入 .ocr_dir，其余脚本将自动使用
python preflight_llama.py         # 无需手动设置 OCR_DIR 即可正常运行
python ocr_run.py "C:\path\to\image.png"

总结

注意：若在 WSL 中运行，subprocess.Popen 不支持 creationflags。脚本已自动处理（当 sys.platform != "win32" 时，_CREATE_NO_WINDOW 设为 0）。

See [preflight_workdir.py](preflight_workdir.py)。

运行命令：python preflight_workdir.py

成功条件：输出中包含一行 OCR_DIR=。该操作还会生成一个 .ocr_dir 配置文件，使后续脚本可自动定位目录（无需设置环境变量）。请记录路径，并在后续步骤中将 <OCR_DIR> 替换为实际路径。

检查 llama.cpp

See [preflight_llama.py](preflight_llama.py)。

运行命令：python preflight_llama.py

检查模型文件

See [preflight_models.py](preflight_models.py)。

运行命令：python preflight_models.py

提示：✅ 环境检查完成。请按需执行相应步骤。

第 1 步：检查 Python 并安装/更新 llama.cpp Vulkan

🐍 第 1a 步：检查 Python 是否可用…

检查 Python

注意：此步骤需要已存在的 Python 环境来运行脚本。请使用以下代码片段查找 Python 路径，记录为 PYTHON_EXE，并在后续所有步骤中使用该 Python。

选项 A — PowerShell（Windows 默认）

# 最小化 PowerShell 脚本用于定位 Python；后续所有步骤均通过 Python 执行
$customPythonExe = ""  # 可选：手动指定路径，例如 "C:\Python311\python.exe"
$found = $null
if ($customPythonExe -and (Test-Path $customPythonExe)) { $found = $customPythonExe }
if (-not $found) {
    foreach ($cmd in @("python","python3","py")) {
        if (Get-Command $cmd -ErrorAction SilentlyContinue) { $found = (Get-Command $cmd).Source; break }
    }
}
if (-not $found) {
    foreach ($p in @(
        "$env:USERPROFILE\miniforge3\python.exe","$env:USERPROFILE\miniconda3\python.exe",
        "$env:USERPROFILE\anaconda3\python.exe")) {
        if (Test-Path $p) { $found = $p; break }
    }
}
if ($found) { $env:PYTHON_EXE = $found; Write-Host "PYTHON_STATUS=OK"; Write-Host "PYTHON_EXE=$found" }
else { Write-Host "PYTHON_STATUS=MISSING" }

选项 B — Bash / Git Bash / WSL（当 PowerShell 不可用时的备用方案）

# 通过 bash 查找 Python；设置 PYTHON_EXE 供后续步骤使用
CUSTOM_PYTHON_EXE=""  # 可选：例如 "/c/Python311/python.exe"

found=""
if [ -n "$CUSTOM_PYTHON_EXE" ] && [ -x "$CUSTOM_PYTHON_EXE" ]; then
    found="$CUSTOM_PYTHON_EXE"
fi
if [ -z "$found" ]; then
    for cmd in python python3 py; do
        if command -v "$cmd" >/dev/null 2>&1; then
            found=$(command -v "$cmd")
            break
        fi
    done
fi
if [ -z "$found" ]; then
    for p in \
        "$USERPROFILE/miniforge3/python.exe" \
        "$USERPROFILE/miniconda3/python.exe" \
        "$USERPROFILE/anaconda3/python.exe" \
        "$HOME/miniforge3/bin/python" \
        "$HOME/miniconda3/bin/python" \
        "$HOME/anaconda3/bin/python"; do
        if [ -x "$p" ]; then found="$p"; break; fi
    done
fi
if [ -n "$found" ]; then
    export PYTHON_EXE="$found"
    echo "PYTHON_STATUS=OK"
    echo "PYTHON_EXE=$found"
else
    echo "PYTHON_STATUS=MISSING"
fi

**如果未找到 Python（PYTHON_STATUS=MISSING）**，请安装 Miniforge：

需用户确认：Miniforge 将静默安装至 %USERPROFILE%\miniforge3。

安装内容包括 Python 运行时及 conda/pip 工具链。无需管理员权限。

来源：github.com/conda-forge/miniforge。请在继续前获得用户确认。

选项 A — PowerShell

# 使用 PowerShell 下载并静默安装 Miniforge（无法通过 Python 启动——此处必须使用 PowerShell）
$mf = "$env:TEMP\Miniforge3-Windows-x86_64.exe"
Invoke-WebRequest -Uri "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe" -OutFile $mf
Start-Process $mf -ArgumentList "/S /D=$env:USERPROFILE\miniforge3" -Wait
Remove-Item $mf
$env:PYTHON_EXE = "$env:USERPROFILE\miniforge3\python.exe"
& $env:PYTHON_EXE --version
Write-Host "PYTHON_STATUS=OK"

选项 B — Bash / Git Bash / WSL（当 PowerShell 不可用时的备用方案）

# 使用 curl + bash 下载并静默安装 Miniforge
MF_URL="https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
# 在 Windows/Git Bash 中请使用 Windows 安装包：
# MF_URL="https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe"

MF_INSTALLER="/tmp/Miniforge3-install.sh"
curl -fsSL "$MF_URL" -o "$MF_INSTALLER"
bash "$MF_INSTALLER" -b -p "$HOME/miniforge3"
rm -f "$MF_INSTALLER"
export PYTHON_EXE="$HOME/miniforge3/bin/python"
"$PYTHON_EXE" --version
echo "PYTHON_STATUS=OK"

提示：✅ Python 已准备就绪。正在检查 llama.cpp…

⬇️ 第 1b 步：安装/更新 llama.cpp Vulkan…（仅当 LLAMA_STATUS=MISSING/OUTDATED 时执行）

需用户确认：在继续前，请告知用户：

• 将从 github.com/ggml-org/llama.cpp/releases 下载一个 ZIP 包（约 50–100 MB）
• 解压至 <OCR_DIR>\llama.cpp\ 目录，原 ZIP 文件将被删除
• llama-server.exe 将被保存到磁盘，并由 ocr_run.py 启动为本地 HTTP 服务

请在运行下载命令前向用户确认。

查看 [install_llama.py](install_llama.py)。若存在新版本，请修改顶部的 TAG 变量。

运行命令：python install_llama.py

提示：✅ llama.cpp 已安装。继续执行第 2 步以下载模型。

第 2 步：下载 GLM-OCR 模型

📦 第二步：下载 GLM-OCR 模型…（仅当 MODEL_STATUS=MISSING 时执行）

注意：模型通过 Python 的 hf download（huggingface_hub）或 modelscope 下载。

请确保 Python 已正确安装（第1步中 PYTHON_STATUS=OK）。将使用 $env:PYTHON_EXE 执行。

首次下载提示（当 MODEL_STATUS=MISSING 时必读）

向用户展示以下信息，然后询问是否继续：

📥 首次模型下载约 1.5 GB
   （GLM-OCR-Q8_0.gguf ~950 MB + mmproj ~484 MB）。
   预估下载时间：
   • 100 Mbps 网络：约 2 分钟
   •  50 Mbps 网络：约 4 分钟
   •  10 Mbps 网络：约 20 分钟

   下载支持断点续传 —— 若中断，重新运行此步骤将自动从断点处继续。

   ✅ 准备就绪 —— 开始自动下载
   📂 我希望手动下载 —— 跳过自动下载

• 用户选择 自动下载 → 继续执行下方的下载命令
• 用户选择 手动下载 → 跳转至本步骤末尾的“手动下载备用方案”部分

检查磁盘空间

参考 [check_disk.py](check_disk.py)。

执行命令：python check_disk.py

下载模型

选项 A：使用 huggingface_hub Python API（推荐）

参考 [download_models_hf.py](download_models_hf.py)。若需使用中国镜像，请取消注释文件中的 HF_ENDPOINT 行。

执行命令：python download_models_hf.py

选项 B：使用 ModelScope（适用于中国用户）

参考 [download_models_modelscope.py](download_models_modelscope.py)。

执行命令：python download_models_modelscope.py

验证下载结果

参考 [verify_models.py](verify_models.py)。

执行命令：python verify_models.py

提示信息：✅ 模型下载完成。

手动下载备用方案

若自动下载多次失败，请引导用户手动下载并放置到正确目录：

⚠️ 自动下载失败。请手动下载以下两个文件：

1. GLM-OCR-Q8_0.gguf (~950 MB)
   HuggingFace: https://huggingface.co/ggml-org/GLM-OCR-GGUF/resolve/main/GLM-OCR-Q8_0.gguf
   HF镜像站:   https://hf-mirror.com/ggml-org/GLM-OCR-GGUF/resolve/main/GLM-OCR-Q8_0.gguf
   ModelScope:  https://modelscope.cn/models/ggml-org/GLM-OCR-GGUF/resolve/master/GLM-OCR-Q8_0.gguf

2. mmproj-GLM-OCR-Q8_0.gguf (~484 MB)
   HuggingFace: https://huggingface.co/ggml-org/GLM-OCR-GGUF/resolve/main/mmproj-GLM-OCR-Q8_0.gguf
   HF镜像站:   https://hf-mirror.com/ggml-org/GLM-OCR-GGUF/resolve/main/mmproj-GLM-OCR-Q8_0.gguf
   ModelScope:  https://modelscope.cn/models/ggml-org/GLM-OCR-GGUF/resolve/master/mmproj-GLM-OCR-Q8_0.gguf

下载完成后，请将两个文件放入以下目录：
   <OCR_DIR>\models\GLM-OCR-GGUF\

然后重新运行验证命令，确认文件完整无误后，再进入第三步。

第三步：处理识别结果

🔍 第三步：处理 GLM-OCR 识别结果…

确定输入来源

情况 A：用户提供了本地文件路径

步骤 1 — 设置图像路径：打开 [ocr_run.py](ocr_run.py)，将 IMG_PATH 设置为从用户消息中提取的文件路径。也可通过命令行参数传入路径。

步骤 2 — 运行推理：

python ocr_run.py "<从用户消息中提取的文件路径>"

成功标准：标准输出中包含识别出的文本内容。

情况 B：用户通过界面上传了图片

OpenClaw 将上传的图片保存在临时路径中。请从上下文获取该路径。

步骤 1 — 设置图像路径：打开 [ocr_run.py](ocr_run.py)，将 IMG_PATH 设置为 OpenClaw 提供的临时路径。也可通过命令行参数传入。

步骤 2 — 运行推理：

python ocr_run.py "<OpenClaw 提供的临时图像路径>"

成功标准：标准输出中包含识别出的文本内容。

格式化输出

获取识别文本后，根据用户意图进行处理：

完成提示：

✅ 识别完成！
如需重新处理、更改输出格式或导出为文件，请告知我。

故障排查

参考资料

• llama.cpp 发布页：https://github.com/ggml-org/llama.cpp/releases
• GLM-OCR GGUF 模型：https://huggingface.co/ggml-org/GLM-OCR-GGUF