企业官网建设流程全解析

• 游戏开发
• 桌面应用
• 开发工具
• MCP 服务

Rusted PackFile Manager（RPFM）的rpfm_server是一个独立的后端进程，通过本地 WebSocket 接口把 RPFM 的全部 Pack 文件管理能力暴露给外部程序——桌面 UI（rpfm_ui）只是它的客户端之一，任何支持 WebSocket 与 JSON 的语言都能驱动同一个后端。本文基于 docs/server/client-example.md 提供的一份可直接落地的客户端实现，逐段讲解连接与会话处理、请求-响应关联、Pack 与文件操作、设置读写等完整调用链，并对照rpfm_server与rpfm_ipc的源码说明协议底层原理。读完本文，你将能够用 TypeScript 或 C# 从零写出一个可运行、可重连、可并发发请求的 RPFM 服务端客户端，并掌握将其移植到任意语言的方法。

协议全景：先理解你要对接的服务器

在动手写客户端之前，先明确rpfm_server暴露的协议形态。服务器默认监听127.0.0.1:45127（端口常量定义于 rpfm_server/src/main.rs），提供三个 HTTP 端点，其中与本文直接相关的是 WebSocket 端点：

服务器端 WebSocket 处理逻辑位于 rpfm_server/src/server_websocket.rs：握手时接受可选的session_id查询参数，升级成功后每个连接都绑定一个独立的会话（Session），会话拥有专属的后台线程，串行处理该会话内的命令。会话之间完全隔离——一个会话里打开的 Pack 不会被另一个会话看到，这正是"多个客户端共享一个服务器进程却互不干扰"的架构基础（详见 docs/server/overview.md）。

协议的所有消息都遵循一个统一信封（envelope），其 Rust 定义在 rpfm_ipc/src/messages.rs：

pub struct Message<T: Debug> { pub id: u64, pub data: T, }

对应到 JSON 就是：

{ "id": <number>, "data": <Command 或 Response> }

其中id是客户端自增的请求号，服务器在响应中原样回显，用于把响应匹配回对应的请求；data是命令或响应载荷。id只允许客户端请求使用，值为0时专用于服务器主动推送的消息（如连接时的SessionConnected）。

连接与会话处理：核心客户端的骨架

连接并接收 SessionConnected

客户端连接ws://127.0.0.1:45127/ws后，服务器会立刻主动推送一条未请求的SessionConnected消息，携带本次分配的会话 ID。这条消息是客户端建立后续一切操作的锚点——有了会话 ID，才能在连接意外断开后重连到原会话，保住已打开的 Pack 和依赖缓存。源码中这条消息的构造见 rpfm_server/src/server_websocket.rs：

let session_connected_msg = IpcMessage { id: 0, // Special ID for connection message data: Response::SessionConnected(session_id), };

发送到线上的 JSON 形如：

{ "id": 0, "data": { "SessionConnected": 42 } }

文档给出的 TypeScript 客户端在onmessage回调里专门截获这一消息并保存会话 ID：

// Handle SessionConnected (unsolicited, id=0) if (typeof msg.data === "object" && "SessionConnected" in msg.data) { this.sessionId = msg.data.SessionConnected; console.log(`Connected to session ${this.sessionId}`); return; }

C# 版本则在ReceiveLoop里做同样的判断：

// Handle SessionConnected (unsolicited, id=0) if (data.ValueKind == JsonValueKind.Object && data.TryGetProperty("SessionConnected", out var sid)) { SessionId = sid.GetInt32(); Console.WriteLine($"Connected to session {SessionId}"); continue; }

请求-响应关联：pending Map 与并发安全

协议的关联机制是：客户端为每条请求分配唯一自增id，把resolve/reject回调放进一个 pending 表；收到响应时按id从表里取出回调并执行。这样多条请求可以同时在空中飞行（in-flight），无需排队等待。

TypeScript 实现用一个Map<number, { resolve, reject }>：

private nextId = 1; private pending = new Map<number, { resolve: (resp: any) => void; reject: (err: Error) => void; }>(); send(command: object | string): Promise<any> { return new Promise((resolve, reject) => { const id = this.nextId++; this.pending.set(id, { resolve, reject }); this.ws.send(JSON.stringify({ id, data: command })); }); }

收到消息时先尝试从 pending 表取出对应id的处理器；若响应数据里带有Error字段，则拒绝（reject）该 Promise，否则解析（resolve）：

const handler = this.pending.get(msg.id); if (handler) { this.pending.delete(msg.id); if (typeof msg.data === "object" && "Error" in msg.data) { handler.reject(new Error(msg.data.Error)); } else { handler.resolve(msg.data); } }

C# 版本用ConcurrentDictionary<int, TaskCompletionSource<JsonElement>>实现同样的关联，ReceiveLoop在后台任务中持续收消息并完成对应的TaskCompletionSource：

private readonly ConcurrentDictionary<int, TaskCompletionSource<JsonElement>> _pending = new(); private async Task ReceiveLoop() { var buffer = new byte[65536]; while (_ws.State == WebSocketState.Open) { var result = await _ws.ReceiveAsync(buffer, CancellationToken.None); var json = Encoding.UTF8.GetString(buffer, 0, result.Count); var msg = JsonDocument.Parse(json).RootElement; var data = msg.GetProperty("data"); // ... SessionConnected 特判 ... var id = msg.GetProperty("id").GetInt32(); if (_pending.TryRemove(id, out var tcs)) { if (data.ValueKind == JsonValueKind.Object && data.TryGetProperty("Error", out var err)) { tcs.SetException(new Exception(err.GetString())); } else { tcs.SetResult(data); } } } }

一个容易忽略的实现细节：收消息与发请求不能共用一个"顺序假设"。由于服务器为每个命令在自己的后台线程上执行（rpfm_server/src/server_websocket.rs 中每个命令都tokio::spawn一个任务，把响应经 mpsc 通道送回），响应到达顺序可能与发送顺序不同，因此只能依赖id关联，绝不能假设响应按请求顺序返回。

优雅断开：ClientDisconnecting

断开连接时，协议要求先发送ClientDisconnecting命令，再关闭 socket。服务器收到后会立即清理会话（而不是等待默认 300 秒的超时）；若这是最后一个会话，服务器进程会直接退出。这正是客户端示例中disconnect方法的由来：

async disconnect(): Promise<void> { await this.send("ClientDisconnecting"); this.ws.close(); }

public async Task DisconnectAsync() { await SendAsync("ClientDisconnecting"); await _ws.CloseAsync( WebSocketCloseStatus.NormalClosure, "done", CancellationToken.None); }

服务器的对应处理在 rpfm_server/src/server_websocket.rs：它先回送Response::Success（{ "id": <原id>, "data": "Success" }），再把graceful_disconnect置位并跳出接收循环，随后立即session_manager.remove_session(session_id)；若会话计数归零则 flush 遥测并std::process::exit(0)（见同文件 L201-L211）。

如果没有发送ClientDisconnecting就断线，会话会进入5 分钟宽限期（DEFAULT_SESSION_TIMEOUT_SECS = 300，定义于 rpfm_server/src/session.rs），期间若客户端携带原session_id重连则会话状态完整保留；超时未重连才会被回收。完整生命周期说明见 docs/server/sessions.md。

类型化便捷方法：把协议命令封装成可调用 API

原文档的客户端类把常用命令封装成带类型的便捷方法。这些方法名与rpfm_ipc中Command枚举的变体一一对应（枚举定义见 rpfm_ipc/src/messages.rs），理解这一点对排查问题很有帮助——响应 JSON 里的键名（如StringContainerInfo、ContainerInfoVecRFileInfo）就是Response枚举变体名，见 rpfm_ipc/src/messages.rs。

Pack 管理：打开、列出、保存

// --- Pack management --- async openPack(paths: string[]): Promise<[string, any]> { const resp = await this.send({ OpenPackFiles: paths }); return resp.StringContainerInfo; } async listOpenPacks(): Promise<[string, any][]> { const resp = await this.send("ListOpenPacks"); return resp.VecStringContainerInfo; } async closePack(packKey: string): Promise<void> { await this.send({ ClosePack: packKey }); } async closeAllPacks(): Promise<void> { await this.send("CloseAllPacks"); } async savePack(packKey: string): Promise<any> { const resp = await this.send({ SavePack: packKey }); return resp.ContainerInfo; } async savePackAs(packKey: string, path: string): Promise<any> { const resp = await this.send({ SavePackAs: [packKey, path] }); return resp.ContainerInfo; }

对应到线上 JSON，OpenPackFiles是 Newtype 变体{ "OpenPackFiles": ["/path/to/my_mod.pack"] }，响应为{ "StringContainerInfo": [packKey, ContainerInfo] }；SavePackAs是 Tuple 变体{ "SavePackAs": ["key", "/path"] }。ContainerInfo是 Pack 的容器级元数据，字段包括file_name、file_path、pfh_version、pfh_file_type、bitmask、compress、timestamp（详见 docs/server/ws-shared-types.md），因此示例代码里才能直接访问containerInfo.file_name打印 Pack 名。

值得注意：pack key 是服务器为每个打开的 Pack 生成的字符串标识，后续所有针对该 Pack 的操作（解码、删除、提取、保存）都要以它为第一个参数。打开多个 Pack 时它们会合并进当前会话，ListOpenPacks返回全部已打开 Pack 的[key, ContainerInfo]数组。

C# 侧对应方法如下（OpenPackAsync返回StringContainerInfo属性，packKey取resp[0]）：

public async Task<JsonElement> OpenPackAsync(string[] paths) { var resp = await SendAsync(new { OpenPackFiles = paths }); return resp.GetProperty("StringContainerInfo"); } public async Task<JsonElement> ListOpenPacksAsync() { var resp = await SendAsync("ListOpenPacks"); return resp.GetProperty("VecStringContainerInfo"); } public async Task<JsonElement> SavePackAsync(string packKey) { var resp = await SendAsync(new { SavePack = packKey }); return resp.GetProperty("ContainerInfo"); }

文件操作：树视图、解码、删除、提取

// --- File operations --- async getTreeView(packKey: string): Promise<[any, any[]]> { const resp = await this.send({ GetPackFileDataForTreeView: packKey }); return resp.ContainerInfoVecRFileInfo; } async decodeFile(packKey: string, path: string, source = "PackFile"): Promise<any> { return this.send({ DecodePackedFile: [packKey, path, source] }); } async deleteFiles(packKey: string, paths: any[]): Promise<any[]> { const resp = await this.send({ DeletePackedFiles: [packKey, paths] }); return resp.VecContainerPath; } async extractFiles( packKey: string, paths: Record<string, any[]>, destPath: string, asTsv = false, ): Promise<[string, string[]]> { const resp = await this.send({ ExtractPackedFiles: [packKey, paths, destPath, asTsv] }); return resp.StringVecPathBuf; }

几个关键理解点：

1. GetPackFileDataForTreeView返回[ContainerInfo, RFileInfo[]]（即ContainerInfoVecRFileInfo），RFileInfo是单个文件的元数据（path、container_name、timestamp、file_type），用于在客户端渲染 Pack 目录树。
2. DecodePackedFile的source参数是DataSource枚举，取值为"PackFile"|"GameFiles"|"ParentFiles"|"AssKitFiles"|"ExternalFile"。默认"PackFile"表示从当前打开的 Pack 解码。该命令的响应是按文件类型分派的 tagged union——例如 DB 表返回{ "DBRFileInfo": [DB, RFileInfo] }，文本文件返回{ "TextRFileInfo": [Text, RFileInfo] }，共 20 种左右变体（完整清单见 docs/server/ws-commands.md 的DecodePackedFile一节与 docs/server/ws-responses.md 的 File-Type Decoded Responses 表）。
3. DeletePackedFiles与ExtractPackedFiles的路径参数是ContainerPath的 tagged enum：单文件写作{ "File": "db/units_tables/data" }，文件夹写作{ "Folder": "db/units_tables" }。ExtractPackedFiles的参数是按DataSource分组的Record<DataSource, ContainerPath[]>，配合第四个布尔参数asTsv（为true时 DB/Loc 表以 TSV 文本形式导出）。该命令的 Rust 签名可对照 rpfm_ipc/src/messages.rs：

ExtractPackedFiles(String, BTreeMap<DataSource, Vec<ContainerPath>>, PathBuf, bool),

游戏选择

async setGame(gameKey: string, rebuildDeps: boolean): Promise<void> { await this.send({ SetGameSelected: [gameKey, rebuildDeps] }); }

SetGameSelected的第二个参数rebuildDeps控制是否重建依赖缓存。注意游戏选择是会话级状态，只影响当前会话，不会全局改变服务器（docs/server/sessions.md 明确说明："When you call something likeCommand::SetGameSelected, you're changing it foryoursession, not globally."）。示例中使用的"warhammer_3"是游戏键（game key），支持的完整游戏列表见 docs/reference/supported-games.md。

设置读写：单键查询与批量快照

async getSetting(key: string): Promise<string> { const resp = await this.send({ SettingsGetString: key }); return resp.String; } async getAllSettings(): Promise<{ bools: Record<string, boolean>; ints: Record<string, number>; floats: Record<string, number>; strings: Record<string, string>; }> { const resp = await this.send("SettingsGetAll"); const [bools, ints, floats, strings] = resp.SettingsAll; return { bools, ints, floats, strings }; }

设置系统分为两类命令：

• 单键 getter：SettingsGetBool/SettingsGetI32/SettingsGetF32/SettingsGetString/SettingsGetPathBuf/SettingsGetVecString/SettingsGetVecRaw，均以{ "<命令名>": key }请求，返回{ "Bool": ... }、{ "String": ... }等类型化包装。
• 批量快照：SettingsGetAll一次拉取全部设置，返回{ "SettingsAll": SettingsSnapshot }。SettingsSnapshot是六个 map（bool/i32/f32/string/raw_data/vec_string），其 Rust 结构定义于 rpfm_ipc/src/settings_keys.rs。一次往返替代 N 次单键调用，需要多个设置时效率高得多。

所有设置键都有类型化常量定义（如DEFAULT_GAME = "default_game"、LANGUAGE = "language"、THEME、AUTOSAVE_INTERVAL、ENABLE_USAGE_TELEMETRY、AI_API_URL等，见 rpfm_ipc/src/settings_keys.rs），写客户端时建议以这些常量名作为key参数，避免拼写错误。

完整使用示例：一个端到端的客户端脚本

原文档提供了 TypeScript 与 C# 各一份完整示例，串联了"连接 → 选游戏 → 打开 Pack → 查看树 → 解码 DB 表 → 提取文件 → 保存 → 断开"全流程。TypeScript 版本如下：

async function main() { const client = new RpfmClient(); // Wait for connection await new Promise<void>((resolve) => { client["ws"].onopen = () => resolve(); }); console.log(`Session ID: ${client.sessionId}`); // Select a game await client.setGame("warhammer_3", true); // Open a pack file const [packKey, containerInfo] = await client.openPack([ "/home/user/mods/my_mod.pack" ]); console.log(`Opened pack: ${containerInfo.file_name} (key: ${packKey})`); // Get the file tree const [info, files] = await client.getTreeView(packKey); console.log(`Pack contains ${files.length} files`); // Decode a DB table const decoded = await client.decodeFile( packKey, "db/units_tables/data", "PackFile" ); if ("DBRFileInfo" in decoded) { const [db, fileInfo] = decoded.DBRFileInfo; console.log(`Table: ${db.table.table_name}, rows: ${db.table.table_data.length}`); } // Extract files to disk const [extractPath, extractedFiles] = await client.extractFiles( packKey, { PackFile: [{ File: "db/units_tables/data" }] }, "/tmp/extracted" ); console.log(`Extracted ${extractedFiles.length} files to ${extractPath}`); // Save and disconnect await client.savePack(packKey); await client.disconnect(); } main().catch(console.error);

C# 版本流程相同，差异仅在语法层面——OpenPackAsync返回的元组用packResult[0]取 pack key、[1]取容器信息；DecodeFileAsync后用decoded.TryGetProperty("DBRFileInfo", out var dbResult)判断文件类型并取表数据；ExtractFilesAsync的路径用Dictionary<string, object[]>表达Record<DataSource, ContainerPath[]>：

var decoded = await client.DecodeFileAsync(packKey, "db/units_tables/data", "PackFile"); if (decoded.TryGetProperty("DBRFileInfo", out var dbResult)) { var db = dbResult[0]; var table = db.GetProperty("table"); Console.WriteLine( $"Table: {table.GetProperty("table_name")}, " + $"rows: {table.GetProperty("table_data").GetArrayLength()}"); }

几个实战要点：

• 解码 DB 表的内层结构：DBRFileInfo的DB载荷含mysterious_byte（布尔标志，置 0 可能导致 WH2 崩溃）、guid、table（即TableInMemory，含table_name、definition、table_data二维数组等，见 docs/server/ws-shared-types.md 的TableInMemory与DB小节）。示例中db.table.table_name就是表类型标识（如units_tables），db.table.table_data.length是行数。
• 提取路径的语义：extractFiles返回[提取根目录, 已提取文件路径数组]，第一个元素即传入的destPath。
• TypeScript 直接访问私有成员：示例通过client["ws"].onopen访问私有ws字段等待连接建立——这是文档示例的写法，工程化实现更推荐在类内部用onopen回调或暴露waitForConnection()方法。

移植到其他语言：5 步协议要点与 serde 序列化规则

该协议与语言无关，任何具备 WebSocket 与 JSON 支持的运行时都能实现客户端。原文档给出了五个移植步骤，这里结合协议文档展开：

1. 连接：任意 WebSocket 库连接到ws://127.0.0.1:45127/ws；若要重连已有会话，追加查询参数?session_id=<id>（服务器在 rpfm_server/src/server_websocket.rs 通过WsQueryParams解析该参数，并通过session_manager.get_or_create_session(requested_session_id)决定是复用会话还是新建，见同文件 L83-L93）。
2. 发送：以{ "id": <number>, "data": <command> }格式发送 JSON 文本帧。无参命令直接发送字符串（如"ListOpenPacks"）；带参命令用{ "命令名": 参数 }包裹。
3. 接收：解析收到的 JSON，按id把响应匹配回请求。注意id: 0的SessionConnected是服务器主动推送，不要当作某个请求的响应。
4. 处理会话消息：连接建立后立刻处理SessionConnected并保存会话 ID，供后续重连使用。
5. 优雅退出：关闭连接前先发送ClientDisconnecting，让服务器立即回收会话资源。

跨语言移植最容易踩坑的是serde 序列化约定——因为Command/Response都是 Rust 枚举，其 JSON 形态由 serde 的枚举序列化规则决定（Command、Response枚举定义见 [rpfm_ipc/src/messages.rs](https://link.gitcode.com/i/66304496193a46366aaec39591896d9d 与 L1393-L1394)，Message<T>直接#[derive(Serialize, Deserialize)]）。三种变体形态的映射如下（详见 docs/server/ws-protocol.md）：

这意味着线上 JSON 的形状与 Rust 客户端写同样的请求几乎一致——阅读 docs/server/ws-commands.md 的命令参考时，直接照 JSON 形状构造请求即可。另外注意：

• ContainerPath（{ "File": ... }/{ "Folder": ... }）与DataSource（纯字符串枚举）在参数中高频出现，移植时建议封装成对应语言的类型；
• 错误响应统一是{ "id": <原id>, "data": { "Error": "消息" } }（对应Response::Error(String)，见 rpfm_ipc/src/messages.rs），任何响应只要带Error字段就应视为对应请求被拒绝，错误消息适合面向开发者展示；
• 响应键名即类型名：例如StringContainerInfo、VecStringContainerInfo、ContainerInfoVecRFileInfo、DBRFileInfo、VecContainerPath、StringVecPathBuf等，都是Response枚举变体名，Response的完整清单见 docs/server/ws-responses.md。

源码级验证：客户端示例背后的实现事实

本文所有协议行为均可在仓库源码中交叉验证，整理如下，便于读者深入：

• 会话与超时：DEFAULT_SESSION_TIMEOUT_SECS = 300（5 分钟）定义于 rpfm_server/src/session.rs；会话拥有独立后台线程串行处理命令（rpfm_server/src/session.rs 的模块文档有详细说明）。
• 握手与 SessionConnected：ws_handler接受?session_id参数、升级后立即发送id: 0的SessionConnected，见 rpfm_server/src/server_websocket.rs。
• ClientDisconnecting 特判：在接收循环内单独匹配Command::ClientDisconnecting，先回Success再清理会话、必要时退出进程，见 rpfm_server/src/server_websocket.rs。
• 命令路由：除ClientDisconnecting外的命令统一转发给会话后台线程执行，每个命令独立tokio::spawn，响应经 mpsc 通道按id送回——这是"响应顺序与请求顺序无关"的根源，见 rpfm_server/src/server_websocket.rs。
• 设置快照结构：SettingsSnapshot的六 map 字段定义于 rpfm_ipc/src/settings_keys.rs，与SettingsGetAll响应中的SettingsAll载荷一一对应。
• 测试文件与格式参考：仓库自带各 PFH 版本测试包（test_files 下的PFH0_test.pack至PFH6_test.pack），以及test_decode_db、test_decode.loc等各类文件解码样例，可用来验证客户端解码结果是否与预期一致。

常见问题与注意事项

• 响应顺序不可假设：服务器为每个命令并发执行，务必以id关联响应，不要把"先发先回"当作事实。
• SessionConnected是未请求消息：它没有对应的 pending 处理器，客户端必须在onmessage入口处先特判，否则会误当作未知响应丢弃，导致拿不到会话 ID。
• 错误就是Error响应：不要依赖 HTTP 状态或连接异常判断命令失败；协议层面任何{ "Error": ... }都是对原请求的拒绝。例如OpenPackFiles打开不存在的路径时，服务器会以Error变体回包。
• 会话隔离：两个客户端连同一个服务器互不共享状态；WebSocket 客户端可凭session_id重连恢复状态，MCP 客户端则每次连接都是全新会话（docs/server/overview.md）。
• 解码响应的类型分派：DecodePackedFile的响应是 tagged union，客户端需按 JSON 顶层键（如DBRFileInfo、TextRFileInfo、LocRFileInfo、"Unknown"）分派处理，不能假定返回固定结构。未知文件类型会返回"Unknown"（对应 rpfm_ipc/src/messages.rs 中Response::Unknown变体）。

延伸阅读

• docs/server/overview.md — 服务器架构、三个端点、WebSocket 与 MCP 两条接入路径
• docs/server/ws-protocol.md — 消息信封、序列化约定、错误与优雅断开
• docs/server/ws-commands.md — 全部可发送命令的参考（含参数表与 JSON 示例）
• docs/server/ws-responses.md — 全部响应变体与载荷结构
• docs/server/ws-shared-types.md —ContainerInfo、RFileInfo、DB、Loc、Text等共享类型定义
• docs/server/sessions.md — 会话生命周期、重连示例与/sessionsREST 端点
• docs/server/mcp.md — 面向 AI Agent 的 MCP 接入方式
• rpfm_ipc/src/messages.rs — 协议三要素Message<T>/Command/Response的 Rust 定义
• rpfm_server/src/server_websocket.rs — WebSocket 端点的完整服务端实现
• rpfm_ipc/src/settings_keys.rs — 全部设置键常量与SettingsSnapshot结构

• 游戏开发
• 桌面应用
• 开发工具
• MCP 服务