travel-frog

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