diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index a43bbab5d..7e2d98345 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -1,5 +1,12 @@
 # 踩坑与排障记录
 
+## AGC 素材直传的 OSS 权限必须同步到 Native shell 契约检查
+
+- **现象**：Native shell CI 在 `check:native-shells:contract` 的 HTTP scope 检查失败，尚未准备 Rust 缓存；后续导出步骤正常退出但实际跳过，导致 master 缓存产物缺组、自动镜像刷新等待。
+- **原因**：`capabilities/main.json` 已为封面与截图直传加入 `https://*.aliyuncs.com/*`，`scripts/check-native-shells.mjs` 的精确白名单仍只有五项，且误以为更新下载迁至原生 updater 后就不再需要 OSS 权限。`assetDirectUpload.ts` 仍通过 Tauri HTTP 插件执行素材直传。
+- **处理**：契约期望同步包含现有 OSS HTTPS 项，保留完整白名单精确比较；不得删除业务所需权限或改成任意 URL 放行。更新下载与素材直传是不同调用链，变更能力配置时同步检查调用方和契约。
+- **验证**：运行 `npm run check:native-shells:contract` 与 `apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts`；缓存完整性以实际 artifact 和导出日志为准，不能仅看上传 step 是否成功。
+
 ## release 安装包文件名中的编码空格不能按控制字符拒绝
 
 - **现象**：release 环境点击“下载客户端”只显示无法获取最新版本，`GET /api/client-downloads` 返回 `502 UPSTREAM_ERROR`；dev 环境正常。
diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs
index 23b20818d..5c0f8af18 100644
--- a/scripts/check-native-shells.mjs
+++ b/scripts/check-native-shells.mjs
@@ -2602,12 +2602,13 @@ function assertAiGameCreatorShellUserDevBoundary() {
         { url: 'https://*/api/*' },
         { url: 'http://localhost:*/*' },
         { url: 'http://127.0.0.1:*/*' },
+        { url: 'https://*.aliyuncs.com/*' },
       ])
   ) {
     throw new Error(
-      // 更新清单与安装包下载已改由 tauri-plugin-updater 在原生侧完成，
-      // 不再需要为 webview 的 http 插件放行 OSS 域名。
-      'AI game creator native HTTP scope must match the release, dev, custom HTTPS, and loopback API boundary',
+      // 更新清单与安装包下载由 tauri-plugin-updater 在原生侧完成；
+      // 封面与截图仍通过 webview 的 http 插件向凭证指定的 OSS 地址直传。
+      'AI game creator native HTTP scope must match the release, dev, custom HTTPS, loopback API, and OSS media upload boundary',
     );
   }