# Bot 转发通道完整实现计划

本文用于把工作分配给多个 Agent 分步实现。本文是设计及任务约束，不代表功能已经实现。

工作区根目录：`/home/wupeng/Project/mf_v3`。

## 1. 目标与边界

用户在 Web 请求连接某个 Bot 的转发通道，主服务器鉴权并确认 Node 在线后，命令 Node 连接转发服务器。Node 成功入房并准备好请求处理后，主服务器返回 Web 连接地址与 Web 专用凭证。Web 经转发服务器查询状态、订阅事件及执行白名单交互。

必须满足：

- 任意 `bot_status` 均允许申请转发通道，包括 `offline`、`ready`、`connecting`、`online`、`disconnecting`、`reconnecting`。
- 不存在 BotContext 也允许建立通道，查询结果为 `offline`、`context_exists: false`。
- Node 必须是主服务器当前已认证、在线且能接收命令的节点会话。
- 建立或恢复转发连接不得调用 `start_bot_context()`，不得重置 Minecraft 自动重连次数。
- `stop_bot` 只销毁 BotContext，转发通道保持，前端收到 `offline`。
- 再次启动 Bot 后，通道自动绑定新 BotContext，无需重新连接 Web Socket。
- Node 和 Web 使用不同角色凭证；Web 不能伪装 Node，不能向其他 Web 广播。
- 命令响应只返回请求方；只允许白名单事件和业务方法。
- 每一个连接、入房、请求及关闭过程都有超时、取消及身份检查。
- 本次实现统一升级协议，不增加旧协议兼容分支。
- Bot 游戏状态、Node 在线状态、转发连接状态分别维护，禁止互相覆盖。

首版转发支持：快照、日志读取、事件订阅、取消订阅、在线聊天。启动、停止、配置修改继续走主服务器现有接口，不在转发层复制一套生命周期入口。

## 2. 当前源码问题与处理归属

以下是设计时确认的源码问题，实施前应重新核对文件现状和行号。

| 问题 | 位置 | 归属任务 |
| --- | --- | --- |
| handler 参数 `socket` 与局部变量重复，缺少 `io` 导入，动态加载可能导致 Node 启动失败 | `node_server/event_handler/bot/forward_bot.ts` | D |
| 分发器忽略所有 `forward_` 开头事件，导致 `forward_bot` 被静默丢弃 | `node_server/event_handler/init.ts` | D |
| HTTP 转发路由缺少开头 `/`，校验后没有响应及命令流程 | `main_server/router/node/action.ts` | E |
| 转发房间不区分 Node/Web，任意事件广播给所有其他成员 | `forward_server/index.ts` | B |
| 将原始 ACK 函数传给房间广播，实际变成广播 ACK，语义和超时错误 | `forward_server/index.ts` | B |
| token 只有 `node_id`、`bot_id`，没有角色、有效期及会话作用域 | `forward_server/types.ts` 和 token 工具 | A、B、E |
| 把转发服务启动 ID 当作执行 Node ID，内置服务 `-1` 与实际节点不匹配 | `forward_server/index.ts`、`main_server/index.ts` | B、G |
| 重复加入新房间后没有离开旧房间 | `forward_server/index.ts` | B |
| 服务单例并发初始化、监听端口错误、关闭清理和单例复位不完整 | `forward_server/index.ts` | G |
| 转发服务注册表不清理死连接，重复注册可能断开共享 Node 控制 Socket | `main_server/runtime/forward_server/socket.ts` | G |
| BotContext 注册表缺少查询、创建、移除通知；直接绑定一个 Bot 实例无法跨重建保持 | `node_server/bot/instance/index.ts` | C |
| `BotContext.onAny()` 没有对应解绑入口；原始事件可能包含完整 Bot 对象 | `node_server/bot/instance/bot_instance_init.ts` | C、D |
| 跨域、公开地址、TLS 和反向代理未形成明确配置 | 转发服务启动配置 | G、F |

AES-GCM 解密已有完整性校验，不应把问题误写成“token 没有验签”。问题是缺少声明验证、角色隔离、到期和撤销机制。没有证据说明当前公开 HTTP DTO 已泄漏转发密钥，新接口仍必须显式投影公开字段。

## 3. 推荐端到端时序

```mermaid
sequenceDiagram
    participant W as Web
    participant M as Main
    participant N as Node
    participant F as Forward
    W->>M: POST /api/user/node/forward_bot {bot_id}
    M->>M: 用户/Bot归属/节点与转发权限/当前Node会话
    M->>F: forward_open_session
    F-->>M: 控制ACK
    M->>N: forward_bot(作用域、地址、Node凭证、截止时间)
    N->>F: Socket.IO connect + join_room(node)
    F-->>N: join ACK
    N->>N: 注册请求处理及Bot上下文订阅
    N-->>M: joined:true ACK
    M->>M: 再次核对当前Node会话及Bot归属/分配
    M-->>W: 公开URL/path/namespace + Web凭证
    W->>F: connect + join_room(web)
    F-->>W: join ACK + node_ready
    W->>F: relay_request(bot.snapshot)
    F->>N: relay_request(内部关联ID)
    N-->>F: 定向ACK
    F-->>W: 定向ACK
    N-->>F: bot_event
    F-->>W: 已授权且已订阅的Web
```

`forward_open_session` 由已经认证的主服务器与转发服务控制通道发送。不能由 Web Socket 调用。

## 4. 任务 A：协议约定与各项目本地实现清单

### 4.1 文件所有权

不新增根目录共享协议目录或公共包，也不要求各项目跨目录引用类型、校验器或 token 工具。每个项目使用自己的类型、工具和测试目录，沿用现有结构。

本文件是多 Agent 协作时的通信协议约定，不是运行时依赖。相同协议类型允许在各项目本地定义，但事件名、字段、错误码、时间单位和验证行为必须一致。

建议落点及文件所有权：

| 项目 | 本地类型与校验 | 凭证工具 | 实现 owner |
| --- | --- | --- | --- |
| `forward_server` | 沿用 `types.ts`，校验与常量放本项目工具目录 | 沿用 `utils/token_utils.ts`，负责验证 | B；启动校验由 G 接入 |
| `node_server` | 在现有 `types/`、`utils/` 中定义节点命令、ACK 和事件 DTO | 节点转发客户端只使用 Main 下发的 token，不为远程转发服务签发凭证 | D；C 提供观察事件接口 |
| `main_server` | 在现有 `types/`、`utils/` 中定义控制协议和 HTTP DTO | 沿用 `utils/token_utils.ts`，负责签发 | E；控制接入由 G 负责 |
| `main_server_web` | 在现有类型/API目录中定义浏览器所需类型和响应检查 | 不包含密钥、签发或服务端解密工具 | F |

A 只整理并冻结文档中的协议、字段归属、校验规则及测试向量，不提前创建或占用 B/D/E/F 负责的生产文件。各 Agent 只实现本项目实际使用的部分，不必复制无关服务端类型。

不得为此引入跨项目源码别名、新 workspace 包、代码生成或改变项目构建结构。协议校验不依赖数据库、BotContext 或 UI 框架；服务端密钥工具禁止进入前端 bundle。

协议变更先更新本文件并通知受影响的 owner，再分别同步各项目本地实现。H 通过共同的合法/非法消息样例、token 测试向量及跨服务联调验证一致性，不能仅凭本地 TypeScript 类型检查判断网络协议兼容。

### 4.2 身份与时间约定

| 字段 | 定义 |
| --- | --- |
| `forward_id` | 转发服务 ID，非负安全整数，内置服务为 `0` |
| `node_id`、`bot_id`、`user_id` | 正安全整数 |
| `node_session_id` | Main 当前认证的 Node 会话标识，不由浏览器提供 |
| `forward_session_id` | Main 分配的转发通道 UUID，独立于 Socket.IO `socket.id` |
| `grant_id` | 单个浏览器授权的 UUID，不同标签页独立 |
| `request_id` | 一次业务请求的 UUID |
| `context_generation` | 每次 BotContext 创建的新 UUID；无上下文时为 `null` |
| `stream_id` | 节点事件流 UUID；Node 重启或流重建时改变 |
| `seq` | 同一 `stream_id` 内递增的安全整数 |
| `*_at`、`*_before` | Unix 毫秒时间戳 |

Bot 状态类型不包含 `disposed`。销毁是内部终止标记，公开状态为 `offline`。

### 4.3 Socket ACK

```ts
type ForwardAck<T> =
    | {status: 'success'; data: T}
    | {status: 'error'; data: {
        code: ForwardErrorCode;
        message: string;
        retryable: boolean;
    }};

type ForwardErrorCode =
    | 'INVALID_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN'
    | 'NODE_OFFLINE' | 'RELAY_UNAVAILABLE' | 'SESSION_STALE'
    | 'TOKEN_EXPIRED' | 'TIMEOUT' | 'CANCELLED'
    | 'NO_CONTEXT' | 'BOT_NOT_ONLINE' | 'RATE_LIMITED'
    | 'RESYNC_REQUIRED' | 'INTERNAL_ERROR';
```

转发业务统一采用这个 ACK；现有 `register_node` 等控制协议不在 A 中整体重写。HTTP 层沿用项目响应包装，并显式映射错误，不调用只适配旧数字 `data` 的辅助函数来解析新 ACK。

### 4.4 Main → Node 命令

事件 `forward_bot`：

```ts
interface ForwardBotCommand {
    request_id: string;
    forward_session_id: string;
    node_session_id: string;
    forward_id: number;
    node_id: number;
    bot_id: number;
    user_id: number;
    deadline_at: number;
    relay: {
        url: string;
        path: string;
        namespace: string;
        token: string;
    };
}

interface ForwardBotReady {
    request_id: string;
    forward_session_id: string;
    node_session_id: string;
    forward_id: number;
    node_id: number;
    bot_id: number;
    joined: true;
}
```

`ForwardAck<ForwardBotReady>` 成功表示 Node 已入房、业务请求处理器已安装、上下文观察已建立；不要求存在 BotContext，也不代表 Minecraft 在线。

### 4.5 入房及续期

```ts
interface JoinRoomRequest {token: string}

interface JoinRoomReady {
    forward_session_id: string;
    forward_id: number;
    node_id: number;
    bot_id: number;
    role: 'node' | 'web';
    node_ready: boolean;
    expires_at: number;
}
```

事件 `join_room` 使用 `ForwardAck<JoinRoomReady>`。作用域全部从受保护 token 取得，不相信客户端另传的房间名、角色和 Bot ID。

事件 `reauth` 接收 `{token: string}`，返回同一作用域的更新凭证结果。续期不得改变角色、Bot、Node、会话或 Web `grant_id`；变更这些字段必须重新建立授权。

### 4.6 Token 声明

```ts
interface RelayClaims {
    v: 1;
    forward_id: number;
    forward_session_id: string;
    node_session_id: string;
    node_id: number;
    bot_id: number;
    role: 'node' | 'web';
    user_id?: number;
    grant_id?: string;
    permissions: RelayMethod[];
    issued_at: number;
    join_before: number;
    expires_at: number;
    jti: string;
}
```

默认策略：新 token 在 60 秒内可用于入房或 reauth，连接授权最长 5 分钟，到期前 60 秒续期。时间参数集中定义，可配置；所有端使用相同毫秒单位，允许有限时钟偏差。

验证顺序：大小与格式 → GCM 完整性 → JSON 字段 → 版本/服务 audience → 时间 → 控制通道登记的有效会话 → 角色/权限/浏览器 grant。

Node token 不带 Web grant；Web token 必须带 `user_id`、`grant_id`。Main 与指定转发服务共享服务端密钥，密钥不得进入 Node 命令、公开响应或日志；Node 只获得受限 token，不获得转发密钥。Node 自己提供内置转发服务时，只能持有它本来配置的本地服务密钥，不能借此取得其他转发服务密钥。Node 不能仅通过解码把 token 当成已验证身份，最终有效性由转发服务 ACK 确认。

### 4.7 业务 RPC

```ts
type RelayMethod =
    | 'bot.snapshot' | 'bot.logs'
    | 'bot.subscribe' | 'bot.unsubscribe' | 'bot.chat';

interface RelayRequest {
    request_id: string;
    method: RelayMethod;
    payload: unknown;
}
```

Web 发送 `relay_request` 并等待 ACK。转发服务为它分配内部关联 ID，只对当前 Node Socket 发单目标 `emitWithAck`；Node 的响应由转发服务校验后返回原 Web ACK。禁止把 Web 的 ACK 函数传进房间广播。

每个内部关联记录绑定 Web Socket、grant、Node Socket 版本及超时。Web 的 `request_id` 仅在对应 grant 内唯一，不直接作为全局 Map 键。

`bot.subscribe` 参数为 `{events: BotEventName[]}`，整体替换当前 Web 的订阅集；重复请求幂等。`bot.unsubscribe` 删除给定事件，空数组不影响其他事件。订阅默认空，Web 入房后显式设置。

`bot.logs` 参数为 `{stream_id?: string, after_seq?: number, limit: number}`，限制 1 到 200；传 after_seq 时必须携带 stream_id。流已更换或缓存不覆盖请求区间时返回 `RESYNC_REQUIRED` 或明确 `truncated: true`，不得伪装完整记录。响应包含本次 stream ID、读取水位、记录及是否截断。

`bot.chat` 参数为 `{message: string}`，限制为非空字符串和可配置长度。Node 再次检查上下文及当前实例在线；不自动重放。

### 4.8 快照及事件

```ts
interface BotSnapshot {
    bot_id: number;
    bot_status: BotStatus;
    context_exists: boolean;
    context_generation: string | null;
    stream_id: string;
    seq: number;
    captured_at: number;
}

type BotEventName = 'status_update' | 'log' | 'message' | 'bot_error';

interface BotEvent {
    forward_session_id: string;
    bot_id: number;
    context_generation: string | null;
    stream_id: string;
    seq: number;
    emitted_at: number;
    name: BotEventName;
    payload: unknown;
}
```

`bot_event` 只允许从 Node 输入，转发给已授权、订阅相应事件的 Web。每种 `payload` 定义具体 DTO，不保留最终的任意 `unknown` 实现。

- 状态：`{status: BotStatus, context_exists: boolean}`。
- 日志：保留项目日志 ID、时间戳和样式 DTO，限制批次数及总字节数。
- 消息：文本、位置及必要的有界 JSON，禁止直接发送 ChatMessage 类实例。
- 错误：`{code?: string, message: string}`，生产环境不传完整堆栈和敏感配置。

`relay_status` 由转发服务发给 Web，包含 `node_ready` 和原因，不改变 `bot_status`。节点通道未准备好时可允许 Web 入房，但业务请求返回 `NODE_OFFLINE`，不能返回虚假成功。

### 4.9 控制通道事件

Main 与转发服务器的已认证控制通道支持：

- `forward_open_session`：登记/更新作用域、当前 Node 会话及租约，严格幂等。
- `forward_authorize_grant`：登记/延长浏览器 grant、用户身份、权限和有效期，必须在签发 Web token 并返回前完成。
- `forward_revoke_session`：关闭指定转发会话，撤销 Node/Web，失败所有等待请求。
- `forward_revoke_grant`：撤销指定浏览器授权，不关闭其他浏览器。
- `forward_session_status`：转发服务上报会话就绪/失联信息，绑定当前控制会话。

控制 payload 和 ACK 类型在 A 中一并冻结。open/renew 不得覆盖不同 Node 会话的旧作用域而不先撤销旧会话。

会话租约上限不得由数据面自行延长；Main 根据仍有效的 grant 续租。转发服务重启丢失内存授权后，Main 先重新登记 session/grant，再允许 Node/Web 恢复入房。

### 4.10 A 的验收

- 文档明确非法 ID、错误角色、过期 token、错误 audience、缺字段及超大输入的预期结果。
- 提供无生产密钥的固定 token 测试向量和篡改/跨作用域失败样例，由 B/E 在各项目测试中分别验证。
- 浏览器 bundle 不包含密钥及 Node token 工具。
- 所有 Agent 获得事件名、payload、错误码、时间单位与版本的固定清单。
- 不新增根目录共享协议包，不引入跨项目源码依赖；本地类型和校验的 owner 已明确。

## 5. 任务 B：实现转发服务器的数据路由与鉴权

### 5.1 文件所有权与依赖

依赖 A；与 G 在接口冻结后并行。

B 独占 `forward_server` 新增的 room/session/router/auth 模块及相关测试。B 不直接改启动入口；向 G 提供 `install_relay_routes(io, session_store)` 和对应清理函数，由 G 接入。

已有 `types.ts` 的旧声明由 B 按 A 冻结的文档约定更新为本项目本地类型；不得保留两套含义不同的 token 类型，也不从其他项目导入协议实现。

### 5.2 会话存储

按 `forward_session_id` 存储：

- 固定 `forward_id / node_id / bot_id / node_session_id`。
- 当前有效 Node Socket 及本地连接 generation。
- Web Socket 与 grant 的映射、订阅集。
- 会话及每个 Socket 的授权截止时间。
- 有界 pending RPC 表。
- 首个 Web 到达前、最后 Web 离开后的回收定时器。

房间名由服务端生成，建议包含 Node、Bot、会话；禁止客户端任意指定 room。可以使用独立 Node/Web 子房间，但 RPC 必须仍按单 Socket 定向。

### 5.3 入房

1. 连接后启动 10 秒未鉴权截止定时器。
2. 要求有效 ACK 回调，校验 token 和登记会话。
3. 同一 Socket 只能绑定一个不可变作用域；相同入房请求幂等返回，不累积其他房间。
4. Node 同作用域最多一条有效上行连接。新连接入房成功后才替换旧连接，并递增 generation。
5. 旧连接断开回调只能清理自己拥有的记录，不能清空新连接。
6. Web grant 和权限写入服务端 `socket.data`，不相信每次消息中的身份字段。
7. `await socket.join()` 成功后才 ACK。
8. 成功或断开时清理未鉴权定时器。

Node 尚未 ready 时 Web 可入房并收到 `node_ready: false`；HTTP 初次建立仍必须先等 Node ready。此设计处理 HTTP 返回后到 Web 入房之间 Node 又掉线的竞态。

### 5.4 RPC 路由

1. Web 必须已鉴权，检查 method 权限和对应 payload。
2. `bot.subscribe/unsubscribe` 在转发服务处理，仅修改本 Web 订阅集。
3. 其他 method 选择该会话唯一当前 Node Socket。
4. 分配内部关联 ID，保存请求方和 Node generation。
5. 对 Node 单目标调用，设置明确 timeout；Node 必须返回完整 `ForwardAck`。
6. 校验当前 Node 所有权仍一致后，把结果回给原 Web，ACK 只调用一次。
7. 超时、Web 离开、Node 替换、会话撤销时清理记录，拒绝迟到结果。

默认 RPC timeout 5 秒；限制每个 Web 的 pending 数量及速率。请求 ID 去重缓存只保留有界窗口，不能宣称跨进程“恰好一次”。有副作用请求断线后不得自动重发。

### 5.5 事件推送

- 只接受当前 Node Socket 的 `bot_event`。
- 校验 Bot、会话、事件白名单、大小和单流递增序号。
- 发给匹配订阅及权限的 Web，不广播给 Node 或其他房间。
- 非当前 Node、Web 伪造 `bot_event`、任意未知事件全部拒绝。
- 不使用 `error` 作为 Bot 业务事件名，避免与 Socket.IO 控制错误混淆。

### 5.6 授权与回收

- token 到期计时器真正断开已有 Socket；不能只在入房时检查。
- `reauth` 仅允许延长同一作用域与 grant 的授权，替换到期计时器。
- 会话撤销及 grant 撤销分别清理对应资源。
- 初次 Node ready 后 60 秒没有任何 Web 加入，回收未使用会话。
- 最后一个 Web 离开后保留 30 秒宽限期，再向 Node 通知释放并清理会话。
- 回收操作核对 generation，不能回收并发建立的新会话。

### 5.7 B 的验收

- Web A 请求不会被 Web B 接收，响应只给 A。
- Web 无法伪造 Node、越权换 Bot、调用控制事件。
- 两个 Web 使用相同 request ID 不冲突。
- Node 替换后旧 ACK、旧事件和旧 disconnect 不影响新连接。
- 重复入房不累积房间；过期、断开及回收后无遗留 timer/pending。
- 默认同步 adapter 和模拟异步 `join` 均在真实入房后 ACK。

## 6. 任务 C：节点 BotContext 注册表观察接口

### 6.1 文件所有权与依赖

依赖 A，可与 B、G 并行。

C 独占：

- `node_server/bot/instance/index.ts`。
- `node_server/bot/instance/bot_instance_init.ts` 中注册表观察所需的最小改动。
- 新增节点 Bot 快照/事件序列化模块。
- 对应测试。

不重写现有 Bot 生命周期、不修改 Minecraft 自动重连插件，不让 D 在这些文件重复实现另一套观察机制。

### 6.2 注册表 API

建议暴露：

```ts
get_bot_context(bot_id: number): bot_instance_context<any> | undefined;
observe_bot_context(bot_id: number, listener: ContextObserver): () => void;
get_bot_snapshot(bot_id: number): BotSnapshot;
```

`observe_bot_context` 注册时应提供当前上下文快照，之后提供创建、替换、状态更新及移除通知；每次通知包含 generation。

明确线性化点：创建通知在上下文可查询且状态上报绑定完成后、实际连接前发出；移除通知在该代次最终 `offline` 可观察后发出。初始化失败的短暂上下文也必须解绑，不留下幽灵订阅。

可以返回一个订阅对象同时含初始快照和 dispose，避免“先查询后注册”之间漏事件。具体 API 由 C 提前冻结给 D，不得让调用方自己轮询私有 Map。

### 6.3 事件桥

- 对稳定的 BotContext 订阅 `status_update/log/message/error`，不对某个 mineflayer Bot 长期持有引用。
- 使用明确事件名及 `off` 解绑；若使用 `onAny`，必须增加匹配的 `offAny` 或 disposer。
- 不把 `instance_created`、完整 Bot、插件状态对象、配置密钥发往转发层。
- 新上下文使用新 generation；旧代次回调立即失效。
- Node 级事件流维护 stream ID、seq 和有界日志缓存，BotContext 销毁不丢失最后 offline 事件。
- 旧日志明确标注历史 generation；状态事件不得用旧代次覆盖当前状态。
- 无上下文快照为 `offline/context_exists:false/context_generation:null`，不创建 Bot 来获取日志。

### 6.4 C 的验收

- 先订阅后启动、先启动后订阅均收到一致快照和后续事件。
- stop/start 跨上下文替换后订阅自动转移。
- Minecraft 实例重建不重复绑定、不丢失稳定上下文事件。
- 解绑后监听器计数恢复；旧回调不修改新 generation。
- JSON 序列化不会遍历 Bot、循环对象或泄漏代理密码。
- snapshot 的 seq 与事件水位一致，可供 F 解决快照竞态。

## 7. 任务 D：节点转发连接管理器与 forward_bot handler

### 7.1 文件所有权与依赖

依赖 A、C 的接口，以及 B 的入房/RPC 协议；允许先对协议桩开发。

D 独占：

- `node_server/event_handler/bot/forward_bot.ts`。
- `node_server/event_handler/init.ts` 的精确分发规则。
- 新增 `node_server/runtime/forward/` 或等效独立管理目录。
- 节点转发 RPC 处理器与测试。

`node_server/index.ts` 由 G 独占，D 提供控制连接状态 hook，由 G 调用。不要在 handler 每次执行时创建不受管理的 Socket。

### 7.2 管理器接口

```ts
ensure_connected(command: ForwardBotCommand): Promise<ForwardBotReady>;
release_session(session_id: string, reason: string): Promise<void>;
on_main_registered(node_session_id: string): Promise<void>;
on_main_disconnected(): void;
close_all(): Promise<void>;
```

按 `(forward_id,node_id,bot_id)` 去重，记录当前 forward session、连接代次、pending ensure、Socket、context disposer、定时器和租约。

会话状态：`idle / connecting / joining / ready / retry_wait / closed`，不得写入 `bot_status`。

### 7.3 ensure_connected

1. 校验命令、URL scheme/path、当前 Node ID/会话和截止时间。
2. 来源必须是主服务器当前已注册控制连接；拒绝旧连接迟到命令。
3. 同作用域同会话 ready 时幂等返回；若 token 更新，先 reauth 成功再 ACK。
4. 同会话正在初始化时共享同一个建立任务，各请求保留自己的等待截止时间。
5. 新会话替代旧会话时取消旧任务、解绑旧观察、关闭旧 Socket。
6. 创建 Socket 使用 `autoConnect:false`，先安装所有监听器，再 connect。
7. 每次 `connect` 都发送 `join_room` 并等待 ACK。
8. 校验 ACK 作用域后安装/确认 RPC 和 C 的观察桥，标记 ready。
9. 向 Main 返回对应 request ID 的成功 ACK。
10. 失败路径标准化错误，只执行一次 ACK，清理仅由本会话拥有的资源。

多个并发申请共享通道，某一个调用者超时不能直接关闭仍被其他有效申请/授权使用的通道。请求截止与会话租约分别管理，控制租约过期才能回收孤立结果。

### 7.4 Node RPC

- `bot.snapshot`：从 C 获取一致快照，Bot 离线也成功。
- `bot.logs`：读取 C 的有界日志缓存；没有上下文时仍可返回已有历史或空列表。
- `bot.chat`：校验权限和字符串，临执行前核对当前上下文 generation、实例身份和 `online`；否则返回 `NO_CONTEXT/BOT_NOT_ONLINE`。
- 未知 method 拒绝，禁止根据字符串任意调用 context 方法。
- 业务事件通过 serializer 后使用 `bot_event` 发送。
- 主服务器断开期间不接受新的有副作用操作；已有只读订阅可在租约内继续。

### 7.5 重连

- 转发连接重连独立于主服务器重连和 Minecraft 自动重连插件。
- 默认指数退避 1 秒到 30 秒，加入随机抖动，最多 8 次；参数集中配置。
- 只有入房 ACK 成功才重置次数，不以 TCP/Socket.IO connect 为准。
- 意外 `io server disconnect` 可重试；通过明确的撤销/过期/旧会话错误停止旧凭证重试。
- 每次重连必须重新入房；不依赖服务端恢复自动恢复权限。
- token 过期时等待 Main 下发新 token，不能使用旧凭证无限重试。
- 不缓存并重放 chat；状态恢复靠快照，日志按序补偿。
- 关闭/替换时先递增连接代次，使排队回调失效，再清理 timer、监听器、观察桥和 Socket。

### 7.6 handler 与分发修复

- 主控制 Socket 命名为 `main_socket`，转发客户端为 `relay_socket`。
- 修复重复声明并导入正确的 `io`。
- 将广泛的 `startsWith('forward_')` 忽略改为明确的控制事件路由，确保 `forward_bot` 可执行。
- 转发数据 Socket 使用独立白名单 handler，不把它接进主服务器命令的全量 dispatcher。
- 保持 Node 启动时所有 handler 可正常导入。

### 7.7 D 的验收

- 所有 Bot 状态及无上下文均能建立转发通道，不产生 Minecraft 连接动作。
- 两个并发 ensure 只创建一个 Socket，超时调用者不误关闭共享会话。
- 重连时重新入房但不重复绑定上下文事件。
- stop/start 只改变 Bot 快照，转发连接保持。
- 旧命令、旧 ACK、旧重试回调均不能污染新连接。
- 超时、租约到期、手动释放和进程关闭无监听器或定时器泄漏。

## 8. 任务 E：主服务器 HTTP 编排、授权、续期与撤销

### 8.1 文件所有权与依赖

依赖 A；B、D 协议冻结后可并行开发，最终集成依赖 G 的健康注册表。

E 独占：

- `main_server/router/node/action.ts`。
- 新增主服务器转发业务 service、会话与 grant 存储。
- 相关权限 helper 的必要提取及测试。
- HTTP 续期和释放接口。

E 不直接修改 G 所有的转发注册表及启动入口，使用 G 暴露的健康连接及控制命令 API。

### 8.2 初次申请

接口：`POST /api/user/node/forward_bot`，body 严格为 `{bot_id}`。

1. 检查用户会话、账号有效性和请求数据。
2. 用 `query_bot_info(user_id,bot_id)` 或等效逻辑检查 Bot 归属。
3. 检查对应 Node/团队/转发资源权限，但不检查 Bot 游戏状态、版本、代理可用性或启动队列。
4. 使用 `get_node_server_socket()` 获取当前可命令 Node，不仅看缓存 ONLINE。
5. 按 `(forward_id,node_id,bot_id,node_session_id)` 查找/创建通道，合并建立任务。
6. 分配浏览器独立 grant，不让不同标签页互相覆盖。
7. 经 G 的控制通道调用 `forward_open_session`。
8. 签发 Node token，发送 `forward_bot`，等待完整 ready ACK。
9. ACK 前后核对相同 Node 当前会话；再次检查 Bot 归属、节点/转发分配及配置版本。
10. 经控制通道登记该浏览器 grant，成功后签发 Web token，构造公开 DTO 返回。

不得把资源授权 helper 返回的完整实体序列化给浏览器，其中可能包含转发密钥。

公开 DTO：

```ts
interface ForwardAccess {
    bot_id: number;
    node_id: number;
    forward_id: number;
    forward_session_id: string;
    grant_id: string;
    url: string; // 浏览器可访问的公开地址
    path: string;
    namespace: string;
    token: string; // 仅 Web 角色
    expires_at: number;
}
```

### 8.3 续期与释放

- `POST /api/user/node/forward_bot/renew`，body `{bot_id,forward_session_id,grant_id}`。
- `POST /api/user/node/forward_bot/release`，body `{bot_id,forward_session_id,grant_id}`。
- 两者都验证登录会话、Bot 归属、grant 所有权及当前资源分配，不能仅凭 grant ID 操作。
- renew 先延长控制会话，再对 Node ensure/reauth 成功，登记更新后的 grant，最后签发 Web 新 token。
- renew 若发现 Node 会话/转发分配变化，返回 `SESSION_STALE`，前端重新初次申请。
- release 幂等撤销本 grant，立即通知转发层；不关闭其他 grant 使用的通道。
- 主服务器可依据有效 grant 延长 Node 会话租约，但不得绕过账号/资源复核。
- 浏览器异常关闭无法保证 release 到达，仍由租约和 B 的空闲回收兜底。

用户退出、权限撤销、Bot 删除、节点迁移、Node 控制会话替换时撤销对应 grant 或通道。首次实现只要求覆盖项目已有这些操作的入口，避免创建一个永不调用的撤销 API。

### 8.4 超时、幂等与失败

- Node 建立总预算 8 秒，Main 等待 10 秒，HTTP 总预算 12 秒，前端约 15 秒。
- 所有等待包含排队时间，不逐阶段无限叠加 timeout。
- 在 HTTP 超时后不返回凭证。迟到成功只能保留在有效租约/其他申请仍使用的共享通道内。
- 不把转发建立加入持久化的离线 Bot 停止队列。
- Node 离线与转发不可用使用不同错误。
- 沿用当前 HTTP 响应 envelope，错误码映射由 E 明确写测试并向 F 发布。
- 进程重启不假装恢复内存会话：旧租约过期/撤销，Web 重新申请。

### 8.5 E 的验收

- foreign Bot、无权限 Node、离线 Node 不能获取凭证。
- offline Bot 和无运行上下文不阻止申请。
- 非当前 Node 的成功 ACK 不被采纳。
- 等待期间 Bot 被迁移/删除或权限撤销不会返回可用旧凭证。
- 并发标签页共用上行但各有独立 grant，释放一个不影响另一个。
- 公开响应没有 Node token、密钥、内部地址或数据库实体泄漏。

## 9. 任务 F：前端转发客户端与页面接入

### 9.1 文件所有权与依赖

依赖 A、E 的 HTTP 约定及 B 的 Socket 协议。F 独占 `main_server_web` 中新增转发 API、连接管理模块、状态展示和相关测试。

不要把现有 Main Socket 和转发 Socket 混成同一个全局变量，也不要修改 Minecraft Bot 状态来表达转发断线。

### 9.2 客户端生命周期

1. 用户打开 Bot 交互页或显式连接时申请 ForwardAccess。
2. 保存页面/账号/Bot 的请求 generation，丢弃迟到的旧响应。
3. 用返回的 URL/path/namespace 创建 Socket，先安装监听器。
4. connect 后 join_room，成功后才启用交互操作。
5. 设置事件订阅，再请求 snapshot，同步完成前缓冲实时事件。
6. 账号退出、切换 Bot、离开页面时取消 pending、移除监听器、关闭 Socket，尽力 release grant。

连接状态建议：`idle / requesting / connecting / joining / syncing / ready / retrying / expired / error`。

同页多个组件共用一个会话客户端，组件卸载采用引用计数，不各建一条 Socket。不同标签页使用独立 grant。

### 9.3 快照与事件顺序

- 订阅后暂存事件，再请求快照，防止入房前首次状态丢失。
- 快照携带 stream ID 和 seq 水位，先应用快照，再应用同流中 seq 更大的缓冲事件。
- 流改变时丢弃旧流缓冲，重新同步，不能跨流比较 seq。
- context generation 改变时重置当前上下文视图，历史日志仍可按 generation 显示。
- seq 用于去重与快照水位，按事件订阅过滤后不保证连续，不能把自然跳号误判成丢包。由服务端显式 resync 通知、日志缓存截断或 `RESYNC_REQUIRED` 触发快照/日志重新同步。
- UI 不把 `node_ready:false` 显示成 Bot 已 offline，分别展示通道状态和 Bot 状态。

### 9.4 重连与凭证

- 网络断线采用有限退避，connect 后必须重新 join。
- 凭证在 expires_at 前 60 秒 renew，成功后调用 reauth，不必断开整个 Socket。
- 过期、SESSION_STALE 时重新走 HTTP 初次申请，不使用旧 token 无限重试。
- 服务端明确撤销授权时停止自动重试并提示重新授权，不能无条件重连绕过撤销。
- snapshot、日志读取可显式重试；chat 不能在 ACK 超时后自动重发。
- 切换 Bot 后旧 ACK、旧事件、旧 HTTP 响应不能更新新页面。

### 9.5 F 的验收

- Bot 离线页面可连接并展示 `context_exists:false`。
- 多标签页互不收到对方命令内容或私有响应。
- 停止/再次启动 Bot 后无需重连页面，即可显示新状态。
- 短断线、token 续期、主服务器重新分配转发地址均可恢复。
- 页面快速切换、重复挂载卸载不增加 Socket/监听器数量。
- 保持现有设计系统，桌面和移动端可用，不为此重做无关页面。

## 10. 任务 G：服务启动、控制注册表与部署配置

### 10.1 文件所有权与依赖

依赖 A，与 B/C 并行。G 是以下共享入口的唯一修改者：

- `forward_server/index.ts` 和现有控制 runtime 入口。
- `main_server/index.ts`。
- `main_server/runtime/forward_server/socket.ts` 及控制注册 handler。
- `node_server/index.ts` 中与控制认证会话及进程关闭相关的集成。
- 所需配置、配置校验和生命周期测试。

注意：`node_server/forward_server`、`main_server/forward_server` 可能引用同一份共享源码。实施前确认实际路径，不把别名当成独立文件让不同 Agent 同时编辑。

### 10.2 转发服务启动/关闭

- 使用共享初始化 Promise，避免 await 前检查单例造成并发启动。
- 等待 owned HTTP server 的 listening，处理端口占用与启动失败。
- 明确 HTTP server 所有权：内置服务借用 Main 的 HTTP server，停止转发功能不能意外关闭主站。
- 显式 stop API 清理 B 的会话、pending、监听器、定时器，再释放自有服务。
- 停止后复位单例和初始化状态，允许受控重启。
- 不依赖未保证存在的 Engine.IO server `close` 事件作为唯一清理入口。
- 启动参数明确为 forward ID，不继续使用 `-1` 充当执行 Node 身份。
- 密钥缺失时启动失败，取消已知字符串兜底。

### 10.3 Main 注册表

- 同一当前连接重复注册同一转发服务幂等成功。
- 注册准备完成后才加入健康表并 ACK，初始化失败必须返回失败。
- 保存 cleanup disposer；断开时仅删除仍由该连接持有的记录。
- 健康查询不返回已断开的 Socket。
- origin 1 借用 Node 控制 Socket，移除转发登记不能直接 disconnect 整个 Node。
- origin 0 的 EventEmitter 不能调用不存在的 disconnect。
- 替代时间戳猜测，使用明确注册 generation/节点会话所有权。
- 暴露供 E 使用的当前转发健康查询、控制命令及撤销方法。

### 10.4 控制链路恢复

- Main/Node 控制连接成功认证后，通知 D 当前 node_session_id。
- 主服务器短断线时，已有转发只读通道可存活到租约到期，禁止新有副作用请求。
- Main 重新认证产生新 Node 会话时，旧转发会话被替换/撤销，Web 重新申请。
- 内置转发使用进程内 EventEmitter 也必须遵守相同控制协议、ACK 和清理契约。
- 外部控制连接必须先认证，数据 Socket 不得调用控制事件。

Node 自带转发服务时，共用的 Main-Node 控制 Socket 需要同时路由 Node 命令和本地转发控制事件。G 与 D 采用明确事件表及独立 disposer，不得让修复 `forward_` 前缀过滤后，同一个控制事件被两套 handler 重复执行。Main 内置 EventEmitter 使用相同 request/ACK 适配，但不依赖 Socket.IO 才有的 timeout/disconnect 方法。

### 10.5 地址和部署

每个转发服务配置分别包含：

- `node_url`：Node 可访问地址。
- `public_url`：浏览器可访问地址。
- `path`、`namespace`。
- 明确允许的 Web Origin。
- TLS/反向代理配置及载荷限制。

HTTPS 页面必须使用可访问的 HTTPS/WSS 入口；Socket.IO 客户端传 HTTP(S) URL，不把 path 拼成错误 namespace。默认 polling 与 WebSocket 都应通过代理，不能以强制 WebSocket 掩盖未配置的跨域问题。

首版限定每个转发实例单进程。未来多进程需要共享唯一 Node 所有权、会话、pending 路由及 adapter；只加 Redis 房间广播不等于完成横向扩展。

### 10.6 G 的验收

- 并发启动只创建一个服务，端口占用不返回成功。
- 关闭再启动可用，借用 Main HTTP server 时不误关主站。
- 重复注册不踢掉 Node；旧 disconnect 不删除新注册。
- 内置与外部转发使用相同作用域规则。
- Node 初始化过程中 `forward_bot` handler 可正常导入。
- 浏览器默认连接方式能通过配置的公开域名和代理连接。

## 11. 任务 H：集成测试、故障注入与交付核对

### 11.1 文件所有权

H 独占跨服务集成测试目录及测试运行说明。生产文件修改归原 owner，H 发现问题后给证据和复现，不跨范围修复同一文件。

建议使用可控 Main、真实 Socket.IO relay 和模拟 BotContext，避免依赖公网 Minecraft 服务。时间相关使用可控时钟，额外保留至少一组真实网络连接测试。

### 11.2 必测矩阵

| 类别 | 场景 | 期望 |
| --- | --- | --- |
| Bot 状态 | 六种状态及无上下文 | 均允许申请，状态真实，不触发 start |
| 权限 | 未登录、他人 Bot、无 Node/转发资源权限 | 拒绝，不签发有效凭证 |
| Node | 离线、会话替换、等待期间断开 | 不返回旧连接成功 |
| 角色 | Web 伪造 Node、伪造事件、控制消息 | 拒绝 |
| 作用域 | 跨 Bot、跨 Node、跨 relay、旧 session token | 拒绝 |
| 入房 | 重复、不同 room、异步 join | 幂等或明确拒绝，ACK 时已入房 |
| RPC | 两 Web 相同请求 ID、超时、迟到 ACK | 不串响应，不泄漏 pending |
| RPC | Node 在执行期间替换 | 旧响应失效，有副作用请求不自动重放 |
| 生命周期 | Bot stop/start、实例 Minecraft 重连 | 通道保持，订阅跟随新上下文 |
| 事件 | 首次状态、快照期间事件、序号缺口 | 一致同步，不让旧状态覆盖新状态 |
| 重连 | Node-relay、Web-relay、Main-Node 分别断开 | 独立恢复，重新入房，无重复监听 |
| 凭证 | 到期前续期、已连接后到期、撤销 | 正确续期或断开，不能永久授权 |
| 并发 | 两标签页同时申请、一个超时/关闭 | 一条上行，各自授权，不误关共享连接 |
| 回收 | 浏览器从未到达、最后浏览器离开、进程退出 | timer/Socket/listener/pending 回收 |
| 部署 | 内置 relay、外部 relay、HTTPS、跨域 polling | 全流程可用 |
| 容量 | 日志洪峰、慢客户端、恶意 pending | 限流/截断明确，内存有界 |

### 11.3 检查与交付

- 各服务类型检查通过，前端构建通过。
- 单元测试、Socket.IO 集成测试通过。
- 每个 Agent 列出修改文件、协议变化、执行的命令及未覆盖风险。
- 明确区分“transport connected”“joined”“node ready”“Bot online”。
- 不把 mock 通过描述成真实生产部署已验证。
- 验证全过程不输出密钥、token、代理密码或完整用户配置。

## 12. 执行依赖与分工顺序

```mermaid
flowchart TD
    A[A 协议约定冻结] --> B[B 转发数据面]
    A --> C[C Bot注册表观察]
    A --> G[G 启动与控制注册]
    A --> E[E Main业务编排]
    C --> D[D Node转发管理]
    B --> D
    G --> E
    D --> E
    E --> F[F Web接入]
    B --> F
    B --> H[H 集成验收]
    C --> H
    D --> H
    E --> H
    F --> H
    G --> H
```

推荐批次：

1. A 先冻结协议，明确全部类型、错误和事件；B/C/G 提前检查接口是否可实现。
2. B、C、G 并行实现；E/F 可按已冻结协议开发本地桩，不自行变更契约。
3. C 的观察 API 完成后 D 实现 Node 管理器；B/G 提供真实 relay 联调。
4. E 接通授权、会话及 HTTP 全流程；F 接入真实 API。
5. H 执行故障注入和完整验收，原 owner 修复各自模块。

不要让 E 和 G 同时修改主服务器启动/注册表，也不要让 C 和 D 同时修改 BotContext 生命周期。

## 13. 可直接附给各 Agent 的工作指令

```text
以 FORWARD_IMPLEMENTATION_PLAN.md 为协议和任务边界来源。
只实现分配给你的任务及文件，不顺手重构其他模块。
先核对当前源码，保留已有用户修改。
共享 forward_server 路径可能为别名，先确认真实文件归属。
不自行更改事件名、字段、时间单位、角色、错误码和权限语义。
不新增根目录共享协议包，不跨项目引用协议源码；在自己负责的项目内定义必要类型和校验。
契约有问题时给出具体冲突，由协调 Agent 更新本文，再由受影响 owner 同步本地实现。
所有异步操作考虑超时、取消、旧会话和回收。
提供真实验收证据，不以 Socket connect 代替入房成功。
不得把转发重连实现成重新启动 Bot。
完成后报告：修改文件、接口、测试、依赖、未完成项和联调注意事项。
不要提交 Git commit，除非用户另有明确要求。
```

协调 Agent 负责协议冻结、文件所有权、集成顺序和最终验证；各 Agent 的局部测试通过不自动代表端到端交付完成。