给桌宠做一个自定义 LoRA 人格

MiniCPM-Desk-Pet 支持上传你自己的 LoRA 适配器，给桌宠换一套说话风格 / 人格（内置的「猫娘」就是这么来的）。这条 Skill 把整个链路串起来：

  微调 LoRA            转成 GGUF              在 App 里
 (任一框架)   ──►   (llama.cpp 转换)   ──►   上传 + 启用
 PEFT adapter        adapter.gguf            Settings → MiniCPM

关键认知：App 的后端是 llama-server，它只认 GGUF 格式的 LoRA 适配器（通过 --lora 加载）。 大多数微调框架产出的是 PEFT 格式（adapter_model.safetensors），不能直接上传——中间必须做一次 safetensors → GGUF 的转换。这是最容易卡住的地方。

前提：必须针对 MiniCPM5-1B 训练

桌宠跑的就是 MiniCPM5-1B（GGUF）。你的 LoRA 必须基于同一个 base 模型训练，否则适配器套上去等于乱码。

• base 模型：openbmb/MiniCPM5-1B（fp16 HF 版，用于训练）。
• 训练数据：messages 格式 JSONL，例如 [{"messages":[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]}]。

完整步骤

1. 训练一个 LoRA（在 OpenBMB/MiniCPM 仓库里做）

训练相关的 Skill 都在上游 OpenBMB/MiniCPM 仓库的 skills/ 下，不在本仓库。按硬件挑一个：

产物是一个目录，里面有 adapter_config.json + adapter_model.safetensors。

2. 转成 GGUF 适配器（这一步桌宠才认）

同样在上游仓库，有专门的 Skill：minicpm5-finetune-gguf-lora。核心命令：

# 在 llama.cpp 仓库目录下
python convert_lora_to_gguf.py /path/to/你的adapter目录 \
    --base openbmb/MiniCPM5-1B \
    --outtype f16 \
    --outfile ~/my-pet-persona.gguf

🔑 最大的坑：adapter_config.json 里记录的 base_model_name_or_path 往往是训练那台机器的绝对路径， 换到你的机器上找不到。所以一定要显式传 --base openbmb/MiniCPM5-1B（或 --base-model-id openbmb/MiniCPM5-1B） 覆盖它。--base 只需要 base 模型的 config，不需要完整权重。

转出来的 .gguf 很小（r=16 的适配器大约几十 MB），这就是要上传的文件。

本仓库 adapters/ 下那个内置「猫娘」适配器，旁边的 adapter_model.f16.gguf 就是这么从 adapter_model.safetensors 转出来的——可以照着对。

3. 在 App 里上传

1. 打开 Settings → 🐾 MiniCPM，找到「适配器 (LoRA)」区。
2. 点 上传，选你的 .gguf 文件。App 会把它复制进 <userData>/adapters/uploads/ 并登记。
3. 填一个显示名和别名（逗号分隔）。别名用于语音 / 聊天切换，例如设了别名「小狐狸」，之后对桌宠说"换成小狐狸"就能切。
4. 在适配器列表里选中它即可启用——sidecar 会带上你的 --lora 重启 llama-server。

App 的校验（不满足会被拒）：

• 只接受单个 .gguf 文件（第 2 步转出来的那个，不是 .safetensors，也不是合并后的整模型）。
• 适配器是叠在 App 自带的 MiniCPM5-1B GGUF base 上跑的，所以必须针对 MiniCPM5-1B 训练。

4. 验证

切到你的适配器后，对桌宠说几句，看人格 / 语气有没有变。

• 变了 → 成功。
• 跟原来一模一样 → 适配器没真正生效：多半是第 2 步 --base 没对上（base 不匹配），或者你上传错了文件。
• 想确认 GGUF 是不是合法的 LoRA：python -c "import gguf; r=gguf.GGUFReader('~/my-pet-persona.gguf'); print(len(r.tensors),'tensors')"，tensor 数应大于 0。

常见问题

上传时提示「必须是 .gguf 文件」

你选的是 .safetensors（PEFT 原始产物）。回到第 2 步先转成 GGUF。

上传成功但桌宠没反应 / 像没装一样

• LoRA 只做风格偏置，分量不够时效果不明显——可以加大训练数据 / epoch，或调高 lora_alpha。
• 内置人格（如猫娘）除了 LoRA 还配了系统提示词；自定义上传目前主要靠 LoRA 本身的风格。想要更强的人格感，训练数据里就把目标语气/口头禅喂足。

转换报 can't load base model config / FileNotFoundError

就是第 2 步那个坑：adapter_config.json 里的 base 路径在你机器上不存在。用 --base openbmb/MiniCPM5-1B 覆盖。

想删掉上传的适配器

在同一个适配器列表里删除即可（只能删自己上传的，内置预置删不掉）。如果删的正好是当前启用的，App 会先在 sidecar 侧卸载再删文件。

适配器去哪了 / 文件在哪

上传的文件在 <userData>/adapters/uploads/（dev 模式下是仓库的 adapters/）。sidecar 启动时扫描这个目录里的 *.gguf。

这条 Skill 不负责什么

• 怎么训练（数据准备、超参、跑训练）→ 上游 minicpm5-finetune* 系列。
• 转换命令的全部细节 → 上游 minicpm5-finetune-gguf-lora。
• 从源码部署桌宠 → 本仓库的 deploy-minicpm-pet。

本 Skill 是把上面这些串成"给桌宠做人格"的一条用户视角主线。

参考

• 上游训练 / 转换 Skills：OpenBMB/MiniCPM 仓库 skills/（minicpm5-finetune、minicpm5-finetune-gguf-lora）。
• App 内入口：Settings → 🐾 MiniCPM → 适配器 (LoRA)。
• README 的 Persona Adapters 段落也有简述。

Deploying MiniCPM-Desk-Pet (开发者从源码)

重要：这个 Skill 只针对开发者。普通最终用户走的是 下载 dmg → Onboarding 流程，不应使用本 Skill。如果对方只是想"用一下这个应用"，请引导他们去 Releases 下载 dmg。

v0.8 起推理后端从 PyTorch / transformers 切换到 llama.cpp。本 Skill 已按 v0.9 平铺布局更新；sidecar 结构与构建方式以 minicpm-sidecar/README.md 为准。

This skill walks the agent through deploying the MiniCPM-Desk-Pet project on a colleague's machine from source. The project has 3 moving parts that need to come up in the right order: llama-server (compiled from vendored llama.cpp), the FastAPI gateway, and the Electron clawd-on-desk app.

Quick assessment first

Before doing anything, check what state the colleague's machine is in:

# Are we in the repo root?
ls README.md go.sh clawd-on-desk minicpm-sidecar 2>&1 | head -5

# What's already installed?
command -v node && node -v          # need 18+
command -v uv && uv --version       # go.sh installs if missing
command -v cmake && cmake --version # go.sh installs if missing (needed for llama-server)

If the user isn't in the repo root, cd to wherever they cloned it first.

Critical prerequisite: GGUF model

The model weight (~600 MB – 1 GB GGUF) is NOT in the repo. Without it, the gateway boots in "waiting for model" mode and Onboarding prompts the user to download one.

Check first:

ls -la models/*.gguf 2>&1

If missing, three ways to obtain it:

1. Already have a .gguf locally (most likely if the colleague worked on MiniCPM before):

   mkdir -p models
   ln -s /absolute/path/to/your/minicpm5-0.9b.Q4_K_M.gguf models/
   

2. Let Onboarding download — just run ./go.sh and follow the wizard's "Download model" step (~2–5 minutes from Hugging Face).

3. From a teammate's machine (scp):

   scp teammate@host:/path/to/minicpm5-0.9b.Q4_K_M.gguf ./models/
   

The gateway accepts both a .gguf file path and a directory containing .gguf files.

Install path (uv + cmake, what go.sh uses)

./go.sh

go.sh is idempotent. It will:

1. Check Node 18+ (auto-install via brew or fnm if missing)
2. Auto-install uv if missing (curl install.sh)
3. Auto-install cmake if missing (brew / apt)
4. First-time: clone vendored llama.cpp + cmake build llama-server (~5–10 min)
5. uv sync in minicpm-sidecar/ (a few dozen MB: fastapi / uvicorn / httpx / huggingface_hub — no torch)
6. npm install in clawd-on-desk/ (~1 minute, first time only)
7. Export MINICPM_SIDECAR_DIR + MINICPM_PYTHON + MINICPM_MODEL_DIR
8. npm start to launch Electron

If only the dependency-install part is needed (no launch yet):

./go.sh setup

Environment-check only (no install, no launch):

./go.sh doctor

Force a rebuild of llama-server (after pulling a new vendor pin):

./go.sh build-llama

Verifying the deploy

Once Electron starts, you should see:

1. Menu bar icon — paw, top-right
2. Floating pet — sitting on the desktop, can be dragged
3. Sidecar log in terminal — [sidecar] lines, eventually llama-server ready + gateway listening on :18765

Quick sanity check (in another terminal):

curl -s http://127.0.0.1:18765/api/health | python3 -m json.tool

Expected ok: true plus reported backend (metal on Apple Silicon, cuda, or cpu).

Then click the pet (or ⌘⇧M), type "你好" — pet should think and reply within a few seconds.

Common deploy failures & fixes

Cannot find module 'electron' / npm start fails immediately

cd clawd-on-desk && npm install

ModuleNotFoundError: fastapi (or uvicorn / httpx)

cd minicpm-sidecar && uv sync

llama-server: command not found / bin/<triple>/llama-server missing

The vendored llama.cpp didn't build. Re-run:

./go.sh build-llama

If cmake errors out, check cmake --version (need 3.20+) and re-install via brew / apt.

Sidecar log says model not found / No GGUF files in MODEL_DIR

The gateway couldn't locate a .gguf. Drop one into models/ or override:

MINICPM_MODEL_DIR=/abs/path/to/dir ./go.sh start
# or point directly at one file via Onboarding's "选本地模型"

Pet starts but "气泡聊天没反应 / 卡住"

Probably the sidecar didn't come up. In the clawd-on-desk terminal, look for [sidecar] lines.

• If gateway can't find Python: ensure minicpm-sidecar/.venv/bin/python exists (cd minicpm-sidecar && uv sync)
• If llama-server crashed during model load: check memory (Q4_K_M needs ~1 GB RAM resident; F16 needs ~2 GB)

port 18765 in use (or 23333)

Old sidecar / clawd HTTP server didn't die cleanly:

lsof -ti:18765 | xargs -r kill -9   # sidecar
lsof -ti:23333 | xargs -r kill -9   # clawd HTTP server

Cursor / Claude / Codex hook didn't auto-register

This is supposed to happen on first launch. Re-trigger via Settings → 🐾 MiniCPM, or restart the pet. Manual fallback (Claude as example):

cd clawd-on-desk
node -e "require('./hooks/install.js').installAll({silent:false})"

Updating someone else's already-deployed install

If a teammate already has an older checkout and wants the latest:

git pull
./go.sh setup     # re-syncs deps + rebuilds llama-server if vendor pin changed
./go.sh start

uv sync, npm install, and cmake are idempotent — no-op if nothing changed.

What "success" looks like

The deploy is done when:

• Pet visible on desktop
• curl -s http://127.0.0.1:18765/api/health returns ok:true
• Click pet → bubble pops up → type a message → reply within a few seconds
• In Cursor: ask Cursor anything → after Cursor finishes → pet says a one-line reaction (proves cursor-hook is wired)
• Settings → 🐾 MiniCPM shows current model + adapter status

If any of these fail, walk back through the corresponding "Common failure" section above.

Local-MiniCPM-Pet-OpenVINO Skill Guide

使用本 Skill 可一键部署一个完整的 MiniCPM 桌宠体验环境。 后端采用 OpenVINO 推理引擎，前端从源码 npm start 启动。 部署完成后，用户直接与桌宠对话，无需再次调用本脚本。

!! CRITICAL: 环境依赖 !!

以下依赖缺一不可，必须在执行前验证：

!! CRITICAL: 中国大陆网络环境 !!

所有网络操作必须使用国内源，否则极慢或不可用：

--china 参数已内置上述所有配置，无需手动设置。

!! CRITICAL: 沙箱外运行要求 !!

以下目录必须持久化（沙箱外），否则每次重试将重新下载 ~2.4GB：

严格执行流程（必须按顺序，不可跳过）

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

脚本自动完成以下步骤：

1. 硬件检测（Intel AIPC）
2. 配置镜像源（--china 时锁定国内源）
3. 创建 Python 虚拟环境 + 安装 OpenVINO 依赖
4. 获取桌宠源码（git clone）
5. 安装桌宠 npm 依赖
6. 预写 Onboarding Sentinel（跳过引导界面）
7. 启动 OpenVINO 推理服务（HTTP，端口 18765）
8. 启动桌宠前端（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)

参数说明

注意事项：

• 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

排障指南（Agent 遇到错误时参考）

推理服务未运行（server_status=error 或 timeout）

1. 执行 scripts\run.ps1 --debug 查看诊断信息
2. 检查「Python 环境」部分：确认 openvino-genai 已安装
3. 检查「端口 18765 占用」：如果被其他进程占用，先 kill 再重试
4. 检查「最近日志」：查找 Python traceback 或 ImportError
5. 常见原因：
   • Python 依赖安装不完整 → 删除 venv 重新执行部署
   • 端口被占用 → netstat -ano | findstr :18765 找到 PID 并 kill
   • OpenVINO 不支持当前硬件 → 确认是 Intel AIPC（LNL/ARL/PTL/WCL）

桌宠前端未运行（pet_frontend=not_running）

1. 确认 Node.js 18+ 和 npm 已安装：node --version
2. 确认 MINICPM_BACKEND=openvino 环境变量已设置
3. 检查 npm install 是否成功完成（是否有 node_modules 目录）
4. 再次执行 scripts\run.ps1（幂等，会自动重试启动前端）
5. 如果前端卡在 onboarding 引导界面：说明 MINICPM_BACKEND 未正确传递，检查环境变量

模型下载超时（model_status=downloading）

1. 这不是错误，模型约 1.5GB，首次下载需要时间
2. 确认已使用 --china 参数（国内 ModelScope 直连更快）
3. 用 scripts\run.ps1 --status 查看推理服务是否仍在下载
4. 下载完成后推理服务会自动加载模型，无需额外操作

通用排障步骤

# 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 安装包（从源码运行）