> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baimoqilin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理会话

> 高级会话工作流、历史回顾、存储结构与恢复流程。

## 为什么要维护会话纪律

会话是 MineClawd 的长期记忆。清晰的会话流程能提升答案准确度、减少上下文错误，并在出现故障时快速恢复。

## 会话的作用域

* 会话按拥有者密钥隔离。
* 玩家命令使用玩家 UUID 作为拥有者密钥。
* 控制台命令使用命令来源名称。
* 每个拥有者仅保存一个活动会话指针。
* 所有会话命令都需要 OP 权限等级 `2`。

## 每日命令工作流

| 目标              | 命令                                | GUI 替代                           |
| --------------- | --------------------------------- | -------------------------------- |
| 开始一个干净上下文       | `/mineclawd sessions new`         | 在 Sessions 视图中点击 **New Session** |
| 查看所有保存会话        | `/mineclawd sessions list`        | 在覆盖层菜单打开 **Sessions**            |
| 切换活动上下文         | `/mineclawd sessions resume <会话>` | 点击 Sessions 视图中的任意行              |
| 删除过时会话          | `/mineclawd sessions remove <会话>` | --                               |
| 查看当前聊天历史        | `/mineclawd history`              | 在覆盖层滚动对话记录                       |
| 修复损坏的 Vertex 轮次 | `/mineclawd sessions repair [会话]` | --                               |

`<会话>` 可以是类似 `1a2b` 的短 ID，也可以是 `1a2b-my-build-plan` 这样的令牌。

<Tip>
  优先使用短 ID（如 `1a2b`）记录笔记、脚本与运行手册。ID 较稳定，而令牌的标题部分可能会在 MineClawd 生成更好标题时改变。
</Tip>

## 长任务最佳实践

1. 每个目标开启一个会话，而非一个会话处理所有任务。
2. 想要重命名上下文时，用新会话替代旧历史，避免无限拖动旧记录。
3. 在运行 `resume`、`remove` 或 `repair` 前先执行 `/mineclawd sessions list`。
4. 不要在请求仍在运行时修改会话。
5. 在执行破坏性任务前，先用 `/mineclawd history` 回顾上下文。

## 高效使用 `/mineclawd history`

* 历史书显示会话令牌、更新时间与可见的对话轮次。
* 该命令仅对玩家有效，控制台无法使用。
* 历史书 UI 需要客户端安装 MineClawd。
* 超长历史会因为 Minecraft 书页面限制而截断。

如果客户端未安装 MineClawd，可用 `sessions list` 配合最近的聊天日志作为备用上下文检查方式。

## 恢复操作流程

### 请求失败但要保留上下文

使用最新失败提示中的 `/mineclawd retry <令牌>`。重试令牌有效期 30 分钟。

### Vertex 函数调用不匹配错误

运行：

```bash theme={null}
/mineclawd sessions repair
```

或指定会话：

```bash theme={null}
/mineclawd sessions repair <会话>
```

`repair` 会规范化损坏的 Vertex 函数调用轮次并保存修复后的会话。

## 会话文件位置

MineClawd 在游戏目录下保存：

```text theme={null}
mineclawd/
  sessions/
    <owner>/
      active.json
      <id>.json
```

* `active.json` 保存活动会话 id。
* `<id>.json` 存储元数据及 OpenAI 与 Vertex 历史。
* 如果删除活动会话，MineClawd 会自动选取最近更新的会话作为新活动；如果没有剩余会话，活动指针会清空。

## 备份与清理策略

1. 批量清理前备份 `mineclawd/sessions/`。
2. 使用 `/mineclawd sessions remove <会话>` 删除过时会话。
3. 每位运营者保留一个可快速恢复的稳定会话。
4. 需要查看存储内部时参考 `/resources/technical-details`。

## 相关页面

* [使用 GUI](/tutorials/using-the-gui)
* [/commands/sessions-list](/commands/sessions-list)
* [/commands/sessions-resume](/commands/sessions-resume)
* [/commands/sessions-repair](/commands/sessions-repair)
* [/commands/history](/commands/history)