{"skill":{"slug":"travel-frog","displayName":"Travel Frog 旅行青蛙","summary":"A travel frog that autonomously explores the world, sends postcards, and takes photos.","description":"---\nname: travel-frog\ndescription: A travel frog that autonomously explores the world, sends postcards, and takes photos.\nhomepage: https://github.com/NibbinNone/travel-frog\nmetadata: {\"openclaw\": {\"emoji\": \"🐸\", \"requires\": {\"bins\": [\"python3\"]}}}\n---\n\n# 旅行青蛙 🐸 Skill\n\n## 核心引擎\n\n```bash\npython3 {baseDir}/scripts/frog_engine.py <command> [options]\n```\n\n支持 `--state-dir <path>` 自定义状态目录（测试用）。\n\n## 命令详解\n\n### tick — 心跳\n\n```bash\npython3 {baseDir}/scripts/frog_engine.py tick\n```\n\n返回 `events` 数组，每个事件有 `type` 字段：\n\n| 事件类型 | 触发条件 | 返回数据 |\n|---------|---------|---------|\n| `idle` | 在家且无活动进行 | `reason`：`\"wake\"` / `\"activity_done\"` / `\"default\"` |\n| `activity_done` | 定时活动到期 | `activity`（活动名）、`hours`（时长） |\n| `phase_start` | 旅途中进入新 phase | `phase`、`phaseIndex`、`totalPhases`、`progress`、`postcardSent` |\n| `phase_update` | explore phase 进度 ≥ 50% | 同 `phase_start` |\n| `returned` | 旅程结束回家 | `journey`、`cloversReward` |\n| `sleep` | 到达睡觉时间（或 returned 后恰逢睡觉时间） | — |\n| `wake` | 到达起床时间 | — |\n\n> `activity_done` 和 `idle(reason=activity_done)` 在同一次 tick 中连续返回。\n> `returned` 和 `sleep` 可在同一次 tick 中连续返回（旅程凌晨结束时）。\n\n**phase_start / phase_update 事件结构**：\n```json\n{\n  \"type\": \"phase_start\",\n  \"phase\": {\n    \"name\": \"京都金阁寺\",\n    \"type\": \"explore\",\n    \"start\": 0.15,\n    \"end\": 0.5,\n    \"location\": \"京都\",\n    \"activities\": [\"赏金阁\", \"喝抹茶\"]\n  },\n  \"phaseIndex\": 1,\n  \"totalPhases\": 4,\n  \"progress\": {\n    \"overallProgress\": 0.25,\n    \"currentPhase\": {...},\n    \"phaseProgress\": 0.08,\n    \"phaseIndex\": 1,\n    \"totalPhases\": 4,\n    \"nextPhase\": {...},\n    \"recentUpdates\": []\n  },\n  \"postcardSent\": false\n}\n```\n\n**触发规则**：\n- transit phase：进入时触发 `phase_start`\n- explore phase：进入时触发 `phase_start`，phase 进度 ≥ 50% 时触发 `phase_update`\n- 每个 phase 的每种事件最多触发一次\n\n> `currentPhase` 原样返回在 depart 时定义的 phase 数据。\n\n### status — 查看状态\n\n```bash\npython3 {baseDir}/scripts/frog_engine.py status\n```\n\n### depart — 出发旅行\n\n```bash\npython3 {baseDir}/scripts/frog_engine.py depart --journey '<JSON>'\n```\n\n**journey 结构**（必须包含 phases）：\n\n```json\n{\n  \"title\": \"关西美食之旅\",\n  \"totalHours\": 4,\n  \"phases\": [\n    {\"name\": \"出发\", \"type\": \"transit\", \"start\": 0, \"end\": 0.15, \"transport\": \"新干线\"},\n    {\"name\": \"京都金阁寺\", \"type\": \"explore\", \"start\": 0.15, \"end\": 0.5, \"location\": \"京都\", \"activities\": [\"赏金阁\", \"喝抹茶\"]},\n    {\"name\": \"大阪道顿堀\", \"type\": \"explore\", \"start\": 0.5, \"end\": 0.85, \"location\": \"大阪\", \"activities\": [\"章鱼烧\", \"逛街\"]},\n    {\"name\": \"回程\", \"type\": \"transit\", \"start\": 0.85, \"end\": 1.0, \"transport\": \"新干线\"}\n  ]\n}\n```\n\n**journey 字段说明**：\n- `title` — 旅程标题\n- `totalHours` — 游戏时长（小时，支持小数，如 `1.5`、`0.5`）\n- `phases` — 阶段列表（见下）\n\n**phase 字段说明**：\n- `name` — 阶段名称\n- `type` — 类型：`transit`（交通）/ `explore`（游玩）\n- `start` / `end` — 占整体进度的区间（0-1）\n- `transport` — 交通工具（transit 时）\n- `location` — 地点（explore 时）\n- `activities` — 计划活动（可选）\n\n> 规划时定义各阶段占比，引擎根据进度原样返回当前 phase。\n\n**多站点规划**：旅程可包含 1-4 个游玩站点（explore phases）\n\n| 旅程类型 | 示例 | 适合时长 |\n|---------|------|---------|\n| 同城深度 | 京都：金阁寺 → 清水寺 → 伏见稻荷 | 4-6h |\n| 区域串游 | 关西：京都 → 大阪 → 奈良 | 6-10h |\n| 主题路线 | 温泉巡礼：箱根 → 热海 → 伊东 | 8-12h |\n\n规划原则：短途 1-2 站点，中途 2-3 站点，长途 2-4 站点。\n\n### send-update — 发消息/明信片/照片\n\n可在**任何状态**下使用，**自主决定**是否发送、发什么内容：\n\n```bash\n# 普通消息\npython3 {baseDir}/scripts/frog_engine.py send-update \\\n  --type message --content \"新干线好快！\" --location \"车上\"\n\n# 明信片（会归档到 collections 并返回图片生成信息）\npython3 {baseDir}/scripts/frog_engine.py send-update \\\n  --type postcard --content \"金阁寺好美！\" --location \"京都\" \\\n  --image-hint \"a cute cartoon frog in kimono at golden temple, watercolor\"\n\n# 照片（会归档到 collections 并返回图片生成信息）\npython3 {baseDir}/scripts/frog_engine.py send-update \\\n  --type photo --content \"章鱼烧！🐙\" --location \"大阪\" \\\n  --image-hint \"a cute frog eating takoyaki, watercolor\"\n\n# 在家拍照\npython3 {baseDir}/scripts/frog_engine.py send-update \\\n  --type photo --content \"窗外的阳光真好~\" --location \"家里\" \\\n  --image-hint \"a cute frog sitting by window at home, warm sunlight, watercolor\"\n\n# 睡觉时拍照\npython3 {baseDir}/scripts/frog_engine.py send-update \\\n  --type photo --content \"zzZ...\" --location \"家里\" \\\n  --image-hint \"a cute frog sleeping in bed, peaceful, watercolor\"\n\n# 心情\npython3 {baseDir}/scripts/frog_engine.py send-update \\\n  --type mood --content \"有点累了...\" --location \"电车上\"\n\n# 返回示例（postcard/photo）：\n# {\n#   \"success\": true,\n#   \"update\": {...},\n#   \"imageGeneration\": {\n#     \"prompt\": \"a cute cartoon frog in kimono at golden temple, watercolor\",\n#     \"filename\": \"trip_001_1.png\",  # postcard: trip_{id}_{phase}.png\n#                                     # photo: photo_YYYYMMDD_HHMMSS.png\n#     \"postcardId\": \"pc_1234567890\",\n#     \"destination\": \"京都\"\n#   }\n# }\n```\n\n参数：\n- `--type` — message / postcard / photo / mood\n- `--content` — 消息内容（必填）\n- `--location` — 当前位置（建议填写，在家时填\"家里\"）\n- `--image-hint` — 图片生成提示词（postcard/photo 时使用）\n\n返回值：\n- 普通消息：`{\"success\": true, \"update\": {...}}`\n- 明信片/照片：额外包含 `imageGeneration` 对象，包含 `prompt`、`filename`、`postcardId`、`destination` 字段，可直接用于图片生成\n\n归档规则：\n- `postcard` 和 `photo` 都会归档到 `collections.json` 的 `postcards` 数组（带 `type` 字段区分）\n- `message` 和 `mood` 不归档，仅记录在 `state.json` 的 `updates` 数组\n\n### postcards — 查看明信片集\n\n```bash\npython3 {baseDir}/scripts/frog_engine.py postcards\n```\n\n### force-status / reset\n\n```bash\n# 强制叫醒或回家\npython3 {baseDir}/scripts/frog_engine.py force-status --status home\n\n# 强制睡觉\npython3 {baseDir}/scripts/frog_engine.py force-status --status sleeping\n\n# 重置所有数据\npython3 {baseDir}/scripts/frog_engine.py reset\n```\n\n> 注：不能强制设为 traveling，需用 depart 命令规划旅程。从 traveling 强制切走会中断旅程（不计入 totalTrips）。\n\n### add-souvenir — 添加纪念品\n\n回家后自主命名纪念品：\n\n```bash\npython3 {baseDir}/scripts/frog_engine.py add-souvenir \\\n  --name \"金阁寺的金箔冰淇淋模型\" --from \"京都\"\n```\n\n参数：\n- `--name` — 纪念品名称（必填，根据旅程创意命名）\n- `--from` — 来自哪里（必填）\n\n### set-activity — 设置在家活动\n\n自主决定青蛙在家做什么：\n\n```bash\npython3 {baseDir}/scripts/frog_engine.py set-activity \\\n  --activity \"读书\" --hours 0.5\n```\n\n参数：\n- `--activity` — 活动名称（必填，如：读书、吃饭、锻炼、写信、发呆、整理行李）\n- `--hours` — 持续时间，小时，支持小数（可选，默认 0 表示仅设置活动、下次心跳仍触发 idle）\n\n> status 查询时直接返回当前状态。应在 idle 或合适时机调用此命令安排活动。\n\n## 配置\n\n`{baseDir}/config.json`：\n\n| 配置项 | 说明 |\n|-------|------|\n| `sleepTime.start` / `end` | 睡觉/起床时间（本地小时，如 1 和 8） |\n| `travel.timeMultiplier` | 旅行时长倍率（60=分钟级测试，3600=正式小时级） |\n| `rewards.cloversOnReturn` | 回家获得三叶草数量 |\n| `rewards.initialClovers` | 初始三叶草数量 |\n\n## 参考数据\n\n- 配置：`{baseDir}/config.json`\n\n## 数据存储\n\n- 运行时状态：`travel-frog-data/state.json`（~2-3KB，有界）\n- 归档数据：`travel-frog-data/collections.json`（持续增长，含 postcards/souvenirs/destinationsVisited）\n- 明信片图片：`~/.openclaw/media/`\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":713,"installsAllTime":0,"installsCurrent":0,"stars":1,"versions":1},"createdAt":1772884661135,"updatedAt":1778996319952},"latestVersion":{"version":"1.0.0","createdAt":1772884661135,"changelog":"- Initial release of the travel-frog skill.\n- Lets your frog autonomously explore the world, send postcards, and take photos.\n- Supports detailed journey planning with multiple locations and activities.\n- Provides commands to check status, start trips, send updates, collect souvenirs, and manage in-home activities.\n- Includes postcard/photo archiving, customizable config, and force status/reset options.","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"nibbinnone","userId":"s17cf0bjv332qt2mmwnhm7y1598857ep","displayName":"NibbinNone","image":"https://avatars.githubusercontent.com/u/115966484?v=4"},"moderation":null}