P1 协议子 ID lock 持久化分配

## 问题

`MessageHelper.MessageIdHandler` 历史上按行序自增分配 `Opcode`，proto 文件插入/重排/删除 message 会导致整个模块的 SubId 全线平移，连带 C#/C++/Go/Lua/TS 五个 helper 全部错位。线上协议与历史消息包的对接会因此被破坏。

## 方案

新增 `ProtoExport/Persistence/` 模块，把 (Module, Name) → SubId 的映射持久化到 lock JSON 文件：

- `MessageIdLock`：数据模型，`SortedDictionary` 保证序列化按 key 排序便于 PR diff。
- `MessageIdLockStore`：原子写（.tmp + replace），schema 版本不匹配 / module key 越界直接抛 `InvalidDataException`，绝不静默重排。
- `MessageIdAllocator.Mutate`：决策表 —— Messages 命中沿用 / Retired 命中恢复为活跃 / 新消息 `max+1`（含 retired 占用）/ 缺失消息进 Retired 永不回收。
- `MessageIdCoordinator.AssignAndPersist`：跨文件按 Module 聚合 → Mutate → Save。
- `LockSeedGenerator`：一次性迁移，把当前 Opcode 1:1 序列化为 lock 起点。

## 接入点

- `MessageHelper.SkipAutoAssignOpcode`：lock 模式下 Parse 不自增，Opcode 全留 0 等 Coordinator 统一分配。
- `LauncherOptions.MessageIdLockPath`：CLI 选项 `--messageIdLockPath`，空字符串保留旧自增行为（向后兼容）。
- `Program.cs` 新增 `--print-lock` 与 `--regenerate-lock` 两个子命令。
- `tools/migrate-message-id-lock.sh`：一次性迁移脚本，先尝试 `Protobuf/Tools/ProtoExport.dll`，否则回退 `dotnet run`，传 `--isServer true` 以冻结全部模块（含 server-only）。

## 文档

README 新增「子 ID 稳定性（lock 文件）」章节，覆盖：问题（行序自增的代价）、lock 机制、迁移步骤（含「不回滚历史漂移」声明）、merge conflict 处理。

## 测试

`ProtoExporterGUI.Tests` 已加 `ProjectReference` 指向 `ProtoExport`，4 套测试 58 用例全绿：

- `MessageIdAllocatorTests`：首次分配起点 10 / 中间插入 / 重排 / 删除→Retired / 重命名 / 幂等 / 多模块独立 / schema 校验 / 往返等价 / Opcode 写回断言。
- `MessageIdCoordinatorTests`：跨文件续号 / 整体重排与插入 / 删除→Retired / 多模块互不影响 / Lock 损坏报错。
- `LockSeedGeneratorTests`：冻结当前 Opcode 作为起点 / Seed 后 Coordinator 沿用 / Opcode 非法/超界报错 / 格式化与序列化等价。
- `MessageIdLockScenarioTests`：端到端修改性矩阵（基线 + A 插入 / B 重排 / C 删除 / D 重命名 / 回归重跑基线）。

CLI 真实集成（TestProtos 5 模块）也跑了 A 中间插入 / B 整体重排 / C 删除 / D 重命名 / E 重命名回归 / 损坏 lock 拒绝 / schema 不兼容拒绝 —— 全部通过。

## 向后兼容

未传 `--messageIdLockPath` 时走旧路径，行为零变化。所有现有导出脚本不受影响。

## 后续 PR

PR2（`feat/proto-messageid-lock-gui`）：GUI 状态面板（基于本 PR head）。

Author: AlianBlank

ProtoExport/LauncherOptions.cs

@@ -76,6 +76,12 @@ public sealed class LauncherOptions
     [Option("requireComments", Required = false, DefaultValue = "none", Description = "注释校验级别: none(不校验) | container(类型级) | member(成员级) | all(全部)")]
     public string RequireComments { get; set; }
 
+    /// <summary>
+    /// 子 ID 持久化 lock 文件路径。空字符串表示禁用 lock 模式（保留旧的自增分配行为，向后兼容）。
+    /// </summary>
+    [Option("messageIdLockPath", Required = false, DefaultValue = "", Description = "子 ID 持久化 lock 文件路径，留空则禁用 lock 模式（向后兼容旧行为）")]
+    public string MessageIdLockPath { get; set; }
+
     /// <summary>
     /// 解析后的注释校验级别
     /// </summary>

ProtoExport/MessageHelper.cs

@@ -67,8 +67,24 @@ public static MessageInfoList Parse(string proto, string fileName, string filePa
         return messageInfo;
     }
 
+    /// <summary>
+    /// 当 <c>true</c> 时，<see cref="Parse"/> 内部不再自动给 <c>Opcode</c> 赋值；
+    /// 调用方需自行通过 <see cref="Persistence.MessageIdAllocator"/> 等机制分配 SubId。
+    /// <para>
+    /// 进程级静态标志位：导出器进程模型为单次命令行（CLI）/ 单实例 GUI，不会并发触发两轮解析。
+    /// 若未来并发场景出现，需改为参数注入（<see cref="Parse"/> 接收 skipAutoAssign 形参）。
+    /// </para>
+    /// </summary>
+    public static bool SkipAutoAssignOpcode { get; set; }
+
     private static void MessageIdHandler(List<MessageInfo> operationCodeInfos, int start)
     {
+        if (SkipAutoAssignOpcode)
+        {
+            // 关闭旧的自增分配。Opcode==0 的消息将由外部 MessageIdAllocator 处理。
+            return;
+        }
+
         foreach (var operationCodeInfo in operationCodeInfos)
         {
             if (operationCodeInfo.IsMessage)

ProtoExport/Persistence/CoordinatorResult.cs

@@ -0,0 +1,31 @@
+using System.Collections.Generic;
+
+namespace GameFrameX.ProtoExport.Persistence;
+
+/// <summary>
+/// <see cref="MessageIdCoordinator.AssignAndPersist"/> 与 <see cref="LockSeedGenerator.SeedFromCurrentOpcodes"/> 的统计结果。
+/// </summary>
+public sealed class CoordinatorResult
+{
+    /// <summary>
+    /// 本次涉及的模块数。
+    /// </summary>
+    public int ModuleCount { get; }
+
+    /// <summary>
+    /// 本次新增 SubId 的消息总数。
+    /// </summary>
+    public int NewlyAssignedCount { get; }
+
+    /// <summary>
+    /// 形如 <c>"&lt;ModuleKey&gt;.&lt;MessageName&gt;"</c> 的新增条目列表。
+    /// </summary>
+    public IReadOnlyList<string> NewlyAssigned { get; }
+
+    public CoordinatorResult(int moduleCount, int newlyAssignedCount, IReadOnlyList<string> newlyAssigned)
+    {
+        ModuleCount = moduleCount;
+        NewlyAssignedCount = newlyAssignedCount;
+        NewlyAssigned = newlyAssigned;
+    }
+}

ProtoExport/Persistence/LockSeedGenerator.cs

@@ -0,0 +1,112 @@
+using System.Collections.Generic;
+using System.IO;
+
+namespace GameFrameX.ProtoExport.Persistence;
+
+/// <summary>
+/// 把当前解析出的 <see cref="MessageInfoList"/> 序列化为「冻结态」<see cref="MessageIdLock"/>：
+/// 每个消息的当前 <c>Opcode</c> 直接落进 <see cref="ModuleEntry.Messages"/>，作为后续稳定分配的起点。
+/// <para>
+/// 用法：迁移脚本一次调用。语义等同 <c>--regenerate-lock</c>。
+/// </para>
+/// <para>
+/// 注意：旧版本（无 lock）下 Opcode 来自行序自增 —— 此举不是「修复历史」，只是「冻结当前」。
+/// 历史里已经发生的重排/插入所产生的协议漂移不会因此回滚。
+/// </para>
+/// </summary>
+public static class LockSeedGenerator
+{
+    /// <summary>
+    /// 解析所有 proto，关闭自增，按当前 Opcode 序列化为 lock 写入 <paramref name="lockPath"/>。
+    /// </summary>
+    public static CoordinatorResult SeedFromCurrentOpcodes(
+        string lockPath,
+        IEnumerable<MessageInfoList> lists)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(lockPath);
+        ArgumentNullException.ThrowIfNull(lists);
+
+        var lockData = MessageIdLock.CreateEmpty();
+
+        // 同 Coordinator：按 Module 分组。
+        var byModule = new SortedDictionary<short, List<MessageInfo>>();
+        foreach (var list in lists)
+        {
+            if (!byModule.TryGetValue(list.Module, out var bucket))
+            {
+                bucket = new List<MessageInfo>();
+                byModule[list.Module] = bucket;
+            }
+
+            foreach (var info in list.Infos)
+            {
+                if (info.IsEnum || !info.IsMessage)
+                {
+                    continue;
+                }
+
+                bucket.Add(info);
+            }
+        }
+
+        var moduleKey = new List<string>();
+        var assigned = new List<string>();
+
+        foreach (var (module, messages) in byModule)
+        {
+            var key = module.ToString(System.Globalization.CultureInfo.InvariantCulture);
+            var entry = new ModuleEntry
+            {
+                ModuleName = FindModuleName(lists, module),
+            };
+            lockData.Modules[key] = entry;
+
+            foreach (var info in messages)
+            {
+                if (info.Opcode <= 0)
+                {
+                    throw new InvalidDataException(
+                        $"seed 模式下 module={key} 消息 '{info.Name}' 的当前 Opcode={info.Opcode} 不合法，"
+                        + "请先跑一次普通导出（不使用 --messageIdLockPath）让行序自增跑完，再做 seed。");
+                }
+
+                if (info.Opcode > MessageIdAllocator.MaxSubId)
+                {
+                    throw new InvalidDataException(
+                        $"seed 模式下 module={key} 消息 '{info.Name}' 的 Opcode={info.Opcode} 超过 SubId 上限 {MessageIdAllocator.MaxSubId}");
+                }
+
+                entry.Messages[info.Name] = info.Opcode;
+                assigned.Add($"{key}.{info.Name}");
+            }
+
+            moduleKey.Add(key);
+        }
+
+        MessageIdLockStore.Save(lockPath, lockData);
+
+        return new CoordinatorResult(moduleKey.Count, assigned.Count, assigned);
+    }
+
+    private static string FindModuleName(IEnumerable<MessageInfoList> lists, short module)
+    {
+        foreach (var list in lists)
+        {
+            if (list.Module == module)
+            {
+                return list.ModuleName;
+            }
+        }
+
+        return string.Empty;
+    }
+
+    /// <summary>
+    /// 把 lock 文件以可读形式打印到 stdout。供 <c>--print-lock</c> 使用。
+    /// </summary>
+    public static string FormatLockForDisplay(MessageIdLock lockData)
+    {
+        ArgumentNullException.ThrowIfNull(lockData);
+        return MessageIdLockStore.SaveToString(lockData);
+    }
+}