旅行青蛙 🐸 Skill

核心引擎

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

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

命令详解

tick — 心跳

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 事件结构：

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

旅程类型	示例	适合时长
同城深度	京都：金阁寺 → 清水寺 → 伏见稻荷	4-6h
区域串游	关西：京都 → 大阪 → 奈良	6-10h
主题路线	温泉巡礼：箱根 → 热海 → 伊东	8-12h

规划原则：短途 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：

配置项	说明
`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/

Travel Frog 旅行青蛙