local-ai-use

本地 AI 使用（通过 Lemonade 路由图像、TTS、STT）

这是一项元技能。只需运行一次。之后，所有需要图像生成、文本转语音或语音转文本的请求，都会使用本地 Lemonade Server，而不是云端 API。Agent 自身的大模型仍负责处理文本；只有高成本的多模态调用会转移到设备本地。

这项技能会完成三件事：

1. 确保本地 Lemonade 已安装并正在运行。 如果找不到新版 lemonade CLI，安装脚本会代用户安装最新版本的 Lemonade。新版 Lemonade 没有 serve 命令——Lemonade 服务（lemond 守护进程）会在安装时自动启动，并由操作系统管理——因此，安装脚本会等待服务启动；如果服务仍未运行，则会显示对应操作系统的确切启动命令（例如，Linux 上的 sudo systemctl start lemond）。
2. 验证本地 Lemonade 可通过 lemonade status 报告的端口访问，这样，已在非默认端口运行的服务也能直接使用，而不会被误报为缺失（13305 仅为备用端口）。
3. 向工作区的 AGENTS.md 添加 Local AI Use 区块，让 Agent 在之后的每一轮对话中都能读取路由规则。该规则适用于 Cursor、Claude Code、Codex、Gemini CLI，以及任何遵循 AGENTS.md 的其他 Agent。

需要新版 Lemonade（v10.1.0 或更高版本）。 新版 Lemonade 将所有功能统一到一个 lemonade CLI（lemonade status、lemonade pull 等）中，由始终运行的 lemond 服务提供支持。lemonade 是唯一有效的 CLI；此技能只会从第 1a 步列出的官方安装途径安装 Lemonade。如果 PATH 中已有旧版 lemonade，它会优先于新版 CLI；运行此技能前，请先将其卸载（参见第 1a 步中的卸载命令）。

设置期间不会下载模型。每个默认模型都会由路由规则在首次使用时按需下载（例如，首次提出图像请求时会下载图像模型）。这样可以加快设置速度，并避免下载用户可能永远用不到的数 GB 模型文件。

何时使用此技能

只有在以下条件全部满足时，才使用此技能：

• 用户需要本地 Lemonade。如果尚未安装，安装脚本会自动为其安装最新版本。
• 用户接受使用此设备上的 Lemonade 端点，无论服务报告的端口是什么（如果从未更改，则为 http://localhost:13305）。
• 用户希望此更改在未来的对话轮次和 Agent 重启后持续生效（规则会写入磁盘）。

如果用户要在应用安装程序中将 Lemonade 作为私有子进程嵌入，请勿使用此技能；请改用 local-ai-app-integration。

前置条件

• 操作系统： Windows 11 x64、Ubuntu/Debian x64 或 macOS（测试版）。
• Lemonade： 如果未安装，设置脚本会安装最新版本：Windows 使用 winget，Ubuntu/Debian 使用 ppa:lemonade-team/stable PPA，macOS 使用 Homebrew cask（回退方案见步骤 1a）。安装后，lemond 服务会自动启动；脚本会等待服务启动，而不会主动启动它。在 Linux 上安装需要 sudo。如果用户想自行安装，请传入 --no-install。
• 磁盘空间： 三个默认模型（SD-Turbo + Whisper-Tiny
  • kokoro-v1）需要约 8 GB 可用空间，安装程序本身还需要约 0.1 GB。首次请求图像时， 如果尚未缓存 SD-Turbo，还会触发约 5 GB 的下载；如果网络按流量计费或速度较慢， 可考虑在设置完成后提前拉取模型（参见 reference.md 中的 lemonade pull）。
• 网络： 安装下载以及首次 lemonade pull 每个模型时都需要网络。之后，所有模态都可离线运行。
• 版本： 需要 v10.1.0 或更高版本（本技能针对统一的 lemonade CLI）。 模型 ID 和 system-info 字段可能随版本更新而变化；请根据实际安装的版本，通过 lemonade status 和 GET /api/v1/models 确认，而不要假设本文档始终是最新的。

建议的操作路径

按顺序从上到下执行此清单。根据清单跟踪进度；每一步验证通过后再继续。

[ ] 1. Ensure Lemonade Server is installed and running (auto-install if missing)
[ ] 2. Install the routing rule into the workspace AGENTS.md

在受管理或共享的计算机上，如果 Agent 不得运行 sudo apt-get install，请向设置脚本传入 --no-install，并在继续前确认已安装 Lemonade。

以下单条命令可一次性完成这两个步骤：

python scripts/setup_local_ai.py

务必先运行此脚本——即使 Lemonade 已安装且服务已在运行，也要在生成任何图像之前运行。 将路由规则写入 AGENTS.md 才能使此技能完整；若因为“Lemonade 已经在运行”而跳过此步骤，工作区在后续轮次中仍未完成配置。即使在这种情况下运行此脚本也很安全：它会检测正在运行的服务、跳过安装，并仅写入规则。

如果未找到新版 lemonade CLI，脚本会自动安装最新版本的 Lemonade，等待自动启动的 lemond 服务，然后写入规则。脚本具有幂等性：在已完成配置的工作区中重新运行，只会执行健康检查，不会进行其他操作。若任一步骤失败，请阅读下文相应章节，了解如何处理。

---

步骤 1：确保 Lemonade Server 已安装并正在运行

scripts/setup_local_ai.py 会端到端处理此过程；以下说明其具体操作，方便你手动执行或调试。如果 Lemonade 已由其他方式管理，且 Agent 不得尝试安装软件包，请传入 --no-install。

1a. 是否安装了新版 lemonade CLI？ 运行 lemonade status。检查依据是功能而非名称：新版 Lemonade 会输出 Server is running... 或 Server is not running。如果得到的是“invalid choice”／用法错误，则 PATH 上的 lemonade 是早于统一 CLI（v10.1.0）的旧版本——请勿使用。将其卸载，然后重新运行此技能：

操作系统	使用以下方式卸载旧版本
Windows	winget uninstall -e --id AMD.LemonadeServer，或依次打开“设置”>“应用”>“已安装的应用”>“Lemonade Server”>“卸载”
Ubuntu/Debian	sudo apt remove lemonade-server
macOS	brew uninstall --cask lemonade-server，或删除已安装的 Lemonade.app 及其 .pkg 收据

切勿尝试代替用户操作或自动卸载。

如果完全找不到 lemonade，请代用户安装最新版本。优先使用软件包管理器；如果软件包管理器不可用，再通过下载方式安装。完整的平台列表（包括 Arch、Fedora、Debian、Snap 和 Docker）见安装文档。

操作系统	安装	备用方案
Windows	winget install -e --id AMD.LemonadeServer	下载 lemonade.msi，并运行 msiexec /i lemonade.msi /qn（静默安装、仅当前用户、无需提升权限）。
Ubuntu	sudo add-apt-repository -y ppa:lemonade-team/stable && sudo apt-get update && sudo apt-get install -y lemonade-server	sudo snap install lemonade-server
macOS	brew install --cask lemonade-server	从最新版本下载 Lemonade-<ver>-Darwin.pkg，并运行 sudo installer -pkg Lemonade-<ver>-Darwin.pkg -target /。

Ubuntu apt 软件包名为 lemonade-server，但它安装的 CLI 名称是 lemonade。浏览器 UI 会在 http://localhost:13305 提供服务，无需额外安装 软件包；只有用户需要桌面前端时，才添加 sudo apt install lemonade-desktop。

在 Windows 上安装后，CLI 会放在 %LOCALAPPDATA%\lemonade_server，并添加到 用户 PATH（仅对新 shell 生效）；安装脚本会检查该目录，因此在同一次运行中也能正常工作。

1b. 服务是否正在运行，运行在哪个端口？ 检查 lemonade status --json， 它会通过打印绑定的端口（{"port": 13305}）同时回答这两个问题。lemond 服务会在安装时 自动启动——现代版 Lemonade 中没有 lemonade serve。

lemonade status 的输出	操作
Server is running on port <N>	后续每个请求和规则都使用端口 <N>，即使它不是 13305。继续执行步骤 2。
Server is not running	等待几秒，让自动启动的服务启动（脚本会轮询 /api/v1/health，并重新执行 status，以防服务在其他端口启动）。如果服务仍未启动，请通过操作系统服务管理器启动：sudo systemctl start lemond（Linux 系统级安装）或 systemctl --user start lemond（按用户安装）；launchctl load /Library/LaunchDaemons/com.lemonade.server.plist（macOS）；Lemonade 托盘应用或 Start-Service lemond（Windows）。

不要将 13305 当作“正在运行”的判定标准：端口是一个配置值 （lemonade config set port），现有配置、其他安装渠道或端口冲突都可能改变它，因此只探测默认端口会误报健康的服务不存在。请查询 status，它会通过服务的 UDP 信标解析端口——lemonade scan 用于查找其他机器上的服务 （参见reference.md），绝不能用于选择本地端点。安装脚本优先使用 --host / --port 或 LEMONADE_HOST / LEMONADE_PORT，而不是自动发现，并会将最终确定的值写入规则；连接另一台机器时，请同时传入两者，因为此处的 CLI 无法报告远程服务的端口。

只有在自动安装确实失败时（没有 apt-get、没有 sudo、下载受阻），才应停止并指引用户访问 https://lemonade-server.ai/docs/guide/install/。

本技能其余部分将端点写作 http://localhost:13305/api/v1，这是默认值；如果端口与 status 报告的不同，请替换为该端口。本技能还假设不需要 API 密钥（系统级服务默认在 loopback 上不启用身份验证）。如果用户设置了 LEMONADE_API_KEY，templates/local-ai-rule.md 中的路由规则模板会显示添加 Authorization 标头的位置。

1c. 各模态的后端是否就绪？ 后端健康状态按模态分别判定。聊天或图像请求可正常工作，并不能证明转录也能正常工作：auto 会为每种模态选择不同的后端，某种模态可能会静默回退，而另一种模态却没有可用的替代方案。完成设置前，请检查各模态的实际状态：

lemonade backends --all

工作区路由所依赖的任何变体都应显示为 installed。如果某种模态唯一已安装的变体是 rocm，请同时安装 Vulkan 变体，以便 auto 有回退选择（例如， lemonade backends install whispercpp:vulkan）。

默认模态模型（首次使用时下载，而非设置期间下载）

设置过程不会下载这些模型。已安装的规则会在首次请求相应模态时下载对应模型。它们是 Lemonade 为每种模态提供的最小模型，旨在确保在普通硬件上也能切实节省 token 和成本：

模态	模型	大小	默认选择原因
图像生成	SD-Turbo	~5 GB	单步生成，可在 CPU 和 AMD iGPU/dGPU 上运行
文本转语音	kokoro-v1	~0.3 GB	Lemonade 目前唯一支持的 TTS 模型；仅使用 CPU，延迟低
语音转文本	Whisper-Tiny	~0.1 GB	最小的 Whisper 模型；在 CPU 上速度快。如果准确性比延迟更重要，可升级到 Whisper-Large-v3-Turbo。

若要将其他模型 ID 写入规则，请将其传递给设置脚本。例如，要让之后的图像请求使用 SDXL：

python scripts/setup_local_ai.py --image-model SDXL-Turbo

该模型 ID 会写入已安装的 AGENTS.md 规则，并在首次使用时下载。--tts-model 和 --stt-model 也可使用相同方式。有关更大／质量更高的替代模型（SDXL-Turbo、Flux-2-Klein-4B、Whisper-Large-v3-Turbo），请参阅 reference.md 中的模型选择器。

步骤 2：将路由规则安装到 AGENTS.md

该规则是一个 Markdown 块，存储在 templates/local-ai-rule.md 中。将它追加到工作区的 AGENTS.md（如果文件不存在，则创建该文件）。Cursor 和 Claude Code 都会在每轮对话中自动加载 AGENTS.md，因此 Agent 会在下一条消息中看到该规则，无需进行其他设置。

scripts/setup_local_ai.py 会替你完成此操作。它会将所选端点和模型 ID 写入规则，并用固定标记包围规则块，以便重新运行脚本时替换原有规则块，而不是再次追加。标记如下：

...rule...

如果你手动写入文件，请保留这些完全一致的标记。脚本依赖这些标记来实现幂等更新。

如果用户的 Agent 只遵循其他约定，请将相同的规则块复制到：

• CLAUDE.md（Claude Code，项目范围）或 ~/.claude/CLAUDE.md（全局）
• .cursor/rules/local-ai-use.mdc（Cursor 用户／项目规则）
• GEMINI.md（Gemini CLI）

规则内容完全相同；只有文件位置不同。

---

此技能运行后会发生什么

从下一轮开始，Agent 会在每条消息中读取 AGENTS.md 中的规则。该规则会明确告知 Agent：

• 图像生成：调用本地服务上的 POST /api/v1/images/generations。不要调用任何云端图像 API，也不要使用内置的 GenerateImage 工具（该路径会向云服务提供商计费）。
• **文本转语音：**调用 POST /api/v1/audio/speech。不要调用云端 TTS 服务提供商（OpenAI TTS、ElevenLabs 等）。
• **语音转文本：**调用 POST /api/v1/audio/transcriptions。不要调用云端转录服务提供商。
• 回退：只有在一次本地尝试失败且已告知用户本地调用失败后，才能回退到云端 API。绝不静默回退；此技能的核心目的就是让成本可预测。对于语音转文本，还必须说明转录文本来自不同的引擎，因为不应比较或去重由不同引擎生成的转录文本。

Agent 自身的文本推理仍会使用 Cursor／Claude Code／Codex 配置的大模型。此技能不会重定向聊天 token；它只会重定向原本会离开本机的多模态调用。

故障排查速查表

症状	原因	解决方法
lemonade: command not found	未安装 CLI	重新运行 python scripts/setup_local_ai.py（会自动安装最新版本）。如果刚在 Windows 上安装，请打开新的 shell，以刷新用户 PATH；否则脚本会在 %LOCALAPPDATA%\lemonade_server 下查找。
status 提示“invalid choice”／用法错误	旧版 lemonade（早于 v10.1.0）覆盖了新版 CLI	卸载旧版（参见步骤 1a 的表格：winget uninstall -e --id AMD.LemonadeServer／sudo apt remove lemonade-server／brew uninstall --cask lemonade-server），然后重新运行设置脚本。
对 http://localhost:13305 的请求被拒绝，但 lemonade status 显示服务正在运行	服务绑定到了非默认端口（已有配置、通过其他安装渠道安装，或端口冲突）	使用 lemonade status --json 中的端口，并重新运行 python scripts/setup_local_ai.py，以便用该端口重写规则。不要启动第二个服务；正在运行的服务可以正常使用。
Server is not running	lemond 服务已停止	通过操作系统的服务管理器启动服务——sudo systemctl start lemond／systemctl --user start lemond（Linux）、launchctl load /Library/LaunchDaemons/com.lemonade.server.plist（macOS），或通过托盘应用／Start-Service lemond（Windows）。没有 lemonade serve 命令。
POST /v1/images/generations 返回 404 model not found	尚未下载图像模型	运行 lemonade pull SD-Turbo，然后重试。
lemonade pull 一直显示 Progress: NN%，但始终无法完成	下载目标路径存在问题（空间不足、没有写入权限、配额限制或挂载为只读）。写入错误可能只会出现在服务日志中，而控制台仍持续显示进度	先检查目标路径和可用空间：GET /api/v1/system-info 会报告 models_dir 和 model_storage.free_bytes。如果拉取卡住，请查看服务日志的最新内容（通常位于操作系统临时目录下的 lemonade-server.log），查找实际错误（例如 CURL code 23 之类的下载／写入失败，或空间不足提示），然后将下载目标改为有足够空间且可写入的磁盘。
CPU 上的图像生成速度较慢（约 4–5 分钟）	sd-cpp 使用 CPU 后端	在受支持的 AMD 硬件上安装 GPU 后端：lemonade backends install sd-cpp:rocm。
安装 GPU 后端后仍然很慢	后端已安装，但实际并未启用；运行时静默回退到了 CPU	system-info 中显示 installed 状态，以及 rocminfo 成功运行，都仍可能发生静默 CPU 回退。请在请求期间检查实际 GPU 利用率（gpu_busy_percent），并确认主机的 GPU 驱动程序栈，而不要重新安装后端。
POST /v1/audio/transcriptions 返回 400 unsupported format	输入不是 16 kHz 单声道 WAV	使用 ffmpeg -i in.* -ar 16000 -ac 1 out.wav 重新编码。
POST /v1/audio/speech 返回 404	尚未下载 TTS 模型	运行 lemonade pull kokoro-v1。
每个请求都返回 401 Unauthorized	用户设置了 LEMONADE_API_KEY	在每个请求和规则块中添加 Authorization: Bearer $LEMONADE_API_KEY。

验证清单

仅当以下所有条件均满足时，才将此技能标记为已完成：

• lemonade status --json 报告服务正在运行，且报告的端口与已安装规则中的端口一致（除非服务经过其他配置，否则为 13305）。
• 工作区的 AGENTS.md 包含 amd-skills:local-ai-use 区块。即使 Lemonade 已安装并正在运行，这项要求仍然适用——仅生成图像并不意味着技能已完成。
• 在后续轮次中，要求 Agent“生成一张 X 的图像”时，它会向规则中指定的端点发送 POST 请求至 /api/v1/images/generations（首次使用时拉取模型），而不是调用云端工具。
• lemonade backends --all 对此工作区路由所依赖的每个后端变体都显示 installed（请参阅步骤 1c）。不要将图像或聊天路径可正常工作视为转录功能也能正常工作的证明。

如果有任何一项未勾选，用户仍在为至少一种模态支付云端费用，或者某个路由模态在首次使用时可能会静默失败。

---

参考

如需查看完整的模型选择器、其他质量选项、完整端点参考、API 密钥流程，以及可交给 Agent 工具调用循环使用的 OmniRouter 工具定义，请参阅 reference.md。