豹纹守宫旅行桌宠 morphlinglan/dsh-leopard-gecko

dsh-leopard-gecko — 豹纹守宫旅行桌宠

一只会自己出门旅行的豹纹守宫，住在你的 DSH Web GUI 右下角。采用「宿主半区 + 浏览器半区」的单包形态与同源 JSON 端点模式，存档极简地存放在 $DSH_HOME/.json，玩法是《旅行青蛙》式的被动观察游戏（主角换成自家的豹纹守宫）。

玩法

| 玩法 | 说明 |
| 🌿 庭院 | 三叶草每 10 分钟长 1 棵（上限 24），点击收割入钱包 |
| 🛍 商店 | 用三叶草买便当 / 护身符 / 道具（10 种商品） |
| 🎒 行囊 | 给守宫装便当、护身符、道具各一件；没有便当绝不出门。便当出发时消耗，其余长期有效 |
| 🦎 出发 | 装好便当后几分钟内动身；旅行 15 分钟～6 小时不等——去的每个地方耗时不同 |
| 📮 明信片 | 旅途中寄回 1~4 张明信片，每张都有地点、风景与一句旅途小故事 |
| 🏠 回家 | 带回特产（14 种图鉴）；回家后不会自动再出门——想让它出发就把下一份便当装进行囊 |

环境联动：真实天气与季节（2026-08-27 新增）

| 机制 | 说明 |
| 🌦 实时天气 | 服务端通过 ip-api（IP 定位城市）+ Open-Meteo 拉取你电脑所在城市的当前天气，每 30 分钟刷新。守宫出发时把"你这里的天气"带在路上：雨天明信片带 🌧️ 布景与旅途小句；斗篷雨天加速 15%、灯笼雨雾夜多寄一张。断网/接口失败自动回落随机天气，游戏永不卡住 |
| 🍀 幸运四叶草 | 庭院每个生长周期 3% 概率长出幸运四叶草（存栏上限 3）。出发时自动消耗一朵，本趟稀有特产概率 ×1.5 |
| ✦ 稀有明信片 | 投递时 5% 基础概率抽到"同伴同框"稀有明信片（蜥蜴前辈、蜗牛邮差…），幸运铃/四叶草各 +6%。金框 ✦ 徽记，图鉴控福音 |
| 🌸 季节限定 | 现实月份映射四季，商店当季多 1 件限定便当（春樱花麻糬/夏冷面/秋栗子/冬红豆汤），当季可买、永久可用 |

🏆 成就与 📬 信箱（2026-08-27 新增）

| 机制 | 说明 |
| 🏆 成就 | 12 枚里程碑（首旅/常旅客/旅行家/明信片×30/特产×50/在外百时/云顶登顶/星砂拾光/好客之道×5/抽奖×5/粮草先行/图鉴大满贯），达成即自动到账 🍀 奖励并广播事件；相册页底部查看进度，未达成显示 🔒 与奖励 |
| 📬 信箱 | 相册页顶部。访客的感谢信（附回礼明细）、回家 20% 概率的家书碎碎念；未读高亮，点击单封已读或一键全部已读，留档最近 30 封 |

家的延伸：桌面、访客与抽奖（2026-08-27 新增）

| 机制 | 说明 |
| 🍽 桌面备餐 | 行囊之外的第二组三栏（便当/护身符/道具）。守宫回家看到行囊空着，会自己从桌面取餐装包继续出发——睡前把便当摆上桌，它就能自主续旅程 |
| 💢 闹脾气 | 行囊+桌面全空在家干等 24 小时 → 闹脾气：冷淡台词、缩在墙角，装饭才哄好，且那趟出门拖拖拉拉（延迟 ×2） |
| 🐌 访客 | 守宫出门期间，蜗牛/蟋蟀/面包虫随机来访（每 30 分钟 35% 概率，停留 6 小时）。喂一件背包里的食物换谢礼：三叶草或特产，喂中偏爱礼物翻倍。回家时没喂的客人会悄悄走掉 |
| 🎟 抽奖 | 每消费 5 🍀 得 1 券，5 券一抽。奖池：地点车票（下一趟必去指定地点，无视门槛）/ 旅行糖（快去快回）/ 幸运四叶草 / 平安符 / 三叶草 |

出行规则：搭配与花费决定一切

1. 没有便当不出行——行囊的便当槽是空的时候，守宫会一直待在家里等你。
2. 搭配决定去哪——便当 × 护身符 × 道具的每一件都有自己的偏好地点（灯笼向往夜巷与灯塔、帐篷指向露营与登顶……），同时每件商品的价格是"门槛"：便宜的搭配只能在近郊转悠，去山脊、灯塔这类远途需要攒够更贵的组合（例如百吉饼 + 帐篷就能翻云顶山脊）。
3. 花费越多走得越远越久、带回越多——行囊里三件装备的三叶草总花费越高，旅行时间越长（还叠加目的地的路程系数），寄回的明信片和带回的特产也越多。装好便当后它会在几分钟内动身。
| 🏷 头衔 | 初出茅庐 → 见习旅行家 → … → 浪迹天涯（按旅行次数解锁） |

核心体验：你无法控制它，只能准备行囊然后等待。关掉页面、关机重启都不影响——所有推进由时间戳惰性结算，重新打开页面时会一次性补算离线期间的旅程。

架构

lib/
├── sim.js # 纯游戏逻辑：地点/特产/商店目录 + settle() 惰性结算引擎（可注入 rng） ├── persist.js # $DSH_HOME/gecko.json 存档（原子写入、容错读取） ├── routes.js # /api/gecko/ 路由族 + 回环信任栅栏（复刻 dsh-pet 模式） ├── service.js # 服务层：结算→落盘→下发完整视图 ├── index.js # 宿主半区入口：挂服务 + 注册路由（mountOnce 守卫） └── client.js # 浏览器半区：__ModuleLoader__ bundle，纯 DOM 悬浮桌宠（零构建） test/ └── sim.test.mjs # node --test 单元测试（11 例全绿）

与 dsh-pet 的关键差异：

- 不依赖 React / CSS modules / 构建链——客户端是手写的
window.__ModuleLoader__.load({ id, factory }) bundle + 注入式 ，
改完文件重启即生效；
- 游戏判定全部在宿主侧，客户端只是视图：轮询 GET /api/gecko/state，动作走 POST /api/gecko/{collect,buy,pack,set-name,set-display,reset}；
- 存档独立在 $DSH_HOME/gecko.json，与原宠物插件的 pet.json 互不影响，可以两个桌宠共存。

安装

1. 以链接方式装入 profile（pnpm link，无网络请求）
dsh plugin --profile web add "link:"

2. 在 profile 的 cordis.patch.yml 追加插件行：
- insert:
- id: leopard-gecko
name: dsh-leopard-gecko

3. 重启 dsh web，刷新页面即可看到右下角的蛙

⚠️ 重要（2026-08-25 实测）：必须用 cmd 方式启动 dsh web （例如双击桌面快捷方式 / start_dsh.bat）。如果从 Git Bash 会话里以子进程方式拉起 dsh web，插件树会静默降级为纯核心（所有 insert 行与 bundle 补丁全部不加载，且无任何报错）——症状是页面能开但宠物/工具全消失。
疑似与 MSYS 注入的 npm_* 环境变量有关，未深究；cmd 启动一切正常。

自定义素材替换

内置像素画全部由 scripts/generate-assets.mjs 程序化生成（原创，致敬原作风格但不含任何版权素材）。
如果你有自备图片（自己的画、截图裁剪等合法来源），可一键覆盖任意素材：

1. 查看全部素材名与建议尺寸
node scripts/generate-assets.mjs --list

2. 把图片放进 assets/custom/ 并按素材名命名，例如： assets/custom/gecko-sit.png （青蛙坐姿，透明底） assets/custom/item-lucky_bell.png （幸运铃图标） assets/custom/scene-hot-spring.png （温泉明信片风景）

3. 重新生成 + 刷新页面
node scripts/generate-assets.mjs

自定义图优先于内置像素画；删掉对应 PNG 再跑一次即恢复内置。

开发

npm test # 跑游戏逻辑单元测试
node --check lib/*.js # 语法检查
node scripts/generate-assets.mjs --list # 列出全部素材名
改 lib/client.js 后无需任何构建，重启 dsh web 即生效

从源码安装

git clone https://github.com/morphlinglan/dsh-leopard-gecko.git
dsh plugin --profile web add "link:/dsh-leopard-gecko"

然后在 profile 的 cordis.patch.yml 追加：

- insert:
- id: leopard-gecko
name: dsh-leopard-gecko