From aff50317cb3bc2b57f86bbf3c006aadc49a864af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=BD=95=E5=86=A0=E5=B3=B0?= <33317070@qq.com>
Date: Thu, 28 May 2026 10:37:42 +0800
Subject: [PATCH] feat : add IBuiltinFileAccessor

---
 .../FileSystem/EFileSystemParameter.cs        |  5 +++
 .../BuiltinFileSystem/BuiltinFileSystem.cs    |  9 +++++
 .../internal/CopyBuiltinFileOperation.cs      | 37 ++++++++++++++++---
 .../Interfaces/IBuiltinFileAccessor.cs        | 24 ++++++++++++
 .../Interfaces/IBuiltinFileAccessor.cs.meta   | 11 ++++++
 5 files changed, 80 insertions(+), 6 deletions(-)
 create mode 100644 Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs
 create mode 100644 Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs.meta

diff --git a/Assets/YooAsset/Runtime/FileSystem/EFileSystemParameter.cs b/Assets/YooAsset/Runtime/FileSystem/EFileSystemParameter.cs
index 717948bd..5eb56c64 100644
--- a/Assets/YooAsset/Runtime/FileSystem/EFileSystemParameter.cs
+++ b/Assets/YooAsset/Runtime/FileSystem/EFileSystemParameter.cs
@@ -145,5 +145,10 @@ namespace YooAsset
         /// 内置资源包解包策略 <see cref="IBundleUnpackPolicy"/>
         /// </summary>
         BundleUnpackPolicy,
+
+        /// <summary>
+        /// 内置文件访问器 <see cref="IBuiltinFileAccessor"/>
+        /// </summary>
+        BuiltinFileAccessor,
     }
 }
\ No newline at end of file
diff --git a/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/BuiltinFileSystem.cs b/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/BuiltinFileSystem.cs
index 270b443e..c5e99b9b 100644
--- a/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/BuiltinFileSystem.cs
+++ b/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/BuiltinFileSystem.cs
@@ -145,6 +145,11 @@ namespace YooAsset
         /// 自定义参数：内置资源包解包策略
         /// </summary>
         internal IBundleUnpackPolicy BundleUnpackPolicy { get; private set; }
+
+        /// <summary>
+        /// 自定义参数：内置文件访问器
+        /// </summary>
+        internal IBuiltinFileAccessor BuiltinFileAccessor { get; private set; }
         #endregion
 
         /// <summary>
@@ -293,6 +298,10 @@ namespace YooAsset
             {
                 BundleUnpackPolicy = FileSystemHelper.CastParameter<IBundleUnpackPolicy>(paramName, value);
             }
+            else if (paramName == nameof(EFileSystemParameter.BuiltinFileAccessor))
+            {
+                BuiltinFileAccessor = FileSystemHelper.CastParameter<IBuiltinFileAccessor>(paramName, value);
+            }
             else
             {
                 throw new ArgumentException($"Unrecognized parameter name: '{paramName}'.", nameof(paramName));
diff --git a/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/Operations/internal/CopyBuiltinFileOperation.cs b/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/Operations/internal/CopyBuiltinFileOperation.cs
index 9b56beb0..22b09d9a 100644
--- a/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/Operations/internal/CopyBuiltinFileOperation.cs
+++ b/Assets/YooAsset/Runtime/FileSystem/Services/BuiltinFileSystem/Operations/internal/CopyBuiltinFileOperation.cs
@@ -13,7 +13,8 @@ namespace YooAsset
             None,
             CheckFileExist,
             TryCopyFile,
-            UnpackFile,
+            TryCopyByAccessor,
+            TryCopyByRequest,
             Done,
         }
 
@@ -55,6 +56,8 @@ namespace YooAsset
 
             if (_steps == ESteps.TryCopyFile)
             {
+                // 注意：Android/OpenHarmony 平台 File.Exists 无法识别包体内文件。
+                // 该步骤仅对 StreamingAssets 为真实文件系统目录的平台（Windows/iOS/Mac）生效。
                 if (File.Exists(_sourceFilePath))
                 {
                     try
@@ -66,21 +69,43 @@ namespace YooAsset
                     }
                     catch (Exception ex)
                     {
-                        YooLogger.LogWarning($"Failed to copy builtin file: {ex.Message}.");
-                        _steps = ESteps.UnpackFile;
+                        _steps = ESteps.Done;
+                        SetError($"Failed to copy builtin file: {ex.Message}.");
+                        YooLogger.LogError(Error);
                     }
                 }
                 else
                 {
-                    _steps = ESteps.UnpackFile;
+                    if (_fileSystem.BuiltinFileAccessor != null)
+                        _steps = ESteps.TryCopyByAccessor;
+                    else
+                        _steps = ESteps.TryCopyByRequest;
                 }
             }
 
-            if (_steps == ESteps.UnpackFile)
+            if (_steps == ESteps.TryCopyByAccessor)
+            {
+                try
+                {
+                    FileUtility.EnsureParentDirectoryExists(_destFilePath);
+                    byte[] data = _fileSystem.BuiltinFileAccessor.ReadAllBytes(_sourceFilePath);
+                    File.WriteAllBytes(_destFilePath, data);
+                    _steps = ESteps.Done;
+                    SetResult();
+                }
+                catch (Exception ex)
+                {
+                    _steps = ESteps.Done;
+                    SetError($"Failed to copy builtin file by accessor: {ex.Message}.");
+                    YooLogger.LogError(Error);
+                }
+            }
+
+            if (_steps == ESteps.TryCopyByRequest)
             {
                 if (_downloadFileRequest == null)
                 {
-                    // TODO: 团结引擎，在某些安卓机型（红米），通过UnityWebRequest拷贝包内文件会小概率失败！需要借助其它方式来拷贝包内文件。
+                    // TODO: 团结引擎，在某些安卓机型（红米），通过UnityWebRequest拷贝包内文件会小概率失败。
                     string url = DownloadUrlHelper.ToLocalFileUrl(_sourceFilePath);
                     var args = new DownloadFileRequestArgs(
                         url: url,
diff --git a/Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs b/Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs
new file mode 100644
index 00000000..48a414f4
--- /dev/null
+++ b/Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs
@@ -0,0 +1,24 @@
+
+namespace YooAsset
+{
+    /// <summary>
+    /// 内置文件访问器接口，提供对 StreamingAssets 目录的直接访问能力。
+    /// </summary>
+    /// <remarks>
+    /// Android 平台，可通过第三方库（如 BetterStreamingAssets）实现该接口，提供同步文件读取能力。</para>
+    /// </remarks>
+    public interface IBuiltinFileAccessor
+    {
+        /// <summary>
+        /// 检查内置文件是否存在
+        /// </summary>
+        /// <param name="filePath">内置文件路径</param>
+        bool FileExists(string filePath);
+
+        /// <summary>
+        /// 读取内置文件的所有字节
+        /// </summary>
+        /// <param name="filePath">内置文件路径</param>
+        byte[] ReadAllBytes(string filePath);
+    }
+}
diff --git a/Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs.meta b/Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs.meta
new file mode 100644
index 00000000..3f93499e
--- /dev/null
+++ b/Assets/YooAsset/Runtime/Interfaces/IBuiltinFileAccessor.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 0942e034de20eff458c1fdb0ab745fda
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: