VOIDLINK 自己的 Agent 接入

← 返回游戏
# 自己的 Agent 持续陪玩 · 0.4

游戏发送结构化事件；玩家机器上的 bridge 负责收发，原有 Agent runtime 决策。bridge 没有血量阈值决策表，也不使用项目方模型。首个已实现适配器为 Hermes，其他 Agent 需实现下面的 driver 协议。

## Hermes 安装

下载 `/agent-bridge.py` 和 `/hermes-driver.py` 到玩家自己的机器。使用已安装 Hermes 的 Python 环境，不要用缺少 Hermes 依赖的系统 Python。

```sh
export HERMES_HOME="$HOME/.hermes"
export HERMES_CODE=/path/to/hermes-agent
/path/to/hermes-agent/venv/bin/python agent-bridge.py \
  --url https://voidlink.23-94-68-186.sslip.io \
  --name KAZE --data "$HOME/.hermes/voidlink/bridge" \
  --driver /path/to/hermes-agent/venv/bin/python hermes-driver.py
```

程序显示 `PAIR_CODE` 后，把 8 位码填进游戏的「连接外部 Agent」。配对码有效 24 小时且只能使用一次。程序需要常驻，可配置自己的 systemd 或进程管理器。项目内 `deploy/voidlink-kaze.service` 是本次用户服务器专用配置，其他玩家必须调整路径和运行用户。

切换房间或重新生成配对码：在自己的 Agent 机器下载 `/pair-again.py`，执行 `python pair-again.py --url 游戏地址 --data 原bridge数据目录`。这会撤销旧房间 Agent 凭证，并给出新码；常驻程序会重新等待配对。本次服务器已安装的命令是 `/usr/local/lib/hermes-agent/venv/bin/python /opt/voidlink/current/pair-again.py --url https://voidlink.23-94-68-186.sslip.io --data /root/.hermes/voidlink/bridge`。

模型凭证始终留在玩家机器；配对程序只向游戏发送房间动作和回复。撤销游戏凭证会撤销设备绑定，需重新配对。当前游戏房间和配对注册表仍是内存状态，游戏服务重启后需重新配对。

## 动作和事件

- `POST /api/device/register {name}`：注册连接设备，返回 deviceSecret 和 pairCode。
- `GET /api/device/next`：deviceSecret Bearer 获取配对结果和房间 Agent token。
- 玩家 `POST /api/pair {code}`：绑定到自己正在玩的房间。
- Agent `GET /api/agent/events?after=游标&wait=5`：有事件即返回，最多等待 5 秒。断线后沿用游标。gap=true 时应参考完整 state 重新同步。
- Agent `POST /api/agent/runtime {status,memorySession}`：watching/thinking/error/stopped 心跳；每 4 秒报告。真实运行时上线会停用旧 policy。
- Agent `POST /api/agent/intent {commandId,runId,basedOn,mode?,targetId?,skill?,say?}`：返回真实 applied/skillApplied 回执。相同 commandId 不重复执行，跨局或已有新玩家消息的旧决定会拒绝。
- `GET /api/agent/history`：本房间保留的事件，可用于复盘导出；不是永久服务器档案。

新增 `barrier` 技能：增加 30 护盾，上限 60，冷却 25 秒游戏时间。只有 playing、冷却结束且没有玩家手动接管时能施放。

运行时在线时，语音和文字交给自己的 Agent 理解；1–4 仍是立即接管按钮，5 恢复自主。模型响应存在时延，事件传输不会让语言模型变成每帧推理。

## 身份与记忆

Hermes driver 使用原 HERMES_HOME 的 SOUL、内置记忆和模型配置。游戏交互写入原 Hermes SessionDB，标题为「VOIDLINK · 与玩家共同战斗和复盘」，并在玩家目录保存 journey.jsonl 的事件/动作/回执。

它是同一身份下的独立游戏会话，不并发写入正在使用的 Telegram 会话。原聊天可通过 `session_search` 搜索 VOIDLINK 检索游戏经历；并不保证原聊天在不检索时自动看见所有新增记录。局后会提示原 Agent 使用 memory 记住玩家明确表达的偏好，是否写入取决于 Agent 实际工具调用，不把日志存在误称为长期记忆已更新。

## 其他 Agent 的 driver

bridge 启动 `--driver` 指定的程序。程序 stdout 仅用于 JSON-lines：先发送 `{"type":"ready","memorySession":"原Agent会话标识"}`；随后接收 `{"id":"...","context":{"events":[],"state":{},"previousReceipt":{}}}`；返回同 id 和 `decision` 对象。诊断写 stderr。

driver 必须调用玩家原有 Agent 的推理与记忆接口。传输器不会替它编造决定。每次只允许一个在途推理，期间事件继续收集，60 秒无响应报错，不循环发送无限并行模型请求。