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 + 注入式 <style>， 改完文件重启即生效；
• 游戏判定全部在宿主侧，客户端只是视图：轮询 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