说明书介绍了打卡、计时、任务与悬赏、书签、四档强监督巡逻、离线语音、YuQuiz 联动，以及小鹿的位置与提醒机制；其中“今日、任务、记录、统计、书签”均使用当前版本的真实界面和虚构演示数据。可以直接下载 PDF，也可以在下方展开阅读。
展开完整图文说明书（18 页）
共学日记不是先写好需求文档、再由专业团队开发的产品。它从一张角色图和一个很小的念头开始，由一个没有编程经验的人通过持续对话、测试和取舍，一点点 vibe coding 出来。
最初只需要准备一张能说明人物外形的参考图，再让 Codex Pet 的制作能力补全动作。当前项目使用的是 v2 宠物素材：
pet.json描述角色名称、图集和动画版本；spritesheet.webp是一张8 × 11的精灵图；- 图集中包含待机、跑步、挥手、跳跃、失落、等待、专注、回顾等标准动作，以及 16 个看向方向。
这一步只负责“让角色动起来”。你可以先在 Codex 中反复调整形象与动作，确认人物没有走样，再把最终的 pet.json 和 spritesheet 放进本项目的 assets/xiaolu/。Codex Pet 是素材的起点，不是运行依赖；打包后的应用可以完全脱离 Codex。
有了动画素材以后，本项目重新实现了桌面外壳：
- 创建透明、置顶且没有系统边框的 Electron 窗口；
- 只让人物和气泡附近接收鼠标，避免透明区域挡住其他程序；
- 根据鼠标方向选择视线帧；拖动或自动移动时播放左右跑步；
- 处理 Windows 缩放、屏幕边缘、工作区和窗口坐标，避免角色漂移或越拖越偏；
- 通过托盘、开机自启和 MSI 安装包，让它像普通软件一样运行。
如果只想做一个会动的桌面角色，到这里已经足够。后面的学习功能都建立在这个稳定的桌面窗口之上。
这个项目真正发生变化，是从“桌面宠物”改成“桌面学习搭子”以后。定位确定后，功能才有了统一的判断标准：她不是等待喂食的宠物，而是替一位现实中的朋友陪伴和监督学习。
于是交互被尽量压缩成几个自然动作：双击开始或结束学习，右键打开日记，拖动改变位置；固定时间只确认“我在”，任务、悬赏和书签负责留下长期成果。没有商店、金币、等级和复杂养成，因为这些内容虽然常见，却会让学习工具反过来消耗注意力。
核心学习数据集中在 src/game.ts，包括计时、打卡、任务、悬赏、书签和统计；窗口、动作、通知、语音、YuQuiz 联动与自动移动主要位于 src/main.ts。本地状态保存为 JSON，不需要服务器或账号。
一个提醒通常不是“弹出一句话”这么简单，而是一段状态变化：
检测到场景 → 选择台词和动作 → 必要时移动到提醒位置
→ 等待回应或超时 → 恢复学习驻守点或自由位置
把它写成明确状态后，才不会出现动作互相覆盖、网页关闭后无法返程、重复计时或提醒无限触发等问题。
YuQuiz 在 127.0.0.1:8765 暴露少量 companion 状态，共学日记只读取“页面是否打开、是否处于有效学习、今日题量”等摘要。题目、答案、笔记和密钥都不需要共享。
这种方式很适合继续扩展：你的背词软件、阅读器、番茄钟或其他网页工具，只要提供一个很小的本机接口，就可以驱动桌面角色的计时、动作和提醒，而不必把两个项目强行合并。
最省力的路线不是从空项目重写，而是 Fork 本仓库后逐层替换：
- 换角色：替换
assets/xiaolu/pet.json和spritesheet.webp。 - 换图标与收藏物：修改
assets/icons/和assets/bookmarks/。 - 换声音：按现有文件命名替换
assets/voice/，或在src/main.ts中调整语音触发关系。 - 换规则：在
src/game.ts修改打卡时间、任务、奖励和统计；优先为规则补测试。 - 换界面：修改
src/renderer/panel.html、panel.css和panel.js，继续保持一屏布局或设计自己的信息结构。 - 换联动：参考 YuQuiz 的本机 HTTP 状态接口，为自己的学习工具暴露最少量的数据。
- 测试与打包：运行
pnpm check，确认后用pnpm package:msi生成安装包。
建议第一次只替换角色、名称和一句提醒，先让开发版正常运行。确认“这个角色确实像你想要的人”以后，再逐个增加功能。一次改十件事通常不会更快，只会让问题变得难以定位。
“拖动不舒服”很难直接修；“按住十秒后每秒向右下偏移几像素”就能调查。“页面不好看”也很宽泛；“不允许滚动条、所有内容必须在固定高度内显示”才是可以验证的约束。
向 AI 描述问题时，尽量包含：发生前的状态、具体操作、实际结果、预期结果、截图，以及问题是否能稳定复现。
连续试错最容易把一个小问题改成多个问题。比较可靠的对话方式是：
先不要改代码。请阅读相关实现并复现问题，说明根因、涉及的状态和坐标系。
确认根因后再给出最小修改方案，并列出必须保持不变的行为。
等解释能够对应实际现象，再让 AI 动手。涉及窗口拖动、计时、跨进程通信和多状态切换时，这一步尤其重要。
增加中央提醒时，必须说明不能覆盖自由位置和学习驻守点；增加 YuQuiz 自动计时时，要说明手动时长仍需累计；调整页面高度时，要说明不能重新引入滚动条。负面约束往往比“新增什么”更能保护已经稳定的功能。
每完成一组相关功能再升级版本，不要每改一个像素就发布。核心规则放在纯逻辑文件中测试，视觉修改则必须真实打开页面检查。提交前至少运行：
pnpm check如果某次尝试让角色形象走样或交互更糟，应果断回到上一个稳定提交。vibe coding 的优势是试验成本低，而不是所有试验都必须留下。
AI 很擅长查代码、补状态、写测试和机械调整，却不知道哪一句话像你的朋友、哪个动作显得生硬、什么功能会反过来造成负担。这些判断无法外包。这个项目能逐渐形成统一性，主要依靠不断使用、指出细微的不协调，并主动删掉不需要的功能。
开发时不要把真实日记、数据库、录音源文件、密钥和本机备份交给 Git。先配置 .gitignore，提交前查看 git status，发布前再搜索一次绝对路径和密钥格式。开源的是程序与可公开素材，不是使用者的生活记录。
- 在 Releases 下载最新的
xiaolu-study-mate-*-x64.msi。 - 双击安装；首次启动后，小鹿会出现在桌面并默认随 Windows 登录启动。
- 双击小鹿开始或结束手动学习计时，右键打开共学日记，拖动可以调整自由位置。
安装包暂未使用商业代码签名，因此 Windows 可能显示“未知发布者”。
学习记录默认保存在：
%APPDATA%\xiaolu-desktop-pet\xiaolu-study-state.json
应用没有账号、排行榜或云同步。可选的 YuQuiz 联动只读取本机 http://127.0.0.1:8765 提供的学习状态与当日题量；不会读取题目、答案、API Key 或个人笔记，也不会把数据上传到外部服务器。卸载前如需保留日记，请备份上面的状态文件。
仓库不会收录使用者的日记、任务、打卡、位置、数据库、日志、密钥或备份。原始肖像、源录音和私人制作文件也不随项目发布；常见的本地数据路径已经加入 .gitignore。
需要 Node.js 20 或更高版本，以及 pnpm。
git clone https://github.com/UniqueYu8988/XiaoLu.git
cd XiaoLu
pnpm install
pnpm check
pnpm start生成 Windows x64 MSI：
pnpm package:msi安装包输出到 release/。MSI 的 upgradeCode 已固定，后续版本只更新版本号，不要更换它。
assets/ 图标、角色动画、书签与离线语音
docs/ PDF 说明书、预览长图和版本说明
scripts/ 构建、说明书与 MSI 辅助脚本
src/game.ts 学习记录、打卡、任务、书签和统计逻辑
src/main.ts Electron 主进程、窗口、联动、移动与自启动
src/renderer/ 桌面角色与共学日记界面
tests/ 核心状态逻辑测试
- 角色动画素材最初按照 Codex v2 动画宠物素材规范整理；应用安装后可以完全脱离 Codex 独立运行。
- 独立桌面窗口的早期实现参考了 OpenPets 的思路，详见 THIRD_PARTY_NOTICES.md。
- 共学日记的学习计时、打卡、启动监督、任务、书签、语音、YuQuiz 联动和本地存储均在本项目中重新实现。
共学日记已经完整开源。项目原创的代码、角色动画、图标、书签、离线语音、文档和说明书素材统一采用宽松的 MIT License，可以自由使用、修改、分发或制作自己的桌面搭子；分发时请保留版权声明和许可证。
个人学习数据不会随仓库公开。完整授权与隐私边界见 ASSET_LICENSE.md，第三方声明见 THIRD_PARTY_NOTICES.md。