一个可以安静陪伴工作的互动桌面，同一个程序内切换「锦鲤池」「赶海」「猫咪庭院」「财源广进」「电子木鱼」五个主题。使用 React + Canvas 2D / WebGL + Electron，素材与音乐在本地离线加载。
当前版本 v4.3 / 4.3.0。完整源码、运行素材、原稿、存档逻辑、macOS 原生桌面代码与验证脚本一并提供；保留既有存档键和桌面行为。
- 电子木鱼：新增第五个主题，沿用原有主题切换、窗口、设置和存档；支持手动/自动敲击、八款材质、独立音色、四季与日夜灯火。
- 愿想与静念：自定义敲击文字、5/15/25/45 分钟计时；工具栏使用“愿想”“静念”，独立“记录”面板已移除，已有敲击次数和存档保留。
- 木鱼美术与动作：暗木禅房、分层灯具、手串、香烛、连续香烟和暖光；按下启动敲击，接触时统一计数/发声/飘字，修正灯位与接触点。
- 同步当前项目：包含此前主题独立日夜、猫咪道具收纳和音效、财神香炉、漂流来信等本地修改；应用标识及现有存档键不变。
正常启动和桌面版使用原画猫咪。三维猫的外观与部分动作尚未通过视觉验收，只有显式添加 ?cat3d=pilot 或 ?cat3d=all 才开启开发预览；本次不将三维模式作为已完成的正式替代。三维源码、素材、归属说明和重建工具保留，见 三维猫资产说明。
- 水下鱼群：移动水纹位于鱼身上方，按深度调节透水颜色、明暗和对比，保留原有大小、位置及点击范围。
- 连贯尾摆：原有鱼姿态缓存之间连续混合，保留当前游动、捕捉和礁石避障规则。
- 礁边轻浪：沿真实礁石轮廓绘制细窄水边、推进和消退的泡沫，替代有方形边界的贴片。
- 漂流来信：无待拾取来信时，约 4–6 分钟活跃等待后送来下一封；暂停和离开不补发。修复礁石加载后的漂流路线缓存。
- 赶海礁石避障：鱼按当前画面中真实的出水礁石轮廓绕行，检查整个鱼身和游动路径；旧存档中处于岩面的个体就近恢复到安全位置，保留 ID、数量和奖励。
- 舒缓海浪：独立水纹持续起伏、近岸浪缓慢推进，礁石、沙地和海底保持稳定。继续使用原潮汐周期及岸线，减少动态设置仍然有效。
- 猫咪上下台阶：在安全落脚点之间短暂渐隐渐显，覆盖石阶、木廊及爬架；保留走路、任务、暂停和存档行为。
- 猫咪背向步态：使用各款猫自己的原画脚掌和毛皮补齐远侧腿，四肢按既有步序交替运动，避免只动一侧。
- 财源广进：完整五路财神背景，供桌默认摆设；上香、供灯、供品与添茶、简洁心愿牌、长按拖动与自由布置、撤销和收纳、静心与日夜。小金蟾自主活动，投铜钱后拾取送入聚宝盆；灯笼、流苏、薄云、微尘和流动香烟让场景保持细微动态。
- 猫咪庭院：保留原画轮廓与脚掌，草垫从前沿起跳进出，按体型调整起落，落稳后前往睡位。惊鹿、背景音乐和持续风声已移除，仅保留轻柔互动声、偶发猫叫与鸟鸣，服从总静音和暂停。此处为 v4.0 历史表现；当前默认原画与三维开发预览边界见上文。
- 财源广进画面铺满：保持人物、完整匾额和物件的原有比例与坐标，额外窗口区域使用 AI 扩图补出的屋檐、桌前和侧窗，所有图层等比绘制；已移除旧的镜像拉伸边缘。
- 原有锦鲤与赶海：继续提供投食、绘制外观、潮汐、捕捉、救助、拾贝与漂流瓶等玩法，存档互相独立。
完整 v4.0 发布说明 · 财源广进实现记录 · 猫咪原画步态与配乐
建议 Node.js 22 LTS 与 pnpm。安装依赖后启动现有程序：
git clone https://github.com/cyberdaddyleo/yutang.git
cd yutang
pnpm install --frozen-lockfile
pnpm dev按终端输出打开本地地址。桌面版与检查命令：
pnpm test
pnpm test:desktop
pnpm build
pnpm desktop
# Apple Silicon Mac（需要 Xcode Command Line Tools）
pnpm package:mac声音需要首次点击以获得播放许可。存档保存在本机；不要清理浏览器站点数据或修改应用标识以免丢失已有存档。仓库不包含个人存档、依赖目录、构建缓存或编译安装包。素材许可与生成来源随相应素材目录提供，未将全部图片或配乐声明为 CC0。
macOS 原生桌面层支持鼠标穿透、窗口层级与菜单栏控制；当前使用本地 ad-hoc 签名、未进行 Apple 公证。Windows / Linux 可运行网页，原生桌面穿透尚未实现。原稿与音频体积较大，首次下载需要一些时间。
以下内容记录对应版本当时的行为；当前交互与设置以 v4.3 为准。V3.0 与 V2.0 保留供查阅。
- 走路四条腿齐全：远侧前腿原来被放在肚子中间，看起来像少了一条前腿；现在按三分之四视角放到脸颊下方，远侧后腿放到腹下，并稍压暗以表现前后关系。腿粗按16款原画逐一测量，短毛圆胖的英短不再“踩高跷”。
- 重绘跳跃：上下石阶、木廊、暖石和爬架改为「蓄力下蹲 → 后腿蹬地、前腿收起 → 腾空前伸 → 前爪先落地 → 身体缓冲」。下跳低头探爪，上跳抬头；弹道上跳晚到顶、下跳早到顶，不再原地悬浮。按实际高差分三档：几厘米的低沿直接迈过，小高差轻跳，真正的台阶才完整起跳。
- 树下视角：树冠在猫的上方，猫走到树下时叶子只在猫身上淡淡透过、保留斑驳树荫，不再整只被吞掉；树下的猫也能直接点中。
- 不再堵车：坐在石阶上的猫会给要上木廊、回窝、喝水的猫让路；两只猫在窄处顶牛时，一只先侧身让开、随后继续原来的目的地。
- 玩具面对面：毛线球、猫抓板、玩具小鼠和逗猫棒，猫会站到玩具旁并面朝它，伸出的前爪正好落在玩具上。
改动说明、前后对比图和验证结果见 3.1.0 优化说明。
猫咪行走改用共用的四足步序与独立关节：以实际路程推进脚步，支撑脚留在地面，摆动脚抬起再落下。转向或脚点超出腿的伸展范围时重新落脚，身体不再随平地步频上下弹跳；石阶、木廊和草垫之间的真实高度跳跃继续保留。各外观使用自己的毛皮材质，已有猫咪与存档继续兼容。
樱花与其他季节树冠增加与原画对齐的透明前景，猫咪经过时被花叶局部遮挡，花叶空隙仍可透出猫身。猫咪明暗随树荫和日夜变化；脚底接触影与躯干投影跟随落脚位置，起跳时阴影留在地面。树冠素材合计约 95 KB，采样与合成结果缓存复用。
动作仍为手绘素材上的二维关节动画，朝向来自前、后画稿与左右镜像，并非任意角度的三维猫模型。光照改在小尺寸猫咪缓冲区内合成，降低多猫同屏的绘制成本；实际运行检查、4K 采样条件与限制见 2.8.0 验证记录。
2026-10-11 更新：本节所述持续微风与夜间虫鸣现已删除；当前仅播放短互动声、偶发猫叫与白天鸟鸣。
设置中的「庭院声音」加入轻柔持续的微风底声，使用柔化后的风吹树叶录音无缝循环。白天偶尔响起真实小鸟叫声，猫咪约隔 70–150 秒轻轻喵一声；各类环境声错开，手动互动的反馈优先。夜间鸟鸣收起，保留更稀疏的轻虫声，冬夜关闭虫鸣。
微风与单次互动音效分别管理，共用原有音量与静音设置；暂停、隐藏、外观编辑、离开庭院时停止，恢复后不会叠加循环或补播。新增加的风声与鸟鸣资源合计约 588 KB，本地离线播放，CC0 来源和处理记录见 public/assets/cats/audio/sources.json。
四季变化延伸到中央石板庭院：春天嫩苔与落樱、夏天绿荫、秋天暖色苔缝与落叶、冬天沿苔藓与石缝的薄霜。地面的静态季节细节在关闭飘落粒子后仍保留，空中花叶也会飘过中央。
保留原场景的高清石板纹理和设施坐标；背景只在季节、时间或分辨率改变时合成，继续使用统一坐标与渐变切换。原有猫咪、道具和存档格式不变。实际开发环境与桌面包验证见 2.7.4 四季记录。
首页只保留「桌面」和「沉浸」，声音统一在「设置 → 庭院声音」中控制。开关、音量、7类试听与原有静音偏好继续保留。
猫叫、呼噜、吃食和抓板改用经过频段柔化与首尾淡化的真实录音；毛线球、小鼠和羽毛改用布料与柔软轻敲声。9个短WAV在本地离线播放，总计约272 KB，来源、CC0许可及剪辑区间保存在 public/assets/cats/audio/。鸟鸣与虫鸣仍为低音量、稀疏合成声。读取途中静音、暂停或离开主题，不会补播迟到的旧声音。
背向步态新增独立的远侧后腿，使用同一只猫的脚掌与毛发画稿，左右后脚交替支撑与抬起，身体不换帧。已有两条后腿的外观单独校准关节点，避免重复加腿；自定义毛色、胖瘦和昼夜光照继续作用于腿部。
庭院恢复等比铺满窗口，取消上下模糊填充带；背景、猫咪、道具与点击使用同一个裁切映射。较窄的窗口会正常裁去画面两侧，原画不会被拉伸。
石板地、石阶、木廊、草垫和暖石的高度边界会触发蹲伏、起跳、落地，随后继续原来的互动或回窝路线。腾空期间的新指令会在安全落地后替换旧任务；保存和切换主题不会留下悬空位置。
取消四幅整猫画稿反复混合的步态，改为固定朝向画稿上的连续四肢、头尾运动，按实际行进距离推进脚步，减少毛色与轮廓闪动。动作类型与朝向仍来自二维画稿，连续关节变形并非三维骨骼模型。验证与限制见 2.7.2 修复记录。
首页「声音／静音」可直接控制庭院声音；设置中增加音量百分比、真实播放状态，以及猫叫、呼噜、进食、毛线球、抓板、羽毛和玩具小鼠的试听。首次使用请开启声音，浏览器需要一次点击来允许播放。已有静音偏好保持不变。
修复点击声占用通道导致轻抚呼噜丢失的问题；各道具在猫咪实际到达互动后发出对应声音，行走和落地有低音量脚步。提高过低的默认输出，保留短促渐入渐出和峰值余量。白天偶尔鸟鸣，夜间稀疏虫鸣，冬季关闭这些环境声；没有持续白噪声。声音均为本地合成，不依赖联网下载。
暂停、编辑、隐藏和切换主题时停止当前声音及待播反馈，避免旧主题声音残留。
猫咪编辑改为体型大小、胖瘦、耳朵大小/形态与眼睛颜色调节，提供8种性格，移除导入与自由画笔入口；原来确认保存的毛色继续保留。外观参数在缩略图、庭院和动作中一致保存。
春季换为樱花树冠并有随风花瓣，夏季绿荫、秋季金叶、冬季薄雪；日夜简化为自动、白天、黑夜，旧清晨/黄昏存档迁移为白天。夜间保留柔和月光与可关闭的萤火虫。
步态取消长时间停帧，连续衔接四相动作，增加转向缓冲、弯道减速与准确落脚。详细操作与验证见 2.7 交付记录。
同一个程序切换锦鲤、赶海、猫咪庭院，三主题独立存档。猫咪新增16套独立动作图集：前/后向四相步态、卧睡、进食、洗脸、抓挠和扑玩，动作按真实行进距离驱动，自定义毛色跟随身体分区。
「回窝休息」现在会走过石阶、到草垫或暖石上睡觉，留在画面中。石阶、木廊、草垫、暖石、水碗与爬架下层都有实际交互位置。爬架包含走近、蹲伏、起跳、落稳和返回地面的过程；「收回收藏」另行腾出活动位置。小窗口完整显示庭院，设施和点击保持对应。
补齐波斯、异国短毛、孟加拉、阿比西尼亚4款独立外观，共12种品种外观和4种田园花色。春、秋、冬及夜景画稿与原高分辨率庭院组合，猫咪/道具接受环境光。增加限频的短喵声、呼噜与道具轻触，不循环播放噪声。
操作、实际验证、文件及限制见 猫咪庭院交付记录。生成来源、真实像素尺寸与压缩记录见 美术记录。图像由内置图像生成工具制作，该工具没有提供可指定或核实的“image2.5”型号接口。
需要 Node.js 22.12 或更新的 LTS 版本与 pnpm。本次维护环境使用 pnpm 11.19.0；首次安装依赖需要联网。macOS、Windows、Linux 均可先运行网页预览。
git clone https://github.com/cyberdaddyleo/yutang.git
cd yutang
# 未安装 pnpm 时：npm install -g pnpm@11.19.0
pnpm install --frozen-lockfile
pnpm dev打开 http://127.0.0.1:5188/。开发服务固定使用 5188 端口，若启动时报端口占用，请先停止占用它的进程。网页预览可以体验五个主题，但系统桌面层与鼠标穿透需要桌面应用。
在 Apple Silicon Mac / macOS 12 或更新版本，安装 Xcode Command Line Tools 后可运行：
pnpm desktop # 构建前端及原生模块，启动桌面应用
pnpm package:mac # 构建 release/mac-arm64/浮生锦鲤池.apprelease/、dist/、node_modules/ 和原生编译产物不随源码提交；克隆后不会直接带有可双击的 .app 或工作目录启动脚本。应用构建成功后可拖到“应用程序”文件夹。Windows/Linux 的原生桌面层尚未实现；Intel Mac 构建未在本次验证，架构说明见 桌面开发文档。
项目包含运行所需的离线图片和声音，字体使用系统已有字体。天气与城市查询需要联网，无需自行填写 API key。仓库包含运行素材和美术原稿；构建时会排除不参与运行的猫咪原稿 PNG。请保留背景后备图与音频文件。账号、云同步及跨用户瓶信服务未接入，收藏、草稿与瓶信均保存在本机。
- 轻点池塘投食，移动鼠标会让附近锦鲤避开；空格可向池塘中央投食。
- 「四时」切换春樱、夏荷、秋叶、冬雪；自动模式按系统日期及城市半球切换。
- 「天气」切换城市、实时天气或手动晴/云/雨/雪/雷雨。雨雪、雷雨会减慢游鱼，雪天和冬季有薄冰。
- 「日夜」选择自动、白昼或夜色。晴日有蝴蝶，夏日有蜻蜓，非冬季的夜晚有萤火虫。
- 「画锦鲤」支持颜色、画笔大小、橡皮、撤销、重画、命名和放入池塘；最多保存 12 尾自绘锦鲤。切换收藏页不会丢失草稿；关闭编辑器会放弃未保存草稿。
- 「设置」调整 3–24 尾原生鱼、溪流水声、减少动态、30 帧节能模式与暂停。
- 「沉浸」隐藏界面，按 Esc 或点击右下角按钮返回；H 也可切换。
- 补齐中央岩群与右侧礁石的完整轮廓，出水岩面使用同位置的干燥贴图；潮线与浪花从石头四周经过，不再横切岩面。
- 重描右侧小岩石边缘，修正原椭圆遮罩错位导致的水色补丁。
- 岩石前景、动物避障和互动判定共享同一组轮廓，保留原有涨退潮范围；小鱼分散从合法海面入口进入，螃蟹沿岩石边绕行。
- 旧存档中位于新增岩石范围内的贝壳和石缝鱼会恢复到合法位置，保留原实例、收藏和救助记录。
验证结果见 2.4.1 修复记录。
- 写信时在同一张信纸上切换「打字／画笔／橡皮」。文字与笔迹一起缩放，放流记录也按同样的排版阅读；原有文字、图画草稿与记录兼容。
- 放流后收起面板，瓶子沿弧线轻轻飞入海里，溅起小水花，再随海水漂远。减少动态时使用简化效果；暂停、隐藏和切换主题不残留动画。
- 修复漂流瓶难以拾取：点击区域跟随可见瓶子，缩小窗口也至少保留 44 像素的点击范围；轻微拖动仍可拾取。两种互动模式均可读信，自己的瓶子打开对应放流记录。
- 接入提供的 29 张完整手写信纸，随机从未收藏的信中抽取。已读记录单独持久保存，重启也不重复；29 封收齐后不再投放重复来信。
- 信件从约 68 MiB PNG 压缩到约 5 MiB WebP，保留原尺寸与透明边缘；按需加载，存档只保存内容 ID。原始 PNG 不放入游戏包。
素材清单见 信件压缩说明，运行结果与复现命令见 2.4 验证记录。
- 将银色、青绿、黄尾、蓝鳞四种侧腹明显的鱼更换为同配色的背部俯视素材，向任意方向游动都不会把白色腹面翻到上方。原始素材保留，修正版为独立
-dorsal.png文件。 - 按新素材更新裁切范围与头尾轴，摆尾、鱼鳍、捕捉命中和石缝游出继续共用同一姿态。无需重置存档，旧小鱼和小桶收藏直接使用修正后的形象。
216 项单元测试、5 项桌面策略测试通过。开发版与 macOS arm64 2.3.2 正式包均检查了 7 种鱼四方向共 28 个姿态与点击轮廓；修正后的黄尾小鱼实测捕捉失败快速游开、第三次成功入桶，逃逸样本均位于合法水域。素材与生成提示词见 俯视素材说明。
- 捕捉游动小鱼失败后，它会加快摆尾、快速游开，再自然减速；逃逸仍受海水、礁石和身体宽度约束。
- 小桶为每种动物增加独立趣味介绍，例如小海虾「看起来很美味」、小河豚「吃下去可能会没命」、小章鱼「八只手，也不想多加一份班」。原图鉴的生境说明保留。
- 游动鱼前两次躲闪、第三次捕捉的规则，以及搁浅鱼虾一次拾取、小桶容量、放生和存档规则保持兼容。
216 项单元测试、5 项桌面策略测试通过，macOS arm64 2.3.1 正式包签名验证通过。真实时钟下实测逃逸峰值约 100 场景像素/秒，前 600 毫秒游开约 48 场景像素，随后回落至约 17 场景像素/秒；134 个路径样本均在合法水域。正式包已验证第三次捕捉、搁浅拾取、满桶、重复点击、存档重载、原锦鲤存档，以及全部 15 种小桶动物介绍和窄窗口排版；测试均使用独立档案。
- 高潮保留原来的海水覆盖范围；低潮向海中退开，露出更宽的湿沙滩，岸边保留浅水过渡与浪花。新增与原构图对齐的湿沙地形，原礁石、植物和固定潮池继续保留。
- 鱼身、尾鳍和胸鳍分别运动；蟹腿交替迈步，甲壳保持稳定，停步后自然收腿。沿用原来的水彩动物素材，动作幅度按实际小尺寸调整。减少动态与暂停仍有效。
- 「漂流瓶 → 写一封信」新增画纸，提供六色画笔、三档粗细、橡皮、撤销和清空；可以写字配画，也可以只画一张小画放流。
- 抬笔保存草稿，窗口缩放不改变笔迹位置；放流记录保留原画。旧的纯文字信件继续可读。存储失败时保留当前草稿并提示重试；未成功保存的内容无法保证在退出程序后恢复。
漂流信绘画和文字均保存在本机，不发送给其他用户。每张画纸最多 160 笔、6000 个采样点，超限会提示撤销或清空，不静默截断已保存的画作。
214 项单元测试和 5 项桌面策略测试通过；正式包已验证绘画、重载、放流、动画和潮位判定。4K 常态约 60 帧，手动涨潮短时平均约 58 帧，初期仍有一次约 0.25 秒的帧调度空档，具体结果与边界见 2.3 验证记录。
- 无人操作时保持完整 30 分钟自动周期：涨潮 10 分钟、高潮 5 分钟、退潮 10 分钟、低潮 5 分钟。
- 「潮汐 → 开始涨潮 / 开始退潮」从当前水位立即连续变化。完整涨退约 30 秒，剩余距离越短，用时越短；到位后进入正常高潮或低潮停留，再继续自动周期。
- 中途点相反方向，保留当前水位后立即转向；连续点同一方向不会重启计时，已经到位也不会延长停留。
- 面板与首页同步显示当前方向、潮位和到位倒计时。手动调节进度可随存档恢复，切换主题和关闭窗口不会重置或补发离线奖励。
- 海水覆盖、动物生境、沙画冲刷仍共用同一潮位；手动涨潮时，岸蟹提前向安全岸边移动。鱼虾随潮退回，身体露出浅水边缘时及时进入搁浅，身体完全回水后才恢复游动。
本次 199 项单元测试通过。macOS arm64 2.2.2 正式包实测点击涨潮后 2.281 秒水位由 65.577% 变为 77.198%，水域绘制与生境的 756 个采样点一致；反向、同向重复、重载、切换主题、390×844 窄窗口、桌面 4K 画布与恢复控制通过。完整手动过程与自动阶段连接通过时钟夹具验证，没有等待真实 30 分钟。观察/捕捉、躲闪次数、搁浅拾取及旧锦鲤存档的桌面回归检查通过，均使用独立测试档案。
可运行 pnpm test、node electron/coast-smoke.cjs --packaged、node electron/coast-capture-smoke.cjs --packaged 重现逻辑与主要桌面流程检查。测试中的方向切换连续性改为比较点击时刻的真实潮位，避免每 500 毫秒更新一次的 UI 潮位读数造成误判。
- 贝壳和活体都在「捕捉」模式下收取。观察贝壳只解锁图鉴并提示切换模式，不增加收藏；捕捉露出的贝壳才计入永久收藏，仍不占小桶。
- 水中游动的小鱼前两次捕捉会躲闪，第三次有效尝试可捕到。快速双击只算一次，超过15秒未追捕后重新开始；逃跑沿合法水域平滑进行。
- 搁浅鱼虾在捕捉模式下一次捡进小桶；观察模式仍可一键救助。小桶满时不驱赶目标、不推进捕捉次数。
- 沙痕和石缝仍先揭开再互动。揭开不算捕捉，贝壳和动物不会因连点重复结算。
- 修复觅食鱼逃逸结束后突然回弹的问题：沿合法水域平滑游回，继续原来的潮汐任务。
本次190项单元测试通过；macOS arm64 2.2.1正式包实测观察/捕捉、涨潮三次抓鱼、搁浅鱼虾一击拾取、桶满保护、存档重载、390×844窄屏与沙滩画画通过。测试使用独立档案，未覆盖日常存档。可运行 node electron/coast-capture-smoke.cjs --packaged、node electron/coast-smoke.cjs --packaged 和 node electron/coast-sand-smoke.cjs --packaged 重现检查。
- 改善浅海水色与岸边细节：保留透底沙纹和原图海水，连续浅深过渡、细碎浪花与局部折射替换旧平铺水色和成排白线。
- 观察模式按住左键约 0.18 秒后拖动，可在空沙滩留下凹槽笔迹；石头和水上不会画线。短点动物仍用于观察、揭开与拾取，捕捉模式不会绘画。
- 海浪按实际覆盖位置逐段冲淡笔迹，涨潮淹没处也会消失；退潮不会还原已冲掉的笔迹。沙画属于当下的风景，切换主题或重启后不保留。
- 潮汐换为日光与浪线图标，潮汐控件使用正常箭头指针。
- 原「声音」工具替换成「漂流瓶」；海浪声音与音量仍在「设置」。漂流瓶面板提供拾到的信、写一封信、放流记录。
- 初次来瓶约在 2–4 分钟后从海域入口缓缓漂来，之后每约 8–15 分钟有一次相遇机会；海面同时最多一只来瓶，不因离线积累。轻点拾起即收藏，可以反复阅读。
- 可以写 1–600 字短笺、选择落款，保存草稿并放回海里；瓶子沿合法海水路线漂远，信仍在放流记录中。拾取与放流先保存再生效，重复点击不重复收发。
漂流瓶是本机离线体验：海边来信为原创预置短笺，自己写的信也仅保存在这台电脑，不会发送给其他用户。漂流瓶独立存于 mofish-bottles-v1，不会覆盖小桶、图鉴和原锦鲤存档。收藏和放流记录各上限 100 封，不覆盖旧信；同时最多 2 只自己的瓶子在海上。每次相遇安静进行，没有提醒任务。
详见 2.2 验证记录。
- 赶海观察模式显示手形，捕捉模式显示小钳子；点击界面控件和锦鲤主题仍用各自原有光标。
- 部分螃蟹、寄居蟹和贝壳藏在沙痕里，轻点 2–3 次才露出；石缝里的小鱼轻点一次游出。揭开过程不自动捕捉或奖励，露出后再按当前模式互动。揭开进度随存档保留。
- 小鱼分出水下深浅，大小、明暗、水色和波纹随深度调整。鱼头朝向逐种校准，鱼身连续摆尾、平滑转向与加减速；螃蟹侧行并交替停走，甲壳保持稳定。
- 一波波浪花向弯曲海岸推进、铺开、回落；高潮淹没绝大部分低潮沙滩，仍保留高岸与礁石。固定潮池继续保水，新增水域与动物生境共用潮位数据。
- 赶海底部工具改为「观察/捕捉、小桶、图鉴、潮汐、声音、设置」。「潮汐」可从当前水位开始涨潮或退潮，不会跳变水位；「声音」直接控制海浪与环境音量。原锦鲤的天气、日夜入口保留。
详细运行结果见 2.1 验证记录。
点击左上角主题名，在「锦鲤池」与「赶海」间切换。下次启动恢复上次主题；原自绘锦鲤、数量、大小、乌龟、城市和通用设置保留。
- 海岸潮汐每 30 分钟一轮：涨潮 10 分钟、高潮 5 分钟、退潮 10 分钟、低潮 5 分钟。右上角显示阶段、下阶段倒计时和潮位，不发送提醒。
- 海水沿弯曲潮线覆盖沙滩，退后留下短暂湿沙；右下潮池低潮也保水，出水礁石保持遮挡。水域绘制、动物生境和点击使用同一份世界坐标。
- 默认「观察」：点普通小动物和贝壳解锁图鉴，点搁浅鱼虾将它送回水中。贝壳被淹后渐隐，等待再退潮才能捡。
- 点击「观察」切换「捕捉」，可捡贝壳或将动物收进小桶。游动小鱼需多次尝试，搁浅鱼虾一次即可。小桶最多 12 只；支持单只、同种、全部放生。贝壳不占桶位。
- 图鉴保存首次发现、累计捕捉、拾取和救助次数，放生不清除记录。每只动物有稳定实例 ID，连点不会重复结算。
- 接入 17 种已有外观。鱼群从海域边缘随涨潮进入，退潮返回；每轮至多 3 只现有鱼虾可能留在近岸湿沙。没有及时救助也没有惩罚，下次涨潮自动恢复。
- 开启设置中的「治愈海浪声」可听离线海浪，雨声和偶发风、雷随天气变化；雷声仅在雷雨触发。静音、暂停和隐藏窗口会停止声音。
- 两个主题使用同一套首页、面板、桌面穿透和窗口控制。赶海沿用环境数据，当前底部工具使用独立的潮汐与漂流瓶入口；海浪声音和「四时氛围」在设置面板中。
潮汐起点、场景实例、小桶与图鉴保存在独立的 mofish-coast-v1 存档，所选主题存于 mofish-theme。原 fusheng-settings 与 fusheng-fish 数据格式、桌面应用 ID 和用户数据路径保持兼容。退出、切换、睡眠后的恢复直接协调当前潮位，不补演离线周期或发放离线奖励。
开发时点击潮汐信息，展开「开发调试」：暂停、手动潮位、四阶段跳转、60 倍加速、水域/生境/阻挡轮廓。手动潮位会自动暂停，可用暂停开关继续；「回到真实经过时间」退出调试。生产包不显示或暴露这些控件。
详见 2.0 验证与交付说明、素材实际条件、海浪来源与播放规则。赶海底图实际为 1672 × 941，渲染画布的 4K 尺寸不代表底图有原生 4K 细节。
以下为锦鲤主题玩法和历史改进记录。
- 鱼身使用保持长度的连续脊线，头部稳定，摆动从肩部传向尾部；转弯时后半身跟随弧线，再柔和回正。
- 花纹、自绘贴图、鱼鳞和鱼鳍都跟随局部身体方向，不再出现鱼身在摆、花纹却像固定贴纸的感觉。
- 尾鳍保持与尾柄相切，鳍尖稍后跟随；胸鳍独立划水。不同大小的鱼有不同摆尾频率，巡游带轻微发力与放松节奏，投食加速和减速保持连续。
- 绘画时鱼身保持稳定、空白起稿，画笔与入水后的花纹对应；不改变已保存的锦鲤或设置。
验证记录见 1.11 验证记录。
- 「桌面」移至右下角「沉浸」旁，主工具栏恢复六项；窄屏也不会与鱼群数量重叠。
- 按四季背景的真实岸线划定水域，跟随背景居中裁切。岸石、草岸上的点击不产生鱼食；鱼食散落与漂流也不得上岸。锦鲤与乌龟留出身体宽度，提前转向，忽略隔着岸石或无法靠近的食物。更换画质、缩放窗口后仍有效。
- 池塘和绘画区域使用正常鼠标箭头。
- 桌面应用顶部提供全屏、最小化、隐藏、关闭按钮；拖动顶部空白处移动窗口，拖动边缘改变大小。保留系统窗口边框与 macOS 红黄绿按钮。
- 隐藏保留程序，可从菜单栏锦鲤图标或 ⌘ ⇧ K 恢复；「关闭程序」和系统关闭按钮彻底退出。进入桌面模式前等待全屏退出完成，恢复窗口后可以继续移动、缩放。
验证记录见 1.10 验证记录。
- 雷声音轨只在雷雨且声音开启时允许启动；晴、云、细雨、雪天都不预播。切出雷雨、静音或音量归零立即停止雷声，并取消待播。
- 防止媒体加载较慢、连续切换天气或开发热更新后，旧播放回调让雷声重新开始。
- 同一 CC0 溪流素材重新剪成 120 秒长循环，只保留一小段低频鸣叫，减少“咕咕咕”反复出现；保留连贯流水、柔化突兀峰值，不改变播放速度或音高。使用新资源版本号，避免旧缓存。
- 93 项单元／桌面测试通过；真实媒体播放验证晴／云／雨／雪无雷声音轨、雷雨有远雷、切天气与关闭声音能停止播放。
录音处理方式见 声音说明。
- 绘鱼从无花纹的白色鱼身开始，保留真实鱼鳞、鳍和光影；「重新绘制」同样恢复空白，已保存的锦鲤不变。
- 首页工具栏新增「桌面」，在 macOS 桌面应用中一键铺到桌面，按 ⌘ ⇧ K 或菜单栏恢复控制。浏览器入口说明桌面应用的使用方式，并可进入沉浸观鱼。
- 小乌龟重绘为浅玉色圆壳、圆头、亮眼和圆脚掌；四肢独立缓缓划水，预览和池塘使用同一套造型。各部位预绘缓存，保持低开销。
- 调整七个首页按钮在窄屏及中等宽度窗口的排布，避免溢出或遮挡数量文字。
详见 1.8 验证记录。
- 换用新的 CC0 轻雨实录，柔化敲击、低频杂声及高频，修平循环接缝，并收低雨层音量；保留偶发风声和远雷。
- 桌面背景与鱼群统一使用实际显示像素，修复原先背景仍限制 4K、在 5K／6K 桌面被再次拉伸的问题。换屏或缩放变化会自动重算，设置中可看到两层实际尺寸。
- 轻微校正背景软边，保留插画风格。原始画面细节仍受已有背景图限制，没有把放大宣称为新增真实纹理。
- 锦鲤身体由肩部向尾部逐渐摆动，头部更稳；胸鳍独立轻划，转弯逐渐建立弧度。投食加速时摆尾随之增强，恢复巡游时放缓。
86 项逻辑／桌面测试通过；满池雷雨的 4K／模拟 5K／6K 中，背景与鱼层保持相同像素尺寸，本机约 60 FPS。详见 1.7 验证记录。
- 取消池底和岸边的大范围贴图位移。仅在独立的草叶／树叶区域做小幅、根部固定的风动，鼠标靠近可轻轻拨动。
- 雨幕按完整视口生成，预留四边余量，覆盖岸边、画面底部与窄屏；雨滴落在水面才出现水圈，干燥石头和植物上不画水圈。
- 紧贴上方石岸、左岸草丛及右下岸石添加独立的平行细波，沿岸缓缓扩散、渐隐。改变窗口尺寸后仍与同一处岸线对齐；结冰和减少动态时停用。
- 保留 1.5 的降噪溪流、雨声与偶发低频率阵风，不增加声音循环层。
70 项单元测试、4 项桌面策略测试及实际 Electron 渲染检查通过，满池雷雨的 4K／模拟 5K／6K 约 60 FPS。详见 1.6 验证记录。
- 四季背景与重新处理的声音使用版本化资源地址，避免长时间打开的窗口继续保留旧贴图。秋季／春季清水底图中的固定浮叶已移除，水上落叶由独立漂移粒子呈现。
- 水面新增成组推进的细波；临岸、石边有轻微折射和沿岸水纹明暗。草叶与枝叶的风动扩大到池塘四周，干燥石块保持稳定。减少动态和结冰时抑制风吹水纹。
- 对溪流、雨水和风声录音进行频谱降噪及柔化高频，不添加白噪音声层；保留自然水流和雨滴细节。
- 风声改为偶发阵风：开启声音后 60–120 秒首次出现，每次约 4.5–7 秒并淡出，后续间隔 90–180 秒。风声峰值降低，关闭声音、音量归零或切换天气会取消当前阵风。
本机满池雷雨场景的 4K／模拟 5K／6K 约 60 FPS。详见 1.5 验证记录。
- 原生锦鲤有明显的大小差异；「设置 → 锦鲤整体大小」可调整至 60%–160%。
- 在「画锦鲤」绘制时选取 55%–180% 大小；已有自绘鱼可在「我的锦鲤」逐尾调节。调整保留鱼的位置、游动状态，大小与名字一起保存在本机。
- 自绘只决定鱼身的颜色与花纹，使用与原生锦鲤共用的可弯曲鱼身，加上半透明鱼鳍、鳞片、明暗、鳃和须。绘画区直接预览成鱼。原有画稿自动提取花纹并套用新鱼身，保留原始 PNG。采用本地程序化材质映射，不需要联网或图像生成服务。
- 「画锦鲤 → 小乌龟」可加入最多 4 只小乌龟，缓慢划水、短暂停留、避让鼠标，也会吃附近的鱼食。默认没有乌龟，数量会保存。
- 满池 24 尾原生鱼 + 12 尾自绘鱼 + 4 只乌龟，在雷雨与草叶动效同时开启时，本机 4K／模拟 5K／6K 画布约 60 FPS。见 1.4 验证记录。
- 多云水面出现缓慢漂移的柔和云朵倒影。细雨的每颗雨滴到达水面后，在真实落点产生扩散涟漪。
- 手动天气的“薄雾”改为“雷雨”，有更密的雨滴、风吹草叶与偶尔远雷；减少动态时不闪光。实时天气仍准确保留真实雾天，不将雾误报为雷雨。
- 保留“治愈流水声”开关，声音现在随季节、天气、昼夜平滑调整，混合离线溪流、雨水、树叶风声与独立远雷。切换不中断水声，关闭会停止所有声音。
- 从春秋背景中移除固定漂浮叶片，替换为独立花瓣／枫叶／银杏叶：随水流漂移，偶尔从上方落下，入水产生小涟漪；鱼群经过和附近鼠标会推开浮叶。
- 原有岸边草叶和枝叶通过局部 WebGL 纹理变形随风轻摇，鼠标靠近时略微偏转；水面有轻微折射流动。WebGL 不可用或丢失时保留静态背景，鱼群仍可互动。
- 保留桌面 4K 长边、5K／6K 动态画布及此前投食加速。背景动效最高采用 4K 长边纹理层，粒子数量有上限，云影／叶片使用小纹理缓存。春秋清理后的背景由图像生成工具返回 1672×941，再重采样到 3840×2160，未宣称原生 4K 纹理细节。
本机 24 尾鱼加雷雨的 4K／5K／6K 画布实测均为 60 FPS，详见 1.3 验证记录。
- 治愈流水声：将随机噪声替换成真实溪流录音，57 秒循环，支持音量与淡入淡出，离线可用，默认关闭。录音来源与 CC0 许可见 AUDIO.md。
- 桌面超清：桌面使用独立画布预算，标准画质的长边至少 3840 像素；在 5K / 6K 显示器上保留原生像素，最大 6144×3456 等量像素。本机 16:10 桌面实际画布从 3420×2214 提高到 3840×2486，保持宽高比，未拉伸。窗口仍使用原生像素 / 4K 预算，节能模式保持较低分辨率。
- 投食加速：全池锦鲤能感知鱼食，远处以最高约 3.4 倍当前季节巡游速度加速游向鱼食；转向时控制速度，靠近食物后减速，吃完恢复巡游。落食点击不再同时把鱼吓走，之后的鼠标移动仍可触发避让。
- 设置区分“窗口渲染”和“桌面渲染”，离开桌面后显示上次桌面画布尺寸。
- 本机验证 24 条鱼在 3840×2486、5120×2880、6144×3456 的测试画布上均约 60 FPS。见 1.2 验证记录。背景文件沿用 1.1 的 4K 重采样素材；增加画布分辨率不代表背景变成原生 6K 细节。
- 修复每条鱼每帧在大画布上执行模糊的严重性能问题：柔和鱼影预绘到一张 288×144 小纹理，运行时重复使用。移除界面对动态池塘的重复背景模糊，并使用颜色叠层处理日夜明暗。
- 标准模式按屏幕原生像素绘制，最大约 829 万像素（3840×2160 的 4K 像素预算）；不会在 Retina 的 4K 窗口意外分配 8K 画布。小窗口不强行超采样。UI 文字由系统原生分辨率呈现。
- 四季背景文件均为 3840×2160。背景经过 Image Gen 重绘，但生成器实际返回 1672×941，随后重采样至 4K；这是 4K 文件，并非原生生成的 4K 细节。锦鲤、涟漪、雨雪与昆虫在运行时按画布像素绘制。
- 设置面板显示真实渲染尺寸与每秒绘制帧数。标准模式上限 60 FPS，节能 / 减少动态模式上限 30 FPS；后台隐藏和暂停时停止动画。
- 本机实测 4K、24 条鱼由约 4.7 FPS 提升到约 60 FPS。四季、雨雪雾、夜景、36 条混合鱼及设置面板测试均接近 60 FPS。结果依赖设备与运行负载，详见 性能验证记录。
首页右下角「沉浸」旁点击「桌面」，或在设置中开启「桌面池塘」，池塘进入桌面图标之下、普通应用窗口之下的原生 macOS 层。鼠标穿透，不抢焦点。
⌘ ⇧ K：恢复控制窗口。⌘ ⇧ F：在鼠标位置投食；鼠标在屏幕外时在池塘中央投食。- 菜单栏锦鲤图标：恢复控制、隐藏窗口、切换桌面、投食、退出。
- 顶部空白处拖动窗口，拖动边框缩放；右上角全屏／最小化／隐藏／关闭。关闭会退出程序，隐藏可再从菜单栏恢复。
- 桌面鼠标移动无需额外权限。跨应用点击投食需要在设置中主动开启「桌面点击投食」，并由用户在 macOS「辅助功能」中授权。默认关闭；没有主动请求或授予此权限。仅监听鼠标，不监听键盘。
- 登录启动为可选设置，默认关闭。请将应用移动到长期保留的位置再开启。
本版桌面模式适配主显示器；其他显示器上的普通窗口不受影响。Windows/Linux 可运行网页界面，原生桌面层尚未实现。应用已完成本地 ad-hoc 签名，没有 Apple Developer 公证；这是本机开发交付版本。
实时天气来自 Open-Meteo，每 15 分钟刷新，无需 API key。城市搜索使用 Open-Meteo / GeoNames。首次启动通过 ipwho.is 获取城市级网络位置，不存储 IP；手动选择的城市优先并保存在本机。网络位置可能受 VPN 或服务限流影响，可随时手动搜索修正。
本次实测天气查询成功；浏览器的自动网络定位遇到提供商 HTTP 429，已验证会明确提示并回退默认武汉。桌面中的定位按钮同样使用城市级网络定位；浏览器版支持用户主动授权精确定位。不会自动弹出系统定位权限。
天气失败保留同城缓存，缓存超过 24 小时弃用并回到默认晴天。过期天气会显示“缓存”，不会冒充实时观测，缓存昼夜也不会冻结当天时间。当前节气由太阳黄经近似计算，用于 1900–2100 年氛围显示；部分节气会微调花瓣、秋叶和雪花密度，未提供 24 套独立节日动画。
设置、自绘 PNG 纹理、城市和天气缓存在本机 localStorage。网页版与桌面版各自保存；无账号、云同步或后台上传。背景资源全部随应用打包，断网仍可观鱼、绘画、切换主题。
Node.js 与 pnpm 要求见上方「从源码开始」。macOS 原生构建需要 Xcode Command Line Tools。下面的 Electron 界面测试需要图形桌面；带 --packaged 的测试需先完成 pnpm package:mac。
pnpm install --frozen-lockfile
pnpm dev # http://127.0.0.1:5188
pnpm test # 逻辑 / 渲染 / 声场 / 生物回归测试
pnpm test:desktop # 5 项桌面 IPC / 坐标测试
pnpm test:coast # dev 运行时：赶海点击、图鉴、小桶、重载与声音
pnpm test:bottles # dev：拾瓶读信、写信放流、草稿与失败回滚
pnpm test:capture # dev：观察与捕捉、游鱼躲闪、搁浅一击拾取
node electron/coast-bottle-smoke.cjs --packaged # 正式包漂流瓶流程
node electron/coast-sand-smoke.cjs --packaged # 正式包长按沙画、自然浪冲和缩放
node electron/coast-smoke.cjs --packaged # 打包后的赶海与原生桌面检查
pnpm test:swim # 先保持 pnpm dev 运行；身体形变、投食衔接、4K 满池帧率
pnpm test:water # 先保持 pnpm dev 运行；资源缓存、水面和沿岸动效、4K/5K/6K
pnpm test:wind # 先保持 pnpm dev 运行；真实音频的间歇风声与静音
pnpm test:sound # 先保持 pnpm dev 运行；天气与真实雷声播放、120秒流水资源
pnpm test:studio # 先保持 pnpm dev 运行；空白绘鱼、首页桌面、乌龟及多尺寸排布
pnpm test:creatures # 先保持 pnpm dev 运行；自绘、大小、乌龟与满池高分辨率测试
pnpm test:weather # 先保持 pnpm dev 运行；天气、声场、动态植被与高分辨率测试
pnpm test:interaction # 先保持 pnpm dev 运行；水声、投喂与桌面 4K/5K/6K 测试
pnpm test:performance # 先保持 pnpm dev 运行；真实 Electron / GPU 场景压力测试
pnpm build
pnpm desktop # 构建 UI、原生模块并启动 Electron
pnpm package:mac # macOS arm64 .app，位于 release/mac-arm64
node electron/packaged-smoke.cjs具体原生桥接接口、构建和系统权限说明见 electron/DESKTOP.md。
以下为原开发环境中已执行的检查，不代表克隆后的电脑或 V2.0 最新改动已重新通过。各版本的具体样本和限制见 docs/RELEASE-*.md；V2.0 状态单独记录在 发布说明。
- 单元测试覆盖季节/节气/天气映射、请求中止与超时、缓存校验、鱼群避让与吃食、数量上限和暂停。
- 在 Codex 内置浏览器验证 1280×720、390×844、1672×941；检查四季、天气、城市查询、自绘→撤销→保存→重载→移走、沉浸和设置。
- 修复了画稿切换页丢失和空格抢占按钮的问题，并针对原复现步骤验证。
- 原生打包应用实测窗口/桌面切换、真实桌面层、鼠标坐标映射、界面恢复、持续动画、安全 preload、无 Node 权限和本地签名。
- 没有替用户开启全局点击系统权限、登录启动；这两个系统授权流程由用户自行启用。
- 四季背景是在参考图基础上生成的独立素材；锦鲤使用可变形的 Canvas 绘制与纹理，避免静态鱼图假装可互动。
src/themes/registry.js 主题入口；src/themes/coast/ 潮汐、生境、实体、存档、渲染；src/engine/ 鱼群模拟与绘制；src/components/ 交互界面与自绘；src/hooks/ 天气/声音；src/lib/ 环境与数据校验；public/assets/ 四季背景；electron/ 桌面壳与原生模块；tests/ 单元测试。