youle_cocos/docs/protocol/02-协议-agent路由.md

# 02 · 平台层协议 — agent 路由（大厅服务器）

> 信封：`{ app:"youle", route:"agent", rpc:"<下列名称>", data:{...} }`
> 本篇覆盖 **route=agent 的全部平台层数据包**（双向）。每个 rpc 给出 C→S 请求字段与 S→C 响应/推送字段。子游戏对局包（route=room）不在此篇。
> 通用身份字段：`agentid`(代理ID)、`gameid`(游戏ID)、`playerid`(玩家ID)。多数请求由各调用点手工拼装，未必三者齐全，下文逐条标注实际字段。
> 统一条目格式：
> > `rpc名` · route=agent · <方向>
> > 场景 / 请求字段(C→S) / 响应或推送字段(S→C) / 源码 发送·接收 / 备注（⚠️待后端确认，🐛源码 bug）

---

## 登录 / 账号

### `player_login` · route=agent · C→S 请求 + S→C 响应
- 场景：连接建立后 `onopen` 自动发送；断线重连、切服后重发（12_Logic.js:35、:61 构造，09_Net.js:122 `Send_login` 注入）。
- 请求字段(C→S)：
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | agentid | string/int | 代理ID |
  | gameid | string/int | 游戏ID |
  | openid | string | 微信 openid（游客可为空/特殊值） |
  | nickname | string | 昵称 |
  | avatar | string | 头像 URL |
  | sex | int | 性别 0未知/1男/2女 |
  | province | string | 省份 |
  | city | string | 城市 |
  | unionid | string/int | 微信开放平台 unionid |
  | version | string | 客户端版本号(GameData.versionCode) |
  | channelid | string/int | 渠道ID |
  | marketid | string/int | 市场ID |
  | ip | string | 客户端IP，`Send_login` 注入 `returnCitySN.ip`（09_Net.js:125，仅 returnCitySN 存在时） |
  | location | object | 定位对象，`Send_login` 注入 `C_Player.addr`（09_Net.js:132，可为 null） |
  | machineid | string | 机器标识 `Logic.getMachineId()`（09_Net.js:139） |
  | machineroom | string | 机房标识 `Utl.getRoomcode()`（09_Net.js:140） |
  | telphone | string | 绑定手机号，仅 `GameData.sysConfig.deviceLogin` 开启时随 `telphoneAuto:true` 一起携带（12_Logic.js:48-50） |
  | telphoneAuto | bool | 设备号自动登录标记，同上条件下=true |
  | playerid | int | 可选，本地缓存 playerid（`GameData.loginPlayerid` 开启时由 `Logic.readPlayerId()` 注入，09_Net.js:143-148，用于复用账号） |
- 响应字段(S→C)：`state`(int 0成功/非0失败) + 大量字段，分两组：
  - **A 组 账号资产**：`roomcard`、`bean`、`bank`(仓库星星)、`bankpower`、`bankpwd`、`charm`、`sign`、`tel`、`invitecode` 等（06_Player.js:88 `SetMyInfo` 读取，详见 [04-数据结构.md → 登录响应](./04-数据结构.md#登录响应-deskloginplayer_login)）。
  - **B 组 房间恢复**：在房时附带房间快照（roomcode/seat/players/deskinfo 等），由 `Desk.login` 处理，详见 doc04。
- 源码：发送 `09_Net.js:236`(`Net.Send_login`→`Net._SendData`)；接收 `09_Net.js:240`(`Net.player_login`→`Desk.login`)。
- 备注：— （请求侧字段以本表为准；响应数据结构引用 doc04）

### `query_player2` · route=agent · C→S 请求 + S→C 响应
- 场景：仓库转账前查询目标玩家信息。
- 请求字段(C→S)：`agentid`、`playerid`(目标玩家ID)。
- 响应字段(S→C)：`avatar`(string)、`nickname`(string)、`playerid`(int)；昵称/头像均空时提示"未找到对应玩家"。
- 源码：发送 `09_Net.js:870`；接收 `09_Net.js:873`→`Desk.query_player2`(`07_Desk.js:1368`)。
- 备注：—

### `binding_phone` · route=agent · C→S 请求 + S→C 响应
- 场景：绑定手机号。
- 请求字段(C→S)：`agentid`、`playerid`、`phonenum`、`smmcode`(短信验证码)。
- 响应字段(S→C)：`phonenum`(string，回写 `C_Player.tel`)。
- 源码：发送 `09_Net.js:830`；接收 `09_Net.js:834`→`Desk.binding_phone`(`07_Desk.js:1337`)。
- 备注：—

### `send_phone_checkcode` · route=agent · C→S 请求 + S→C 响应
- 场景：发送手机短信验证码。
- 请求字段(C→S)：`agentid`、`phonenum`（构造点未集中定位，至少含手机号）。
- 响应字段(S→C)：无业务字段（`Desk.send_phone_checkcode` 为空实现，07_Desk.js:1342）。
- 源码：发送 `09_Net.js:838`；接收 `09_Net.js:842`。
- 备注：⚠️ 请求字段以后端实现为准。

### `send_phone_code_wechat` · route=agent · C→S 请求 + S→C 响应
- 场景：微信渠道发送手机验证码（绑定手机流程的另一入口）。
- 请求字段(C→S)：`agentid`、`phonenum`（唯一调用点 11_GameUI.js:2620-2623 当前被注释，按注释代码为 agentid+phonenum）。
- 响应字段(S→C)：无业务字段（`Desk.send_phone_code_wechat` 为空实现，07_Desk.js:1345）。
- 源码：RpcList 定义 `02_Const.js:81`；发送 `09_Net.js:846`(`Send_send_phone_code_wechat`)；接收 `09_Net.js:850`→`Desk.send_phone_code_wechat`(`07_Desk.js:1345`)。
- 备注：⚠️ 框架完整定义并接线，但**当前前端唯一调用点（11_GameUI.js:2623）被注释，实际不发送**；字段以后端实现为准。

### `setSign` · route=agent · C→S 请求 + S→C 响应
- 场景：设置个性签名。
- 请求字段(C→S)：`agentid`、`playerid`、`sign`。
- 响应字段(S→C)：`sign`(string，回显写入 `C_Player.sign`)。
- 源码：发送 `09_Net.js:736`；接收 `09_Net.js:740`→`C_Player.setSign`(`06_Player.js:525`)。
- 备注：—

---

## 房间创建 / 进入（大厅侧）

### `create_room` · route=agent · C→S 请求 + S→C 响应
- 场景：玩家创建房间。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`roomtype`(房间类型配置数组，见 doc04)；`Send_create_room` 自动注入 `ip`=`C_Player.ip`、`location`=`C_Player.addr`（09_Net.js:106-107）。
- 响应字段(S→C)：`state`(0成功)、`roomcode`、`seat`、`roomtype`、`makewar`、`asetcount`、`shortcode`、`infinite`；失败 `showerror`/`error`。详见 [04 → 房间响应公共字段](./04-数据结构.md#房间创建--进入响应公共字段)。
- 源码：发送 `09_Net.js:104`；接收 `09_Net.js:111`→`Desk.create_room` + `Game_Modify.createRoom`。
- 备注：—

### `self_join_room` · route=agent · C→S 请求 + S→C 响应
- 场景：输入房号 / 快速加入 / H5 唤起 / 进 VIP 配置房。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`roomcode`(房号)；`Send_self_join_room` 自动注入 `location`=`C_Player.addr`、`ip`=`C_Player.ip`（09_Net.js:254-255）；进 VIP 配置房入口额外带 `vipMatch:1`（12_Logic.js:2171）；比赛进房入口可带 `match_id`。
- 响应字段(S→C)：`state`、`roomcode`、`seat`、`isowner`、`players[]`、`roomtype`、`makewar`、`asetcount`、`deskwar`、`deskinfo`(重连快照)。详见 [04 → 房间响应公共字段](./04-数据结构.md#房间创建--进入响应公共字段)。
- 源码：发送 `09_Net.js:251`；接收 `09_Net.js:259`→`Desk.self_join_room`。
- 备注：—

### `quick_enter_share_room` · route=agent · C→S 请求 + S→C 响应
- 场景：快速进入分享/星星场房间。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`type`(房间类型)、`roomtype`(可选)。
- 响应字段(S→C)：走 self_join_room 进房流程（无独立 `Net.quick_enter_share_room` 接收函数，结果通过 self_join_room/show_message 等回包）。
- 源码：发送 `09_Net.js:652`。
- 备注：⚠️ 无对应接收处理函数，进房结果依赖其它推送。

### `advanced_roomlist` · route=agent · C→S 请求 + S→C 响应
- 场景：拉取 VIP/高级房间列表。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`。
- 响应字段(S→C)：房间列表对象，整包写入 `GameData.snrRoomList` 并渲染（07_Desk.js:1176）。
- 源码：发送 `09_Net.js:660`；接收 `09_Net.js:665`→`Desk.advanced_roomlist`。
- 备注：—

### `advanced_createroom` · route=agent · C→S 请求 + S→C 响应
- 场景：创建 VIP/高级房间。
- 请求字段(C→S)：`agentid`、`gameid`、`playerid`、`tea`(茶水费)、`infinite`(0/1无限局)、`roomtype`、`videoConfig`(可选)、`rebateLimit`(可选)、`rebateType`(可选)。
- 响应字段(S→C)：`tea`、`rebateLimit` 及房间配置（整包写入 `GameData.snrRoomList`，并回拉 advanced_roomlist，07_Desk.js:1180）。
- 源码：发送 `09_Net.js:669`；接收 `09_Net.js:674`→`Desk.advanced_createroom`。
- 备注：—

### `get_share_room` · route=agent · C→S 请求 + S→C 响应
- 场景：获取分享/星星场房间列表（仅非大厅环境发送）。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`。
- 响应字段(S→C)：房间数组（`Desk.get_share_room` / `Game_Modify.getShareRoom` 处理）。
- 源码：发送 `09_Net.js:641`（`ConstVal.isGameHall` 为 true 时不发）；接收 `09_Net.js:648`。
- 备注：—

### `getInfoByShortCode` · route=agent · C→S 请求 + S→C 响应
- 场景：按短码批量查询房间信息（VIP 房列表）。
- 请求字段(C→S)：`agentid`、`gameid`、`shortcodeList`(短码列表)。
- 响应字段(S→C)：`roomInfo`(短号房间信息) → `GameUI.setVipRoomListData`（07_Desk.js:1284）。
- 源码：发送 `09_Net.js:754`；接收 `09_Net.js:758`→`Desk.getInfoByShortCode`。
- 备注：—

### `switchRoomList` · route=agent · C→S 请求 + S→C 响应
- 场景：开关房间在列表中的可见/可进入状态。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`isClose`(0开/1关)。
- 响应字段(S→C)：`state`(0成功)、`isClose`；失败 `error`（07_Desk.js:1267）。
- 源码：发送 `09_Net.js:744`；接收 `09_Net.js:748`→`Desk.switchRoomList`。
- 备注：—

---

## 战绩 / 排行 / 财富

### `get_player_grade1` · route=agent · C→S 请求 + S→C 响应
- 场景：拉取战绩（类型1）。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`type`(可选)、`direction`(可选,翻页)、`gradeidx`(可选,分页索引)。
- 响应字段(S→C)：战绩数据（`gameCombat.get_player_grade1` 渲染）。
- 源码：发送 `09_Net.js:359`；接收 `09_Net.js:364`。
- 备注：—

### `get_player_grade2` · route=agent · C→S 请求 + S→C 响应
- 场景：拉取战绩（类型2）。
- 请求字段(C→S)：透传调用方 `_data`，构造点未集中定位；至少含 `agentid`/`playerid`/`gameid`。
- 响应字段(S→C)：战绩数据（`gameCombat.get_player_grade2` 渲染）。
- 源码：发送 `09_Net.js:372`；接收 `09_Net.js:377`。
- 备注：⚠️ 请求字段构造点未定位，待核对。

### `get_treasurelist` · route=agent · C→S 请求 + S→C 响应
- 场景：财富榜。
- 请求字段(C→S)：`agentid`、`gameid`。
- 响应字段(S→C)：`list`(排行数组) → `Desk.get_treasurelist`。
- 源码：发送 `09_Net.js:686`；接收 `09_Net.js:691`。
- 备注：—

### `getShortCodeRankList` · route=agent · C→S 请求 + S→C 响应
- 场景：短号场排行榜。
- 请求字段(C→S)：`agentid`、`playerid`、`shortcode`。
- 响应字段(S→C)：成功为排行数据(整包写入 `GameData.vipRank.data`)；失败 `error:true` + `message`（07_Desk.js:1311）。
- 源码：发送 `09_Net.js:770`；接收 `09_Net.js:774`→`Desk.getShortCodeRankList`。
- 备注：—

### `getVipRankList` · route=agent · C→S 请求 + S→C 响应
- 场景：VIP 排行榜。
- 请求字段(C→S)：`agentid`、`limit`(条数)。
- 响应字段(S→C)：`list`(VIP排行数组) → `GameData.rankList`（07_Desk.js:1328）。
- 源码：发送 `09_Net.js:788`；接收 `09_Net.js:792`→`Desk.getVipRankList`。
- 备注：—

---

## 任务系统

### `get_player_task` · route=agent · C→S 请求 + S→C 响应
- 场景：获取任务列表。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`。
- 响应字段(S→C)：`tasks`(任务数组) → `Desk.get_player_task`。
- 源码：发送 `09_Net.js:409`；接收 `09_Net.js:414`。
- 备注：—

### `player_finish_task` · route=agent · C→S 请求 + S→C 响应
- 场景：上报任务完成（如分享成功触发，06_Player.js:414）。
- 请求字段(C→S)：`agentid`、`playerid`、`taskid`。
- 响应字段(S→C)：`state`(int)——`state==1` 且当前 `taskstate==0` 时把 `C_Player.taskstate` 置 1（06_Player.js:476）。
- 源码：发送 `09_Net.js:421`；接收 `09_Net.js:425`→`C_Player.player_finish_task`(`06_Player.js:474`)。
- 备注：原文档"响应含 `taskstate`"无源码依据，已删除——接收函数仅读 `_msg.data.state`。

### `get_task_award` · route=agent · C→S 请求 + S→C 响应
- 场景：领取任务奖励。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`taskid`。
- 响应字段(S→C)：`taskid`(对应任务 state 置 2=已领取)、`taskstate`(写入 `C_Player.taskstate`)（06_Player.js:482）。
- 源码：发送 `09_Net.js:429`；接收 `09_Net.js:435`→`C_Player.get_task_award`。
- 备注：—

### `refresh_task_state` · route=agent · C→S 请求（发送侧 `Send_can_award`）
- 场景：刷新任务可领取状态。
- 请求字段(C→S)：透传 `_data`（构造点未集中定位，至少含 `agentid`/`playerid`）。
- 响应字段(S→C)：服务器推送 `can_award`（见下条）。
- 源码：发送 `09_Net.js:440`(`Net.Send_can_award`)。
- 备注：⚠️ 发送函数名为 `Send_can_award`，但**实际发出的 rpc 是 `"refresh_task_state"`**（硬编码字面量，**不在 RpcList**）。文档以实际 rpc 名为准。

### `can_award` · route=agent · S→C 推送
- 场景：服务器通知有任务可领取。
- 请求字段：无（纯推送）。
- 推送字段(S→C)：任务可领取标记（载荷字段待后端确认）。
- 源码：接收 `09_Net.js:444`(`Net.can_award`)→ 调 `C_Player.can_award(_msg)`(`09_Net.js:445`)。
- 备注：🐛 `06_Player.js` **未定义** `Player.prototype.can_award`（全文无此方法）。推送一旦到达，`C_Player.can_award` 为 undefined，调用即抛 TypeError。当前为 bug，不可当正常协议使用。

---

## 支付 / 充值 / 资产

### `get_paylist` · route=agent · C→S 请求 + S→C 响应
- 场景：拉取支付项列表。
- 请求字段(C→S)：`agentid`。
- 响应字段(S→C)：`paylist`(支付项数组) → `GameData.payList`，并打开支付界面（09_Net.js:567）。
- 源码：发送 `09_Net.js:562`；接收 `09_Net.js:567`。
- 备注：—

### `pay_succ` · route=agent · C→S 请求（经 HTTP）
- 场景：支付成功后通知服务器入账。
- 请求字段(C→S)：`agentid`、`playerid`、`channelid`、`productid`、`payid`、`amount`、`money`、`paytype`（05_Func.js:2240-2254 构造）。
- 响应字段(S→C)：无显式 WS 回包；资产变化通过 `update_bean`/`update_roomcard` 推送（充房卡场景前端还会本地 `UpdateRoomcard`，05_Func.js:2263）。
- 源码：WS 发送函数 `Net.Send_pay_succ`(`09_Net.js:573`) **被注释**（05_Func.js:2249、:3199）；实际改用 `Func.AjaxHttp` 以同样的 `{app,route:agent,rpc:pay_succ,data}` 信封走 **HTTP** 提交（05_Func.js:2250-2255、:3200-3205）。
- 备注：⚠️ WebSocket 通道当前不发；该包以 HTTP POST 形式上行，rpc 名仍为 `pay_succ`，待后端确认接收端一致。

### `topup_card` · route=agent · C→S 请求 + S→C 响应
- 场景：充值卡兑换。
- 请求字段(C→S)：`agentid`、`playerid`、`cardno`(卡号)。
- 响应字段(S→C)：`Desk.topup_card` 为空实现（07_Desk.js:1365），资产变化经 update_bean/update_roomcard 推送。
- 源码：发送 `09_Net.js:863`；接收 `09_Net.js:867`。
- 备注：—

### `giveCoin` · route=agent · C→S 请求 + S→C 响应
- 场景：仓库面板向他人转账豆豆/金币。
- 请求字段(C→S)：`agentid`、`playerid`(转出)、`toPlayerid`(转入目标ID)、`gameid`、`count`(数量)、`password`(仓库密码)（11_GameUI.js:2132-2139）。
- 响应字段(S→C)：`state`(0成功)、`star2`(转出后**仓库星星**数 → `setWareHouseStarCOunt`，**非豆豆**)；失败 `showerror`/`error`（07_Desk.js:1381）。
- 源码：发送 `09_Net.js:876`；接收 `09_Net.js:879`→`Desk.giveCoin`。
- 备注：响应 `star2` 为仓库星星数，注意区别于豆豆余额。

---

## 仓库 / 星星 / 魅力

### `set_bankpwd` · route=agent · C→S 请求 + S→C 响应
- 场景：设置仓库密码。
- 请求字段(C→S)：`agentid`、`playerid`、`unionid`、`password`。
- 响应字段(S→C)：`state`(0成功)、`password`；失败 `showerror`/`error`（07_Desk.js:1228）。
- 源码：发送 `09_Net.js:697`；接收 `09_Net.js:701`→`Desk.set_bankpwd`。
- 备注：—

### `change_star` · route=agent · C→S 请求 + S→C 响应
- 场景：仓库存/取（豆豆 ↔ 仓库星星）。
- 请求字段(C→S)：`agentid`、`playerid`、`mode`(0存入/1取出，源码 `safeInputType-1`)、`password`(仓库密码,字符串)、`count`(数量)（11_GameUI.js:2065-2069 调用点齐全携带此 5 字段）。
- 响应字段(S→C)：`state`(0成功)、`star1`(更新后豆豆余额 → `update_bean2`)、`star2`(更新后仓库星星数 → `setWareHouseStarCOunt`)、`msg`(可选提示)、`count`(可选,回填安全输入)；失败 `showerror`/`error`（07_Desk.js:1238）。
- 源码：发送 `09_Net.js:707`；接收 `09_Net.js:711`→`Desk.change_star`。
- 备注：原审计疑虑"`mode`/`password` 未见"——经核对仓库存/取调用点（11_GameUI.js:2068-2069）**确含** `mode` 与 `password`，文档正确，疑虑解除。审计提到的"agentid/playerid/toPlayerid/gameid/count"实为相邻的 `giveCoin` 转账包（11_GameUI.js:2132-2139），并非本 rpc。

### `update_charm` · route=agent · S→C 推送
- 场景：座位魅力值更新。
- 请求字段：`Net.Send_update_charm`(`09_Net.js:727`) 已定义但**无任何调用点**；实际只作服务器→客户端推送。
- 推送字段(S→C)：`seatlist`:[ {`seat`(int), `charm`(number)} ]（07_Desk.js:1260 遍历 setCharm）。
- 源码：接收 `09_Net.js:731`→`Desk.update_charm`(`07_Desk.js:1260`)。
- 备注：—

### `setAllCharm` · route=agent · C→S 请求 + S→C 响应
- 场景：批量设置总魅力。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`value`(11_GameUI.js:1269-1275)。
- 响应字段(S→C)：无显式业务字段，`Desk.setAllCharm` 仅本地存储并提示成功（07_Desk.js:1321）。
- 源码：发送 `09_Net.js:779`；接收 `09_Net.js:783`→`Desk.setAllCharm`。
- 备注：—

---

## 邀请码 / 绑定

### `binding_invitecode` · route=agent · C→S 请求 + S→C 响应
- 场景：绑定邀请码。
- 请求字段(C→S)：`agentid`、`playerid`、`invitecode`（11_GameUI.js:1367-1369）。
- 响应字段(S→C)：`state`(0成功时写入 `invitecode`)、`invitecode`、`error`(提示文案)（06_Player.js:251）。
- 源码：发送 `09_Net.js:587`；接收 `09_Net.js:592`→`C_Player.binding_invitecode`。
- 备注：—

### `get_player_invitecode` · route=agent · C→S 请求 + S→C 响应
- 场景：获取自己的邀请码（打开绑定界面）。
- 请求字段(C→S)：`agentid`、`playerid`、`unionid`、`openid`（11_GameUI.js:1378-1382）。
- 响应字段(S→C)：`invitecode`(string) → `C_Player.setInvitecod` 并打开绑定界面（09_Net.js:607）。
- 源码：发送 `09_Net.js:603`；接收 `09_Net.js:607`→`Net.get_player_invitecode`。
- 备注：修正原文档——请求字段为 `agentid/playerid/unionid/openid`，**无 `gameid`**，新增 `unionid`/`openid`（11_GameUI.js:1378）。

---

## VIP 管理 / 黑白名单

### `optBanList` · route=agent · C→S 请求 + S→C 响应
- 场景：黑名单查看/添加/移除（多入口）。
- 请求字段(C→S)：随入口不同，公共字段 `agentid`、`playerid`、`type`：
  - `type=1` 查看黑名单列表（agentid/playerid/type，11_GameUI.js:2401-2405）
  - `type=3` 按 ID 添加（agentid/playerid/optId/type，11_GameUI.js:2376-2381）
  - `type=4` 按 ID 移除（agentid/playerid/optId/type，11_GameUI.js:2389-2394 及列表项删除 2453-2458）
  - `type=6` 一键全部添加（agentid/playerid/type，11_GameUI.js:1262-1267）
  - 另有带 `breakRoom`(0/1) 与 `gameid` 的 `type=3` 添加入口（agentid/gameid/playerid/optId/breakRoom/type，11_GameUI.js:2417-2428；breakRoom 由 `GameData.blackList.breakRoom` 决定，开关在 case 3260）
  - 服务器响应中亦见 `type=5`（另一种列表返回，07_Desk.js:1299）
- 响应字段(S→C)：`type`(1/3/4/5/6)、`banList`(黑名单数组)、`message`(可选提示)（07_Desk.js:1289）。
- 源码：发送 `09_Net.js:762`；接收 `09_Net.js:766`→`Desk.optBanList`。
- 备注：—

### `getPlayerWhiteList` · route=agent · C→S 请求 + S→C 响应
- 场景：获取白名单。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`。
- 响应字段(S→C)：`whiteList`(数组) → `GameData.whiteList.data`（07_Desk.js:1412）。
- 源码：发送 `09_Net.js:882`；接收 `09_Net.js:886`→`Desk.getPlayerWhiteList`。
- 备注：—

### `optWhiteList` · route=agent · C→S 请求 + S→C 响应
- 场景：白名单添加/修改/删除。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`shortcode`、`mode`、`userid`(目标ID)：
  - `mode=1` 添加/修改，并带 `value`(设置的魅力值)
  - `mode=2` 删除（仅 `userid`）
- 响应字段(S→C)：`whiteList`(更新后数组)、`mode`(可选)、`message`(可选提示)（07_Desk.js:1398）。
- 源码：发送 `09_Net.js:890`；接收 `09_Net.js:894`→`Desk.optWhiteList`。
- 备注：—

### `setVipForbidSelect` · route=agent · C→S 请求 + S→C 响应
- 场景：VIP 房禁止玩家选桌开关。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`forbidSelect`(1开/0关，11_GameUI.js:2631-2639)。
- 响应字段(S→C)：`state`(0成功)、`forbidSelect`(1开/0关)；失败 `error`（07_Desk.js:1348）。
- 源码：发送 `09_Net.js:855`；接收 `09_Net.js:859`→`Desk.setVipForbidSelect`。
- 备注：—

---

## 其它 agent 协议

### `submit_opinion` · route=agent · C→S 请求 + S→C 响应
- 场景：提交反馈/意见。
- 请求字段(C→S)：`agentid`、`playerid`、`gameid`、`content`。
- 响应字段(S→C)：`state`(0成功)（07_Desk.js:1100）。
- 源码：发送 `09_Net.js:547`；接收 `09_Net.js:551`→`Desk.submit_opinion`。
- 备注：—

### `submit_location` · route=agent · C→S 请求 + S→C 响应
- 场景：提交定位信息（仅非大厅环境发送）。
- 请求字段(C→S)：`agentid`、`playerid`、`info`(定位对象)。
- 响应字段(S→C)：经 `Game.submit_location` 处理（09_Net.js:583）。
- 源码：发送 `09_Net.js:577`（`ConstVal.isGameHall` 为 true 时不发）；接收 `09_Net.js:583`。
- 备注：—

### `submit_phoneinfo` · route=agent · C→S 请求（无响应处理）
- 场景：提交手机/通讯录信息（仅非大厅环境发送）。
- 请求字段(C→S)：`agentid`、`playerid`、`info`{ `phoneInfo`(手机信息), `addrBook`(通讯录) }。
- 响应字段(S→C)：`Net.submit_phoneinfo` 接收函数为空实现（09_Net.js:722）。
- 源码：发送 `09_Net.js:717`；接收 `09_Net.js:722`。
- 备注：—

### `submit_error` / `submit_log` · route=agent · C→S 上行（硬编码包）
- 场景：上报前端异常/日志。异常捕获时（12_Logic.js:270）、获取 HTML 失败（12_Logic.js:1990/2009/2014）、收到踢下线包（07_Desk.js:963）等处调用。
- 请求字段(C→S)：`packet`(出错数据包字符串)、`msg`(错误/堆栈信息)、`playerid`、`agentid`、`gameid`（09_Net.js:66-72）。
- 响应字段(S→C)：服务器若回 rpc `"submit_error"`，前端在分发处直接 `return` 忽略（12_Logic.js:235）。
- 源码：发送 `Net.submit_error`(`09_Net.js:55`) / `Net.submit_log`(`09_Net.js:81`)。
- 备注：均为**硬编码** `route:"agent", rpc:"submit_error"`，不经 `Send_*`/RpcList。注意 `Net.submit_log`(`09_Net.js:81`) 实际发出的 rpc 同样是 `"submit_error"`（与 submit_error 同包结构）。两者带去重：`submit_error` 对相同 `msg` 只发一次（09_Net.js:57-61），`submit_log` 不去重。

### `kick_server` · route=agent · C→S 请求 + S→C 推送
- 场景：管理端踢出玩家 / 被踢下线弹窗。
- 请求字段(C→S)：`agentid` 等（构造点未集中定位）。
- 推送字段(S→C)：`msg`(踢出提示) → `GameUI.OpenKick`（07_Desk.js:1108）。
- 源码：发送 `09_Net.js:555`；接收 `09_Net.js:558`→`Desk.kick_server`。
- 备注：⚠️ 请求字段待补。

### `broadcast` · route=agent · C→S 请求 + S→C 推送
- 场景：广播消息/滚动公告（主要为服务器推送）。
- 请求字段(C→S)：`agentid` 等（`Send_broadcast` 存在，09_Net.js:530）。
- 推送字段(S→C)：`msgtype`(0消息框/1滚动公告,可选,缺省 0)、`msgcontent`(内容)（07_Desk.js:1112）。
- 源码：发送 `09_Net.js:530`；接收 `09_Net.js:534`→`Desk.broadcast`。
- 备注：—

### `connect_agentserver` · route=agent · 双向（切服）
- 场景：切换到大厅服务器。
- 请求字段(C→S)：`Send_connect_agentserver`(`09_Net.js:515`) 透传 `_data`（切服时使用）。
- 推送字段(S→C)：`agentserver`(新大厅服地址)、`opt`(切换原因，如 `other_break_room`/`free_room`)（09_Net.js:518）。
- 源码：发送 `09_Net.js:515`；接收 `09_Net.js:518`→`Net.connect_agentserver`（关闭当前连接并重连新地址）。
- 备注：—

### `playerBehavior` · route=agent（实际走 HTTP GET）
- 场景：玩家行为埋点。
- 请求字段：原 WS 路径（agentid/gameid/playerid/tag）**被注释**（09_Net.js:799-806），实际改走独立 HTTP GET 上报 `http://test3.1888day.com/api/gamedo/gamedo?agentid=&gameid=&playerid=&tag=`（09_Net.js:807-815）。
- 响应字段(S→C)：HTTP 回调 `playerBehavior_Succ`/`_Fail`（09_Net.js:818/822）；WS 接收函数 `Net.playerBehavior`(`09_Net.js:826`) 当前无触发。
- 源码：发送 `09_Net.js:797`(`Send_playerBehavior`)。
- 备注：**非 WebSocket 协议**，RpcList 中虽有定义，实际不走 agent 路由。

---

## 仅接收的 agent 推送（无对应主动请求）

| rpc | 推送 data 字段 | 说明 | 接收源码 |
|-----|---------------|------|---------|
| `update_roomcard` | `roomcard`、`text`(可选) | 房卡变化（仅 `change` 未定义时更新，09_Net.js:383→06_Player.js:141） | 09_Net.js:383 |
| `update_bean` | `bean`、`change`(可选)、`seat`(可选)、`type`(可选)、`text` | 豆豆变化（09_Net.js:598→Desk.update_bean，07_Desk.js:1201） | 09_Net.js:598 |
| `can_award` | 任务可领取标记 | 🐛 接收即抛异常，见上文 任务系统 章 | 09_Net.js:444 |
| `kick_offline` | `fromOther`(可选)、`gameid`(可选) | 被踢下线，弹 OpenKick；同时本地 `Net.submit_error` 上报"收到踢下线包"（07_Desk.js:945-963） | 09_Net.js:448 |
| `show_message` | `msg`、`time` | 通用消息提示 → `GameUI.OpenTips`（07_Desk.js:1173） | 09_Net.js:656 |