docs: document global resource library

docs/source-analysis.html

@@ -669,6 +669,11 @@ api/main.py
             <div><strong>主要源码</strong><span><code>AudioStoryboardPlanPanel</code>、<code>ProductReferenceCard</code>、<code>MissingProductViewSlot</code>、<code>buildAudioStoryboardRows</code>、<code>selectProductItemsForRow</code>、<code>subjectAssetRefsForPlanning</code>、<code>subjectBriefForEndpoint</code>、<code>endpointAssetRef</code>、<code>buildEndpointFramePrompt</code>、<code>buildStoryboardSceneFromAudioRow</code>、<code>generateEndpointFrameForRow</code>、<code>saveRowStoryboardDraft</code>、<code>saveAllStoryboardDrafts</code>、<code>EndpointFrameSlot</code>、<code>StoryboardVideoSlots</code> in <code>web/components/ad-recreation-board.tsx</code>；产品图、首尾帧和视频候选缩略图统一复用 <code>MediaAssetTile</code>，包括顶层 hover 放大和删除入口。产品白底图上传复用 <code>uploadStoryboardAsset</code>，视角自动识别调用 <code>analyzeProductViews</code>，缺角度自动补图调用 <code>generateProductAngleAsset</code>。当前单条/批量按钮只保存规划；首尾帧按钮调用 <code>generateSceneAsset</code>，传 <code>subject_brief</code> 和端点选择后的 1-2 张 <code>product_images</code>，不再传主体图或 contact sheet，再用 <code>PUT /frames/{idx}/storyboard</code> 保存 asset 首尾帧引用；首尾帧删除只移除本条规划中的引用，避免继续误用旧资产。语言策略由 <code>AudioStoryboardRow</code> 的英文主字段 + <code>*Zh</code> 镜像字段承载：<code>role</code> 内部是 <code>hook/pain/proof/solution/cta/bridge</code>，<code>buildEndpointFramePrompt</code> 和 <code>StoryboardScene</code> 主值默认英文，中文只用于团队阅读；首尾帧提交前前端 <code>translateText</code> 兜底，后端 <code>_ensure_english</code> 再兜底。<code>web/app/page.tsx</code> 的视频提交回调有暂停保护，旧入口误触也不会请求 <code>/storyboard/video</code>。</span></div>
             <div><strong>适合怎么描述</strong><span>“按音频逐句生成产品分镜、每行怎样改写口播、哪几句不需要产品或人物、首帧/尾帧该怎么停、首尾帧是否已经生成并准确、产品素材池识别/补图后的备注是否准确、哪些分镜后续才值得进入单条视频候选”。</span></div>
           </div>
+          <div class="flow-row">
+            <div><strong>你看到的区域</strong><span>全局资源中心浮窗</span></div>
+            <div><strong>主要源码</strong><span><code>LibraryDrawer</code> in <code>web/components/resource-library/library-drawer.tsx</code>；入口、保存到库和应用回写在 <code>AdRecreationBoard</code>、<code>AudioStoryboardPlanPanel</code>、<code>ProductReferenceCard</code>、<code>EndpointFrameSlot</code>；前端接口在 <code>web/lib/api.ts</code>；后端目录扫描、索引、CRUD、删除保护和复制到 job 在 <code>api/main.py</code>。</span></div>
+            <div><strong>适合怎么描述</strong><span>“资源库浮窗的尺寸/位置/Tab 记忆、提示词 5 列、素材 4 列、最近 24 小时条、复制提示词、素材应用到当前 job、保存产品/首尾帧/规划 prompt 到库、删除前引用确认、节点不能拖动这些交互要怎么改”。</span></div>
+          </div>
           <div class="flow-row">
             <div><strong>你看到的区域</strong><span>旧深度素材面板（当前不作为主路径）</span></div>
             <div><strong>主要源码</strong><span><code>FrameLightbox</code>；按“原图/清洗、主体资产、首尾帧、产品融合、审核”五个页签组织；左侧只放主图/框选画布，但主体资产页左侧改为全部已清洗/已选参考帧网格，首尾帧页左侧显示全部关键帧并可勾选人物/机位参考。主体识别页会显示透明骨架人目标和 Vision 验收分数。清洗页右侧支持一键清洗未处理帧、单张替换清洗版和一键替换全部待应用清洗版；批量替换顺序调用 <code>applyCleanedFrame</code>，不新增后端接口。产品融合页左侧是纵向 6 行镜头工作表：顶部选择 5 个内置透明骨架人角色之一，并常驻显示桌面四张真实 SKG 产品角度图；每行只显示已预填场景/产品使用/享受描述、秒数、生成按钮和可横向追加的视频历史结果，产品图和结果视频都支持鼠标停留放大预览。描述词内置 36 条镜头语言模板，按“建立出场、产品入画、佩戴贴合、使用感受、生活延展、收尾记忆”排列，并且会按角色自动改写场景气质、使用动作和享受状态。每行还内置角色参考图调度：例如正面/半身用于出场，侧面/背部特写用于佩戴贴合，半身/背部特写用于收尾产品记忆点。点击“换一组”只刷新 6 行描述词。四张桌面 SKG 产品图是真实产品真源，所选角色 7 张参考图是人物身份参考，生成时分别通过 <code>copyProductLibraryAsset</code> 与 <code>copyCharacterLibraryAssets</code> 自动写入当前 job；视频 prompt 要求产品作为外置刚性实物合成到后颈外侧，禁止穿模、融进透明身体或重绘产品。不再暴露产品角度槽、产品融合辅助栏、产品图库选择器或首尾帧槽。主体资产页只确认一个统一主体，后端按参考重绘六张纯背景、占满画面的标准站立透明骨架人资产图；首尾帧页保留给旧流程/单独生图，不再是产品融合必填步骤。相关接口包括 <code>cleanupFrame</code>、<code>applyCleanedFrame</code>、<code>addElement</code>、<code>generateSubjectAssets</code>、<code>generateSceneAsset</code>、<code>copyProductLibraryAsset</code> 和 <code>copyCharacterLibraryAssets</code>。</span></div>
@@ -802,6 +807,46 @@ SubjectAsset {
   white_score,
   source_path,
   tags[]
+}</pre>
+          </div>
+          <div class="card">
+            <h3>PromptLibraryItem / AssetLibraryItem</h3>
+            <p>全局资源中心的数据模型。提示词库只保存文本和中英镜像，发给模型时使用 <code>prompt_en</code>；素材库保存主体、产品、场景和视频四类全局资源。库目录和 job 目录完全平级，索引文件只是缓存，服务启动会扫描目录重建。素材应用到 job 时永远复制文件，返回普通 <code>ImageRef(kind="asset")</code> 或 job 内视频引用，不把 <code>library_*</code> 引用写入 job state。</p>
+            <pre>PromptLibraryItem {
+  id,
+  category: scene_desc | video_desc | subject_desc | skg_script | product_angle,
+  name,
+  tags[],
+  prompt_en,
+  prompt_zh,
+  use_count,
+  source_job_id,
+  created_at,
+  updated_at
+}
+
+AssetLibraryItem {
+  id,
+  kind: subjects | products | scenes | videos,
+  name,
+  name_zh,
+  note,
+  tags[],
+  source_job_id,
+  use_count,
+  created_at,
+  updated_at,
+  is_official,
+  prompt_brief,
+  prompt_brief_zh,
+  subject_style,
+  product_type,
+  asset_role,
+  duration,
+  aspect_ratio,
+  images: AssetLibraryImage[],
+  poster,
+  video_url
 }</pre>
           </div>
           <div class="card">
@@ -933,6 +978,9 @@ ProductRefStateItem {
             <tr><td>产品缺角度补图</td><td><code>POST /jobs/{id}/assets/product-angle</code></td><td><code>generateProductAngleAsset</code></td><td>用当前同一产品素材池作为参考，通过 <code>gpt-image-2</code> 自动补全缺失视角，输出新的 <code>ImageRef(kind="asset")</code>。前端不再固定传第一张图，而是按目标视角给已上传/已标注参考图打分，优先选择真实上传图、目标相邻视角、侧厚/触点/底部对应用途标签和低风险高置信图，最多传 6 张；后端通过 <code>/images/edits</code> multipart 的多张 <code>image[]</code> 直接提交给 <code>gpt-image-2</code>，不再把参考图拼成一张板，降低模型误解成拼图/多产品的概率。Prompt 会约束白底产品图、左右非对称、厚度、内侧触点和肩颈真实佩戴比例，并禁止输出拼图/多产品；遇到上游 429 / saturated 会按退避节奏重试，最终仍失败时返回 503 和可读提示；遇到 DNS / ConnectError 也返回 503，并提示配置 <code>AI_HTTP_PROXY</code> / <code>IMAGE_HTTP_PROXY</code>。</td></tr>
             <tr><td>角色库</td><td><code>GET /character-library/skg</code></td><td><code>listCharacterLibrary</code></td><td>读取内置 5 个透明骨架人角色 manifest，每个角色含正面、左右 45 度、侧面、背面、半身近景和背部特写 7 张参考图，以及用于相似主体文字生图的 <code>prompt_brief</code>。</td></tr>
             <tr><td>主体模板库</td><td><code>GET /subject-templates</code><br><code>GET /subject-templates/images/{filename}</code><br><code>POST /jobs/{id}/subject-templates</code></td><td><code>listSubjectTemplates</code><br><code>subjectTemplateImageUrl</code><br><code>saveSubjectTemplate</code></td><td>数据库化可复用主体库。前端模板库展示这里保存的主体模板；“保存为主体模板”会把当前 job 的相似主体白底视图按名称、备注、主体类型、原 job/frame/element 和 asset 列表复制到 <code>JOBS_DIR/_subject_templates</code>，并由后端用 Vision LLM 从这些图反推 <code>prompt_brief</code>。以后相似生成通过 <code>subject_template_id</code> 读取这个 brief 作为文字创意方向，不再把模板图直接上传给 image-edit。</td></tr>
+            <tr><td>全局提示词库</td><td><code>GET /prompt-library</code><br><code>GET /prompt-library/{id}</code><br><code>POST /prompt-library</code><br><code>PATCH /prompt-library/{id}</code><br><code>DELETE /prompt-library/{id}</code><br><code>POST /prompt-library/{id}/use</code></td><td><code>listPromptLibrary</code><br><code>createPromptLibraryItem</code><br><code>usePromptLibraryItem</code><br><code>deletePromptLibraryItem</code></td><td>浮窗提示词 Tab 的 5 类文本资源。<code>prompt_en</code> 是实际复制/提交给模型的英文主值，<code>prompt_zh</code> 只给团队阅读；点击复制会调用 <code>/use</code> 增加使用次数。节点位置由前端按“常用 + 月份倒序”硬编码排列，不接受拖拽或自定义排序。</td></tr>
+            <tr><td>全局素材库</td><td><code>GET /asset-library/{kind}</code><br><code>GET /asset-library/{kind}/{id}</code><br><code>POST /asset-library/{kind}</code><br><code>PATCH /asset-library/{kind}/{id}</code><br><code>GET /asset-library/{kind}/{id}/refs</code><br><code>DELETE /asset-library/{kind}/{id}?force=true</code><br><code>POST /asset-library/{kind}/{id}/copy-to-job/{job_id}</code><br><code>GET /asset-library/{kind}/{id}/file/{filename}</code></td><td><code>listAssetLibrary</code><br><code>createAssetLibraryItem</code><br><code>getAssetLibraryRefs</code><br><code>deleteAssetLibraryItem</code><br><code>copyAssetLibraryToJob</code></td><td>素材库四类 <code>subjects/products/scenes/videos</code>。应用到当前 job 时后端复制文件到 <code>jobs/&lt;jobId&gt;/assets</code> 或 <code>storyboard-videos</code> 并增加 <code>use_count</code>，前端只写普通 job 内引用。删除前必须先查 <code>/refs</code>；被 job 引用时不带 <code>force=true</code> 返回 409，强删会把库目录移动到 <code>_trash/asset_library</code>。</td></tr>
+            <tr><td>最近资源</td><td><code>GET /resource-library/recent?hours=24</code></td><td><code>getResourceLibraryRecent</code></td><td>资源中心顶部最近 24 小时横条，混合返回提示词和素材节点。它只做快速定位和新资源提醒，不改变提示词/素材两套库的独立数据边界。</td></tr>
             <tr><td>角色图入库到 job</td><td><code>POST /jobs/{id}/assets/character-library</code></td><td><code>copyCharacterLibraryAssets</code></td><td>把所选角色的 7 张参考图复制为当前 job asset，返回 <code>subject_images</code>，产品融合生成视频时作为人物身份参考图提交。</td></tr>
             <tr><td>产品融合引导图</td><td><code>POST /jobs/{id}/product-fusion/guide</code></td><td><code>createProductFusionGuide</code></td><td>旧流程兼容接口：读取产品图和白底人物图，按 <code>product_region</code> 合成位置引导图。当前内置角色 + 产品 + 描述流程不再主动调用它。</td></tr>
             <tr><td>产品融合描述词</td><td><code>POST /jobs/{id}/product-fusion/descriptions</code></td><td><code>generateProductFusionDescriptions</code></td><td>兼容接口：可生成产品融合动作描述库。当前前端默认直接用本地 36 条镜头语言模板预填 6 行镜头，并通过“换一组”按钮按 6 条一组轮换。</td></tr>
@@ -993,6 +1041,7 @@ ProductRefStateItem {
               <li>分镜工作台 4 图槽和改造说明自动保存。</li>
               <li>音频文案轨：点击开始或提取音频后提取原文案、中文翻译、讲话人、语速节奏、背景音乐/环境声/音效；结果集中在右侧工作表展示。</li>
               <li>GPT Image 生图；当前 <code>IMAGE_MODEL</code> 和主体 6 视图链路默认使用 <code>gpt-image-2</code>。</li>
+              <li>全局资源中心：提示词库和素材库可从顶部“资源库”打开；提示词可复制并计数，素材应用到 job 时会复制成本 job 内普通 asset。</li>
             </ul>
           </div>
           <div class="card">
@@ -1041,6 +1090,19 @@ ProductRefStateItem {
         <h2>变更记录</h2>
         <p>这个记录不是 git log 的替代品。它记录“产品理解发生了什么变化、影响了哪些源码、你以后描述需求时该怎么说”。后续每次改功能都要补一条。</p>
         <div class="changelog">
+          <article class="change">
+            <header>
+              <h3>2026-05-18 · 新增全局资源中心和复制式跨 job 素材库</h3>
+              <span class="tag blue">API</span>
+              <span class="tag violet">UI</span>
+              <span class="tag cyan">Library</span>
+            </header>
+            <div class="body">
+              <p><strong>问题：</strong>主体、产品、首尾帧、视频候选和常用 prompt 都散落在单个 job 里，跨任务复用时容易重新上传、重新生成或误把旧 job 文件当公共引用，后续也缺少删除保护和使用次数记录。</p>
+              <p><strong>改动：</strong>后端新增和 <code>jobs/</code> 平级的 <code>asset_library/</code> 与 <code>prompt_library/</code>，服务启动扫描目录重建索引；提示词提供 CRUD、复制计数和 5 类分类；素材提供主体/产品/场景/视频四类 CRUD、引用检查、强删移入 <code>_trash/</code> 和 <code>copy-to-job</code>。前端新增 <code>LibraryDrawer</code> 浮窗，顶部“资源库”按钮打开；浮窗记忆尺寸、位置和 Tab，提示词按“常用 + 月份”分列，素材按月份分列，节点不能拖动；提示词支持一键复制英文/中文/双语，素材应用到当前 job 时只走复制模式。</p>
+              <p><strong>影响：</strong>后续保存产品图、首尾帧、主体模板和分镜 prompt 时优先进入资源中心。库素材永远不要直接写成 job 引用，必须通过 <code>POST /asset-library/{kind}/{id}/copy-to-job/{job_id}</code> 复制成普通 job asset；删除库素材前必须查 <code>/refs</code> 并让用户确认。</p>
+            </div>
+          </article>
           <article class="change">
             <header>
               <h3>2026-05-18 · 工作台视觉统一到登录页品牌语言</h3>