English: soft hearts currently talks in Chinese only (the interface already has English). An English version, where she talks in English too, is in progress.
项目仓库：GitHub。这是用 Claude Code 聊天的版本，聊天走你自己的 Claude Code 登录。
demo video1:https://www.bilibili.com/video/BV1eEWW6DEQL/
一个面向 MMD 模型的轻量 AI 桌宠，首版为 Windows 桌面开发预览。独立实现，准备长期开发和开源；只支持 PMX/PMD，不引入 Live2D。
把仓库地址发给你自己的 Claude Code：
请从 https://github.com/LexZeon/soft-hearts 帮我安装并启动 soft hearts，聊天用我自己的 Claude Code 登录。请先介绍能用的功能，偏好可以先用默认值，以后再改。
Claude Code 会先检查仓库访问和本机环境，再按首次使用引导准备、启动并验证。也可以下载源码 ZIP：完整解压到一个短一点的路径（比如 C:\soft-hearts），再双击 start-soft-hearts.cmd；Windows 给浏览器下载的脚本打了"来自网络"的标记时，它会先说明并问你要不要只给这个文件夹里的 soft hearts 文件去掉标记（按 Y；也可以解压前在压缩包上右键 → 属性 → 勾选"解除锁定"）。第一次只安装并启动源码版桌宠，几分钟就好。首次默认使用预装 Gene；已有的模型设置会保留，也可以稍后换成自己的 PMX/PMD。源码不包含私人模型、账户或密钥。
每个人都用自己电脑上的官方 Claude Code 和自己的订阅。soft hearts 不读取、不保存、不转交任何登录凭据。应用开着时会给你自己的 Claude Code 开一条"内部通道"（默认开）：启动约 20 秒后在 Claude Code 的用户配置里登记一个 soft-hearts-next MCP 条目，之后你可以让自己的 Claude 帮忙换角色、调设置；可以在「隐私与设置」→「Claude 内部通道」里关掉。语音输入默认用本机识别（第一次要下载识别组件，声音不上传），Claude Code 登录本身不提供语音转写。
- 透明桌宠窗口与控制窗口，可置顶、隐藏及鼠标穿透；靠近各自位置显示功能按钮、聊天输入框和窗口尺寸，按住移动按钮拖动窗口；窗口调整模式可拖动四角独立改变宽高，角色保持自然比例，外框和四角仅在该模式显示。
- 预装 Gene 模型、贴图与 40 个配套 VMD，另有 13 个按来源署名的待机、会话手势与短舞；也可加载本地 PMX/PMD 和 VMD，支持平滑呼吸、眨眼和鼠标视线。
- 在预览或桌宠中进入镜头调整模式：按住左键像第一人称游戏一样原地转向，相机位置不变；右键平移，WASD 移动，Space 上升、Z 下降。按住 Shift 将旋转、平移、键盘移动和滚轮缩放幅度缩小至四分之一；Tab 按当前模型重新全身取景，Esc 完成。快捷键仅在镜头画布获得焦点时生效，输入框保持正常编辑。构图自动保存，另有数值和全身/近景取景。
- 普通聊天使用本机已登录的 Claude Code（一个长驻进程，关闭全部工具）；需要授权的任务执行已接入，默认关闭。
- 角色卡创建、复制、编辑、切换和 JSON 导入导出，可关联当前 MMD；流式文字回复、停止生成、圆角回答气泡和系统语音朗读。支持独立语音输入开关和兼容转录服务。
- 独立开关屏幕/摄像头共享，发送消息时附带最新画面；也可手动添加单帧快照。默认全部关闭。
- 任务执行（读写所选目录的文件、运行命令）用你本机的 Claude Code，已接入、默认关闭：在「Claude 任务」里打开并选一个文件夹；读文件自动放行，写文件和运行命令每次都要你批准。
鼠标视线由眼球和头部共同完成：近处主要转眼球，距离越远头部权重越大；两者分别平滑过渡并限制转动角度。
回答气泡位于角色外侧，框角保留短三角提示方向；请求被接受后先显示轻跳三点，第一段正文替换它，停止或失败时清理。开启朗读时保留到实际播放结束，再停留 5 秒；不朗读时从回复完成开始计时。下一次回复开始会替换旧回答。工具栏与聊天输入框各自在鼠标靠近其位置时显示，离开 1 秒后隐藏；工具栏可用 > 收为单个 <，重新启动默认展开。输入焦点、拖动或调整模式保留所需控件。有效头皮命中立即显示 👋 并平滑回应，同次接触 2 秒后工具栏开始短暂淡出；接触不会主动唤出隐藏工具栏，静止停留不产生互动奖励。
日常界面默认少显示技术信息：需要处理的问题先给简明提示，可主动查看详情；开发者模式显示诊断原文。已有模型配置时启动不自动打开控制窗口，可通过桌宠的设置入口、托盘或再次打开桌面快捷方式进入。聊天区的语音按钮独立排布；工具栏的临时面板一次展开一个，收起不会关闭已选音频开关。
开发版已接入按角色隔离的疲倦状态和语音活动优先级，开发者面板可查看状态；自动入睡入口仍关闭，枕头、家具和新睡姿尚未上线。最近日常版本、具体新增、配置保留与未验范围统一见仓库的 Releases 页；源码、技术部署和实际用户体验分别记录。
准备 Node.js 22.12+、pnpm（版本由 packageManager 固定）和支持 WebGL 的显卡驱动。模型和模型服务按需准备；本机语音识别、姿态感知等组件只在你点"下载"时才下载。最新版桌面入口可选绑定用户已选择的本机识别管理脚本，启动时恢复该识别连接，详见语音输入。
pnpm install
pnpm dev构建后运行：
pnpm build
pnpm startpnpm pack 生成解包后的桌面应用，pnpm dist:win 构建 Windows 便携版，输出在 release/。首次安装需要下载 Electron；首次打包还可能下载打包工具。首版未做代码签名。
双击 start-soft-hearts.cmd：它安装、构建并用开发配置启动源码版桌宠。第一次（这台电脑还没有开发版）到此为止，要桌面快捷方式时在终端运行 start-soft-hearts.cmd desktop 或 pnpm desktop:update；已经有开发版的电脑，它照旧接着（等同 pnpm desktop:update）冻结当前源码，检查类型、测试、资源和打包版，装成开发版并更新桌面的 soft hearts next - 最新开发版 快捷方式。源码没变时只刷新快捷方式，不重新打包。打包失败时桌宠仍按原方式运行，窗口用中文说明原因。
试用满意后双击 promote-to-stable.cmd（等同 pnpm desktop:promote），把测过的当前开发版复制成稳定版，桌面出现 soft hearts next - 稳定版；之后的开发版更新不会改动它。只有稳定版使用原来的配置 %APPDATA%\soft-hearts-claude，日常陪伴请用稳定版快捷方式；开发版和所有源码运行（start-soft-hearts.cmd 打开的那只、pnpm dev、pnpm start）都用单独的开发配置 %APPDATA%\soft-hearts-claude-dev（第一次创建时从稳定版只读复制一次设置，以后不再同步，也从不写回稳定版）。同一份配置同时只能开一个桌宠：要打开新版本，先从托盘菜单退出旧的；开发版和源码版共用开发配置，也只能开其中一个。新的稳定版有问题时，运行 pnpm desktop:rollback（node scripts/update-desktop.mjs --rollback-stable）退回上一个稳定版：不重新打包、不动配置，只把稳定版和它的快捷方式指回上一个已归档、校验通过的版本；之后再双击 promote-to-stable.cmd 就能换回当前开发版。这些脚本只认 soft hearts next.exe 和这两个快捷方式名。
- 首次启动自动载入预装 Gene 和 Stand 动作，无需下载模型或动作。使用自己的模型时，选择
.pmx或.pmd，保留原贴图目录；压缩包先解压。已有配置的模型选择保持原样，可随时点击「使用预装 Gene」切回。 - 点击「调整镜头」控制镜头，桌宠同步保存后的视角。窗口位置通过移动按钮按住拖动；点击「窗口调整模式」后拖动四角改变宽高，松手保存，点击「完成」或 Esc 退出。窗口变扁或变长时角色保持自然比例，尺寸操作保留当前镜头。
- 默认使用自己的 Claude Code 登录，检查后发送文字确认实际回复。语音朗读可单独开启。
- 需要视觉时开启悬浮工具栏中的屏幕/摄像头共享，或手动添加快照；附图需要支持图片输入的模型。共享开启后也只在发送消息时交给模型，不会定时请求 AI。
- 如需语音输入，先确认可用的转录连接，再由你决定是否开启麦克风；Claude Code 登录本身不提供语音转录。打开语音输入后，按住 T 说话，松开就转写并发送（先点一下她，让桌宠窗口在最前面；光标在已有文字的输入框里时 T 照常打字）；不按 T 时麦克风的声音直接丢掉；当前正在回复时，识别文字先留在输入框。
贴图须位于所选模型所在文件夹或其子目录；出于文件访问范围限制，不读取跨到父目录的相对路径。
桌宠穿透后，可通过托盘菜单恢复控制；Ctrl+Alt+P 用于恢复桌宠交互。关闭控制窗口后，应用仍可留在托盘；退出请使用托盘菜单。
控制窗口顶部的「显示桌宠」会显示已有桌宠窗口，保留位置、尺寸、镜头和交互设置。桌宠移出屏幕或镜头偏移时，可点击旁边的「一键恢复桌宠」：在当前设置窗口所在显示器中央显示，恢复默认大小、置顶和可操作状态，并按当前模型自动全身取景。模型、动作、连接和角色卡保留；只重置桌宠显示设置。
默认使用你自己的 Claude Code 登录；模型留空时用 Claude Code 的默认模型，也可以填 haiku、sonnet、opus 或完整模型 ID。这一版只用 Claude：以前保存的 OpenAI 兼容 API 或 Ollama 连接会自动改成 Claude 的默认设置，旧的 API 密钥原样留在本机配置里，不再读取、也不再使用。
聊天用一个长驻的 claude -p --input-format stream-json 进程（每 12 轮或空闲 10 分钟换新；SOFT_HEARTS_CLAUDE_PERSISTENT=0 退回每条回复一次调用），在空的临时目录里运行：关闭全部内置工具、MCP、斜杠命令、技能、插件、钩子、CLAUDE.md 和设置文件，也不保存会话；启动时核对工具列表，只要有任何工具可用，这一轮就停止。从 Claude Code 会话里启动桌宠时，父会话的连接信息不会传给子进程。实现见 electron/claude.ts。
在「连接与声音」管理角色卡，可保存身份、背景、说话方式、开场白、示例和心情数值模板。选择角色会开始新对话，两个窗口同步；本机模型关联可选。v2 导出包含人设与参数，不携带实时状态、私人聊天、模型文件或连接密钥；生成方法见数值卡手册。模型红晕定位校准独立保存在本机。
源码 ZIP 与应用包预装 Gene 模型、10 张必要贴图、40 个配套动作及 13 个精选动作：100STYLE 待机 5 个、MPI EMBM 会话手势 5 个、GENEA 2022 手势 2 个、fnoji Split Dance 1 个，支持离线首次载入与动作切换。在「模型与动作」的「预装动作库」按动作类型、多个 tag 或英文名称筛选，再选择动作，点击「预览动作」在控制窗口试播；「停止预览」恢复原动作，「启用动作」才保存并同步桌宠。点击动作下方的 tag 也能筛选，多个 tag 同时匹配，可逐个移除或清除筛选。「使用预装 Gene」恢复模型和 Stand 动作，同时保留聊天连接、人设等其它设置。已有用户配置不会被首次启动逻辑覆盖。本项目不包含 Uka，也不把用户私人模型或本机测试素材加入源码和发布物。
动作库的「应用到」可选择身体姿态、手势或面部表情，分别启用、清除和预览。例如保持 Stand 身体姿态，同时播放会话手势及 Happy 表情；换一个 pose 不会清除另选的表情。手势只覆盖对应上身骨骼。旧配置继续整段播放，首次分层保留原动作的表情来源。
浮窗工具栏的音乐按钮用于「系统声音律动」：手动开启后，只在本机分析当前系统声音，根据鼓点强弱和频段变化持续轻微摇摆、弹动或点头。在外观设置中可调整“音乐律动强度”，为0时不做律动；朗读、直接互动和手选头部动作优先。静音后平滑停下；再次点击立即停止声音分析，当前律动短暂淡回底动作，隐藏桌宠或退出时释放。默认关闭，不录音、不把系统声音发送给聊天；目前仅 Windows 支持。
公开资源按来源、角色和固定版本保存在 assets/bundled/mmdagent-ex/gene/，分为 model/、motions/pose/、motions/expression/、motions/reaction/ 和 metadata/。文件使用英文命名，原始名称、来源、SHA-256 和 tags 保留在清单中；PMX/VMD 内部名称、贴图引用和原始文件内容不改写。Gene 素材保留 CC BY 4.0、作者署名和完整上游说明，不适用代码的 MIT；角色另有商标与设计权声明，其它商业角色用途按作者说明联系。其它模型可能仅部分匹配这些动作。详见预装资源与授权。
VMD 骨骼、表情动作通过 Three.js MMD 支持播放，不导入 VMD 相机或音频。在「模型与镜头 → 局部物理」可独立开启头发跟随与胸部弹性，分别调整强度，另选物理质量；两项默认关闭，只在模型具备对应结构时可用，效果在桌宠窗口生效。Gene 支持头发、不具备本模块需要的胸部结构。关闭或隐藏会释放局部物理对象，不修改原模型或动作，详见模型物理手册。模型的骨骼、表情名称不同，呼吸、眨眼、视线和张嘴效果可能不同。语音输出默认使用系统 speechSynthesis 可用音色，也可自行配置下述百炼情感语音；嘴型是说话状态动画，不是逐音素同步。
语音输入默认用本机识别（第一次在「语音输入」里下载识别组件，声音不离开电脑）；也可以改用 OpenAI 兼容的 POST /audio/transcriptions，接本地或云端服务，应用发送 16kHz 单声道 WAV。安装包不内置识别权重；仅开启时申请麦克风，关闭立即释放。朗读期间暂停收音分段以减少回声，输入与输出开关独立。
语音输出也可选「百炼情感语音」，提供 qwen-audio-3.1-tts-flash 与默认音色 longanlingxin_v3.1。在「连接与声音」打开百炼控制台，使用自己的账号取得同地域 Key 和 API Host；粘贴完整接口网址也可识别。首次使用会提示这个选项，不会自动开通或调用。音色、情绪指令与语速跟随当前角色和模型保存；系统语音可随时切换。Key 只由主进程调用并以系统存储加密，不随安装包分发。试听会显示网络首音频包耗时和浏览器估计的开始播放耗时，实际结果随服务与网络变化。百炼配置说明
语音输入、屏幕共享和摄像头共享每次启动均关闭，不保存开启状态。屏幕共享会在发消息时获取桌宠所在显示器的最新画面；摄像头共享开启期间保留设备、最多每秒更新一次本地缓存，发消息时使用最新帧。关闭共享会清除画面缓存和本轮视觉对话上下文。图片只随当前请求发送，不写聊天历史；选择云端后端时，消息及附图会发送到该服务，语音片段会发送到配置的转录服务。附图只随当次 Claude 请求发送。
设置保存在 Electron 用户数据目录，API Key 使用操作系统安全存储加密；安全存储不可用时拒绝持久化非空密钥。模型保留在原目录，应用只记录引用。聊天记忆、她的日记和用户画像保存在本机配置目录里（可以在应用里查看和删除）；体验记录默认关闭。外部服务的记录行为由对应服务决定。
默认 30 FPS，支持 24/30/60 FPS，像素比上限 1.5。常见图片贴图按最长边 1024 缩小后再上传 GPU，保留小贴图，不修改原文件；TGA 仍走原始加载器。控制窗口隐藏后释放预览模型，重开时重新载入；桌宠继续运行。局部物理默认关闭，质量档调整计算预算、强度单独调节；不启用大型后处理。复杂模型、多材质和顶点变形仍会增加 CPU/GPU 和显存占用；未提供硬件无关的占用或延迟保证。
装好以后想改她的性格、换模型、调行为，或接着开发，看 装好以后：自己改她、接着开发。
项目根目录的 CLAUDE.md 会告诉你的 Claude Code 这个项目的约定，直接用大白话让它帮你改就行。
pnpm typecheck
pnpm test
pnpm smokepnpm smoke 启动真实 Electron，用本机临时 HTTP 服务检查模型列表、流式回复、取消、隐私边界和窗口操作。设置 MMD_TEST_MODEL 为自己的 PMX/PMD 路径，可额外验证模型、镜头和原创 VMD 夹具；测试输出只写入忽略的 .local/。可用 MMD_TEST_EXE 指向解包后的应用检查打包版本。真实本地服务测试需显式设置 MMD_TEST_LOCAL_URL / MMD_TEST_LOCAL_MODEL；真实 Claude Code 聊天检查用 SOFT_HEARTS_CLAUDE_LIVE=1 pnpm exec tsx --test tests/claude.test.ts（会用你自己的额度）。
结构见 架构。试验心情、悬浮摸头、普通点心与文字记忆已接入；更多闲置动作按后续请求迭代。
聊天走你自己的 Claude Code。