返回内容列表

Desktop Pet

创建一个可以互动和对话的 macOS 桌面伙伴。

TypeScript / macOS进阶SyunWong

实践教程

本教程目录

Desktop Pet / 桌宠

可以拖动、喂米饭、疯狂炫饭、逗狗尾巴草,还能实时语音聊天的 macOS 桌宠。

待机陪伴吃米饭铁盆炫饭狗尾巴草睡觉与唤醒
待机吃米饭铁盆炫饭狗尾巴草睡觉

和她互动

拖动顶部名字,把她挪到身边。点 Feed Rice 喂一碗米饭,或者点 Rice Frenzy,看她两手疯狂炫饭、脚脚乱蹬。

点 Foxtail,就能拖动狗尾巴草逗她玩。草尖在面前停半秒,她会起扑;你可以等她抓住,也可以在她跳起来时抽走,让她扑空。这些互动无需 API 密钥。

点 Sleep,她会先犯困,再挪到一旁睡觉;点她或 Wake up 可以叫醒,喂饭或逗草也会立即唤醒。桌宠窗口内 5 分钟没有互动后会自动睡觉,语音通话期间不会入睡。

语音聊天

点互动按钮下面的 Start Chat 就能和她说话,也可以静音或挂断。语音由 Agora 连接 DeepSeek 和 Fish Audio,填写自己的密钥后即可体验,配置方法见下方。

安装运行

桌面悬浮窗口面向 macOS,目前在 Apple Silicon 上验证过。Intel 和其他 macOS 版本还需要验证;其他系统可以先尝试浏览器预览。

1. 准备工具

安装 Node.js 22+、Python 3 和 Apple Command Line Tools,然后在终端检查。

bash
node --version
python3 --version
xcrun --find swiftc

如果缺少 Command Line Tools,运行 xcode-select --install,等待安装完成后继续。缺少 Node.js 或 Python 时先安装,再重新打开终端。接着安装 pnpm。

bash
npm install -g pnpm@10.11.0

2. 克隆并启动

在你想保存项目的目录运行。

bash
git clone https://github.com/SyunWong/desktop-pet.git
cd desktop-pet
./scripts/setup.sh
./scripts/run-macos.sh

Setup 安装锁定版本的依赖,并在缺少配置文件时创建 voice/.env.local。启动脚本会编译并打开 Desktop Pet.app。你应该看到悬浮角色、互动按钮和 Start Chat。先尝试喂饭、炫饭、狗尾巴草的抓住和扑空,这些无需 API 密钥。拖动标题移动窗口,点 × 退出。

构建脚本会先将网页编译到 voice/.next-desktop/,再构建桌面 app。app 启动本地 Next.js 生产服务器,桌宠窗口不会显示开发模式的 Issues 提示。请保持 app 与 voice/ 在同一个目录;再次运行启动脚本前先关闭旧窗口。修改源码、voice/.env.local 或 Node 路径后,请重新构建。运行 app 需要保留源码目录和已安装的 Node 依赖。

语音配置

下面的 STT、LLM 和 TTS 是作者录制 demo 时的个人选择。开发者可以选择自己的 Agora 集成支持的其他服务商,并按需求调整识别语言、模型和音色。

通过 Agora CLI 配置项目

运行 setup 后,使用 Agora CLI 选择项目并写入凭据,无需从 Console 手动复制 App ID 或 App Certificate。本仓库属于自定义应用,使用 agora project env write 指定 Next.js 变量名和文件路径。

尚未安装 CLI 时,在 macOS/Linux 上运行:

bash
curl -fsSL https://dl.agora.io/cli/install.sh | sh

检查安装状态,再登录本例 Area.US 配置对应的国际站:

bash
agora version
agora doctor --json
agora login --region global
agora project list --refresh-cache

以下命令已核对 CLI 0.2.9 的命令帮助。如果当前版本不支持 project env write --template,请先按官方安装说明更新 CLI。

从列表中选择已有项目;如果需要新项目,先通过 CLI 创建:

bash
agora project create desktop-pet --feature rtc --feature convoai

在仓库根目录执行以下命令,将 YOUR_PROJECT_ID_OR_NAME 替换为所选项目的 ID 或完整名称:

bash
agora project use "YOUR_PROJECT_ID_OR_NAME"
agora project feature enable convoai "YOUR_PROJECT_ID_OR_NAME"
agora project env write voice/.env.local --template nextjs --project "YOUR_PROJECT_ID_OR_NAME"
agora project doctor --feature convoai

显式传入 --project,可以避免仓库已有的本地绑定指向其他项目。CLI 将两项 Agora 凭据写入 voice/.env.local,并在 .agora/project.json 记录项目绑定。两份文件仅保留在本地。切换项目或刷新凭据时,再执行同一条 env-write 命令。不要加 --overwrite,默认更新会保留其他配置,包括已有服务商密钥。

可选服务商密钥

如需复现 DeepSeek 和 Fish Audio demo,用编辑器打开 voice/.env.local,按每行 NAME=value 填入这两个服务商的密钥。Agora 凭据由 CLI 管理。

  • NEXT_PUBLIC_AGORA_APP_ID 和 NEXT_AGORA_APP_CERTIFICATE 由 CLI 从同一个 Agora 项目写入,项目需开通 Conversational AI。
  • DEEPSEEK_API_KEY 用于 DeepSeek。
  • FISH_AUDIO_API_KEY 用于 Fish Audio。填好两个可选 key 可复现英文语音版本。
  • 不填可选 key 时,代码回退到 Agora 托管的 OpenAI / MiniMax,使用中文开场白。

保存配置后,从仓库根目录运行本地配置检查。

bash
cd voice
pnpm doctor
cd ..

Doctor 检查本地环境和两项 Agora 变量是否已填写。密钥有效性和服务商访问权限需要通过实际通话确认。修改 .env.local 后,先关闭桌宠、运行 ./scripts/build-macos.sh 重新构建,再打开桌宠,点 Start Chat,允许麦克风访问。应该能听到开场白,并在说话后收到回应。试一下静音、取消静音、挂断,再发起一次通话,确认能重新连接。语音调用需要网络,服务商可能收费。

Demo 配置与替换位置

环节作者的 demo 选择可调整内容
语音识别 STTDeepgram nova-3,zh-CN服务商、识别模型、输入语言
对话模型 LLMDeepSeek deepseek-flash,关闭 thinking服务商、模型、提示词、生成参数
语音合成 TTSFish Audio s2-pro,示例音色服务商、语音模型、音色、输出语言

voice/app/api/invite-agent/route.ts 中的 PET_SYSTEM_PROMPT 定义桌宠性格,它是普通应用变量,不是 SDK 特殊名称。在该文件的 .withStt(...)、.withLlm(...) 和 .withTts(...) 中修改对应配置。更换服务商时,需要同步修改 SDK provider 配置和服务端环境变量;同一服务商内换模型或音色,可调整对应参数。具体可用范围以你的账号及 SDK 版本支持情况为准。

当前代码会在存在 Fish Audio key 时启用英文提示词和开场白。换成其他语音服务商或语言时,也请在同一文件中调整提示词和开场白。

浏览器预览

先运行 setup,再从仓库根目录运行以下命令。浏览器预览需要 Node.js 和 pnpm,Swift 构建用于 macOS 桌面窗口。

bash
cd voice
pnpm dev --hostname 127.0.0.1

访问 http://127.0.0.1:3000。

让你的 AI 帮你复刻

让编程助手访问这个仓库,复制下面这段任务给它。

text
请在我的电脑上安装并运行 Desktop Pet 仓库。
先读 README.zh-CN.md、scripts/setup.sh 和 scripts/run-macos.sh。
检查系统和依赖。macOS 按桌面安装步骤运行;其他系统先用浏览器预览,
并说明实际验证的平台和范围。使用项目现有 setup 脚本,密钥保存在
voice/.env.local 中。按 README 的 CLI 流程绑定 Agora 项目,使用
agora project env write 和 --template nextjs 写入 Agora 凭据。先验证喂饭、炫饭和玩草;能操作浏览器时,
检查狗尾巴草的抓住和扑空两种结果。
语音部分按我选择的 STT、LLM、TTS 配置。换服务商前阅读语音配置说明
及 invite-agent 路由。缺少第三方服务商密钥时让我在本地填写,服务商不可用时如实说明。
改代码后运行文档中的检查。最后列出已验证的启动、互动、真实通话结果,
以及还需要我手动确认的部分。

开发验证与排障

从仓库根目录运行以下检查,使用空白配置模板也可以执行。

bash
cd voice
pnpm typecheck
pnpm verify:api
node scripts/verify-rtm-lifecycle.mjs
pnpm build:desktop

修改源码或配置后,先关闭 app,在仓库根目录运行 ./scripts/build-macos.sh,再重新打开;脚本会重建网页和桌面程序。浏览器开发仍可使用 pnpm dev 热更新,其 .next/ 目录与桌宠构建分开。文件职责和服务商配置入口见 Recipe。替换角色图片后,还需要调整嘴、袖子、脚部遮罩等动画坐标。

  • 启动失败时查看 desktop.log,确认 setup 已完成,Node 路径改变后重新构建。
  • 麦克风无声时检查 macOS 隐私设置,再重新发起通话。
  • 听不到声音时检查系统输出设备和音量,出现 Enable Sound 时点它。
  • 聊天连接失败时检查两项 Agora 配置、Conversational AI 开通状态和服务商权限。

语音会传给 Agora 及配置的服务商,密钥保存在本地服务端环境中。示例 API 没有用户认证,请保持本地回环访问;对外部署需要补上鉴权和限流。

后续计划

以下是未来版本的探索方向,具体范围和时间还在规划中。

  • 更多表情和反馈:闭眼、开心、困倦、惊讶,以及更丰富的互动反应。
  • 更多角色:增加新角色,让形象、性格和音色更容易切换。
  • 通过聊天交办任务:直接告诉桌宠你想做什么,接入工具后,在同一段对话里听到进展和结果。例如总结文档、整理笔记,需要确认的操作由用户确认后执行。

欢迎通过 GitHub issue 和 PR 提想法或贡献,参见 贡献说明。

复刻和贡献

项目结构、排障方法和数据说明见 英文 README。可复用的 recipe 说明见 docs/RECIPE.md。提交前运行类型检查、API 合约验证和构建,验证记录见 docs/VALIDATION.md。

请勿提交 .env.local、.agora/、日志、依赖目录或本机构建的 app。素材和上游代码署名见 THIRD_PARTY_NOTICES.md。

桌面报错提示

桌宠如果出现红色 Issues 角标,说明运行的是 Next.js 开发模式,请重新构建并打开新版 app。真实的语音错误仍会显示在桌宠状态栏;可以点击收起提示,无法聊天时结束后重试。聊天初始化失败时会清理已创建的 RTM 连接,避免每次重试残留连接。