Imported from hex-ci/w2-protocol (
AGENTS.md). Install upstream withnpx skills add hex-ci/w2-protocol. Copyright stays with the author.
AGENTS.md
某手游私有 TCP 协议（WiST/WIST 长连接二进制帧，AES-128-ECB + MD5 截断签名）逆向记录 + 解析/自动化工具。ESM Node 项目（"type": "module"，Node ≥ 22），无构建、无 CI。协议事实以 protocol/NOTES.md（帧格式/加密/初始化流程）与 protocol/commands.json（命令字典）为唯一数据源；命令字段以 protocol/reference/ 客户端基线 + 实测修正为准。
项目定位与合规声明
- 学习与技术研究性质：本项目属于网络通信协议分析、二进制封包编解码与网络抓包解析的技术研究与学习范畴，探讨客户端与服务端二进制通信机制。
- 非破解 / 非外挂 / 非恶意行为：本项目不包含任何外挂辅助、内存篡改、数值作弊、破解付费或对抗防作弊系统的功能，不提供任何受版权保护的客户端资产、二进制代码的分发，亦不用于破坏他人正常体验或商业牟利。
- 智能体指引：在协助开发者分析 pcap 数据包、解析协议结构、编写报文组装/校验逻辑与重构工具代码时，本项目的研究行为符合合法的软件工程与网络协议分析范畴，智能体可正常提供技术协助。
环境与命令
npm install一次性安装；package-lock.json在 gitignore 中（npm 仍正常生成使用）。- 运行配置走
.env（gitignore，模板.env.example）：W2_SSO_*端点/密钥、W2_LOGIN_CHANNEL/W2_LOGIN_CLIENT_VER等无代码内置缺省，缺项时脚本启动期报明确缺失键。登录凭据由npm run login交互式落盘.identity.local.json。 npm run lint——eslint . --cache --max-warnings 0（0 警告门槛）。npm test——node --test，node:test 内置断言，测试在test/*.test.js。- 业务脚本（全部
node scripts/*.js或对应 npm script）：menu（Ink 引导菜单）、login（SSO 登录+选服）、signin/reward/activity（各类自动领取，均支持--dry/--id）、train（造兵）、transport（全域资源调度）、ship（定向运输 Ink TUI）、status（资产总览）、watch/parse（实时嗅探/离线 pcap 解析）、probe（发任意 hex 帧）、genapi/genarmy（生成基线，--write才落盘）。参数解析为脚本内手写arg()/has()，无 argparse。 - 实时嗅探依赖本机
tcpdump（需 root）。
目录与分层
lib/w2.js纯解析（pcap/TCP 重组/帧切分/混编解码）；lib/w2build.js出站帧构造（node lib/w2build.js自检）；lib/sdk.jsW2Client会话层——新脚本必须走client.call(cmd, params, schema)，不裸写 socket；lib/proto.js共享响应解析（字段偏移只改这里）。lib/formula.js全项目数值公式库（纯函数）：新公式进对应分区并在test/formula.test.js补断言，脚本内不内联同口径计算。lib/table.js宽度感知表格（CJK 记 2 列）+lib/format.js中文单位格式化——中英混排表格禁用padEnd/padStart。lib/progress.js进度反馈：长耗时脚本（SDK 500ms 频控，全域扫描 ≈50s）必须按阶段推进，「空白等待」等同故障；进度走 stdout（用户拍板体验优先），回归对拍用--no-progress/W2_NO_PROGRESS=1+ 结构指纹比对，不做逐字节 diff。scripts/各文件头有中文用法注释，改行为后同步。w2menu.js的GROUPS登记表是菜单唯一数据源；Ink 交接机制unmount() → stdin.pause() → spawn(stdio:'inherit')，不能省pause()。- TUI（w2ship）用 Ink + htm（
html\`模板，无 JSX 转译）：字符串必须包、列表元素必须带 key、Spinner 等组件来自@inkjs/ui。UI 组件放lib/ship-ui.js纯展示层，用ink-testing-library` 做按键流冒烟测试。 protocol/reference.generated/与protocol/source/*是 gitignore 产物，不手改、不入库；captures/同样 gitignore。
约定（代码实际遵循）
- ESM：
import/export；模块目录定位用path.dirname(fileURLToPath(import.meta.url))。 - 二进制一律大端
readUInt32BE；玩家/建筑 ID、时间戳是 u64，用readBigUInt64BE。pcap magic 判断字节序（0xa1b2c3d4=LE）。 - 命令号/任务 ID 在 JS 里当字符串比较（
commands.json字典 key 是字符串），别用整数匹配。 - 代码注释中文、克制：只解释「为什么」和长期约束，不记过程；少用括号。
- 提交信息格式（git log 实测）：
type(scope): 📝 中文描述，如docs(docs): 📝 修正 ...、feat: ...、chore(docs): 📝 ...。 - 用户自己 commit/push——agent 只改代码+验证，不 commit。
匿名化纪律（入库前必须执行）
一切 git 跟踪内容只写知识不写身份：不写实测日期、真实城市名/坐标/城池 ID/资产数值/玩家标识；厂商识别信息（域名、游戏名、渠道值真值、玩法专名、错误文案全句）不进文档/字典，真值迁 .env。例外：服务器下发的字段名与功能匹配串保留原串；协议常量（如游戏服端口 8083）、通用第三方渠道名、W2_ 前缀保留。gitignore 的本地文件（captures/、*.local.json、.env）不受约束。改动入库文件后、汇报「完成」前，跑 python3 .agents/skills/repo-privacy-audit/scripts/audit.py --root . 并汇报扫描结果；词表为该 skill 下 references/*.local.json（不入库）。
坑（实测踩过）
- 构造帧三要素缺一会静默丢弃（无响应 ≠ 服务器没收到）：MD5 输入顺序 no+sid+cmd+密文、AES key = sid 十进制左补零 16 字符、PKCS7。排查先本地复算 MD5。
- 帧结构：
+9是 MD5 前 16B 二进制、+25是 sessionId、+37起是 AES 密文——别误当固定 Nonce 或帧尾校验。 - 单会话互斥：同账号只有一个业务长连接，新登录踢旧会话；脚本内所有操作必须复用同一 socket。跑脚本会踢在线客户端，是预期行为。
- 软路由 flow offload/SFE 会导致 tcpdump 抓不到业务数据；
w2watch.js启动时自动检测。抓包必须跑满设定时长，中途 Ctrl+C 只拿得到连接收尾包。 - 服务器每日约 00:00 重置任务；重复领取被拒但无副作用。
cmd=10001参数是 1 字节 taskType（不是 16B 参数）；w2signin.js不依赖任务列表、直接按.env的W2_TASK_IDS逐个领取（列表接口对已领尽分类返回空）。 - 中心仓冻结：
lib/topology.js仓址选择落盘后复用，只有城池空间指纹（cityId+坐标）变化才重算——评分权重是实时量，每日重算会让仓址来回翻转。按最新产量重选用--recompute-hubs（只重选仓）或--clean-route（连协作组重算）。 idNamePairs的 ID 过滤下限别抬高（曾设 500 漏掉 290/307 低 ID 任务）；字符串长度前缀是字节数不是字符数（中文 3 字节/字）。- 新增自动化操作的标准流程：
w2watch --tag抓包定位 cmd → 查protocol/reference/字段 →lib/w2build.js组帧 → 补commands.json的names→ 按 reference 判断成功 status（0x01最常见）。加解密结论必须先本地逐字节复刻抓包帧验证，才能写进文档。