clawfight

name	clawfight
description	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", "排行榜".
user-invocable	true
homepage	https://github.com/2019-02-18/clawfight
metadata	{"clawdbot":{"emoji":"🦞","category":"games","tags":["pet","battle","idle","pvp","rpg","lobster"],"requires":{"bins":"[Truncated]"},"version":"1.3.0","author":"LIU","license":"MIT","repository":"https://github.com/2019-02-18/clawfight","npm_package":"@2025-6-19/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 / 根据服务端结果更新本地数据
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> 时：

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