travel-frog（旅行青蛙）

旅行青蛙 🐸 Skill

核心引擎

python3 {baseDir}/scripts/frog_engine.py <command> [options]

支持 --state-dir <path> 自定义状态目录（测试用）。

命令详解

tick — 心跳

python3 {baseDir}/scripts/frog_engine.py tick

返回 events 数组，每个事件有 type 字段：

activity_done 和 idle(reason=activity_done) 在同一次 tick 中连续返回。 returned 和 sleep 可在同一次 tick 中连续返回（旅程凌晨结束时）。

phase_start / phase_update 事件结构：

{
  "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 — 查看状态

python3 {baseDir}/scripts/frog_engine.py status

depart — 出发旅行

python3 {baseDir}/scripts/frog_engine.py depart --journey '<JSON>'

journey 结构（必须包含 phases）：

{
  "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）

规划原则：短途 1-2 站点，中途 2-3 站点，长途 2-4 站点。

send-update — 发消息/明信片/照片

可在任何状态下使用，自主决定是否发送、发什么内容：

# 普通消息
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 — 查看明信片集

python3 {baseDir}/scripts/frog_engine.py postcards

force-status / reset

# 强制叫醒或回家
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 — 添加纪念品

回家后自主命名纪念品：

python3 {baseDir}/scripts/frog_engine.py add-souvenir \
  --name "金阁寺的金箔冰淇淋模型" --from "京都"

参数：

• --name — 纪念品名称（必填，根据旅程创意命名）
• --from — 来自哪里（必填）

set-activity — 设置在家活动

自主决定青蛙在家做什么：

python3 {baseDir}/scripts/frog_engine.py set-activity \
  --activity "读书" --hours 0.5

参数：

• --activity — 活动名称（必填，如：读书、吃饭、锻炼、写信、发呆、整理行李）
• --hours — 持续时间，小时，支持小数（可选，默认 0 表示仅设置活动、下次心跳仍触发 idle）

status 查询时直接返回当前状态。应在 idle 或合适时机调用此命令安排活动。

配置

{baseDir}/config.json：

参考数据

• 配置：{baseDir}/config.json

数据存储

• 运行时状态：travel-frog-data/state.json（~2-3KB，有界）
• 归档数据：travel-frog-data/collections.json（持续增长，含 postcards/souvenirs/destinationsVisited）
• 明信片图片：~/.openclaw/media/