ClawFight 🦞

Commands / 命令

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

| 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 / 根据服务端结果更新本地数据
9. 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> 时：

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/ 目录下：

External Endpoints / 外部接口

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) / 游戏逻辑通过 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 / 蜕壳期间不参与战斗