diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasPanelView.tsx b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasPanelView.tsx
index abb2dedf2..b12154f4b 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasPanelView.tsx
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasPanelView.tsx
@@ -6,7 +6,9 @@ import type { ResourceCanvasPanelEntry } from './resourceCanvasAssetTransferMode
 /** 预览位占位文案：预览失败 → 载入中 → 退回素材类型名。 */
 function previewPlaceholder(entry: ResourceCanvasPanelEntry) {
   if (entry.previewStatus === 'failed') {
-    return '预览失败';
+    return entry.previewError?.trim()
+      ? `预览失败：${entry.previewError.trim()}`
+      : '预览失败：未提供具体错误正文';
   }
   if (entry.previewStatus === 'loading') {
     return '载入中…';
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index fd7274dc5..49d0ea922 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -16,6 +16,8 @@
 - **验证**：`conversationModelSelect.test.tsx` 29 passed；`uiEditorModel.test.ts` 2 passed；`llm_catalog::tests::catalog_missing_data_preserves_protocol_detail` passed；TypeScript 检查通过。
 - **关联**：`features/project-workspace/ConversationModelSelect.tsx`、`src-tauri/src/llm_catalog.rs`、`view/ui-editor/model.ts`。
 
+资源画布预览失败态也必须优先显示 `previewError`；只有宿主确实没有正文时才显示“未提供具体错误正文”，不能把已有的读取、解码或权限原因改成单独的“预览失败”。
+
 ## 2026-10-03 AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过
 
 - **现象**：Windows 本机 `npm run check:generated-bindings`（`npm run lint` 链内，`scripts/check-repository-ci.sh` 的 Repository checks 也走它）在 `build.rs:167:29` panic：`插件随包资源校验失败：随包插件存在未声明文件：.../src-tauri/resources/plugins/agc-godot-editor/native/gdextension/bin/win-x64/agc_godot_editor.dll（目标 x86_64-pc-windows-msvc 与当前 feature 组合不允许；请先执行随包资源准备步骤）`；树上换成 `agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe` 时报同一类错。反向还有更隐蔽的形态：门禁 2 秒就 exit 0 说「通过」，但 tree 上其实带着编辑器产物。