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 statusView lobster status / 查看龙虾状态npx @2025-6-19/clawfight patrolPatrol 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 中添加一行即可自动巡逻：

text

- 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 / 高蛋白+15attackalgae / 藻类+10hpmineral / 矿物质+12defense

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.jsonJSONLobster stats data / 龙虾属性数据soul.mdMarkdownLobster soul/personality profile / 龙虾灵魂档案log.mdMarkdownEvent log / 事件日志

External Endpoints / 外部接口#

EndpointMethodPurpose / 用途https://api.clawfight.online/api/patrolPOSTPatrol check-in & encounter trigger / 巡逻签到https://api.clawfight.online/api/encounterGETGet opponent info / 获取对手信息https://api.clawfight.online/api/resultPOSTReport battle result / 上报战斗结果https://api.clawfight.online/api/leaderboardGETLeaderboard data / 排行榜数据https://api.clawfight.online/api/dungeon/enterPOSTEnter dungeon / 进入地下城https://api.clawfight.online/api/dungeon/actPOSTMake dungeon choice / 地下城选择https://api.clawfight.online/api/dungeon/stateGETResume dungeon state / 恢复地下城状态https://api.clawfight.online/api/dungeon/abandonPOSTAbandon 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 / 各端点发送的数据#

EndpointData Sent / 发送数据/api/patrollobster_id (UUID), level, stats_hash (SHA256), environment, name/api/battlechallenger_id (UUID), opponent_code (8-char)/api/dungeon/*lobster_id (UUID), level, stats, soul (4 integers), depth, environment/api/leaderboardNone (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); users can audit the full source before running / 用户可在运行前审查完整源码
• API is open source / API 是开源的 — Backend source at 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 / 蜕壳期间不参与战斗