diff --git a/packages-user/data-common/src/replay/array.test.ts b/packages-user/data-common/src/replay/array.test.ts
index 246cb42..590f70e 100644
--- a/packages-user/data-common/src/replay/array.test.ts
+++ b/packages-user/data-common/src/replay/array.test.ts
@@ -764,6 +764,35 @@ describe('ReplayArray param codec', () => {
     });
 });
 
+describe('ReplayArray param type table', () => {
+    // 参数类型码表只增不改：锚定 float=6、非负 bigint=7、负 bigint=8、短字符串基址 9、负 int64=5
+    it('keeps the param type code mapping stable', () => {
+        const floatArray = createArray();
+        floatArray.add(0, [1.5]);
+        expect(firstParamToken(floatArray)).toBe(6);
+
+        const bigintArray = createArray();
+        bigintArray.add(0, [100n]);
+        expect(firstParamToken(bigintArray)).toBe(7);
+
+        const negativeBigintArray = createArray();
+        negativeBigintArray.add(0, [-100n]);
+        expect(firstParamToken(negativeBigintArray)).toBe(8);
+
+        const int64Array = createArray();
+        int64Array.add(0, [-2147483649]);
+        expect(firstParamToken(int64Array)).toBe(5);
+
+        const shortStringArray = createArray();
+        shortStringArray.add(0, ['hi']);
+        expect(firstParamToken(shortStringArray)).toBe(11);
+
+        const longStringArray = createArray();
+        longStringArray.add(0, ['a'.repeat(300)]);
+        expect(firstParamToken(longStringArray)).toBe(9);
+    });
+});
+
 describe('ReplayArray stream and buffer combination', () => {
     // 验证 createReadStream 从起始索引顺序读回多步，每参数为 number 且流索引逐次递进，末尾返回 null
     it('reads a sequence of steps through a read stream', () => {
diff --git a/packages-user/data-common/src/replay/array.ts b/packages-user/data-common/src/replay/array.ts
index 2323d8f..22ff009 100644
--- a/packages-user/data-common/src/replay/array.ts
+++ b/packages-user/data-common/src/replay/array.ts
@@ -23,6 +23,10 @@ interface INormalizedParam {
      * - 8: 负 bigint，载荷为幅值
      * - 9: string，带 int32 长度前缀
      * - 10 ~ 255: n - 9 长度的字符串
+     *
+     * 该类型码表属于录像参数编解码格式的一部分，遵循只增不改的约定：新语义必须分配
+     * 新的类型码，禁止复用既有类型码。历史上 5/6/7/8 与短字符串基址（长度 + 9）曾
+     * 发生一次性重新分配，项目未发布，旧录像不在兼容范围内。
      */
     readonly paramType: number;
 
diff --git a/packages-user/data-common/src/replay/types.ts b/packages-user/data-common/src/replay/types.ts
index cd94971..ecc4f00 100644
--- a/packages-user/data-common/src/replay/types.ts
+++ b/packages-user/data-common/src/replay/types.ts
@@ -261,6 +261,8 @@ export interface IReplayArray {
      * - 8: 负 bigint
      * - 9: string
      * - 10 ~ 255: n - 9 长度的字符串
+     *
+     * 参数类型码表遵循只增不改的约定：新语义必须分配新的类型码，禁止复用既有类型码。
      */
     getParamArray(): ArrayBuffer;
 
@@ -352,6 +354,10 @@ export interface IReplaySystemSave {
      * - 8: 负 bigint --- n + 2 Byte, 其中 n 是 bigint 的字节数
      * - 9: string    --- n + 5 Byte, 其中 n 是字符串编码后的字节数
      * - 10 ~ 255: n - 9 长度的字符串 --- n + 1 Byte, 其中 n 是字符串编码后的字节数
+     *
+     * 参数类型码表遵循只增不改的约定：新语义必须分配新的类型码，禁止复用既有类型码。
+     * 历史上 5/6/7/8 与短字符串基址曾发生一次性重新分配，且项目未发布，
+     * 因此本存档不承诺能被新版本读回由旧格式写出的录像。
      */
     readonly paramArray: ArrayBuffer;
 }