ygopro-msg-encode 1.0.1

package/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,294 @@
+# CTOS/STOC 协议实现完成总结
+
+## 完成内容
+
+### 1. 模块结构
+
+按照 MSG 协议的模式，为 CTOS 和 STOC 建立了完整的模块结构：
+
+```
+src/protos/
+├── common/                    # 公共数据结构
+│   ├── host-info.ts          # HostInfo 结构（20字节）
+│   └── index.ts
+├── ctos/                      # Client to Server 协议
+│   ├── base.ts               # CTOS 基类
+│   ├── registry.ts           # CTOS 注册器
+│   ├── index.ts
+│   └── proto/                # 19 个 CTOS 协议实现
+│       ├── response.ts
+│       ├── update-deck.ts
+│       ├── hand-result.ts
+│       └── ... (共19个文件)
+└── stoc/                      # Server to Client 协议
+    ├── base.ts               # STOC 基类
+    ├── registry.ts           # STOC 注册器
+    ├── index.ts
+    └── proto/                # 24 个 STOC 协议实现
+        ├── game-msg.ts
+        ├── error-msg.ts
+        ├── replay.ts
+        └── ... (共24个文件)
+```
+
+### 2. 协议格式处理
+
+正确实现了 CTOS/STOC 的二进制格式：
+- `[length 2 bytes][identifier 1 byte][body]`
+- Base 类只处理 body 部分
+- Registry 配置正确的 `identifierOffset: 2` 和 `dataOffset: 3`
+
+### 3. Struct Padding 处理
+
+正确处理了所有 C++ 结构体的 padding：
+- `HostInfo`: 字节 9-11 padding（共 20 字节）
+- `CTOS_JoinGame`: 字节 2-3 padding
+- `STOC_ErrorMsg`: 字节 1-3 padding
+- `STOC_TimeLimit`: 字节 1 padding
+- `STOC_HS_PlayerEnter`: 实际 41 字节（workaround）
+
+### 4. 特殊协议封装
+
+#### CTOS_UPDATE_DECK (0x02)
+```typescript
+export class YGOProCtosUpdateDeck extends YGOProCtosBase {
+  static identifier = 0x2;
+  deck: YGOProDeck;
+  
+  fromPayload(data: Uint8Array): this {
+    this.deck = YGOProDeck.fromUpdateDeckPayload(data);
+    return this;
+  }
+  
+  toPayload(): Uint8Array {
+    return this.deck.toUpdateDeckPayload();
+  }
+  
+  fromPartial(data: Partial<this>): this {
+    if (data.deck) {
+      this.deck = new YGOProDeck(data.deck);
+    }
+    return this;
+  }
+  
+  copy(): this {
+    const copied = new (this.constructor as any)();
+    copied.deck = new YGOProDeck(this.deck);
+    return copied;
+  }
+}
+```
+
+#### STOC_REPLAY (0x17)
+```typescript
+export class YGOProStocReplay extends YGOProStocBase {
+  static identifier = 0x17;
+  replay: YGOProYrp;
+  
+  fromPayload(data: Uint8Array): this {
+    this.replay = new YGOProYrp().fromYrp(data);
+    return this;
+  }
+  
+  toPayload(): Uint8Array {
+    return this.replay.toYrp();
+  }
+  
+  fromPartial(data: Partial<this>): this {
+    if (data.replay) {
+      this.replay = new YGOProYrp(data.replay);
+    }
+    return this;
+  }
+  
+  copy(): this {
+    const copied = new (this.constructor as any)();
+    copied.replay = new YGOProYrp(this.replay);
+    return copied;
+  }
+}
+```
+
+#### STOC_GAME_MSG (0x01)
+```typescript
+export class YGOProStocGameMsg extends YGOProStocBase {
+  static identifier = 0x1;
+  msg: YGOProMsgBase | undefined;
+  
+  fromPayload(data: Uint8Array): this {
+    this.msg = YGOProMessages.getInstanceFromPayload(data);
+    return this;
+  }
+  
+  toPayload(): Uint8Array {
+    if (!this.msg) {
+      return new Uint8Array(0);
+    }
+    return this.msg.toPayload();
+  }
+  
+  fromPartial(data: Partial<this>): this {
+    if (data.msg) {
+      this.msg = data.msg.copy(); // 使用 copy()
+    }
+    return this;
+  }
+}
+```
+
+### 5. 数组字段处理
+
+修正了所有数组字段的写法：
+- ❌ 错误：`@BinaryField('u16[]', 0, () => 20)`
+- ✅ 正确：`@BinaryField('u16', 0, 20)`
+- ✅ UTF-16：`@BinaryField('utf16', 0, 256)`
+
+### 6. 实现的协议列表
+
+#### CTOS 协议（19 个）
+| ID | 协议名 | 说明 |
+|----|--------|------|
+| 0x01 | RESPONSE | 响应数据 |
+| 0x02 | UPDATE_DECK | 更新卡组（ygopro-deck-encode） |
+| 0x03 | HAND_RESULT | 猜拳结果 |
+| 0x04 | TP_RESULT | 先后手结果 |
+| 0x10 | PLAYER_INFO | 玩家信息 |
+| 0x11 | CREATE_GAME | 创建房间 |
+| 0x12 | JOIN_GAME | 加入房间 |
+| 0x13 | LEAVE_GAME | 离开房间 |
+| 0x14 | SURRENDER | 认输 |
+| 0x15 | TIME_CONFIRM | 时间确认 |
+| 0x16 | CHAT | 聊天 |
+| 0x17 | EXTERNAL_ADDRESS | 外部地址 |
+| 0x20 | HS_TODUELIST | 切换到决斗者 |
+| 0x21 | HS_TOOBSERVER | 切换到观战者 |
+| 0x22 | HS_READY | 准备 |
+| 0x23 | HS_NOTREADY | 取消准备 |
+| 0x24 | HS_KICK | 踢人 |
+| 0x25 | HS_START | 开始决斗 |
+| 0x30 | REQUEST_FIELD | 请求场地信息 |
+
+#### STOC 协议（24 个）
+| ID | 协议名 | 说明 |
+|----|--------|------|
+| 0x01 | GAME_MSG | 游戏消息（YGOProMessages） |
+| 0x02 | ERROR_MSG | 错误消息 |
+| 0x03 | SELECT_HAND | 选择猜拳 |
+| 0x04 | SELECT_TP | 选择先后手 |
+| 0x05 | HAND_RESULT | 猜拳结果 |
+| 0x06 | TP_RESULT | 先后手结果 |
+| 0x07 | CHANGE_SIDE | 换边 |
+| 0x08 | WAITING_SIDE | 等待换边 |
+| 0x09 | DECK_COUNT | 卡组数量 |
+| 0x11 | CREATE_GAME | 创建房间 |
+| 0x12 | JOIN_GAME | 加入房间 |
+| 0x13 | TYPE_CHANGE | 类型变更 |
+| 0x14 | LEAVE_GAME | 离开房间 |
+| 0x15 | DUEL_START | 决斗开始 |
+| 0x16 | DUEL_END | 决斗结束 |
+| 0x17 | REPLAY | 录像（ygopro-yrp-encode） |
+| 0x18 | TIME_LIMIT | 时间限制 |
+| 0x19 | CHAT | 聊天 |
+| 0x20 | HS_PLAYER_ENTER | 玩家进入 |
+| 0x21 | HS_PLAYER_CHANGE | 玩家状态变更 |
+| 0x22 | HS_WATCH_CHANGE | 观战者数量变更 |
+| 0x23 | TEAMMATE_SURRENDER | 队友认输 |
+| 0x30 | FIELD_FINISH | 场地同步完成 |
+| 0x31 | SRVPRO_ROOMLIST | 房间列表（SRVPro 服务器） |
+
+### 7. 导出配置
+
+更新了主入口文件 `index.ts`：
+```typescript
+export * from './src/binary/binary-meta';
+export * from './src/binary/fill-binary-fields';
+export * from './src/protos/common';
+export * from './src/protos/ctos';
+export * from './src/protos/stoc';
+export * from './src/protos/msg';
+```
+
+### 8. 构建结果
+
+```
+✓ dist/index.cjs      151.9kb  (之前: 10.8kb)
+✓ dist/index.mjs      141.7kb  (之前: 9.7kb)
+✓ dist/index.d.ts     类型声明文件已生成
+```
+
+## 关键设计决策
+
+### 1. Registry Options
+```typescript
+{
+  identifierOffset: 2,  // identifier 在字节 2（跳过 2 字节长度）
+  dataOffset: 3,        // body 从字节 3 开始（跳过长度 + identifier）
+}
+```
+
+### 2. fromPartial 实现策略
+- **YGOProStocGameMsg**: 使用 `msg.copy()` 复制
+- **YGOProCtosUpdateDeck**: 使用 `new YGOProDeck(data.deck)` 传入构造函数
+- **YGOProStocReplay**: 使用 `new YGOProYrp(data.replay)` 传入构造函数
+
+### 3. copy() 方法
+为 `YGOProCtosUpdateDeck` 和 `YGOProStocReplay` 添加了 `copy()` 方法，确保正确的深拷贝。
+
+### 4. STOC_SRVPRO_ROOMLIST 实现
+根据 `duelclient.cpp` 实现了 SRVPro 服务器的房间列表协议：
+```typescript
+export class SrvproRoomInfo {
+  roomname: string;          // UTF-8, 64 bytes
+  room_status: number;       // 0=Waiting, 1=Dueling, 2=Siding
+  room_duel_count: number;   // 决斗计数
+  room_turn_count: number;   // 回合计数
+  player1: string;           // 玩家1名字, UTF-8, 128 bytes
+  player1_score: number;     // 玩家1分数
+  player1_lp: number;        // 玩家1 LP
+  player2: string;           // 玩家2名字, UTF-8, 128 bytes
+  player2_score: number;     // 玩家2分数
+  player2_lp: number;        // 玩家2 LP
+}
+
+export class YGOProStocSrvproRoomlist {
+  count: number;             // 房间数量
+  rooms: SrvproRoomInfo[];   // 房间数组
+}
+```
+每个房间信息占 333 字节。
+
+## 参考源码
+
+实现参照了以下源码：
+- YGOPro ocgcore: `/home/nanahira/ygo/ygopro/ocgcore`
+- YGOPro gframe: `/home/nanahira/ygo/ygopro/gframe`
+- 特别是 `network.h` 文件中的结构体定义
+- `duelclient.cpp` 中的 `STOC_SRVPRO_ROOMLIST` 实现（第 413-463 行）
+
+## 依赖关系
+
+```
+ygopro-msg-encode
+├── ygopro-deck-encode  (卡组编解码)
+└── ygopro-yrp-encode   (录像编解码)
+```
+
+## 测试
+
+已创建测试脚本 `test-ctos-stoc.ts`，可以验证：
+- 协议序列化和反序列化
+- Registry 正确识别协议类型
+- 数据完整性
+
+运行测试：
+```bash
+npx tsx test-ctos-stoc.ts
+```
+
+## 完成时间
+
+2026-02-02
+
+## 状态
+
+✅ **已完成并通过构建测试**

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Nanahira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/MSG_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,358 @@
+# YGOPro MSG 类实现总结
+
+## 项目概览
+
+已完成 **84 个 MSG 类**的完整实现，涵盖 YGOPro 协议的所有主要消息类型。
+
+## 实现的消息类型
+
+### 基础消息（无字段或简单字段）
+1. MSG_RETRY (1) - 重试
+2. MSG_WAITING (3) - 等待
+3. MSG_WIN (5) - 胜利
+4. MSG_NEW_TURN (40) - 新回合
+5. MSG_NEW_PHASE (41) - 新阶段
+6. MSG_SHUFFLE_DECK (32) - 洗卡组
+7. MSG_SWAP_GRAVE_DECK (35) - 墓地卡组交换
+8. MSG_REVERSE_DECK (37) - 翻转卡组
+9. MSG_CHAIN_END (74) - 连锁结束
+10. MSG_SUMMONED (61) - 召唤完成
+11. MSG_SPSUMMONED (63) - 特殊召唤完成
+12. MSG_FLIPSUMMONED (65) - 翻转召唤完成
+13. MSG_ATTACK_DISABLED (112) - 攻击禁用
+14. MSG_DAMAGE_STEP_START (113) - 伤害步骤开始
+15. MSG_DAMAGE_STEP_END (114) - 伤害步骤结束
+16. MSG_HAND_RES (133) - 猜拳结果
+17. MSG_ROCK_PAPER_SCISSORS (132) - 猜拳
+
+### 玩家状态消息
+18. MSG_HINT (2) - 提示
+19. MSG_DAMAGE (91) - 伤害
+20. MSG_RECOVER (92) - 回复
+21. MSG_LPUPDATE (94) - LP 更新
+22. MSG_PAY_LPCOST (100) - 支付 LP
+23. MSG_PLAYER_HINT (165) - 玩家提示
+24. MSG_RESET_TIME (221) - 重置时间
+
+### 卡片状态消息
+25. MSG_SET (54) - 盖放
+26. MSG_POS_CHANGE (53) - 位置变更
+27. MSG_MOVE (50) - 移动
+28. MSG_SWAP (55) - 交换
+29. MSG_FIELD_DISABLED (56) - 场地禁用
+30. MSG_SUMMONING (60) - 召唤中
+31. MSG_SPSUMMONING (62) - 特殊召唤中
+32. MSG_FLIPSUMMONING (64) - 翻转召唤中
+33. MSG_CARD_HINT (160) - 卡片提示
+34. MSG_DECK_TOP (38) - 卡组顶部
+
+### 战斗相关消息
+35. MSG_ATTACK (110) - 攻击宣言
+36. MSG_BATTLE (111) - 战斗伤害计算
+
+### 连锁相关消息
+37. MSG_CHAINING (70) - 连锁中
+38. MSG_CHAINED (71) - 连锁完成
+39. MSG_CHAIN_SOLVING (72) - 连锁处理中
+40. MSG_CHAIN_SOLVED (73) - 连锁处理完成
+41. MSG_CHAIN_NEGATED (75) - 连锁无效
+42. MSG_CHAIN_DISABLED (76) - 连锁禁用
+
+### 目标和装备消息
+43. MSG_EQUIP (93) - 装备
+44. MSG_CARD_TARGET (96) - 卡片目标
+45. MSG_CANCEL_TARGET (97) - 取消目标
+46. MSG_BECOME_TARGET (83) - 成为目标
+
+### 指示物消息
+47. MSG_ADD_COUNTER (101) - 添加指示物
+48. MSG_REMOVE_COUNTER (102) - 移除指示物
+
+### 随机效果消息
+49. MSG_TOSS_COIN (130) - 投硬币
+50. MSG_TOSS_DICE (131) - 掷骰子
+51. MSG_RANDOM_SELECTED (81) - 随机选择
+52. MSG_MISSED_EFFECT (120) - 错过时点
+
+### 宣言消息
+53. MSG_ANNOUNCE_RACE (140) - 宣言种族
+54. MSG_ANNOUNCE_ATTRIB (141) - 宣言属性
+55. MSG_ANNOUNCE_CARD (142) - 宣言卡片
+56. MSG_ANNOUNCE_NUMBER (143) - 宣言数字
+
+### 选择消息（简单）
+57. MSG_SELECT_YESNO (13) - 是/否选择
+58. MSG_SELECT_OPTION (14) - 选项选择
+59. MSG_SELECT_POSITION (19) - 位置选择
+60. MSG_SELECT_PLACE (18) - 区域选择
+61. MSG_SELECT_DISFIELD (24) - 禁用场地选择
+62. MSG_SELECT_EFFECTYN (12) - 效果是/否
+
+### 选择消息（复杂）
+63. MSG_SELECT_CARD (15) - 卡片选择
+64. MSG_SELECT_TRIBUTE (20) - 解放选择
+65. MSG_SELECT_COUNTER (22) - 指示物选择
+66. MSG_SELECT_SUM (23) - 总和选择
+67. MSG_SELECT_UNSELECT_CARD (26) - 可选/不可选卡片
+68. MSG_SELECT_CHAIN (16) - 连锁选择
+69. MSG_SELECT_BATTLECMD (10) - 战斗命令选择
+70. MSG_SELECT_IDLECMD (11) - 主要阶段命令选择
+
+### 确认和洗牌消息
+71. MSG_CONFIRM_DECKTOP (30) - 确认卡组顶部
+72. MSG_CONFIRM_EXTRATOP (42) - 确认额外卡组顶部
+73. MSG_CONFIRM_CARDS (31) - 确认卡片
+74. MSG_SHUFFLE_HAND (33) - 洗手牌
+75. MSG_SHUFFLE_EXTRA (39) - 洗额外卡组
+76. MSG_SHUFFLE_SET_CARD (36) - 洗覆盖卡
+77. MSG_SORT_CARD (25) - 排序卡片
+78. MSG_DRAW (90) - 抽卡
+
+### TAG 决斗消息
+79. MSG_TAG_SWAP (161) - TAG 交换
+
+### 特殊消息
+80. MSG_MATCH_KILL (170) - 比赛中止
+81. MSG_START (4) - 决斗开始
+82. MSG_UPDATE_CARD (7) - 更新卡片（完整实现）
+83. MSG_UPDATE_DATA (6) - 更新数据（完整实现）
+84. MSG_RELOAD_FIELD (162) - 重载场地
+
+## CardQuery 完整查询数据类
+
+### 标量字段
+- code, alias, type
+- level, rank, attribute, race
+- attack, defense, baseAttack, baseDefense
+- reason, owner, status
+- lscale, rscale, link, linkMarker
+- position
+
+### 数组/对象字段
+- equipCard: CardQuery_CardLocation
+- targetCards: CardQuery_CardLocation[]
+- overlayCards: number[] (卡片代码数组)
+- counters: CardQuery_Counter[] (指示物数组)
+
+### 特性
+- 支持所有 QUERY_* 标志位
+- 自动按标志位顺序序列化和反序列化
+- 正确处理可变长度数组
+- 支持空卡片（flags = 0）
+
+## 视角控制（opponentView/teammateView）
+
+以下消息实现了视角控制，向对方/队友隐藏敏感信息：
+
+1. **MSG_DRAW** - 隐藏未公开的抽牌
+2. **MSG_SHUFFLE_HAND** - 隐藏手牌内容
+3. **MSG_SHUFFLE_EXTRA** - 隐藏未公开的额外卡组
+4. **MSG_DECK_TOP** - 隐藏卡组顶部信息
+5. **MSG_CONFIRM_DECKTOP** - 隐藏未公开的卡组顶部
+6. **MSG_CONFIRM_EXTRATOP** - 隐藏未公开的额外顶部
+7. **MSG_CONFIRM_CARDS** - 隐藏未公开的卡片
+8. **MSG_TAG_SWAP** - TAG 交换时隐藏手牌和额外卡组
+9. **MSG_UPDATE_CARD** - 对手视角隐藏盖放卡片的详细信息
+10. **MSG_UPDATE_DATA** - 对手视角隐藏盖放卡片的详细信息，队友可见全部
+
+## 小类命名规范
+
+所有小类都使用 `{主类名}_{小类名}` 格式，并且全部导出：
+
+### 常见小类
+- `*_CardInfo`: 带代码的卡片信息（code + location）
+- `*_CardLocation`: 卡片位置信息（controller + location + sequence + position）
+- `*_SimpleCardInfo`: 简单卡片信息（code + location，7字节）
+- `*_ActivatableInfo`: 可激活卡片信息（code + location + desc，11字节）
+- `*_AttackableInfo`: 可攻击卡片信息（code + location + directAttack，8字节）
+- `*_ChainInfo`: 连锁信息（13字节）
+- `*_SetCardInfo`: 覆盖卡信息（oldLocation + newLocation）
+- `*_CardStats`: 卡片状态（location + atk + def）
+- `*_Counter`: 指示物信息（type + count）
+- `*_PlayerInfo`: 玩家信息
+- `*_ZoneCard`: 区域卡片信息
+
+## 二进制格式
+
+### 标准格式
+```
+[MSG_IDENTIFIER (1 byte)][字段数据...]
+```
+
+### 查询数据格式（MSG_UPDATE_CARD）
+```
+[MSG_IDENTIFIER][controller][location][sequence][length (4 bytes)][flags (4 bytes)][查询字段...]
+```
+
+### 字段查询数据格式（MSG_UPDATE_DATA）
+```
+[MSG_IDENTIFIER][player][location]
+  [length1 (4 bytes)][flags1 (4 bytes)][查询字段1...]
+  [length2 (4 bytes)][flags2 (4 bytes)][查询字段2...]
+  ...
+```
+
+## 文件统计
+
+- **MSG 类文件**: 84 个
+- **小类**: 30+ 个
+- **测试用例**: 57 个（全部通过）
+- **代码行数**: ~3000+ 行
+
+## 测试覆盖
+
+- ✅ 简单字段序列化/反序列化
+- ✅ 动态长度数组
+- ✅ 嵌套对象和对象数组
+- ✅ 视角控制（opponentView/teammateView）
+- ✅ MSG identifier 验证
+- ✅ 查询数据完整解析
+- ✅ 多卡片查询数据数组
+- ✅ Registry 系统
+
+## 使用示例
+
+### 基础使用
+```typescript
+import { YGOProMsgDraw, OcgcoreCommonConstants } from 'ygopro-msg-encode';
+
+// 创建消息
+const msg = new YGOProMsgDraw();
+msg.player = 0;
+msg.count = 2;
+msg.cards = [12345, 67890];
+
+// 序列化
+const binary = msg.toPayload();
+
+// 反序列化
+const decoded = new YGOProMsgDraw();
+decoded.fromPayload(binary);
+```
+
+### 视角控制
+```typescript
+const msg = new YGOProMsgDraw();
+msg.player = 0;
+msg.count = 2;
+msg.cards = [12345, 0x80000000 | 67890]; // 第二张卡公开
+
+// 对方视角
+const opponentView = msg.opponentView();
+console.log(opponentView.cards); // [0, 0x80000000 | 67890]
+```
+
+### 查询数据
+```typescript
+import { YGOProMsgUpdateCard, CardQuery } from 'ygopro-msg-encode';
+
+const msg = new YGOProMsgUpdateCard();
+msg.controller = 0;
+msg.location = 4; // MZONE
+msg.sequence = 0;
+
+msg.card = new CardQuery();
+msg.card.flags = QUERY_CODE | QUERY_ATTACK | QUERY_DEFENSE;
+msg.card.code = 89631139; // 青眼白龙
+msg.card.attack = 3000;
+msg.card.defense = 2500;
+
+const binary = msg.toPayload();
+```
+
+### Registry 使用
+```typescript
+import { YGOProMessages, OcgcoreCommonConstants } from 'ygopro-msg-encode';
+
+// 根据 identifier 获取类
+const MsgClass = YGOProMessages.get(OcgcoreCommonConstants.MSG_WIN);
+const msg = new MsgClass();
+
+// 解析二进制数据
+const identifier = data[0];
+const MsgClass2 = YGOProMessages.get(identifier);
+const decoded = new MsgClass2();
+decoded.fromPayload(data);
+```
+
+## 技术亮点
+
+### 1. 装饰器系统
+使用 `@BinaryField` 装饰器定义二进制结构，支持：
+- 固定偏移和动态偏移
+- 固定长度和动态长度
+- 嵌套对象和对象数组
+- 基础类型：u8, i8, u16, i16, u32, i32, utf8, utf16
+
+### 2. 自动序列化
+- 自动按字段顺序序列化和反序列化
+- 支持 Little-Endian 字节序
+- 正确处理字符串截断和空终止符
+
+### 3. 视角系统
+- `opponentView()`: 对方视角（隐藏手牌、未公开信息）
+- `teammateView()`: 队友视角（TAG 决斗）
+- `observerView()`: 观察者视角
+- `playerView(playerId)`: 指定玩家视角
+
+### 4. 类型安全
+- 完整的 TypeScript 类型定义
+- 所有小类都导出，可独立使用
+- 编译时类型检查
+
+### 5. 可扩展性
+- Registry 系统支持动态注册
+- 易于添加新的 MSG 类型
+- 小类可在不同 MSG 之间复用
+
+## 参考来源
+
+- YGOPro ocgcore: `/home/nanahira/ygo/ygopro/ocgcore`
+- YGOPro 客户端: `/home/nanahira/ygo/ygopro/gframe`
+- 参考实现: `/home/nanahira/ygo/koishipro-core.js`
+
+## 视角系统实现
+
+### playerView 方法
+基类提供了默认实现，检查 `this['player']` 字段：
+- 如果 `player === playerId`：返回完整数据
+- 否则：返回 `opponentView()`
+
+### 特殊情况
+**MSG_UPDATE_CARD**: 字段名是 `controller` 而非 `player`，需要重写 `playerView` 方法。
+
+### 视角类型总结
+1. **opponentView()**: 对手视角，隐藏未公开信息
+2. **teammateView()**: TAG 决斗队友视角
+   - 场上：可见盖放卡片
+   - 手牌：不可见非公开卡片
+3. **observerView()**: 观察者视角，默认使用 opponentView
+4. **playerView(playerId)**: 根据玩家 ID 自动选择视角
+
+## 测试结果
+
+```
+Test Suites: 4 passed, 4 total
+Tests:       66 passed, 66 total
+Snapshots:   0 total
+Time:        ~11 seconds
+```
+
+### 测试覆盖
+- ✅ 基础序列化/反序列化（31 个测试）
+- ✅ 查询数据完整解析（11 个测试）
+- ✅ 视角控制（24 个测试）
+  - MSG_DRAW, MSG_SHUFFLE_HAND 等的 opponentView
+  - MSG_TAG_SWAP 的 teammateView
+  - MSG_UPDATE_CARD 的视角控制
+    - 对手视角：盖放卡片隐藏
+    - 队友视角：场上盖放卡片可见，非场上盖放卡片隐藏
+    - playerView：正确使用 controller 字段
+  - MSG_UPDATE_DATA 的视角控制
+    - 对手视角：盖放卡片隐藏
+    - 队友视角：MZONE/SZONE 盖放可见，HAND 非公开不可见
+    - playerView：正确使用 player 字段
+
+✅ 所有测试通过
+✅ 构建成功
+✅ 类型检查通过