yeow-api 0.3.9 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.3.9",
+    "version": "0.4.0",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/assets.ts

@@ -1,3 +1,5 @@
+import type { FsEncoding, ReadFileOptions } from './fs.js';
+
 function _sendAssets(payload: Record<string, unknown>): unknown {
   const r = $send('assets', payload);
   if (r == null) return undefined;
@@ -15,21 +17,43 @@ function _sendAssetsAsync(payload: Record<string, unknown>): Promise<unknown> {
   });
 }
 
-export async function read(path: string): Promise<string> {
-  const r = await _sendAssetsAsync({ t: 'read', p: { path } }) as { data: string };
-  return r.data;
-}
-export function readSync(path: string): string {
-  return (_sendAssets({ t: 'read', p: { path } }) as { data: string }).data;
+/** 归一化 encoding 参数（与 fs 一致：缺省 = Uint8Array；utf8/base64 → 字符串）。 */
+function _encoding(options?: FsEncoding | ReadFileOptions): FsEncoding | undefined {
+  if (options == null) return undefined;
+  const e = typeof options === 'string' ? options : options.encoding;
+  if (e != null && e !== 'utf8' && e !== 'base64') {
+    throw new Error('Unsupported encoding: ' + String(e));
+  }
+  return e;
 }
 
-export async function readBase64(path: string): Promise<string> {
-  const r = await _sendAssetsAsync({ t: 'readBase64', p: { path } }) as { data: string };
-  return r.data;
-}
-export function readBase64Sync(path: string): string {
-  return (_sendAssets({ t: 'readBase64', p: { path } }) as { data: string }).data;
-}
+// 与 fs.readFile 相同语义：默认返回 Uint8Array；显式 utf8/base64 返回字符串。
+type AssetsReadFn = {
+  (path: string): Promise<Uint8Array>;
+  (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): Promise<string>;
+  (path: string, options: ReadFileOptions): Promise<Uint8Array | string>;
+};
+type AssetsReadSyncFn = {
+  (path: string): Uint8Array;
+  (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): string;
+  (path: string, options: ReadFileOptions): Uint8Array | string;
+};
+
+const readImpl = async (path: string, options?: FsEncoding | ReadFileOptions): Promise<Uint8Array | string> => {
+  const enc = _encoding(options);
+  const r = await _sendAssetsAsync({ t: enc === 'utf8' ? 'read' : 'readBase64', p: { path } }) as { data: string };
+  if (enc === 'utf8' || enc === 'base64') return r.data;
+  return Uint8Array.fromBase64(r.data);
+};
+const readSyncImpl = (path: string, options?: FsEncoding | ReadFileOptions): Uint8Array | string => {
+  const enc = _encoding(options);
+  const r = _sendAssets({ t: enc === 'utf8' ? 'read' : 'readBase64', p: { path } }) as { data: string };
+  if (enc === 'utf8' || enc === 'base64') return r.data;
+  return Uint8Array.fromBase64(r.data);
+};
+
+export const read = readImpl as AssetsReadFn;
+export const readSync = readSyncImpl as AssetsReadSyncFn;
 
 export async function extract(path: string, dest?: string): Promise<string> {
   const p: Record<string, unknown> = { path };
@@ -55,4 +79,4 @@ export function extractDirSync(path: string, dest?: string): string {
   return (_sendAssets({ t: 'extractDir', p }) as { path: string }).path;
 }
 
-export const assets = { read, readSync, readBase64, readBase64Sync, extract, extractSync, extractDir, extractDirSync };
+export const assets = { read, readSync, extract, extractSync, extractDir, extractDirSync };

package/src/core.ts

@@ -43,16 +43,15 @@ export {
 export type { TpsInfo } from './server.js';
 export {
     fs,
-    readFile, readFileSync, readFileBase64, readFileBase64Sync,
-    writeFile, writeFileSync, writeFileBase64, writeFileBase64Sync,
+    readFile, readFileSync,
+    writeFile, writeFileSync,
     appendFile, appendFileSync,
     exists, existsSync, stat, statSync,
     isDirectory, isDirectorySync,
     deleteFile, deleteFileSync, mkdir, mkdirSync, list, listSync,
 } from './fs.js';
-export type { FileStat } from './fs.js';
+export type { FileStat, FsEncoding, FsData, ReadFileOptions, WriteFileOptions } from './fs.js';
 export { assets, read as assetsRead, readSync as assetsReadSync,
-    readBase64 as assetsReadBase64, readBase64Sync as assetsReadBase64Sync,
     extract as assetsExtract, extractSync as assetsExtractSync,
     extractDir as assetsExtractDir, extractDirSync as assetsExtractDirSync } from './assets.js';
 export { path } from './path.js';
@@ -112,4 +111,4 @@ export {
     bytesToString, bytesToStringAsync,
     Gzip,
 } from './util.js';
-export type { GzipCompressor, GzipDecompressor } from './util.js';
+export type { GzipCompressor, GzipDecompressor, GzipCompressOptions, GzipDecompressOptions } from './util.js';

package/src/fs.ts

@@ -1,6 +1,21 @@
 type FsLevel = 'plugin' | 'server' | 'outer';
 
-import { stringToBytes } from './util.js';
+import { stringToBytes, bytesToString } from './util.js';
+
+/** 文件编码：utf8 = 文本；base64 = 将字符串视为 Base64 编码的二进制数据。 */
+export type FsEncoding = 'utf8' | 'base64';
+
+/** readFile 选项（Node 风格：缺省 encoding = 返回 Uint8Array）。 */
+export interface ReadFileOptions {
+  encoding?: FsEncoding;
+}
+
+/** writeFile / appendFile 选项：字符串默认 utf8；可指定 base64 将字符串视为二进制。 */
+export interface WriteFileOptions {
+  encoding?: FsEncoding;
+}
+
+export type FsData = string | Uint8Array;
 
 function _sendFs(payload: Record<string, unknown>): unknown {
   const r = $send('fs', payload);
@@ -19,46 +34,138 @@ function _sendFsAsync(payload: Record<string, unknown>): Promise<unknown> {
   });
 }
 
+/** 归一化 encoding 参数（string | { encoding }）；未知编码抛错。 */
+function _encoding(options?: FsEncoding | { encoding?: FsEncoding }): FsEncoding | undefined {
+  if (options == null) return undefined;
+  const e = typeof options === 'string' ? options : options.encoding;
+  if (e != null && e !== 'utf8' && e !== 'base64') {
+    throw new Error('Unsupported encoding: ' + String(e));
+  }
+  return e;
+}
+
+/** UTF-8 流式解码器：跨块保留不完整的多字节序列，EOF 时冲刷（非法序列替换为 U+FFFD）。 */
+function _makeUtf8StreamDecoder() {
+  let pending: Uint8Array = new Uint8Array(0);
+
+  const seqLen = (b: number) => {
+    if (b < 0x80) return 1;
+    if ((b & 0xE0) === 0xC0) return 2;
+    if ((b & 0xF0) === 0xE0) return 3;
+    if ((b & 0xF8) === 0xF0) return 4;
+    return 1; // 非法起始字节：交给 bytesToString 以替换字符处理
+  };
+
+  return {
+    push(chunk: Uint8Array): string | null {
+      const buf = pending.length
+        ? (() => { const b = new Uint8Array(pending.length + chunk.length); b.set(pending, 0); b.set(chunk, pending.length); return b; })()
+        : chunk;
+      if (!buf.length) return null;
+
+      let cut = buf.length;
+      const last = buf.length - 1;
+      if ((buf[last] & 0x80) !== 0) {
+        // 回溯找到可能的多字节序列起点（最多 3 个续字节）
+        let start = last;
+        let cont = 0;
+        while (cont < 3 && start > 0 && (buf[start] & 0xC0) === 0x80) { start--; cont++; }
+        const need = seqLen(buf[start]);
+        const have = buf.length - start;
+        if (need > 1 && have < need && need <= 4) {
+          // 仅当确实是合法起始字节时视为“序列未结束”，留给下一块
+          const validLead =
+            (need === 2 && (buf[start] & 0xE0) === 0xC0) ||
+            (need === 3 && (buf[start] & 0xF0) === 0xE0) ||
+            (need === 4 && (buf[start] & 0xF8) === 0xF0);
+          if (validLead) cut = start;
+        }
+      }
+
+      pending = cut === buf.length ? new Uint8Array(0) : buf.slice(cut);
+      const complete = cut === buf.length ? buf : buf.subarray(0, cut);
+      return complete.length ? bytesToString(complete) : null;
+    },
+    /** EOF：把剩余的不完整序列交给 Java 解码（通常产出 U+FFFD）。 */
+    flush(): string | null {
+      if (!pending.length) return null;
+      const s = bytesToString(pending);
+      pending = new Uint8Array(0);
+      return s;
+    },
+  };
+}
+
 /** 按 fs 级别（plugin/server/outer）生成全套文件操作。 */
 function _makeFs(level: FsLevel) {
   const t = (op: string) => `${level}.${op}`;
 
-  async function readFile(path: string): Promise<string> {
-    const r = await _sendFsAsync({ t: t('readFile'), p: { path } }) as { data: string };
-    return r.data;
-  }
-  function readFileSync(path: string): string {
-    return (_sendFs({ t: t('readFile'), p: { path } }) as { data: string }).data;
-  }
-
-  async function readFileBase64(path: string): Promise<string> {
-    const r = await _sendFsAsync({ t: t('readBase64'), p: { path } }) as { data: string };
-    return r.data;
-  }
-  function readFileBase64Sync(path: string): string {
-    return (_sendFs({ t: t('readBase64'), p: { path } }) as { data: string }).data;
-  }
+  // ── 读文件：默认 Uint8Array；encoding 指定后返回字符串 ──────────
+  type ReadFileFn = {
+    (path: string): Promise<Uint8Array>;
+    (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): Promise<string>;
+    (path: string, options: ReadFileOptions): Promise<Uint8Array | string>;
+  };
+  type ReadFileSyncFn = {
+    (path: string): Uint8Array;
+    (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): string;
+    (path: string, options: ReadFileOptions): Uint8Array | string;
+  };
 
-  async function writeFile(path: string, data: string): Promise<void> {
-    await _sendFsAsync({ t: t('writeFile'), p: { path, data } });
-  }
-  function writeFileSync(path: string, data: string): void {
-    _sendFs({ t: t('writeFile'), p: { path, data } });
-  }
+  const readFileImpl = async (path: string, options?: FsEncoding | ReadFileOptions): Promise<Uint8Array | string> => {
+    const enc = _encoding(options);
+    const r = await _sendFsAsync({ t: t(enc === 'utf8' ? 'readFile' : 'readBase64'), p: { path } }) as { data: string };
+    if (enc === 'utf8' || enc === 'base64') return r.data;
+    return Uint8Array.fromBase64(r.data);
+  };
+  const readFileSyncImpl = (path: string, options?: FsEncoding | ReadFileOptions): Uint8Array | string => {
+    const enc = _encoding(options);
+    const r = _sendFs({ t: t(enc === 'utf8' ? 'readFile' : 'readBase64'), p: { path } }) as { data: string };
+    if (enc === 'utf8' || enc === 'base64') return r.data;
+    return Uint8Array.fromBase64(r.data);
+  };
+  const readFile = readFileImpl as ReadFileFn;
+  const readFileSync = readFileSyncImpl as ReadFileSyncFn;
 
-  async function writeFileBase64(path: string, data: string): Promise<void> {
-    await _sendFsAsync({ t: t('writeBase64'), p: { path, data } });
-  }
-  function writeFileBase64Sync(path: string, data: string): void {
-    _sendFs({ t: t('writeBase64'), p: { path, data } });
-  }
+  // ── 写文件：string 默认 utf8（可指定 base64），Uint8Array 写原始字节 ──
+  const writeFile = async (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): Promise<void> => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') await _sendFsAsync({ t: t('writeBase64'), p: { path, data } });
+      else await _sendFsAsync({ t: t('writeFile'), p: { path, data } });
+    } else {
+      await _sendFsAsync({ t: t('writeBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
+  const writeFileSync = (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): void => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') _sendFs({ t: t('writeBase64'), p: { path, data } });
+      else _sendFs({ t: t('writeFile'), p: { path, data } });
+    } else {
+      _sendFs({ t: t('writeBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
 
-  async function appendFile(path: string, data: string): Promise<void> {
-    await _sendFsAsync({ t: t('appendFile'), p: { path, data } });
-  }
-  function appendFileSync(path: string, data: string): void {
-    _sendFs({ t: t('appendFile'), p: { path, data } });
-  }
+  // ── 追加：与 writeFile 相同的数据/编码语义 ────────────────────────
+  const appendFile = async (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): Promise<void> => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') await _sendFsAsync({ t: t('appendBase64'), p: { path, data } });
+      else await _sendFsAsync({ t: t('appendFile'), p: { path, data } });
+    } else {
+      await _sendFsAsync({ t: t('appendBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
+  const appendFileSync = (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): void => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') _sendFs({ t: t('appendBase64'), p: { path, data } });
+      else _sendFs({ t: t('appendFile'), p: { path, data } });
+    } else {
+      _sendFs({ t: t('appendBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
 
   async function exists(path: string): Promise<boolean> {
     const r = await _sendFsAsync({ t: t('exists'), p: { path } });
@@ -123,19 +230,47 @@ function _makeFs(level: FsLevel) {
     return (_sendFs({ t: t('getServerPath') }) as { path: string }).path;
   }
 
-  async function createReadStream(path: string, options?: ReadStreamOptions): Promise<ReadStream> {
-    const r = await _sendFsAsync({ t: t('openRead'), p: { path, ...options } }) as { id: string };
-    return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id);
-  }
+  // ── 读流：encoding 在创建时固定（默认 Uint8Array；utf8/base64 → string）──
+  type CreateReadStreamFn = {
+    (path: string): Promise<ReadStream<Uint8Array>>;
+    (path: string, options: ReadStreamOptions & { encoding?: undefined }): Promise<ReadStream<Uint8Array>>;
+    (path: string, options: ReadStreamOptions & { encoding: FsEncoding }): Promise<ReadStream<string>>;
+    (path: string, options: ReadStreamOptions): Promise<ReadStream<Uint8Array> | ReadStream<string>>;
+  };
 
+  const createReadStreamImpl = async (path: string, options?: ReadStreamOptions): Promise<ReadStream<Uint8Array> | ReadStream<string>> => {
+    const enc = _encoding(options);
+    const r = await _sendFsAsync({ t: t('openRead'), p: { path, start: options?.start, end: options?.end } }) as { id: string };
+    if (enc === 'base64') {
+      return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, {
+        push: (b64: string) => b64,
+        flush: () => null,
+      });
+    }
+    if (enc === 'utf8') {
+      const dec = _makeUtf8StreamDecoder();
+      return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, {
+        push: (b64: string) => dec.push(Uint8Array.fromBase64(b64)),
+        flush: () => dec.flush(),
+      });
+    }
+    return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, {
+      push: (b64: string) => Uint8Array.fromBase64(b64),
+      flush: () => null,
+    });
+  };
+  const createReadStream = createReadStreamImpl as CreateReadStreamFn;
+
+  // ── 写流：与 writeFile 相同的数据/编码语义（encoding 创建时固定）──
   async function createWriteStream(path: string, options?: WriteStreamOptions): Promise<WriteStream> {
-    const r = await _sendFsAsync({ t: t('openWrite'), p: { path, ...options } }) as { id: string };
-    return _makeWriteStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id);
+    const enc = _encoding(options);
+    const r = await _sendFsAsync({ t: t('openWrite'), p: { path, flags: options?.flags } }) as { id: string };
+    return _makeWriteStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, enc);
   }
 
   return {
-    readFile, readFileSync, readFileBase64, readFileBase64Sync,
-    writeFile, writeFileSync, writeFileBase64, writeFileBase64Sync,
+    readFile, readFileSync,
+    writeFile, writeFileSync,
     appendFile, appendFileSync,
     exists, existsSync, stat, statSync,
     isDirectory, isDirectorySync,
@@ -157,12 +292,8 @@ export const fs = {
 // 顶层函数 = plugin 级别（与 fs.* 一致）
 export const readFile = fs.readFile;
 export const readFileSync = fs.readFileSync;
-export const readFileBase64 = fs.readFileBase64;
-export const readFileBase64Sync = fs.readFileBase64Sync;
 export const writeFile = fs.writeFile;
 export const writeFileSync = fs.writeFileSync;
-export const writeFileBase64 = fs.writeFileBase64;
-export const writeFileBase64Sync = fs.writeFileBase64Sync;
 export const appendFile = fs.appendFile;
 export const appendFileSync = fs.appendFileSync;
 export const exists = fs.exists;
@@ -182,15 +313,17 @@ export const createWriteStream = fs.createWriteStream;
 
 // ── 流式读写（有状态句柄；背压 = 显式响应——每个操作 await 结果后才发起下一块）──
 
-/** 读流选项：字节偏移区间（start 含、end 含；缺省 = 全文件）。 */
+/** 读流选项：字节偏移区间（start 含、end 含）；encoding 创建时固定（默认 Uint8Array）。 */
 export interface ReadStreamOptions {
   start?: number;
   end?: number;
+  encoding?: FsEncoding;
 }
 
-/** 写流选项：打开模式——w 覆盖（默认）/ a 追加 / wx 排他创建（已存在报错）。 */
+/** 写流选项：打开模式 + 编码（encoding 创建时固定，运行时不可修改）。 */
 export interface WriteStreamOptions {
   flags?: 'w' | 'a' | 'wx';
+  encoding?: FsEncoding;
 }
 
 /** 文件状态（stat）。mtimeMs / ctimeMs 为 epoch 毫秒。 */
@@ -203,32 +336,39 @@ export interface FileStat {
 }
 
 /** 文件读流：read() 一次返回一块（默认 1 MiB），null = EOF；可 for await。 */
-export interface ReadStream {
-  read(maxBytes?: number): Promise<Uint8Array | null>;
+export interface ReadStream<Chunk = Uint8Array> {
+  read(maxBytes?: number): Promise<Chunk | null>;
   close(): Promise<void>;
-  [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+  [Symbol.asyncIterator](): AsyncIterator<Chunk>;
 }
 
 /** 文件写流：write(chunk) 等到写入完成（显式响应背压），end() 冲刷并关闭。 */
 export interface WriteStream {
+  /** 创建时固定的编码；未指定时字符串 chunk 按 UTF-8 编码。运行时不可修改。 */
+  readonly encoding?: FsEncoding;
   write(chunk: Uint8Array | string): Promise<void>;
   /** 冲刷缓冲并关闭（调用后不可再 write）。 */
   end(): Promise<void>;
   close(): Promise<void>;
 }
 
-function _makeReadStream(
+function _makeReadStream<Chunk>(
   op: (name: string, p: Record<string, unknown>) => Promise<unknown>,
   id: string,
-): ReadStream {
+  decoder: { push(b64: string): Chunk | null; flush(): Chunk | null },
+): ReadStream<Chunk> {
   let closed = false;
   const check = () => { if (closed) throw new Error('read stream closed'); };
   return {
-    async read(maxBytes?: number) {
+    async read(maxBytes?: number): Promise<Chunk | null> {
       check();
-      const r = await op('read', { id, maxBytes }) as { data?: string; eof?: boolean };
-      if (r.eof) return null;
-      return Uint8Array.fromBase64(r.data as string);
+      while (true) {
+        const r = await op('read', { id, maxBytes }) as { data?: string; eof?: boolean };
+        if (r.eof) return decoder.flush();
+        const chunk = decoder.push(r.data as string);
+        // UTF-8 解码器可能因跨块多字节序列暂未产出——继续读下一块
+        if (chunk !== null) return chunk;
+      }
     },
     async close() {
       if (closed) return;
@@ -248,14 +388,19 @@ function _makeReadStream(
 function _makeWriteStream(
   op: (name: string, p: Record<string, unknown>) => Promise<unknown>,
   id: string,
+  encoding?: FsEncoding,
 ): WriteStream {
   let closed = false;
   const check = () => { if (closed) throw new Error('write stream closed'); };
+  const toBytes = (chunk: Uint8Array | string): Uint8Array => {
+    if (typeof chunk !== 'string') return chunk; // Uint8Array 始终按原始字节写入
+    return encoding === 'base64' ? Uint8Array.fromBase64(chunk) : stringToBytes(chunk);
+  };
   return {
+    encoding,
     async write(chunk: Uint8Array | string) {
       check();
-      const data = typeof chunk === 'string' ? stringToBytes(chunk) : chunk;
-      await op('write', { id, data: data.toBase64() });
+      await op('write', { id, data: toBytes(chunk).toBase64() });
     },
     async end() {
       check();

package/src/util.ts

@@ -73,28 +73,48 @@ export interface GzipDecompressor {
   close(): Promise<void>;
 }
 
+/** 压缩选项：level 0-9（默认引擎默认级别）；raw = 原始 deflate（无 GZIP 头/尾/CRC）。 */
+export interface GzipCompressOptions {
+  level?: number;
+  raw?: boolean;
+}
+
+/** 解压选项：raw = 原始 deflate（无 GZIP 头/尾/CRC 校验）。 */
+export interface GzipDecompressOptions {
+  raw?: boolean;
+}
+
+/** 兼容旧式数字 level 参数：Gzip.compress(data, 6) 仍可用。 */
+type LevelArg = number | GzipCompressOptions | undefined;
+
+function normalizeOptions(o?: LevelArg): GzipCompressOptions {
+  return typeof o === 'number' ? { level: o } : (o ?? {});
+}
+
 export const Gzip = {
-  /** 一次性 gzip 压缩（level 0-9，默认引擎默认级别）。输入 string 视为 UTF-8 文本。 */
-  compress(data: Uint8Array | string, level?: number): Promise<Uint8Array> {
-    return sendAsync<{ data: string }>('gzip.compress', { data: toB64(data), level })
+  /** 一次性压缩（level 0-9；raw=true 输出原始 deflate 流）。输入 string 视为 UTF-8 文本。 */
+  compress(data: Uint8Array | string, options?: LevelArg): Promise<Uint8Array> {
+    const o = normalizeOptions(options);
+    return sendAsync<{ data: string }>('gzip.compress', { data: toB64(data), level: o.level, raw: o.raw })
       .then((r) => Uint8Array.fromBase64(r.data));
   },
-  /** 一次性 gzip 压缩（同步版）。 */
-  compressSync(data: Uint8Array | string, level?: number): Uint8Array {
-    return Uint8Array.fromBase64(send<{ data: string }>('gzip.compress', { data: toB64(data), level }).data);
+  /** 一次性压缩（同步版）。 */
+  compressSync(data: Uint8Array | string, options?: LevelArg): Uint8Array {
+    const o = normalizeOptions(options);
+    return Uint8Array.fromBase64(send<{ data: string }>('gzip.compress', { data: toB64(data), level: o.level, raw: o.raw }).data);
   },
-  /** 一次性 gzip 解压（输出上限 256 MiB，超限报错——防压缩炸弹；上限可在 config.yml util 段调整）。 */
-  decompress(data: Uint8Array | string): Promise<Uint8Array> {
-    return sendAsync<{ data: string }>('gzip.decompress', { data: toB64(data) })
+  /** 一次性解压（输出上限 256 MiB，超限报错——防压缩炸弹；上限可在 config.yml util 段调整）。 */
+  decompress(data: Uint8Array | string, options?: GzipDecompressOptions): Promise<Uint8Array> {
+    return sendAsync<{ data: string }>('gzip.decompress', { data: toB64(data), raw: options?.raw })
       .then((r) => Uint8Array.fromBase64(r.data));
   },
-  /** 一次性 gzip 解压（同步版）。 */
-  decompressSync(data: Uint8Array | string): Uint8Array {
-    return Uint8Array.fromBase64(send<{ data: string }>('gzip.decompress', { data: toB64(data) }).data);
+  /** 一次性解压（同步版）。 */
+  decompressSync(data: Uint8Array | string, options?: GzipDecompressOptions): Uint8Array {
+    return Uint8Array.fromBase64(send<{ data: string }>('gzip.decompress', { data: toB64(data), raw: options?.raw }).data);
   },
   /** 创建分块压缩器（流式管道）：create → write×n → finish → close。 */
-  async createCompressor(options?: { level?: number }): Promise<GzipCompressor> {
-    const r = await sendAsync<{ id: string }>('gzip.compressor.create', { level: options?.level });
+  async createCompressor(options?: GzipCompressOptions): Promise<GzipCompressor> {
+    const r = await sendAsync<{ id: string }>('gzip.compressor.create', { level: options?.level, raw: options?.raw });
     let closed = false;
     const check = () => { if (closed) throw new Error('compressor closed'); };
     return {
@@ -116,8 +136,8 @@ export const Gzip = {
     };
   },
   /** 创建分块解压器（流式管道）：create → write×n → finish → close。 */
-  async createDecompressor(): Promise<GzipDecompressor> {
-    const r = await sendAsync<{ id: string }>('gzip.decompressor.create', {});
+  async createDecompressor(options?: GzipDecompressOptions): Promise<GzipDecompressor> {
+    const r = await sendAsync<{ id: string }>('gzip.decompressor.create', { raw: options?.raw });
     let closed = false;
     const check = () => { if (closed) throw new Error('decompressor closed'); };
     return {