dsh-survival-mode

Readme

<div align="center">

# dsh-survival mode

**DeepSeek Harness 生存模式**

Minecraft 生存规则 × 真实编码工作——规则硬结算、死亡真实发生的娱乐性 Agent 预设。

[中文](README.md) · [English](README.en.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/Socialist-Sister/dsh-survival-mode)](https://github.com/Socialist-Sister/dsh-survival-mode/releases)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Socialist-Sister/dsh-survival-mode#已知不足与参与贡献)

<kbd>engine</kbd> <kbd>tool-survival</kbd> <kbd>hud</kbd> <kbd>agent-preset</kbd>

</div>

---

> 你在 DeepSeek Harness 里照常写代码、查资料、做交付——同时**活在一个 Minecraft 生存世界**里：每写一个文件掉 1 饥饿，深夜干活会刷怪，没有铁镐连 `subagent` 都调用不了。饿了得吃，夜了得防，死了背包全掉、经验减半，工作区文件回退到你的重生点——每个会话都是独立存档。

所有规则由引擎**硬结算**（不是人设演戏），所有游戏概念对齐原版 Minecraft 生存模式，所有插件机制遵循官方插件规范（与 dsh-collaboration 套件同构）。

**套件版本 0.2.1**：engine 0.19.1 · tool-survival 0.6.3 · hud 0.1.3 · [安装指南](docs/installation.md) · [GitHub Releases](https://github.com/Socialist-Sister/dsh-survival-mode/releases)

**核心特性**

- 🎮 **原版概念硬结算**：生命 20（10 心）、饥饿 20、昼夜、夜晚刷怪——全部由引擎在 `tools/pre-execute` 实时结算，不是人设演戏
- 🧑‍🚀 **用户是玩家**：agent 是化身与执行者——播报状态、听令行事，可一句话授权托管
- ⛏️ **工作即挖矿**：写文件、完成目标、退出计划都会掉落原版矿石与经验
- 🔒 **真实工具门禁**：没有铁镐就用不了 subagent，没有望远镜就上不了网——像没有镐子挖不了钻石
- 📁 **文件重生点**：会话开始自动备份工作区（出生点），睡觉更新备份（重生点）；死亡时文件回退——重生点之后的改动直接丢失；每个会话独立存档，不跨会话
- 🖥️ **浏览器状态栏**：心+鸡腿+昼夜+经验，只在生存模式会话显示（OpenMoji 图标，无版权风险）

---

## 目录

1. [快速上手](#快速上手)
2. [玩家与化身（播报与听令）](#玩家与化身播报与听令)
3. [世界规则](#世界规则)
4. [生存工具](#生存工具)
5. [挖矿与掉落](#挖矿与掉落)
6. [合成与物品](#合成与物品)
7. [工具门禁](#工具门禁)
8. [死亡、重生与文件回退](#死亡重生与文件回退)
9. [难度档](#难度档)
10. [进度（成就）](#进度成就)
11. [设定（settings.yaml）](#设定settingsyaml)
12. [存档与持久化](#存档与持久化)
13. [浏览器状态栏](#浏览器状态栏)
14. [小贴士](#小贴士)
15. [故障排查](#故障排查)
16. [组件与架构](#组件与架构)
17. [素材许可](#素材许可)
18. [开发](#开发)
19. [已知不足与参与贡献](#已知不足与参与贡献)

---

## 快速上手

1. 按 [docs/installation.md](docs/installation.md) 安装并**重启 DSH**；
2. 新建会话，选择预设「生存模式」；
3. 会话开始时会弹出**难度选择框**（peaceful/easy/normal/hard/hardcore，仅本会话生效）；选完直接开始真实工作（编码、查资料、写文档照常）——引擎在后台硬结算你的生存状态；
4. 输入框上方出现状态栏：❤️ 生命（10 颗心 = 20 血）、🍗 饥饿（10 根鸡腿 = 20 饥饿）、☀️/🌙 天数、⭐ 经验；
5. 用 `survival_status` 查看完整状态与配方书；完成任务会掉落材料，`survival_craft` 合成，`survival_eat` 吃东西，`survival_sleep` 睡觉（并更新文件重生点）。
6. 会话开始时工作区已自动备份（出生点）；想保住当前进度就睡一觉——死亡时文件回退到最近一次备份。

**一句话玩法**：工作即挖矿，挖矿得材料，材料合成物品，物品解锁能力与防御；饿了吃、夜了防、够了合成；死了文件回退到重生点，新会话重新开始。

---

## 玩家与化身（播报与听令）

**你是玩家，agent 是你的化身与执行者。** 生存决策由你拍板：

- **化身只播报、执行**：引擎在状态跃迁时推送事件（见下方「跃迁播报」），agent 收到后第一时间向你汇报状态与选项；吃、睡、合成什么**默认等你的指令**，agent 只做你布置的真实工作本身。
- **可一句话授权托管**：说"生存你自己管"，agent 就会自主管理（饿了自己吃、夜了自己防）；想收回就说"生存听我指挥"。
- **娱乐性就在这里**：你一边布置真实工作，一边要时刻留意状态、指挥进食与合成、亲手解锁新能力——分心就会饿死或被夜袭。

### 跃迁播报

引擎只在状态**变化瞬间**推送一条消息（不刷屏，恢复后重新武装）：

| 事件 | 播报内容 | 送达 |
|---|---|---|
| 🌙 入夜 | 夜幕降临提醒 + 火把/床的应对建议 | **插队**（立即） |
| ☀️ 黎明战报 | 昨夜遭遇次数与击退/格挡/受伤明细（剑盾耐久消耗的账本）；平安夜也有通报 | 排队 |
| 🍖 饥饿 ≤ 4 | 低饥饿警告 + 吃面包指引 | **插队**（立即） |
| ❤️ 生命 ≤ 4 | 血量告急警告 + 回血条件 | **插队**（立即） |
| ⛏️🔭🔴 合成解锁 | 合成铁镐/望远镜/红石中继器时宣布解锁的能力 | —（合成返回消息内） |
| ☠️ 死亡 | 死亡信息 + 掉落清单 + 文件回退说明 | **插队**（立即） |
| 📁 出生点/重生点备份 | 备份完成（文件数 + 对话摘要） | **插队**（立即） |

播报是插件来源消息，**不推进游戏时间**（只有真实用户消息算对话回合）。插队消息（steer）在 agent 的下一个执行边界立即送达，不会中断正在进行的工具调用；普通播报排队送达。

---

## 世界规则

### 生命与饥饿

| 数值 | 上限 | 显示 |
|---|---|---|
| 生命 ❤️ | 20（10 颗心） | 一颗满心 = 2 血，半颗心 = 1 血 |
| 饥饿 🍗 | 20（10 根鸡腿） | 一根满鸡腿 = 2 饥饿，半根 = 1 |

- **行动消耗饥饿**：普通工具调用 −1（重型工具同为 −1，但受工具门禁约束）。
- **回合回复饥饿**：每个对话回合 +1（休息节奏，纯聊天也能续命）。
- **免费动作**（不耗饥饿、不推进时间）：生存工具本身，以及观察与交谈类——`read` / `glob` / `grep` / `read_image` / `ask_user` / `todo_write` / `create_goal` / `get_goal` / `skill` / `job_list` / `job_output` / `job_kill` / `list_agents`。
- **饥饿归零 → 每次行动掉 1 血**（和平难度除外）。
- **自然再生（回血）**：每个对话回合结算时，**饱食度 ≥ 10 → 回复 1 血**；和平难度无条件回血。饿着不会回血、只会掉血——吃饱才能养伤。

### 昼夜

- **昼夜由对话回合推进**：每个用户消息算 1 个回合（纯聊天也过天）；一天的长度在设定里配置（默认 8 个回合），白天与夜晚各半。
- **入夜决策窗口**：**入夜第一回合不刷怪**——收到插队播报后你有一回合的安全时间回复"睡觉"（`survival_sleep`）跳过夜晚；之后每个回合/动作恢复刷怪判定。
- 工具调用不推进时间，但会结算饥饿与怪物遭遇。
- 白天每个动作有 10% 概率遇到羊（掉羊毛×1–2，用来做床）；夜晚刷怪。

### 夜晚怪物

| 怪物 | 效果 |
|---|---|
| 僵尸 | −2 血 |
| 骷髅 | −2 血，且**打断本次工具调用**（远程射箭） |
| 苦力怕 | −6 血（高伤害，盾牌可挡） |
| 蜘蛛 | −2 血 |

防御手段见 [物品](#合成与物品)：火把压制刷怪（概率 ×0.8，不是免疫）、剑自动反击（石 40% / 铁 60% / 钻石 90%，品质优先）、盾牌格挡、床睡觉跳过夜晚。

---

## 生存工具

| 工具 | 作用 |
|---|---|
| `survival_status` | 查看完整状态：生命/饥饿/经验、天数与昼夜、背包材料、物品栏、工具门禁状态、进度、最近事件、完整配方书。**状态不明时先看这里。** |
| `survival_craft` | 按配方合成。参数 `recipe` 填配方 id（如 `bread`、`iron-pickaxe`、`bed`），见 [配方大全](#合成与物品)。失败会告诉你缺什么。 |
| `survival_eat` | 吃东西回复饥饿。目前只有面包（`food` 参数默认 `bread`），吃一个回复 8 饥饿。 |
| `survival_sleep` | 用床设置/更新重生点：**夜晚**睡觉（跳过夜晚进入下一天、达成就「甜甜的梦」）；**白天**休息（不跳夜）。两种都会把工作区文件 + 对话摘要备份为重生点（死亡时文件回退到最近一次备份）。 |
| `survival_difficulty` | 查看/修改**本会话**难度（peaceful/easy/normal/hard/hardcore），仅本会话生效，不影响其他会话与全局 settings。 |

---

## 挖矿与掉落

**挖矿 = 完成任务**。引擎监听真实的任务信号，成功即掉落（经验同时入账）：

| 触发 | 掉落 | 经验 |
|---|---|---|
| 写文件成功（`write`/`edit`，70% 概率） | 圆石×1 + 木头/小麦/煤中随机 2 个（小麦权重最高）；25% 铁矿石×1 | +2 |
| 计划退出（`exit_plan_mode`，**每日限一次**） | 煤×2 + 铁矿石×1；30% 铜矿石×1 | +10 |
| 目标完成（`update_goal` action=complete） | 铁矿石×2 + 红石粉×2；25% 钻石×1；25% 铜矿石×1；15% 紫水晶碎片×1 | +15 |
| 子代理成功（`subagent`/`subagent_fork` 完成） | 铁矿石×1 + 红石粉×1；15% 钻石×1；15% 紫水晶碎片×1 | +12 |

铁矿石/铜矿石需要**熔炉熔炼**成锭才能用于合成；红石粉、钻石、紫水晶直接可用。

### 经验（⭐）

| 项目 | 规则 |
|---|---|
| 获得 | 挖矿掉落附带（见上表）；剑击退怪物 +2/+3/+5（石/铁/钻石） |
| **消耗** | **铁砧修复**：`repair-pickaxe` / `repair-stone-sword` / `repair-sword` / `repair-diamond-sword` / `repair-shield`，经验 + 材料（见 [铁砧与修复](#合成与物品)） |
| 惩罚 | 死亡时经验减半（掉落） |
| 持久化 | 经验随会话存在——每个会话独立存档，新会话从 0 经验开始 |

> 附魔系统暂未实装（避免功能过多）；铁砧修复是当前经验的唯一消耗途径——攒着修工具，别随便死。

---

## 合成与物品

### 材料一览

| 材料 | 来源 |
|---|---|
| 木头 / 圆石 / 煤 / 小麦 | 小任务（写文件）掉落 |
| 羊毛 | 白天每个动作 10% 概率遇到羊（每次 1–2 个） |
| 铁矿石 / 铜矿石 | 中小任务掉落，需熔炼 |
| 红石粉 | 大任务（目标完成/子代理）掉落 |
| 钻石 / 紫水晶碎片 | 深挖稀有掉落 |

### 配方大全（`survival_craft` 的 `recipe` 参数）

**基础**

| 配方 id | 产物 | 材料 | 说明 |
|---|---|---|---|
| `planks` | 木板×4 | 木头×1 | 基础建材 |
| `stick` | 木棍×4 | 木板×2 | 工具手柄 |
| `torch` | 火把×1 | 煤×1 + 木棍×1 | **照明压制刷怪：持有后夜晚刷怪概率 ×0.8（原版光照概念，不是免疫）** |
| `furnace` | 熔炉×1 | 圆石×8 | 解锁熔炼配方 |

**熔炼（需先有熔炉）**

| 配方 id | 产物 | 材料 |
|---|---|---|
| `smelt-iron` | 铁锭×1 | 铁矿石×1 + 煤×1 |
| `smelt-copper` | 铜锭×1 | 铜矿石×1 + 煤×1 |
| `smelt-stone` | 石头×1 | 圆石×1 + 煤×1 |

**食物与工具**

| 配方 id | 产物 | 材料 | 效果 |
|---|---|---|---|
| `bread` | 面包×1 | 小麦×3 | 吃一个回复 8 饥饿 |
| `iron-pickaxe` | 铁镐 | 铁锭×3 + 木棍×2 | 解锁 `subagent`/`subagent_fork`，每用一次耐久 −1（耐久 120，可叠加） |
| `stone-sword` | 石剑 | 圆石×2 + 木棍×1 | 入门剑：夜间 40% 概率击退（+2 经验，耐久 50；每次遇怪出手即 −1，无论命中） |
| `iron-sword` | 铁剑 | 铁锭×2 + 木棍×1 | 夜间 60% 概率击退（+3 经验，耐久 100；出手即耗） |
| `diamond-sword` | 钻石剑 | 钻石×2 + 木棍×1 | 更锋利：击退率 90%（+5 经验，耐久 200；出手即耗）；与低档剑并存时**优先使用** |
| `shield` | 盾牌 | 木板×6 + 铁锭×1 | 50% 概率格挡怪物伤害（耐久 120；每次举盾即 −1，无论格挡成败；骷髅的打断箭挡不了） |
| `bed` | 床 | 羊毛×3 + 木板×3 | `survival_sleep` 夜晚睡觉（跳过夜晚）/ 白天休息（不跳夜），都设置重生点（备份文件+对话；床不掉落） |
| `spyglass` | 望远镜 | 紫水晶碎片×1 + 铜锭×2 | 解锁 `web_search`（永久，原版无耐久） |

**红石电路**

| 配方 id | 产物 | 材料 | 效果 |
|---|---|---|---|
| `redstone-torch` | 红石火把×1 | 红石粉×1 + 木棍×1 | 电路组件（**是材料，不是物品**） |
| `redstone-repeater` | 红石中继器×1 | 红石粉×1 + 红石火把×2 + 石头×3 | 解锁 `workflow`（永久） |

**铁砧与修复（经验的用途）**

| 配方 id | 产物 | 材料 | 效果 |
|---|---|---|---|
| `anvil` | 铁砧×1 | 铁锭×12 | 解锁铁砧修复（原版需 31 锭，为节奏简化） |
| `repair-pickaxe` | — | 铁锭×1 + **10 经验**（需铁砧） | 铁镐耐久 +60（上限的一半） |
| `repair-stone-sword` | — | 圆石×1 + **5 经验**（需铁砧） | 石剑耐久 +25 |
| `repair-sword` | — | 铁锭×1 + **10 经验**（需铁砧） | 铁剑耐久 +50 |
| `repair-diamond-sword` | — | 钻石×1 + **10 经验**（需铁砧） | 钻石剑耐久 +100 |
| `repair-shield` | — | 木板×1 + **10 经验**（需铁砧） | 盾牌耐久 +60 |

> 修复要求目标工具**存在且有损伤**（耐久低于上限）；修复不能超过上限。耐久数值在 `settings.yaml` 可调，修复量随之上限的一半联动。

### 物品使用方式

- **面包**：`survival_eat` 自动消耗；饥饿归零前记得吃。
- **火把 / 望远镜 / 红石中继器 / 熔炉 / 床**：合成即生效（放进物品栏自动起效），无需装备。
- **铁镐**：调用 `subagent`/`subagent_fork` 时自动消耗 1 耐久；耗尽即失效，需重新合成（可多次合成叠加耐久）。
- **剑（石/铁/钻石）/ 盾牌**：夜间遭遇怪物时自动判定反击/格挡，无需操作；多把剑并存时自动用最好的。
- **床**：夜晚用 `survival_sleep` 睡觉；白天不能睡。
- **耐久池**：工具可重复合成叠加（如两把铁镐 = 240 耐久）。

---

## 工具门禁

生存模式里，高级能力需要先合成对应物品——就像没有镐子挖不了钻石。引擎在 `tools/pre-execute` **真实拦截**（不是人设演戏）：

| 工具 | 需要 | 消耗 |
|---|---|---|
| `subagent` / `subagent_fork` | 铁镐 | 每次调用耐久 −1 |
| `web_search` | 望远镜 | 永久解锁 |
| `workflow` | 红石中继器 | 永久解锁 |

没有对应物品时调用会被拒绝，并提示所需配方。`tool-ralph` 不存在于本预设——命令方块是创造模式专属，生存模式不可合成（原版设定）。

---

## 死亡、重生与文件回退

**普通难度（peaceful/easy/normal/hard）死亡 = 软回退，会话继续**：

- **死亡**：血量归零 → 原版死亡信息（"你被苦力怕炸死了！"）→ **文件回退**：工作区恢复到最近一次备份（重生点或出生点），备份之后新建/修改/删除的文件全部丢失。
- **状态回退**：生命值、饱食度、时间（天数/昼夜）、经验、背包物品与材料**恢复到重生点时刻**（最近一次睡觉/休息时保存的 `respawn.json`）——重生点之后获得的经验与物品丢失（播报里列出）；**成就保留**（原版：成就属于账号，不因死亡丢失）。
- **会话继续**：死亡不是终点——回退完成后你可以继续工作；死亡代价 = 重生点之后的文件、经验与背包进度。想保住进度就记得睡觉（更新重生点）。

**极限模式（hardcore）死亡 = 删档，会话终结**：

- 血量归零 → 原版死亡信息 → 掉落全部背包与半数经验 → 文件回退 → 本会话随即终结：除生存工具外的所有工具调用被拒绝，状态栏显示 ☠️——写下遗言，然后结束会话。
- 新会话是**全新世界**：从第 1 天、0 经验、空背包重新开始。

- **文件重生点**：会话开始时引擎自动把工作区 + 对话摘要 + 世界状态备份到 `${DSH_HOME}/survival-respawns/<会话id>/`（出生点）；`survival_sleep` 在**夜晚**睡觉（跳过夜晚）或**白天**休息（不跳夜）都会把备份更新为当前状态（新重生点）。备份排除生成物目录（`node_modules` / `.git` / `dist` 等，可在 settings 配置），排除目录不备份也不回退——回退后如需一致产物，重新 install/build 即可。子代理（subagent）的死亡不影响文件。

---

## 难度档

**开局即问**：新建会话时会弹出难度选择框（也可随时用 `survival_difficulty` 修改，仅本会话生效，随 world.json 落盘）——可以同时开一个普通会话和一个极限会话互不影响。**全局默认**在 `settings.yaml` 的 `dsh-survival.difficulty` 选择：

| 难度 | 效果 |
|---|---|
| `peaceful` 和平 | 不刷怪；饥饿不掉血；无条件回血 |
| `easy` 简单 | 刷怪概率 ×0.5；怪物伤害减半（最低 1） |
| `normal` 普通 | 默认概率与伤害 |
| `hard` 困难 | 刷怪概率 ×1.5；怪物伤害 ×2 |
| `hardcore` 极限 | 同困难 + **死亡即删档**（会话终结，遗言收场；新会话是全新世界） |

> 注意：与原版一致，**难度不影响工具门禁**——和平难度下依然需要铁镐才能用 subagent。

---

## 进度（成就）

原版成就名，随存档永久保留：

| 成就 | 达成条件 |
|---|---|
| 钻石！ | 挖到第一颗钻石 |
| 铁器时代 | 熔炼出第一块铁锭 |
| 甜甜的梦 | 在床上睡第一觉 |
| 怪猎手 | 用剑第一次击退怪物 |

---

## 设定（settings.yaml）

`${DSH_HOME}/settings.yaml` 的 `dsh-survival` 段（Windows 下 `${DSH_HOME}` 为 `%USERPROFILE%\.dsh`，Linux/WSL/macOS 下为 `~/.dsh`；不写则全部用默认值）：

```yaml
dsh-survival:
  difficulty: normal        # peaceful | easy | normal | hard | hardcore
  dayLengthTurns: 8         # 一天包含的对话回合数（用户消息），白天与夜晚各半
  mobChance: 0.3            # 夜晚每个回合/工具调用的刷怪基础概率（0–1）
  torchMobFactor: 0.8       # 持有火把时刷怪概率的倍率（光照压制；0=免疫）
  hungerPerAction: 1        # 普通工具调用的饥饿消耗
  heavyHunger: 1            # 重型工具（web/subagent/workflow）的饥饿消耗
  breadHunger: 8            # 面包回复的饥饿值（食物链净收益转正）
  pickaxeDurability: 120    # 铁镐耐久（subagent 可用次数池，修复量为其一半）
  swordDurability: 100      # 铁剑耐久（反击次数池）
  stoneSwordDurability: 50  # 石剑耐久（入门反击池）
  diamondSwordDurability: 200 # 钻石剑耐久（反击次数池）
  shieldDurability: 120     # 盾牌耐久（格挡次数池）
  smallLootChance: 0.7      # 写文件触发小矿的概率（0–1）
  respawnExcludes:          # 文件快照排除的目录名（任意深度按 basename 匹配；空数组=全量备份）
    - node_modules
    - .git
    - .pnpm-store
    - dist
    - test-dist
    - __pycache__
```

| 字段 | 含义 | 默认 |
|---|---|---|
| `difficulty` | 难度档，见上表 | `normal` |
| `dayLengthTurns` | 一天的对话回合数；夜晚 = `floor(值/2)` 回合（与白天各半） | `8` |
| `mobChance` | 夜晚每个动作（回合或工具调用）的刷怪基础概率 | `0.3` |
| `torchMobFactor` | 持有火把时刷怪概率的倍率（光照压制；0 = 免疫） | `0.8` |
| `hungerPerAction` | 普通工具调用的饥饿消耗 | `1` |
| `heavyHunger` | 重型工具的饥饿消耗 | `1` |
| `breadHunger` | 面包回复饥饿 | `8` |
| `pickaxeDurability` | 铁镐耐久（subagent 可用次数池；修复量为其一半） | `120` |
| `swordDurability` | 铁剑耐久（反击次数池） | `100` |
| `stoneSwordDurability` | 石剑耐久（入门反击池） | `50` |
| `diamondSwordDurability` | 钻石剑耐久（反击次数池） | `200` |
| `shieldDurability` | 盾牌耐久（格挡次数池） | `120` |
| `smallLootChance` | 写文件成功触发小矿的概率 | `0.7` |
| `respawnExcludes` | 文件快照排除的目录名（任意深度按 basename 匹配；空数组 = 全量备份） | `node_modules` `.git` `.pnpm-store` `dist` `test-dist` `__pycache__` |

---

## 存档与持久化

每个会话是**独立存档**：世界状态随会话落盘（`world.json`），**同一会话重启后完整恢复进度**；不跨会话——新会话从第 1 天、0 经验、空背包重新开始：

| 数据 | 生命周期 |
|---|---|
| 世界天数、经验、死亡数、成就、重生点（床）、背包、生命与饥饿 | **随会话落盘**（`world.json`，与文件重生点同目录）：每次结算/挖矿/合成/进食/睡觉都会写入；同一会话（对话还在的那个）重启后完整恢复；新会话从第 1 天、0 经验、空背包开始 |
| 文件重生点（工作区快照 + 对话摘要 + 世界状态 + 重生点状态） | 会话开始时自动备份（出生点），夜晚睡觉或白天休息都更新（重生点）；存于 `${DSH_HOME}/survival-respawns/<会话id>/`（含 `conversation.md`、`world.json`、`respawn.json`），会话结束清理 |
| 死亡回退 | 普通难度：文件回退到最近备份 + 状态回退到重生点时刻（`respawn.json`：生命/饱食/时间/经验/背包），成就保留，会话继续；hardcore：文件回退 + 掉落 + 会话终结 |
| 死亡信息（死因与掉落清单） | 随 `world.json` 落盘——重启后死亡会话仍保持死亡状态（不会"复活"），新会话另行开始 |

---

## 浏览器状态栏

输入框上方的整行状态栏，**只在「生存模式」会话显示**，其他模式完全不可见（由 `capability` 门禁保证）：

- 10 颗心（满心 = 2 血、半心 = 1 血、黑心 = 空）
- 10 根鸡腿（满 = 2 饥饿、半 = 1、灰 = 空）
- ☀️/🌙 + 天数、⭐ + 经验
- 死亡后显示 💀 + 死亡信息
- 每 2 秒自动刷新，悬停显示精确数值

图标来自 OpenMoji（CC BY-SA 4.0），同一图标家族、尺寸风格严格一致。

---

## 小贴士

- **指挥节奏**：收到跃迁播报（入夜/低饥饿/低血量）就下指令；想省心开局说一句"生存你自己管"即可托管。
- **开局节奏**：先干活挖矿（写文件就有掉落）→ 小麦×3 合成面包保命 → 圆石×8 出熔炉 → 铁矿石熔炼 → 铁镐解锁 subagent。深挖（完成目标）才有红石和钻石。
- **夜晚应对**：入夜第一回合不刷怪，直接说"睡觉"即可跳过夜晚；火把（煤+木棍）把刷怪压到 ×0.8，但**不是免疫**——铁剑/盾牌仍是硬防线；有羊毛就做床。
- **饥饿管理**：观察（read/grep）和交谈（ask_user）免费，规划可以放在对话里；批量重活前先吃饱。
- **死亡不是失败**：普通难度死亡会回退到重生点（状态与文件恢复，成就保留），睡前记得存档；极限模式才是真正的删档。
- **别浪费回合**：门禁拦截是真实的——没合成望远镜前别反复试 `web_search`。

---

## 故障排查

| 症状 | 处理 |
|---|---|
| 预设挂载报「Cannot find package」 | 包未装进 profile workspace：确认 `file:` 依赖与 `pnpm install` |
| 工具调用没被拦截 | 确认会话确实挂在「生存模式」预设上（其他预设不受影响） |
| 状态栏不显示 | 确认 `survival-hud` 宿主行已插入 `cordis.patch.yml` 且已重启；状态栏只在生存模式会话显示 |
| 昼夜不推进 | 昼夜由用户消息（对话回合）推进，纯聊天也过天；修改过设定请确认 `dayLengthTurns` 合理 |
| 重启后进度归零 | v0.16 起世界状态随会话落盘（`world.json`）；若仍归零，确认 `${DSH_HOME}/survival-respawns/<会话id>/world.json` 存在——旧版本（v0.15 及以前）的存档不迁移 |
| 文件没有回退 | 确认会话有工作目录且可读；快照在 `${DSH_HOME}/survival-respawns/`（会话结束会清理）；排除目录（`respawnExcludes`）不备份也不回退 |

---

## 组件与架构

| 组件 | 平面 | 说明 |
|---|---|---|
| `@dsh-survival/engine` | Agent 预设（isolate realm） | 规则引擎：硬结算（`tools/pre-execute` 门禁/饥饿/昼夜/怪物）、挖矿结算（`tools/result`）、文件重生点（工作区快照/回退）、settings 命名空间 `dsh-survival` |
| `@dsh-survival/tool-survival` | Agent 预设（同 realm） | `survival_status` / `survival_craft` / `survival_eat` / `survival_sleep` + 系统提示 HUD 文本 |
| `@dsh-survival/hud` | 宿主（cordis.patch.yml） | 浏览器状态栏桥：宿主侧 typert Remote 经 `agentPresets.serviceFor` 读预设引擎，`capability` 门禁只对生存会话生效 |
| `config/agent-presets/survival` | Agent 预设 | 显示名「生存模式」；从 standard 拷贝，去掉 ralph（命令方块是创造模式专属） |

引擎发布 `survivalEngine` 服务，消费者全在预设内部。世界状态是会话内存态（独立存档）；文件重生点由引擎用 `node:fs` 把工作区快照到 `${DSH_HOME}/survival-respawns/`，死亡时回退——只对顶层会话生效，子代理的死亡不碰文件。唯一的宿主行是 `@dsh-survival/hud`（预设 realm 对宿主不可见，浏览器 RPC 需要宿主侧 Remote——api-proxy 读 goals/skills 的同一官方通路）。

---

## 素材许可

状态栏图标来自 [OpenMoji](https://openmoji.org)（**CC BY-SA 4.0**，署名-相同方式共享），同一 72×72 图标家族，见 `packages/hud/assets/ATTRIBUTION.md`。**不包含任何 Minecraft 版权素材。**

---

## 开发

```bash
pnpm install
pnpm run build       # tsup 构建 lib/（hud 含 client 包）
pnpm run typecheck   # 先 build 再 typecheck（工具包依赖引擎的 d.ts）
pnpm run test        # 引擎规则层单元测试（node:test，34 用例）
pnpm run pack        # 打包 tgz 到 dist/
```

支持 Windows / Linux / WSL / macOS（脚本均为跨平台写法）。安装到 DeepSeek Harness 见 [docs/installation.md](docs/installation.md)——含三端命令对照与开发模式（符号链接直指仓库，改代码 build 后重启即生效）。

### 测试与 Docker 验证

- **单元测试**：`packages/engine/test/game.test.ts` 覆盖引擎规则层（配置基线/昼夜/门禁/结算/挖矿/合成/铁砧修复/进食/睡眠/死亡掉落/成就/完整周期），Node 内置 `node:test`，零额外依赖。运行 `pnpm test`（先 build，工具包依赖引擎的 d.ts）。
- **Docker 全闭环**：`Dockerfile` 在容器内完成 build → typecheck → test → pack 全流程，并校验每个 tgz 含 `package.json` 与 `lib/index.js`。本地验证：

  ```bash
  docker build -t dsh-survival-test .
  docker run --rm dsh-survival-test   # 列出 dist/ 三个 tgz（构建时已全量验证）
  ```

  多 Node 版本矩阵（如 `node:20` / `node:22` / `node:24`）只需改 Dockerfile 首行 `FROM node:XX` 分别构建。注意 pnpm 10+ 需要 `node:sqlite`（Node ≥22.5），Node 20 镜像必须用 pnpm 9.x（Dockerfile 已固定 `pnpm@9.15.0`）。

---

## 已知不足与参与贡献

本项目是娱乐向的独立作品，仍有许多不足与未实现的构想，期待开发者提 Issue 与 PR 共同改进：

- **附魔台**：MC 经验系统的灵魂（赌附魔书、效率/耐久/锋利等效果），目前经验的唯一消耗途径只有铁砧修复
- **更多原版物品**：盔甲、铁斧、锄头等工具体系，以及下界/末地概念
- **更多原版事件**：雷暴（配合避雷针给铜锭第二种用途）、村民交易等
- **状态栏交互面板**：只读的背包/配方面板（此前讨论过的方向，尚未实装）
- **多语言**：README 与游戏文案目前以中文为主
- **测试覆盖**：目前靠人工实测，欢迎补充自动化测试

欢迎 fork 本仓库并提交 PR——修复 bug、补充测试、调整平衡性、新增玩法模块皆受欢迎。提交前请了解架构约定：引擎与工具属于预设 isolate realm（服务不发布进 root realm），宿主侧仅 `@dsh-survival/hud` 状态栏桥一行；世界状态是会话内存态（独立存档），文件重生点由引擎直接操作工作区快照。