@lark-apaas/coding-steering 0.1.32-dev.5abff3b → 0.1.32-dev.942e73f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.32-dev.5abff3b",
+  "version": "0.1.32-dev.942e73f",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/design-html/skills/pptx-style-extract/SKILL.md

@@ -74,15 +74,15 @@ mkdir -p tmp/pptx-style-extract/<unique-id> && PYTHONDONTWRITEBYTECODE=1 python3
 1. 读 `<outdir>/l-out/BRIEF.md` 一次，确定待判断文件、视觉组和页型代表页；需要查候选的全部原始位置、尺寸、重复次数、透明度或近白比例时读 `asset-vision-groups.json`。没有候选图片的页无需做图片判断。
 2. 一次并行看全部 `vision-group-*.jpg` 与 `layout-sheet.png`。每张视觉组拼版都同时给出页面语境和带编号的候选卡；透明或近白候选会同时显示棋盘格和深灰底。除非拼版把图片标成 unreadable，不打开单张素材、不再读旧的 `contact-sheet` / `asset-context-sheet`。
 3. 在 `manifest.yaml` 按每个 `asset_vision_groups` 候选实例填写 `visual_kind`；同一素材在不同页型或位置可分别判断。仅在预算外候选或需要改写既有判断时追加 `asset_decisions`；位置例外写 `box: [x, y, w, h]`，同图同位置跨页型不同时再写 `layout`。可用值固定为 `logo|slogan|background|texture|icon|decorative|illustration|photo|chart|screenshot|footer-copyright|page-number|watermark|content-image|unknown`，不新造值；`package.py` 会把它映射回现有 v2 资产类型，视觉组字段不会进入最终包。
-4. 按页面语境判断用途：本 deck 自己的品牌标志才是 `logo`；客户或合作方 logo 墙、图表、截图、产品说明图是 `content-image`；非内容、非品牌的纹理和装饰图用 `decorative` 或 `illustration`；页码、水印和版权标记用对应的 omit 类值。脚本已直接保留不透明满屏背景和封面主视觉，不为它们补判断；半透明满屏叠加层仍要在视觉组中定性。拿不准的候选用 `unknown`，不要按品牌名、页码或图片数量猜用途。
+4. 按页面语境判断用途：本 deck 自己的品牌标志才是 `logo`；图表、截图、logo 墙，以及用于解释当前页具体产品、案例或信息的图片是 `content-image`；封面、目录、章节或封底中承担构图主视觉的局部图，即使是产品或摄影图，也用 `decorative` 或 `illustration` 保留为版式素材。页码、水印和版权标记用对应的 omit 类值。脚本已直接保留不透明满屏背景和封面主视觉，不为它们补判断；半透明满屏叠加层仍要在视觉组中定性。拿不准的候选用 `unknown`，不要按品牌名、页码或图片数量猜用途。
 5. 用一次 `multi_edit` 批量完成其余 TODO：风格气质，以及 `layout-controls.yaml` 中的页型/文本角色、布局模式和背景规则。普通文本槽默认 `body`，只把确实属于 `title|subtitle|header|footer` 的例外写进 `text_roles`；有 flow 与 slots 两种形态时默认保留 slots，只有样张明确需要内容随高度重排才填 `layout_modes: <页型>: flow`。不补不存在的标题、页眉或页脚。直接编辑草案，不写脚本改 YAML，也不修改 Skill 源码。
-6. `layout-controls.yaml` 的 `bg_rules:` 按**背景资产**分组（不是按页型），逐张背景填 `text_safe` / `avoid` / `pairing_rule`：看图标清视觉主体、强光斑、深色透明区，打包时自动并入用该背景的所有页型。标题、正文、关键数字、图表、卡片、时间线及其容器的外接矩形都不得压住背景主体，透明容器也不能跨进禁放区。
+6. `layout-controls.yaml` 的 `bg_rules:` 按**背景资产**分组（不是按页型），只编辑草案已有且被页型 `background:` 引用的真实图片背景；没有 `bg_rules` 就不要新增。纯色、渐变、外框、几何装饰和透明叠层不是这里的背景资产。逐张背景填 `text_safe` / `avoid` / `pairing_rule`：看图标清视觉主体、强光斑、深色透明区，打包时自动并入用该背景的所有页型。标题、正文、关键数字、图表、卡片、时间线及其容器的外接矩形都不得压住背景主体，透明容器也不能跨进禁放区。
 
 `layout-controls.yaml` 是唯一需要编辑的版式判断文件，只含 `names`、`roles`、`text_roles`、`layout_modes` 和 `bg_rules`。`layouts.yaml` 是兼容用的坐标事实——页型、坐标、字号、色值、对齐、以及各页型自带的 `role: logo` 资产槽全部直读，**不要打开或修改它**。打包时控制文件会覆盖旧文件中的同名判断区。
 
 判断口径：
 
-- **图片按用途三分**——整幅替换底图的艺术图/摄影图属**背景族**；服务于具体内容的图表、截图、产品说明图是**内容图，不进包**；剩下既不是 logo、也不服务于内容的纹理、装饰插画、色块、几何点缀是**装饰图，标 `texture` 进 assets**。不透明满屏图默认走背景；局部图和半透明满屏叠加层结合候选图与整页语境逐张定性，避免把重要装饰误当内容丢弃。首页、末页优先保留样张，但是否为 `cover` 或 `closing` 仍按页面意图判断。
+- **图片按用途三分**——整幅替换底图的艺术图/摄影图属**背景族**；服务于当前页具体内容的图表、截图、产品说明图是**内容图，不进包**；用于封面、目录、章节或封底构图的局部主视觉不解释内容，即使画面是产品或摄影图，也属**装饰图，标 `decorative` 或 `illustration` 进 assets**；其余纹理、插画、色块、几何点缀同属装饰图。不透明满屏图默认走背景；局部图和半透明满屏叠加层结合候选图与整页语境逐张定性，避免把重要装饰误当内容丢弃。首页、末页优先保留样张，但是否为 `cover` 或 `closing` 仍按页面意图判断。
 - **logo 特指这份 deck 自己的品牌标志**——看图确认是本 PPT 的品牌文字或标志图形才留 `logo`；一页若是 logo 墙（客户/合作方 logo 罗列），那些是内容图、不当风格 logo。拿不准就保留该候选并填 `unknown`，在 `gaps` 写一句；不要删除或合并 `asset_vision_groups` 条目。
 - **anchors 是事实不是结论**——草案里每条只报测到的数（覆盖率、计数、占比），没有「这套风格的特征是 X」这种断言。这一段在 design.md 里读起来像总纲，消费端会照它建全局样式，所以脚本不敢替你下结论：一条 1/8 覆盖率的元素被描述成「跨页不动」，消费端就会每页都摆它。看过重建图后，把真正是这套模板特征的那几条改写成设计要点，不是特征的直接删掉。
 - **数值只改名不改值**——草案里的坐标/色值/字号来自普查；确需推导值（CJK 行高转译、投影尺度上抬）在 manifest 写 `derived:` 声明理由，机检认声明。
@@ -130,13 +130,20 @@ Read `<pack_dir>/design.md` first, especially `## Usage`, `## Hard Rules`, color
 When generating a deck:
 
 1. Call `copy_starter_component` with `kind: "deck-stage.js"`.
-2. Build `<deck-stage width="<canvas width>" height="<canvas height>">` using the `canvas` declared in `layouts.md` — source decks are not always 16:9, and a default-sized stage shifts every coordinate on the page. Each slide is one static `<section>`.
+2. Build `<deck-stage width="<canvas width>" height="<canvas height>">` using the `canvas` declared in `layouts.md` — source decks are not always 16:9, and a default-sized stage shifts every coordinate on the page. Each slide is one static `<section data-pptx-layout="<chosen archetype>">`.
 3. Inline CSS variables from `design.md` into the HTML `<style>` block using a `--ppt-*` prefix.
 4. **位移动画用独立的 `translate` 属性**：`@keyframes fadeUp { from{opacity:0; translate:0 24px} to{opacity:1; translate:0 0} }`。`transform` 是单一属性，动画里碰它会覆盖掉元素原有的那条（`left:50%; transform:translateX(-50%)` 的居中就此丢失）；`translate` / `rotate` / `scale` 各自独立，与已有 `transform` 叠加。
 5. Map `layouts.md` slots to absolute-positioned elements inside each section: expand `box: [x,y,w,h]` mechanically to `left/top/width/height`, then apply the slot's `css` declaration string unchanged. `box` owns geometry; `css` owns all rendering style, including the template's text padding, typography, alignment, line height, letter spacing, and rotation. Do not reinterpret PPTX fields or replace slot CSS with your own type scale. A slot with `asset` is a fixed image element (logo, mark): place that asset at that box on that archetype only. Do not reflow any of this as generic web grids.
 6. Copy `<pack_dir>/assets/` into the project, for example `assets/pptx-style/<pack-name>/`, and reference those copied files with relative URLs. The scratch `tmp/pptx-style-extract/...` path must never appear in the final HTML.
 7. Use the font stacks and fallback rules from `design.md`; do not install fonts or dependencies at runtime.
-8. Run the slide preflight checks: no resource failures, no section overflow, and sampled screenshots follow the package colors, typography, layouts, assets, and Hard Rules.
+8. Before the regular slide preflight, verify every template logo against the selected archetype:
+
+   ```bash
+   PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/verify_logo_scope.py <pack_dir> <index.html> --asset-prefix <copied-assets-prefix>
+   ```
+
+   `PPTX_LOGO_SCOPE: FAIL` means remove or move every listed logo according to `layouts.md`, then rerun this command.
+9. Run the slide preflight checks: no resource failures, no section overflow, and sampled screenshots follow the package colors, typography, layouts, assets, and Hard Rules.
 
 ## Export Consumer Attachments
 

package/steering/design-html/skills/pptx-style-extract/scripts/census.py

@@ -66,6 +66,7 @@ def image_census(shape_recs, bg_images, units):
             'crop': r.get('crop'), 'placement': r.get('placement'),
             'w_pct': r.get('w_pct'), 'h_pct': r.get('h_pct'),
             'in_group': bool(r.get('group_path')), 'svg': r.get('media_svg'),
+            'visible_instance_blocked': r.get('visible_instance_blocked'),
         })
     for r in shape_recs:
         f = r.get('fill') or {}
@@ -124,6 +125,8 @@ def image_census(shape_recs, bg_images, units):
             'crop_variants': sorted(crop_sigs),
             'stitch_candidate': len(crop_sigs) > 1,
             'svg_companion': next((o.get('svg') for o in occs if o.get('svg')), None),
+            'visible_instance_blocked': any(
+                o.get('visible_instance_blocked') for o in occs),
         })
     images.sort(key=lambda i: (-i['n'], i['media']))
 
@@ -606,6 +609,8 @@ def layout_inventory(pkg, graph, shapes, bg_by_part):
     for lp in pkg.layouts:
         root = pkg.xml(lp)
         cSld = root.find('p:cSld', NS)
+        master = graph['master_of_layout'].get(lp)
+        background = bg_by_part.get(lp) or bg_by_part.get(master)
         phs = Counter()
         for r in shapes:
             if r['part'] == lp and r.get('ph'):
@@ -614,11 +619,12 @@ def layout_inventory(pkg, graph, shapes, bg_by_part):
             'part': lp,
             'name': cSld.get('name') if cSld is not None else None,
             'type_attr': root.get('type', 'cust'),
-            'master': graph['master_of_layout'].get(lp),
+            'master': master,
             'used_by_slides': graph['slides_per_layout'].get(lp, 0),
             'placeholders': dict(phs),
             'shape_n': sum(1 for r in shapes if r['part'] == lp),
-            'background': bg_by_part.get(lp),
+            'background': background,
+            'background_source': lp if bg_by_part.get(lp) else master,
             'ph_signature': _ph_signature(shapes, lp),
             'guides': [],
         })

package/steering/design-html/skills/pptx-style-extract/scripts/draft.py

@@ -648,14 +648,11 @@ def probe_image(path):
 def needs_asset_judgment(candidate):
     """局部图和半透明满屏叠加层需要看图定性；不透明满屏图按背景处理。"""
     effective_alpha = candidate.get('effective_alpha_mean')
-    if ((candidate.get('probe') or {}).get('near_blank')
-            or (effective_alpha is not None and effective_alpha < 13)):
-        return False
     if not candidate.get('fullscreen'):
         return True
     alpha = (effective_alpha if effective_alpha is not None
              else (candidate.get('probe') or {}).get('alpha_mean'))
-    return alpha is not None and alpha < OPAQUE_ENOUGH
+    return alpha is not None and 13 <= alpha < OPAQUE_ENOUGH
 
 
 def fullscreen_effective_alpha(data, outdir, shapes):
@@ -844,8 +841,8 @@ def draft_assets(d, outdir, bg_needed=(), cover_media=None, bg_under=None,
     canvas_w, canvas_h = d['canvas']['px']
     for c in kept:
         effective_am = c.get('effective_alpha_mean')
-        if (c['probe'].get('near_blank')
-                or (effective_am is not None and effective_am < 13)):
+        if (c['fullscreen'] and (c['probe'].get('near_blank')
+                                 or (effective_am is not None and effective_am < 13))):
             rejected.append((c, '近全透明（alpha 均值 %.0f/255），PPT 里看不见'
                              % (effective_am if effective_am is not None
                                 else c['probe']['alpha_mean'])))
@@ -962,6 +959,28 @@ def cover_background_media(archetypes):
                  if archetype['name'] == 'cover'), None)
 
 
+def background_decor(background, canvas):
+    """把可直接重放的 PPT 背景声明落到 layouts.md 的最底层装饰。
+
+    图片背景继续走 `background:` 资产引用；纯色和线性渐变没有可复制的素材文件，
+    但同样是页型视觉的一部分，必须随页型输出。path 渐变不能由 CSS 线性渐变准确表达，
+    保留给图片/渲染链路而不伪造。
+    """
+    if not isinstance(background, dict):
+        return None
+    if background.get('type') not in ('solid', 'gradient'):
+        return None
+    if background.get('path'):
+        return None
+    css = _load_query()._recipe_css(background, None, [], [])
+    css = [re.sub(r'\s*\n\s*', ' ', value).strip() for value in css if value]
+    if not css:
+        return None
+    width, height = canvas
+    return {'box': [0, 0, width, height], 'geom': 'rect', 'css': '; '.join(css),
+            'trace': 'canvas-background'}
+
+
 # ---------------------------------------------------------------- 版式聚类
 DECOR_MIN = 40.0
 
@@ -1273,7 +1292,17 @@ def layouts_from_template(d, shapes, cW, cH):
             slots, bgm = instance_override(
                 shapes, inst, slots, bgm, cW, cH, composites)
         taken = {tuple(s['box']) for s in slots}
-        decor = collect_decor(shapes, inst or l['part'], taken, (cW, cH))
+        decor = []
+        inherited_background = l.get('background')
+        direct_background = next(
+            (slide.get('background') for slide in d.get('slides') or []
+             if slide.get('part') == inst and slide.get('background')),
+            None)
+        background = direct_background or inherited_background
+        background_layer = background_decor(background, (cW, cH))
+        if background_layer:
+            decor.append(background_layer)
+        decor += collect_decor(shapes, inst or l['part'], taken, (cW, cH))
         named_role = role_of_name(l.get('name'))
         rows.append({'zh': clean_layout_name(l.get('name')),
                      'role': named_role or 'content', 'role_guessed': named_role is None,
@@ -1510,13 +1539,13 @@ def draft_layouts(d, outdir, effective_alpha=None):
     image_marks = slide_image_marks(d, overlay_media)
 
     bg_of_slide, layout_of_slide = {}, {}
+    bg_of_layout = {row['part']: row.get('background') for row in d.get('layouts') or []}
     for s in d.get('slides', []):
         bg = s.get('background')
         bg_of_slide[s['part']] = json.dumps(bg, sort_keys=True) if isinstance(bg, dict) else bg
         layout_of_slide[s['part']] = s.get('layout')
     # 版式层的满屏底图（form=2 常态：底图挂在 layout 上）
     composites = d.get('background_composites') or {}
-    bg_of_layout = {}
     for s in shapes:
         if s.get('layer') == 'layout' and is_bleed(s) and s.get('media'):
             bg_of_layout[s['part']] = s['media']
@@ -1571,9 +1600,13 @@ def draft_layouts(d, outdir, effective_alpha=None):
             if key not in seen_marks:
                 seen_marks.add(key)
                 marks.append(mark)
+        background = next((s.get('background') for s in d.get('slides') or []
+                           if s.get('part') == part and s.get('background')), None)
+        background = background or bg_of_layout.get(layout_part)
         pages.append({'part': part, 'no': slide_no(part), 'bg_media': bg_media,
                       'rendered_bg': rendered_bg,
-                      'bg_color': bg_of_slide.get(part), 'texts': texts, 'pic_n': len(pics),
+                      'bg_color': bg_of_slide.get(part), 'background': background,
+                      'texts': texts, 'pic_n': len(pics),
                       'marks': marks, 'shape_n': len(visible_shapes), 'layout': layout_part})
 
     # 页型的**角色**（封面 / 章节页 / 内容页……）不在这里判：那是看图才能下的结论，
@@ -1688,6 +1721,9 @@ def draft_layouts(d, outdir, effective_alpha=None):
                                       round(b.get('w', 0)), round(b.get('h', 0))]})
         taken = {tuple(s['box']) for s in slots}
         decor = []
+        background_layer = background_decor(rep.get('background'), (cW, cH))
+        if background_layer:
+            decor.append(background_layer)
         seen_decor = set()
         for source_part in (rep.get('layout'), rep['part']):
             for item in collect_decor(shapes, source_part, taken, (cW, cH)):
@@ -2338,7 +2374,7 @@ def visual_slot_candidates(candidates, archetypes):
     return rows
 
 
-def emit_manifest(d, assets, vision_groups, ldir):
+def emit_manifest(d, assets, vision_groups, ldir, archetypes=()):
     L = ['version: alpha',
          'name: TODO-style-name        # 英文 kebab，体现气质，不要用文件名',
          'name_zh: TODO中文名',
@@ -2381,6 +2417,15 @@ def emit_manifest(d, assets, vision_groups, ldir):
             '  # - {source_media: example.png, visual_kind: chart}',
             '  # - {source_media: example.png, layout: layout-2, box: [0, 0, 100, 100], visual_kind: decorative}',
         ]
+    if any(decor.get('trace') == 'canvas-background'
+           for archetype in archetypes
+           for decor in archetype.get('decor') or []):
+        canvas = d['canvas']['px']
+        L += [
+            'derived:',
+            '  - value: "[0, 0, %d, %d]"' % (canvas[0], canvas[1]),
+            '    reason: "PPT 背景铺满画布"',
+        ]
     write(os.path.join(ldir, 'manifest.yaml'), '\n'.join(L) + '\n')
 
 
@@ -2727,7 +2772,11 @@ def emit_layout_controls(layout_lines, ldir, text_role_candidates, flow_archetyp
         ]
         controls.extend('# %s: flow' % archetype['name'] for archetype in flow_archetypes)
     if 'bg_rules' in blocks:
-        controls.extend([''] + blocks['bg_rules'])
+        controls += [
+            '',
+            '# 只编辑本草案已列出的真实图片背景；它们都已被 layouts 中的 background: 引用。',
+            '# 纯色、渐变、外框、几何装饰和透明叠层不新建 bg_rules；没有本段就保持没有。',
+        ] + blocks['bg_rules']
     write(os.path.join(ldir, 'layout-controls.yaml'), '\n'.join(controls) + '\n')
 
 
@@ -2982,6 +3031,10 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
               % len(archetypes)) if (d.get('form_hint') or {}).get('form') == 3 else
              ('%d 页样张归纳出 %d 种页型。' % (d['counts']['slides'], len(archetypes))))
     L += ['', '## Usage', '',
+          '**生成前必须完整阅读本 `design.md` 和 %s，确认全部页型后再开始搭页。**'
+          '不能只看摘要、前几个页型或 `## Layouts` 清单；后续页型同样可能定义背景、'
+          '安全区、资产和固定元素。' % sidecar,
+          '',
           '搭一页 PPT 六步，中间四步的数据都在 %s：' % sidecar, '']
     L += ['1. **定画布** —— 舞台按 `layouts.md` 的 `canvas` 设成 %d×%d，'
           '别套用默认尺寸：源模板的长宽比不一定是 16:9，套错了整页坐标全偏。'
@@ -2990,7 +3043,8 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
           '2. **挑页型** —— 在 %s 里按用途选一个 archetype（清单见下面 Layouts 段）。'
           '页数多于页型时，挑最接近的一个原样套用它的 slot：用不到的槽删掉，'
           '内容比槽多就按同类槽的间距等距加，**坐标一律沿用该页型给的那套，不要自己另起网格**。'
-          % sidecar,
+          '每个生成页面的 `<section>` 都写 `data-pptx-layout="<页型名>"`，'
+          '交付前据此核验 logo 只出现在该页型的资产槽中。' % sidecar,
           '3. **按页型给的形态落元素** —— 页型给 `flow` 就用流式，给 `slots` 就用绝对，'
           '两者只会出现一个。'
           '**flow**：整块用一个纵向 flex 容器，`top` 是它的起始 y，`margin` 是整块的左右边距，'
@@ -3357,7 +3411,7 @@ def main(argv=None):
         exceptions.append('源 deck 第 %s 页是单页孤例，没有归纳成 archetype；需要类似构图时按最接近的页型改。'
                           % '、'.join(map(str, leftover)))
 
-    emit_manifest(d, assets, selected_vision_groups, ldir)
+    emit_manifest(d, assets, selected_vision_groups, ldir, archetypes)
     emit_frontmatter(d, tokens, fonts, roles, anchors, gaps, ldir)
     # 每张背景量一次局部对比度，作为「哪里不能压文字」的客观依据摆进判断单。
     # 只报测到的数，不替人填 avoid——哪块算主体、要不要避让，是看图才能定的。

package/steering/design-html/skills/pptx-style-extract/scripts/extract.py

@@ -181,6 +181,8 @@ def export_media(pkg, images, outdir, pillow_ok, export_all=False):
                 reasons.append('variant_group')
             if info['stitch_candidate']:
                 reasons.append('crop_stitch')
+            if info.get('visible_instance_blocked'):
+                reasons.append('visible_instance_fallback')
             if 0 < (info.get('max_w_pct') or 0) < SMALL_IMG_W_PCT and not info['fullscreen']:
                 # 小图（页内图标、角标）。不导出的话 L 层只能看着装饰容器里的空洞
                 # 自己编图形，编出来的与模板无关。
@@ -261,6 +263,30 @@ def _is_full_canvas_picture(shape):
             and (shape.get('h_pct') or 0) >= 95)
 
 
+def _shape_has_visible_text(shape):
+    text = shape.get('text') or {}
+    for paragraph in text.get('paragraphs') or []:
+        for run in paragraph.get('runs') or []:
+            if str(run.get('text') or '').strip():
+                return True
+    return False
+
+
+def _is_full_canvas_fill_overlay(shape):
+    fill = shape.get('fill') or {}
+    geometry = shape.get('geom') or {}
+    line = shape.get('line') or {}
+    return (shape.get('kind') == 'sp' and not shape.get('hidden')
+            and fill.get('type') in ('solid', 'gradient')
+            and not fill.get('path')
+            and geometry.get('prst') == 'rect'
+            and not shape.get('rot')
+            and not line.get('color') and not line.get('gradient')
+            and not _shape_has_visible_text(shape)
+            and (shape.get('w_pct') or 0) >= 95
+            and (shape.get('h_pct') or 0) >= 95)
+
+
 def _picture_has_appearance(shape):
     return bool(shape.get('flipH') or shape.get('flipV') or shape.get('rot')
                 or shape.get('crop')
@@ -333,6 +359,147 @@ def _draw_picture(canvas, shape, pkg, image_cache=None):
     return True
 
 
+def _visible_picture_instance(shape, pkg, image_cache=None):
+    """Render one non-background picture exactly as its PPT instance appears."""
+    from PIL import Image
+
+    bounds = shape.get('box') or {}
+    source_box = shape.get('box_unrotated') or bounds
+    width = max(1, int(round(bounds.get('w') or 0)))
+    height = max(1, int(round(bounds.get('h') or 0)))
+    if not source_box.get('w') or not source_box.get('h'):
+        return None
+    local = dict(shape)
+    local['box_unrotated'] = {
+        'x': float(source_box.get('x') or 0) - float(bounds.get('x') or 0),
+        'y': float(source_box.get('y') or 0) - float(bounds.get('y') or 0),
+        'w': source_box['w'],
+        'h': source_box['h'],
+    }
+    canvas = Image.new('RGBA', (width, height))
+    if not _draw_picture(canvas, local, pkg, image_cache):
+        return None
+    return canvas if canvas.getchannel('A').getbbox() else None
+
+
+def _save_picture_instance_webp(canvas, path):
+    """Keep the instance alpha and shrink only after lossless output exceeds budget."""
+    def write(options):
+        temporary = path + '.tmp'
+        try:
+            canvas.save(temporary, 'WEBP', **options)
+            size = os.path.getsize(temporary)
+            os.replace(temporary, path)
+            return size
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+
+    try:
+        size = write({'lossless': True, 'method': 0})
+    except Exception as exc:
+        return 'pillow-error: %s: %s' % (exc.__class__.__name__, exc)
+    if size <= ASSET_BUDGET_BYTES:
+        return None
+    for quality in (95, 90, 85, 75):
+        try:
+            size = write({'quality': quality, 'method': 6})
+        except Exception:
+            return None
+        if size <= ASSET_BUDGET_BYTES:
+            return None
+    return None
+
+
+def export_visible_picture_instances(pkg, shapes, outdir, pillow_ok, blocked=None):
+    """Replace transformed local pictures with rendered media consumers can reuse.
+
+    A raw media file cannot reproduce an instance-level crop, rotation, flip, or
+    opacity. Flattening only those non-fullscreen instances keeps the downstream
+    contract simple: every asset still resolves through ordinary ``source_media``.
+    """
+    if not pillow_ok:
+        return []
+    try:
+        from PIL import Image  # noqa: F401
+    except Exception:
+        return []
+
+    media_dir = os.path.join(outdir, 'media-out')
+    os.makedirs(media_dir, exist_ok=True)
+    blocked = blocked if blocked is not None else {}
+    rows_by_media, rendered_specs, image_cache = {}, {}, {}
+    for shape in shapes:
+        if (shape.get('kind') != 'pic' or shape.get('hidden')
+                or not shape.get('media') or shape.get('media') not in pkg.names
+                or _is_full_canvas_picture(shape) or not _picture_has_appearance(shape)):
+            continue
+        source = shape['media']
+        source_box = shape.get('box_unrotated') or shape.get('box') or {}
+        visible_box = shape.get('box') or {}
+        spec = json.dumps({
+            'source': source,
+            'source_size': [source_box.get('w'), source_box.get('h')],
+            'visible_size': [visible_box.get('w'), visible_box.get('h')],
+            'crop': shape.get('crop') or {},
+            'flipH': bool(shape.get('flipH')),
+            'flipV': bool(shape.get('flipV')),
+            'rot': shape.get('rot') or 0,
+            'opacity': shape.get('opacity', 1.0),
+        }, ensure_ascii=False, sort_keys=True)
+        media = rendered_specs.get(spec)
+        if media is None:
+            canvas = _visible_picture_instance(shape, pkg, image_cache)
+            if canvas is None:
+                continue
+            digest = hashlib.sha256(spec.encode('utf-8')).hexdigest()[:16]
+            media = 'generated/instance/picture-%s.webp' % digest
+            out = 'media-out/' + os.path.basename(media)
+            path = os.path.join(outdir, out)
+            if not os.path.exists(path):
+                reason = _save_picture_instance_webp(canvas, path)
+                if reason:
+                    row = blocked.setdefault(source, {
+                        'reason': reason, 'attempted_specs': 0, 'part_refs': [],
+                    })
+                    row['attempted_specs'] += 1
+                    row['part_refs'].append(shape.get('part'))
+                    shape['visible_instance_blocked'] = reason
+                    rendered_specs[spec] = False
+                    continue
+            rendered_specs[spec] = media
+            rows_by_media[media] = {
+                'media': media,
+                'ext': 'webp',
+                'bytes': os.path.getsize(path),
+                'used_n': 0,
+                'reasons': ['visible_picture_instance'],
+                'candidate': True,
+                'exported': True,
+                'out': out,
+                'out_bytes': os.path.getsize(path),
+                'transcoded': False,
+                'generated': True,
+                'rendered_from': source,
+                'rendered_with': {
+                    key: shape[key] for key in ('crop', 'flipH', 'flipV', 'rot', 'opacity')
+                    if shape.get(key) not in (None, False, {}, 0, 1.0)
+                },
+                'part_refs': [],
+            }
+        elif media is False:
+            blocked[source]['part_refs'].append(shape.get('part'))
+            shape['visible_instance_blocked'] = blocked[source]['reason']
+            continue
+        row = rows_by_media[media]
+        row['used_n'] += 1
+        row['part_refs'].append(shape.get('part'))
+        shape['media'] = media
+        shape.pop('media_svg', None)
+        shape['rendered_from'] = source
+    return list(rows_by_media.values())
+
+
 def _draw_background(canvas, background, pkg, image_cache=None):
     """Draw the effective p:bg underneath picture layers."""
     from PIL import Image
@@ -353,6 +520,48 @@ def _draw_background(canvas, background, pkg, image_cache=None):
         }, pkg, image_cache)
 
 
+def _draw_background_fill_overlay(canvas, shape):
+    """Draw one full-canvas fill shape that visually modifies a background image."""
+    from PIL import Image
+    from render_pages import _grad_image, _grad_stops, _rgba, css_color, css_gradient
+
+    fill = shape.get('fill') or {}
+    box = shape.get('box_unrotated') or shape.get('box') or {}
+    width = max(1, int(round(box.get('w') or 0)))
+    height = max(1, int(round(box.get('h') or 0)))
+    x = int(round(box.get('x') or 0))
+    y = int(round(box.get('y') or 0))
+    if fill.get('type') == 'solid':
+        color = _rgba(css_color(fill.get('color')))
+        if color is None:
+            return False
+        overlay = Image.new('RGBA', (width, height), color)
+    elif fill.get('type') == 'gradient':
+        gradient = _grad_stops(css_gradient(fill) or '')
+        if not gradient:
+            return False
+        overlay = _grad_image(Image, width, height, gradient[0], gradient[1])
+    else:
+        return False
+    canvas.alpha_composite(overlay, (x, y))
+    return True
+
+
+def _background_layer_source(shape):
+    if shape.get('kind') == 'pic':
+        return {
+            'part': shape['part'], 'kind': 'picture', 'media': shape['media'],
+            'crop': shape.get('crop'), 'flipH': bool(shape.get('flipH')),
+            'flipV': bool(shape.get('flipV')), 'rot': shape.get('rot') or 0,
+            'opacity': shape.get('opacity', 1.0),
+        }
+    return {
+        'part': shape['part'], 'kind': 'fill_overlay',
+        'box': shape.get('box_unrotated') or shape.get('box'),
+        'fill': shape.get('fill'),
+    }
+
+
 def _save_background_webp(canvas, path):
     """Prefer lossless output; fall back to a quality ladder when oversized."""
     canvas.convert('RGB').save(path, 'WEBP', lossless=True, method=0)
@@ -398,15 +607,12 @@ def compose_backgrounds(pkg, graph, shapes, bg_by_part, units, outdir, pillow_ok
     image_cache = {}
     for target, chain in chains.items():
         layers = [shape for part in chain for shape in by_part.get(part, [])
-                  if _is_full_canvas_picture(shape)]
-        if not layers or (len(layers) == 1 and not _picture_has_appearance(layers[0])):
+                  if _is_full_canvas_picture(shape) or _is_full_canvas_fill_overlay(shape)]
+        pictures = [shape for shape in layers if shape.get('kind') == 'pic']
+        if not pictures or (len(pictures) == 1 and not _picture_has_appearance(pictures[0])
+                            and len(layers) == 1):
             continue
-        source_layers = [{
-            'part': shape['part'], 'media': shape['media'],
-            'crop': shape.get('crop'), 'flipH': bool(shape.get('flipH')),
-            'flipV': bool(shape.get('flipV')), 'rot': shape.get('rot') or 0,
-            'opacity': shape.get('opacity', 1.0),
-        } for shape in layers]
+        source_layers = [_background_layer_source(shape) for shape in layers]
         spec = json.dumps({
             'background': _effective_background(chain, bg_by_part),
             'layers': [{k: v for k, v in layer.items() if k != 'part'}
@@ -417,8 +623,12 @@ def compose_backgrounds(pkg, graph, shapes, bg_by_part, units, outdir, pillow_ok
             canvas = Image.new('RGBA', (units.w, units.h))
             _draw_background(
                 canvas, _effective_background(chain, bg_by_part), pkg, image_cache)
-            drawn = [shape for shape in layers
-                     if _draw_picture(canvas, shape, pkg, image_cache)]
+            drawn = [
+                shape for shape in layers
+                if (_draw_picture(canvas, shape, pkg, image_cache)
+                    if shape.get('kind') == 'pic'
+                    else _draw_background_fill_overlay(canvas, shape))
+            ]
             if len(drawn) != len(layers):
                 continue
             digest = hashlib.sha256(canvas.tobytes()).hexdigest()[:16]
@@ -826,6 +1036,9 @@ def extract(pptx, outdir, export_all=False):
                               'box_emu': {'x': 0, 'y': 0, 'cx': cx, 'cy': cy},
                               'crop': bg.get('crop'), 'placement': 'inside',
                               'w_pct': 100.0, 'h_pct': 100.0, 'in_group': False})
+    instance_blocked = {}
+    instance_media = export_visible_picture_instances(
+        pkg, shapes, outdir, pillow_ok, instance_blocked)
     images, variant_groups = image_census(shapes, bg_images, units)        # S5
     t = mark('S5_image_census', t)
 
@@ -845,6 +1058,10 @@ def extract(pptx, outdir, export_all=False):
     t = mark('derived_censuses', t)
 
     media_rows = export_media(pkg, images, outdir, pillow_ok, export_all)  # S9
+    for row in media_rows:
+        if row['media'] in instance_blocked:
+            row['visible_instance_blocked'] = instance_blocked[row['media']]
+    media_rows += instance_media
     background_composites, composite_media, composite_images = compose_backgrounds(
         pkg, graph, shapes, bg_by_part, units, outdir, pillow_ok)
     media_rows += composite_media
@@ -949,6 +1166,8 @@ def extract(pptx, outdir, export_all=False):
             'content_clusters_multi_media': sum(1 for c in clusters if c['member_n'] > 1),
             'media_exported': sum(1 for m in media_rows
                                   if m.get('exported') and not m.get('generated')),
+            'media_instances': len(instance_media),
+            'media_instance_blocked': len(instance_blocked),
             'media_transcoded': sum(1 for m in media_rows
                                     if m.get('transcoded') and not m.get('generated')),
             'media_transcode_blocked': sum(1 for m in media_rows

package/steering/design-html/skills/pptx-style-extract/scripts/parts.py

@@ -299,6 +299,22 @@ NV_TAGS = {'sp': 'p:nvSpPr', 'pic': 'p:nvPicPr', 'grpSp': 'p:nvGrpSpPr',
            'cxnSp': 'p:nvCxnSpPr', 'graphicFrame': 'p:nvGraphicFramePr'}
 
 
+def blip_opacity(blip):
+    """Combine the alpha modulation transforms attached to one local picture."""
+    opacity = 1.0
+    found = False
+    for effect in blip:
+        if local(effect.tag) not in ('alphaMod', 'alphaModFix'):
+            continue
+        try:
+            amount = int(effect.get('amt'))
+        except (TypeError, ValueError):
+            continue
+        opacity *= max(0.0, min(amount / 100000.0, 1.0))
+        found = True
+    return round(opacity, 6) if found else None
+
+
 def walk_tree(el, ctx, out, path=(), xf=(1.0, 1.0, 0.0, 0.0), depth=0):
     sx, sy, dx, dy = xf
     U, W, H = ctx.units, ctx.units.w, ctx.units.h
@@ -393,9 +409,9 @@ def walk_tree(el, ctx, out, path=(), xf=(1.0, 1.0, 0.0, 0.0), depth=0):
             blip = sp.find('p:blipFill/a:blip', NS)
             if blip is not None:
                 rec['media'] = ctx.media_of(blip.get(R_EMBED)) or ctx.media_of(blip.get(R_LINK))
-                alpha = blip.find('a:alphaModFix', NS)
-                if alpha is not None and alpha.get('amt') is not None:
-                    rec['opacity'] = round(int(alpha.get('amt')) / 100000.0, 6)
+                opacity = blip_opacity(blip)
+                if opacity is not None:
+                    rec['opacity'] = opacity
                 svg = blip.find('a:extLst//asvg:svgBlip', NS)
                 if svg is not None:
                     rec['media_svg'] = ctx.media_of(svg.get(R_EMBED))

package/steering/design-html/skills/pptx-style-extract/scripts/render_pages.py

@@ -88,13 +88,15 @@ def css_gradient(grad):
 def background_css(bg):
     """页底 <p:bg> 描述符 → CSS background 值。解析不出返回 None，交上层回退到下一层底色。
 
-    bgPr solid / bgRef 都带 `color`；gradient 与形状渐变共用 css_gradient；
-    背景图不重建（媒体未必导出），按无底色处理。
+    bgPr solid / bgRef 都带 `color`；线性 gradient 与形状渐变共用 css_gradient；
+    path 渐变和背景图不重建，按无底色处理，不能伪装成线性渐变。
     """
     if not bg:
         return None
     kind = bg.get('type')
     if kind == 'gradient':
+        if bg.get('path'):
+            return None
         return css_gradient(bg)
     if kind in ('image', 'none', 'pattern'):
         return None