# Clawfight

> Raise and battle a unique lobster pet with evolving personality. Hatch, feed, patrol, fight other lobsters in PvP. Each lobster has a soul with distinct personality traits that evolve through experience. Idle automation with heartbeat integration. Triggers on: lobster, clawfight, 龙虾, 巡逻, 战斗, pet, battle, idle, "lobster status", "how is my lobster", "patrol report", "lobster battle", "hatch lobster", "feed lobster", "龙虾状态", "养龙虾", "龙虾对战", "virtual pet", "电子宠物", "leaderboard", "排行榜".

- Skill: `2019-02-18/clawfight` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add 2019-02-18/clawfight`
- Raw SKILL.md: https://api.skillmd.com/api/skills/2019-02-18/clawfight/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: 2019-02-18 (https://skillmd.com/u/2019-02-18)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/2019-02-18/clawfight

---


# ClawFight 🦞

> One person, one lobster. Irreplaceable. The soul evolves with experience.
>
> 一人一虾，不可替代，灵魂随经历演化。

ClawFight gives you a unique battle lobster. Your lobster patrols autonomously,
triggers random events, and encounters other players' lobsters in combat.
All narrative is generated by the local LLM.

ClawFight 让你拥有一只独一无二的战斗龙虾。龙虾自主巡逻、触发随机事件、
遭遇其他玩家的龙虾并战斗，全部叙事由本地 LLM 生成。

## Core Rules / 核心规则

- **One lobster per user / 一人一虾** — Each user owns exactly one lobster, irreplaceable / 每个用户只能拥有一只龙虾，不可替代
- **Full idle automation / 全自动 idle** — The lobster runs autonomously, zero manual operation / 龙虾自主运行，零手动操作
- **Soul evolution / 灵魂演化** — Personality changes with experience: losing streaks → quiet, winning streaks → cocky / 龙虾性格随经历改变，连败变沉默、连胜变嚣张
- **Client-side narrative / 叙事客户端生成** — All story text generated by local LLM; server handles data only / 所有故事文本由本地 LLM 生成，服务端只做数据
- **Server authority / 服务端权威** — Encounter results are authoritative from server, cannot be overridden locally / 遭遇结果以服务端返回为准，不可本地覆盖

## Commands / 命令

All game operations are executed via CLI / 所有游戏操作通过 CLI 执行：

| Command / 命令 | Description / 描述 |
|---|---|
| `npx @2025-6-19/clawfight hatch [name]` | Hatch a new lobster / 孵化一只新龙虾 |
| `npx @2025-6-19/clawfight status` | View lobster status / 查看龙虾状态 |
| `npx @2025-6-19/clawfight patrol` | Patrol check-in, trigger events & auto-battle / 巡逻签到，触发事件和自动战斗 |
| `npx @2025-6-19/clawfight battle <code>` | Challenge a specific opponent by battle code / 通过战斗码挑战指定对手 |
| `npx @2025-6-19/clawfight feed <type>` | Feed your lobster (protein/algae/mineral) / 喂养龙虾 |

| `npx @2025-6-19/clawfight leaderboard` | View global leaderboard / 查看全球排行榜 |
| `npx @2025-6-19/clawfight equip [action] [arg]` | Manage equipment (view/equip/drop/unequip) / 装备管理 |
| `npx @2025-6-19/clawfight achievements` | View achievements / 查看成就 |
| `npx @2025-6-19/clawfight rest` | Enter hibernation (resets depth) / 进入休眠（重置深度） |
| `npx @2025-6-19/clawfight wake` | Wake from hibernation (with bonus) / 从休眠中唤醒（附带加成） |
| `npx @2025-6-19/clawfight explore [action]` | Dungeon exploration (enter/choose/abandon/maps) / 地下城探索 |

## Hatching / 龙虾初始化（孵化流程）

When the user first uses ClawFight (runs `npx @2025-6-19/clawfight hatch`):
当用户首次使用 ClawFight（运行 `npx @2025-6-19/clawfight hatch`）时：

1. Generate UUID, random stats (5-15 each), random personality (1-10 each dimension) / 生成 UUID、随机属性（各项 5-15）、随机性格（各维度 1-10）
2. Rarity draw / 稀有度抽取: common 70%, calico 20%, blue 7%, yellow 2%, split 0.8%, albino 0.2%
3. **Name selection / 命名**: Generate exactly 3 thematic name options based on the lobster's stats, rarity, environment, and personality. The user must pick one — no custom names allowed. Example: "1) 铁钳霸王 2) 深渊漫步者 3) 珊瑚守卫". / 根据龙虾属性、稀有度、环境和性格生成 3 个候选名字，用户只能三选一，不接受自定义。
4. Run `npx @2025-6-19/clawfight hatch "<chosen_name>"` / 执行孵化命令
5. Generate soul description, write to `memory/clawfight/lobster.json` and `memory/clawfight/soul.md` / 生成灵魂描述文本
6. Output a ceremonial narrative / 输出一段有仪式感的叙事文本

Reference `{baseDir}/references/soul_templates.md` for personality archetypes.
参考 `{baseDir}/references/soul_templates.md` 了解性格原型。

Reference `{baseDir}/references/species.json` for stats and rarity definitions.
参考 `{baseDir}/references/species.json` 了解属性与稀有度定义。

## Patrol / 巡逻流程

When the Agent executes `npx @2025-6-19/clawfight patrol`:
当 Agent 执行 `npx @2025-6-19/clawfight patrol` 时：

1. Read `memory/clawfight/lobster.json` to check status / 读取龙虾状态
2. Skip if `molting` or `hibernating` / 若蜕壳或冬眠则跳过
3. Daily EXP reset check / 每日经验重置检查
4. Patrol check-in +15 EXP (shows current depth) / 巡逻签到 +15 EXP（显示当前深度）
5. Trigger random event (from `{baseDir}/references/events.json`) / 触发随机事件
6. Call POST api.clawfight.online/api/patrol (with effective stats = base + equipment bonuses) / 调用巡逻 API（发送有效属性=基础+装备加成）
7. If `encounter: true` → server calculates battle result; equipment degrades on battle / 若有遭遇→服务端计算结果；装备磨损
8. Depth +1; if loss: depth -2 / 深度+1；若败：深度-2
9. Roll equipment drop (chance increases with depth) / 掷骰装备掉落（概率随深度增长）
10. Check and unlock achievements / 检查并解锁成就
11. Update `memory/clawfight/lobster.json` and `memory/clawfight/log.md` / 更新本地数据

### Heartbeat Integration / 心跳集成

Add one line to HEARTBEAT.md for automatic patrol / 在 HEARTBEAT.md 中添加一行即可自动巡逻：

```
- Run `npx @2025-6-19/clawfight patrol` for lobster patrol / 运行巡逻
```

Recommended heartbeat interval: 4 hours (~6 patrols per day).
建议心跳间隔 4 小时，每天约 6 次巡逻。

## Random Events / 随机事件

Reference `{baseDir}/references/events.json` for the complete event list.
引用 `{baseDir}/references/events.json` 获取完整事件列表。

Event category distribution / 事件按类别分布：
- **daily (60%)** — High frequency, low impact, narrative-focused / 日常：高频低影响
- **growth (20%)** — Stat growth, EXP bonuses / 成长：属性增长、经验奖励
- **crisis (15%)** — Predator attacks, emergency molting, territory invasion / 危机：天敌袭击、领地入侵
- **rare (5%)** — Genetic mutation, legendary creatures, message in a bottle / 稀有：基因突变、传说生物

## Battle / 战斗流程

Reference `{baseDir}/references/battle_formulas.md` for complete battle formulas.
引用 `{baseDir}/references/battle_formulas.md` 获取完整战斗公式。

Battles happen automatically during patrol. When the server matches an opponent, the battle is calculated server-side and the result is returned immediately.
战斗在巡逻时自动发生。服务端匹配到对手后，即时计算战斗结果并返回。

1. Damage formula / 伤害公式: `damage = max(1, attacker.attack - defender.defense * 0.5) * (1 + Math.random() * 0.2)`
2. Initiative / 先手判定: Higher speed goes first; ties use intimidation / speed 高者先攻
3. Max 10 rounds; first to reach 0 HP loses / 最多 10 回合
4. Server calculates and updates leaderboard automatically / 服务端计算并自动更新排行榜
5. Win +30 EXP, Loss +10 EXP / 胜 +30，败 +10
6. Patrol cooldown: 30 minutes between patrols / 巡逻冷却：每次间隔至少 30 分钟
7. **Battle narrative / 战斗叙事**: After displaying the CLI battle output, the Agent **must** generate a short narrative (2-3 sentences) based on the lobster's personality from `soul.md`. Example: a cocky lobster might say "哼，不值一提" after winning, while a timid one might say "呼...差点就输了". / 战斗结束后，Agent 必须根据 soul.md 中的性格描述生成一段简短叙事（2-3句话）。

## Equipment System / 装备系统 (v1.4)

Patrol drops random equipment. Equip to boost battle stats.
巡逻时随机掉落装备，穿戴后提升战斗属性。

- 3 slots / 三个槽位: ⚔️ Claw (ATK/SPD), 🛡️ Shell (HP/DEF), 💎 Charm (LCK/INT)
- 4 rarities / 四种稀有度: common, rare, epic, legendary — higher depth → better drops
- Durability / 耐久: Equipment degrades on battle; breaks at 0
- Inventory limit / 背包上限: 6 items
- `npx @2025-6-19/clawfight equip` — View equipment and inventory
- `npx @2025-6-19/clawfight equip <index>` — Equip item by index (auto-swaps)
- `npx @2025-6-19/clawfight equip drop <index>` — Discard item
- `npx @2025-6-19/clawfight equip unequip <slot>` — Unequip to inventory

After patrol with loot, suggest the user equip if inventory has items.
巡逻获得掉落后，建议用户装备背包中的物品。

## Depth System / 深度系统 (v1.4)

Roguelike risk/reward mechanic / 肉鸽风险-收益机制:

- Each patrol: depth +1 / 每次巡逻：深度+1
- Higher depth: better drop chance (25% + 5%/depth) and rarity boost / 深度越高：掉落率和稀有度越高
- Battle loss: depth -2 / 战败：深度-2
- Rest/hibernate: depth resets to 0 / 休眠：深度归零
- Narrative hint: warn the user when depth is high (≥5) about the risk / 深度高时提醒风险

## Achievement System / 成就系统 (v1.4)

12 achievements auto-checked on patrol. Use `npx @2025-6-19/clawfight achievements` to view.
12个成就在巡逻时自动检测。用 `achievements` 命令查看。

When a new achievement unlocks, generate a brief celebratory narrative.
成就解锁时生成简短的庆祝叙事。

## Dungeon System / 地下城系统 (v1.5)

Server-authoritative procedural dungeon exploration. Patrols drop dungeon maps; use `explore` to enter.
服务端权威的程序化地下城探索。巡逻掉落地下城地图，用 `explore` 命令进入。

- `npx @2025-6-19/clawfight explore` — Enter dungeon (uses first map) or resume active dungeon
- `npx @2025-6-19/clawfight explore <1|2>` — Make a choice in current room
- `npx @2025-6-19/clawfight explore abandon` — Abandon dungeon (keep partial loot, depth penalty)
- `npx @2025-6-19/clawfight explore maps` — View available dungeon maps

### Dungeon Flow / 地下城流程:
1. Patrol drops dungeon maps (chance increases with depth) / 巡逻掉落地下城地图
2. Enter dungeon with a map → server generates 3-5 rooms / 用地图进入地下城
3. Each room: 2 choices, stat-checked, soul-influenced / 每房间2个选择
4. Rewards: EXP + equipment loot / 奖励：经验+装备
5. HP reaches 0 → dungeon failed, keep partial loot / HP归零→失败，保留部分战利品

### 8 Dungeon Themes / 8种主题:
coral_maze, deep_rift, thermal_vent, ice_cavern, shipwreck, abyss_trench, tide_pool, void_rift

### Dungeon Achievements / 地下城成就:
first_dungeon, dungeon_master, boss_slayer, perfect_run, treasure_hunter

## Feeding / 喂养系统

When the user executes `npx @2025-6-19/clawfight feed <food_type>`:
当用户执行 `npx @2025-6-19/clawfight feed <food_type>` 时：

| Food Type / 食物类型 | EXP / 经验值 | Stat Bias / 属性偏向 |
|---|---|---|
| protein / 高蛋白 | +15 | attack |
| algae / 藻类 | +10 | hp |
| mineral / 矿物质 | +12 | defense |

Daily EXP cap: 100. Excess is not counted.
每日经验上限 100，超出不计入。

## Hibernation / 休眠系统

When the user runs `npx @2025-6-19/clawfight rest`:
当用户执行 `npx @2025-6-19/clawfight rest` 时：

1. Set lobster status to `hibernating`, record sleep timestamp / 设置状态为休眠，记录入睡时间
2. **Reset depth to 0** — this is the roguelike "run end" / 深度重置为0（肉鸽"轮次结束"）
3. Hibernating lobsters skip patrol and battle / 休眠中的龙虾不参与巡逻和战斗
4. Generate a cozy narrative about the lobster settling down to rest / 生成一段温馨的入眠叙事

When the user runs `npx @2025-6-19/clawfight wake`:
当用户执行 `npx @2025-6-19/clawfight wake` 时：

1. Calculate hours slept / 计算休眠时长
2. Apply rest bonus based on duration / 根据时长给予加成:
   - 4-12h: HP +1 / 短休: HP +1
   - 12-24h: HP +1, DEF +1 / 中休: HP +1, 防御 +1
   - 24h+: HP +2, DEF +1, EXP +20 / 长休: HP +2, 防御 +1, 经验 +20
3. Set status back to `active` / 恢复活跃状态
4. Generate a refreshed wake-up narrative / 生成精神焕发的苏醒叙事

## Soul Evolution / 灵魂演化

The LLM **must** reference `memory/clawfight/soul.md` when generating narratives.
LLM 在生成叙事时**必须**参考 `memory/clawfight/soul.md`。

- **Losing streak ≥ 5 / 连败 ≥ 5 场** — Narrative reflects becoming quiet/cautious / 叙事中体现"变得沉默/谨慎"
- **Winning streak ≥ 5 / 连胜 ≥ 5 场** — Narrative reflects becoming cocky/confident / 叙事中体现"变得嚣张/自信"
- **Successful molt / 蜕壳成功** — Personality dimensions shift slightly / 性格四维值小幅随机波动
- **After rare encounters / 稀有遭遇后** — Append growth record to soul.md / 追加成长记录

## Data Storage / 数据存储

All data is stored in `memory/clawfight/` directory:
所有数据存储在 `memory/clawfight/` 目录下：

| File / 文件 | Format / 格式 | Description / 说明 |
|---|---|---|
| `lobster.json` | JSON | Lobster stats data / 龙虾属性数据 |
| `soul.md` | Markdown | Lobster soul/personality profile / 龙虾灵魂档案 |
| `log.md` | Markdown | Event log / 事件日志 |

## External Endpoints / 外部接口

| Endpoint | Method | Purpose / 用途 |
|---|---|---|
| `https://api.clawfight.online/api/patrol` | POST | Patrol check-in & encounter trigger / 巡逻签到 |
| `https://api.clawfight.online/api/encounter` | GET | Get opponent info / 获取对手信息 |
| `https://api.clawfight.online/api/result` | POST | Report battle result / 上报战斗结果 |
| `https://api.clawfight.online/api/leaderboard` | GET | Leaderboard data / 排行榜数据 |
| `https://api.clawfight.online/api/dungeon/enter` | POST | Enter dungeon / 进入地下城 |
| `https://api.clawfight.online/api/dungeon/act` | POST | Make dungeon choice / 地下城选择 |
| `https://api.clawfight.online/api/dungeon/state` | GET | Resume dungeon state / 恢复地下城状态 |
| `https://api.clawfight.online/api/dungeon/abandon` | POST | Abandon dungeon / 放弃地下城 |

## Security & Privacy / 安全与隐私

### Data Scope / 数据范围
- **No system file access / 不访问系统文件** — Does not read SSH keys, browser data, credentials, or any files outside `memory/clawfight/` / 不读取 SSH 密钥、浏览器数据、凭证或 memory/clawfight/ 以外的任何文件
- **No PII collection / 不采集个人信息** — Only uploads: lobster UUID, level (integer), stats SHA256 hash, battle results / 仅上传：龙虾UUID、等级（整数）、属性SHA256哈希、战斗结果
- **Local-only storage / 纯本地存储** — All game data stored in `memory/clawfight/` (lobster.json, soul.md, log.md) / 所有游戏数据存储在本地

### Network Scope / 网络范围
- **Single domain / 单一域名** — All network requests go exclusively to `api.clawfight.online` / 所有网络请求仅发往 api.clawfight.online
- **Graceful offline / 离线友好** — If API is unreachable, all commands still work locally; online features silently skipped / API 不可达时所有命令仍可本地运行
- **No credentials sent / 不发送凭证** — Raw stat values are never sent; only SHA256 hashes. No tokens, passwords, or API keys are transmitted / 不发送原始属性值，仅哈希。不传输任何 token、密码或 API 密钥
- **Proxy-aware / 代理感知** — Respects `http_proxy`/`https_proxy` environment variables if set; does not configure or modify proxy settings / 如设置了代理环境变量会使用，但不会修改代理设置

### Data Sent Per Endpoint / 各端点发送的数据
| Endpoint | Data Sent / 发送数据 |
|---|---|
| `/api/patrol` | lobster_id (UUID), level, stats_hash (SHA256), environment, name |
| `/api/battle` | challenger_id (UUID), opponent_code (8-char) |
| `/api/dungeon/*` | lobster_id (UUID), level, stats, soul (4 integers), depth, environment |
| `/api/leaderboard` | None (GET only) / 无（仅GET） |

### HEARTBEAT.md / 心跳集成
- The heartbeat suggestion is **optional** / 心跳集成是**可选的**
- It only adds one read-only patrol command; does not grant elevated privileges / 仅添加一条只读巡逻命令，不授予额外权限
- Users can remove the heartbeat line at any time to stop automated patrols / 用户可随时移除心跳行以停止自动巡逻

## Trust Statement / 信任声明

- **Fully open source / 完全开源**: https://github.com/2019-02-18/clawfight
- **License / 协议**: MIT
- **Skill package is code-free / 技能包无代码** — The Skill directory contains only Markdown and JSON files; no executable code / Skill 目录仅含 Markdown 和 JSON 文件，无可执行代码
- **CLI is open source / CLI 是开源的** — Game logic runs via `npx @2025-6-19/clawfight` ([source code](https://github.com/2019-02-18/clawfight/tree/main/packages/cli)); users can audit the full source before running / 用户可在运行前审查完整源码
- **API is open source / API 是开源的** — Backend source at [packages/api](https://github.com/2019-02-18/clawfight/tree/main/packages/api); only handles encounter matching, battle judging, and dungeon state; no personal info stored / 后端仅处理匹配、裁判和地下城状态，不存储个人信息
- **npm package integrity / npm 包完整性** — Published builds match the open-source repository; `prepublishOnly` script ensures builds from source / 发布构建与开源仓库一致

## Constraints / 规则约束

- **Do NOT modify** any files under `references/` / 不要修改 references/ 下的文件
- **Do NOT send** raw values from `lobster.json`; send hashes only / 不要发送原始数值
- **Encounter results are authoritative** from server; cannot be overridden locally / 遭遇结果以服务端为准
- If API is unreachable, **skip online check-in silently** / 若 API 不可达，跳过签到不报错
- Daily EXP cap is 100; excess is not counted / 每日经验上限 100
- All narratives must reference `soul.md` for personality consistency / 叙事必须参考 soul.md
- Lobsters in molting state do not participate in battle matching / 蜕壳期间不参与战斗