| name | local-minicpm-pet-openvino |
| description | 一键部署 MiniCPM 桌宠体验环境，后端采用 OpenVINO 推理引擎（Deploy MiniCPM Desk Pet with OpenVINO backend）.
使用本 Skill 可部署一个完整的桌宠体验环境，在 Intel AIPC 上本地运行，无需云端服务。
部署完成后，用户直接通过桌宠 UI 界面进行对话交互。
Use this skill when the user wants to deploy/set up/run the MiniCPM desk pet with OpenVINO backend,
or build a local AI pet experience environment on Intel hardware.
Trigger on: 部署桌宠/体验环境/搭建环境/本地推理/OpenVINO后端/桌宠环境/deploy pet/setup environment/run desk pet/
英特尔/intel/AIPC/本地/离线/offline/MiniCPM/OpenVINO/桌宠.
This is a DEPLOYMENT skill — it sets up the environment and launches the pet.
After deployment, the user interacts with the pet directly through its UI (not via this script).
|
Local-MiniCPM-Pet-OpenVINO Skill Guide
使用本 Skill 可一键部署一个完整的 MiniCPM 桌宠体验环境。
后端采用 OpenVINO 推理引擎，前端从源码 npm start 启动。
部署完成后，用户直接与桌宠对话，无需再次调用本脚本。
!! CRITICAL: 环境依赖 !!
以下依赖缺一不可，必须在执行前验证：
| 依赖 | 最低版本 | 验证命令 | 用途 |
|---|
| Windows 10/11 | - | - | 操作系统 |
| Intel AIPC 硬件 | LNL/ARL/PTL/WCL | bin\platform.exe --is-aipc | 本地推理加速 |
| Python | 3.11 | python --version | OpenVINO 推理服务 |
| Node.js | 18+ | node --version | 桌宠前端 |
| npm | - | npm --version | 桌宠依赖安装 |
| git | - | git --version | 获取桌宠源码 |
!! CRITICAL: 中国大陆网络环境 !!
所有网络操作必须使用国内源，否则极慢或不可用：
| 操作 | 国内源 | 说明 |
|---|
| git clone | GitCode 镜像 | gitcode.com/OpenBMB/MiniCPM-Desk-Pet.git |
| pip 安装 | 清华镜像 | mirrors.tuna.tsinghua.edu.cn |
| npm 安装 | 淘宝镜像 | registry.npmmirror.com |
| Electron 下载 | npmmirror | npmmirror.com/mirrors/electron/ |
| 模型下载 | ModelScope | 默认国内直连 |
| HuggingFace | hf-mirror | hf-mirror.com |
--china 参数已内置上述所有配置，无需手动设置。
!! CRITICAL: 沙箱外运行要求 !!
以下目录必须持久化（沙箱外），否则每次重试将重新下载 ~2.4GB：
| 目录 | 大小 | 内容 |
|---|
%USERPROFILE%\.openvino\venv\ | ~500MB | Python 虚拟环境 |
%USERPROFILE%\.openvino\models\ | ~1.5GB | AI 模型文件 |
%LOCALAPPDATA%\electron\Cache\ | ~180MB | Electron 二进制缓存 |
桌宠源码 node_modules\ | ~200MB | npm 依赖 |
严格执行流程（必须按顺序，不可跳过）
Step 0: 判断用户网络环境（Agent 必须在调用前完成）
调用 scripts\run.ps1 之前，Agent 必须先判断用户的网络环境。
判断方法（任选其一）：
- 用户明确说在中国大陆 / 国内
- 用户系统语言为中文（zh-CN）
- 用户时区为 UTC+8 且非新加坡/港澳台
- 网络环境无法直接访问 GitHub / PyPI / npmjs.org
判断为中国大陆环境 → 加 --china；否则不加。
Step 1–8: 由 run.ps1 自动执行
Agent 必须使用以下方式调用脚本（禁止直接双击 ps1 文件）：
# 中国大陆环境（一条命令完成全部部署）
powershell -ExecutionPolicy Bypass -File "scripts\run.ps1" --china
# 海外 / 可直连环境
powershell -ExecutionPolicy Bypass -File "scripts\run.ps1"
# 指定推理设备（可选：NPU、GPU、CPU，默认自动检测）
powershell -ExecutionPolicy Bypass -File "scripts\run.ps1" --china --device NPU
或使用 run.cmd 包装入口（用户可直接双击）：
scripts\run.cmd --china
脚本自动完成以下步骤：
- 硬件检测（Intel AIPC）
- 配置镜像源（
--china 时锁定国内源）
- 创建 Python 虚拟环境 + 安装 OpenVINO 依赖
- 获取桌宠源码（git clone）
- 安装桌宠 npm 依赖
- 预写 Onboarding Sentinel（跳过引导界面）
- 启动 OpenVINO 推理服务（HTTP，端口 18765）
- 启动桌宠前端（npm start）
部署完成后，用户直接通过桌宠界面进行对话。
Step 9: 验证部署结果（Agent 必须执行）
部署脚本执行完毕后，Agent 必须验证部署是否成功，不能直接报告"已完成"。
验证方法：
scripts\run.ps1 --status
判断标准（解析脚本输出）：
- 输出包含
推理服务: 运行中 且 桌宠前端: 运行中 → 部署成功，向用户报告
- 输出包含
推理服务: 未运行 → 部署失败，执行排障流程（见下方排障指南）
- 输出包含
桌宠前端: 未运行 → 前端未启动，再次执行 scripts\run.ps1 重试
脚本在部署结束时也会输出结构化摘要，格式如下：
[DEPLOY_RESULT]
server_status=ok|error|timeout
server_port=18765
pet_frontend=running|not_running
model_status=loaded|downloading|error
[/DEPLOY_RESULT]
Agent 应解析此摘要：
server_status=ok + pet_frontend=running → 部署成功server_status=error → 执行 scripts\run.ps1 --debug 获取诊断信息model_status=downloading → 模型仍在下载中，提示用户等待
如果 --debug 也无法定位问题，将 debug 输出展示给用户协助排查。
部署后的架构
┌────────────────┐ HTTP :18765 ┌────────────────────┐ OpenVINO ┌──────────┐
│ 桌宠前端 │ ──────────────→ │ server.py (FastAPI)│ ──────────→ │ MiniCPM5 │
│ (Electron) │ ←────────────── │ (常驻后台) │ ←────────── │ INT8 模型 │
└────────────────┘ └────────────────────┘ └──────────┘
server.py 提供 /v1/chat/completions（OpenAI 兼容）和 /api/health- 桌宠前端通过 HTTP 与推理服务通信
- 模型首次运行时从 ModelScope 自动下载 (~1.5GB)
参数说明
| 参数 | 说明 |
|---|
--china | 锁定中国大陆镜像源，不做网络探测 |
--device NPU|GPU|CPU | 指定推理设备（默认自动检测，优先 GPU） |
--status | 查看当前运行状态（推理服务 + 桌宠前端） |
--stop | 停止所有服务（推理服务 + 桌宠前端，含强杀残留进程） |
--debug | 输出详细诊断信息（Python 环境、模型文件、端口、日志） |
注意事项：
- Agent 必须使用
powershell -ExecutionPolicy Bypass -File 方式调用（Windows 默认不允许直接执行 .ps1）
- git clone 时自动设置
GIT_LFS_SKIP_SMUDGE=1 跳过 LFS 大文件（模型由 server.py 单独从 ModelScope 下载）
- 处理器检测：非 Intel CPU 会直接阻断，非 Core Ultra 系列会警告但继续
生命周期示例：
# 部署并启动
scripts\run.ps1 --china
# 查看状态
scripts\run.ps1 --status
# 不想跑了，停止所有服务
scripts\run.ps1 --stop
# 再次启动（幂等，跳过已完成的步骤）
scripts\run.ps1 --china
Exit Codes
| Exit Code | 含义 |
|---|
| 0 | 部署成功，桌宠已启动 |
| 1 | 一般错误（硬件不支持、环境缺失、网络失败） |
排障指南（Agent 遇到错误时参考）
推理服务未运行（server_status=error 或 timeout）
- 执行
scripts\run.ps1 --debug 查看诊断信息
- 检查「Python 环境」部分：确认 openvino-genai 已安装
- 检查「端口 18765 占用」：如果被其他进程占用，先 kill 再重试
- 检查「最近日志」：查找 Python traceback 或 ImportError
- 常见原因：
- Python 依赖安装不完整 → 删除 venv 重新执行部署
- 端口被占用 →
netstat -ano | findstr :18765 找到 PID 并 kill
- OpenVINO 不支持当前硬件 → 确认是 Intel AIPC（LNL/ARL/PTL/WCL）
桌宠前端未运行（pet_frontend=not_running）
- 确认 Node.js 18+ 和 npm 已安装：
node --version
- 确认
MINICPM_BACKEND=openvino 环境变量已设置
- 检查 npm install 是否成功完成（是否有 node_modules 目录）
- 再次执行
scripts\run.ps1（幂等，会自动重试启动前端）
- 如果前端卡在 onboarding 引导界面：说明
MINICPM_BACKEND 未正确传递，检查环境变量
模型下载超时（model_status=downloading）
- 这不是错误，模型约 1.5GB，首次下载需要时间
- 确认已使用
--china 参数（国内 ModelScope 直连更快）
- 用
scripts\run.ps1 --status 查看推理服务是否仍在下载
- 下载完成后推理服务会自动加载模型，无需额外操作
通用排障步骤
# 1. 查看完整诊断信息
scripts\run.ps1 --debug
# 2. 停止所有服务
scripts\run.ps1 --stop
# 3. 重新部署（幂等，已完成的步骤会跳过）
scripts\run.ps1 --china
# 4. 验证
scripts\run.ps1 --status
日志位置：%USERPROFILE%\.openvino\log\
本 Skill 不做的事
- 不接受对话 prompt 参数（对话通过桌宠 UI 进行）
- 不调用任何云端服务
- 不支持非 Intel 平台
- 不在沙箱内执行大文件下载
- 不使用预构建 .exe 安装包（从源码运行）
