图像 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，必需）

与本文档（SKILL.md）位于同一目录的 Python 辅助脚本：

⚠️ 安装前须知——安全与合规声明

本技能将在您的系统上执行以下操作。在允许自动执行前请仔细审查。

操作	来源	风险等级
下载并解压 llama-server.exe 及相关二进制文件	github.com/ggml-org/llama.cpp 发布版本	中等 —— 执行下载的二进制文件
下载模型文件（总计约 1.5 GB）	HuggingFace（huggingface.co）或 ModelScope（modelscope.cn）	低 —— 大文件下载
如果未找到 Python，自动安装 Miniforge	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 + 模型            → STATUS 值
步骤 1：检查 Python（PYTHON_OK/MISSING）           → PYTHON_OK
         安装/更新 llama.cpp（仅在 MISSING 时）     → LLAMA_OK
步骤 2：下载模型（仅在 MISSING 时）                → 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 目录**，无论使用哪个 shell。无需手动设置环境变量。

如果使用 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）。

预检：检查环境

🔍 预检：正在检查工作目录、llama.cpp 和模型文件…

定位工作目录

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

使用命令运行：python preflight_workdir.py

成功标准：输出中包含一行 OCR_DIR=。该脚本还会写入 .ocr_dir 配置文件，以便后续所有脚本能自动找到该目录（无需环境变量）。记录路径，并在后续步骤中替换 <OCR_DIR>。

检查 llama.cpp

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

使用命令运行：python preflight_llama.py

检查模型文件

见 [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 模型

📦 步骤 2：下载 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 镜像（中国），请取消文件内 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\

然后重新运行验证命令以确认文件完整，之后再继续步骤 3。

步骤 3：处理识别结果

🔍 步骤 3：处理 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