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 rest` | Enter hibernation / 进入休眠 |
| `npx @2025-6-19/clawfight wake` | Wake from hibernation (with bonus) / 从休眠中唤醒（附带加成） |

## 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 / 巡逻签到 +15 EXP
5. Trigger random event (from `{baseDir}/references/events.json`) / 触发随机事件
6. Call POST api.clawfight.online/api/patrol (with stats for server-side battle) / 调用巡逻 API（携带属性供服务端计算战斗）
7. If `encounter: true` → server calculates battle result immediately / 若有遭遇则服务端即时计算战斗结果
8. Update local wins/losses/streak/exp based on server result / 根据服务端结果更新本地数据
8. 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句话）。

## 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. Hibernating lobsters skip patrol and battle / 休眠中的龙虾不参与巡逻和战斗
3. 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 / 排行榜数据 |

## Security & Privacy / 安全与隐私

- Does not read any system files (SSH keys, browser data, etc.) / 不读取任何系统文件
- Does not collect PII; only uploads lobster ID, level, stats hash, battle results / 不采集 PII
- All data stored locally in user's `memory/clawfight/` directory / 所有数据存储在用户本地
- Network requests only go to `api.clawfight.online` / 网络请求仅发往 api.clawfight.online
- Raw stat values are never sent in plaintext; only SHA256 hashes / 原始属性不以明文发送

## Trust Statement / 信任声明

- Open source / 开源仓库: https://github.com/2019-02-18/clawfight
- License / 协议: MIT
- The Skill directory contains only Markdown and JSON files / Skill 目录仅包含 Markdown 和 JSON 文件
- Game logic runs via `npx @2025-6-19/clawfight` (open-source npm package, [source code](https://github.com/2019-02-18/clawfight/tree/main/packages/cli)) / 游戏逻辑通过 npx 执行开源 npm 包
- Backend API only handles encounter matching and battle judging; no personal info stored / 后端 API 仅处理匹配和裁判

## 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 / 蜕壳期间不参与战斗