@lark-apaas/coding-steering 0.1.32-dev.4f80f68 → 0.1.32-dev.5abff3b

package/package.json

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

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

@@ -65,35 +65,37 @@ mkdir -p tmp/pptx-style-extract/<unique-id> && PYTHONDONTWRITEBYTECODE=1 python3
 
 **目录里没有 `.pptx` / `.potx`**（只有 `skills/` 之类）说明这次上传没有落成沙箱本地文件，本 skill 无法执行：如实告诉用户模板文件在沙箱里取不到、请重新上传或反馈平台，然后停下。此时**不要**用 `summarize_attachment_or_file` 的文本摘要当风格来源，也不要用 `generate_image` 自造配图充当模板视觉——那样产出的 deck 与模板无关，却看起来像成功了。
 
-一条命令出全部：`extract.json`（普查数值）、`media-out/`（候选图）、`ref/`（审计层）、`l-out/`（**四件判断单草案 + BRIEF.md + contact-sheet.png + layout-sheet.png**）。
+一条命令出全部：`extract.json`（普查数值）、`media-out/`（候选图）、`ref/`（审计层）、`l-out/`（**判断单、坐标事实、BRIEF.md、分批候选图、整页语境图和 layout-sheet.png**）。
 
 非 OOXML / 损坏 / 加密 → 报告调用方，不产半成品。
 
 ## 2. 判断
 
-1. 读 `<outdir>/l-out/BRIEF.md` —— 事实、草案依据、待判断清单一页看完。清单是实时扫出来的，**只列真正还有 TODO 的文件**，没列到的那份不用打开。
-2. 看 `<outdir>/l-out/contact-sheet.png` 与 `<outdir>/l-out/layout-sheet.png` —— 候选图和代表页型都已拼好，对应 BRIEF 的表。
-3. 用 `multi_edit` 一次批量改掉四件草案里的每一处 `TODO`：风格命名与气质、页型角色、`text_roles` 里的文本角色、`layout_modes` 里的布局模式、以及下面第 4 条的禁放区。文本角色只按模板中实际存在的文字判断为 `title|subtitle|header|footer|body`；判断不清就填 `body`，不补模板里没有的标题、页眉或页脚。草案就在项目内相对路径下，直接编辑，**不要写脚本去改 YAML**。看过重建图后真有这套模板特有的硬规则（例如主色只许用在哪类元素）再往 `## Hard Rules` 补一条；没有就不补，别为凑数编规则。
-4. `layouts.yaml` 顶部 `bg_rules:` 按**背景资产**分组（不是按页型），逐张背景填 `text_safe` / `avoid` / `pairing_rule`：看图标清视觉主体、强光斑、深色透明区，打包时自动并入用该背景的所有页型。标题、正文、关键数字、图表、卡片、时间线及其容器的外接矩形都不得压住背景主体，透明容器也不能跨进禁放区。
+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`，不要按品牌名、页码或图片数量猜用途。
+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`：看图标清视觉主体、强光斑、深色透明区，打包时自动并入用该背景的所有页型。标题、正文、关键数字、图表、卡片、时间线及其容器的外接矩形都不得压住背景主体，透明容器也不能跨进禁放区。
 
-`layouts.yaml` 的 `layouts:` 段是普查数值——页型、坐标、字号、色值、对齐、以及各页型自带的 `role: logo` 资产槽全部直读，**一个字都不要动**。模板自己给版式起过名时 `names:` 已经填好，读一遍确认表意即可。
+`layout-controls.yaml` 是唯一需要编辑的版式判断文件，只含 `names`、`roles`、`text_roles`、`layout_modes` 和 `bg_rules`。`layouts.yaml` 是兼容用的坐标事实——页型、坐标、字号、色值、对齐、以及各页型自带的 `role: logo` 资产槽全部直读，**不要打开或修改它**。打包时控制文件会覆盖旧文件中的同名判断区。
 
 判断口径：
 
-- **满屏图默认属背景族**——整幅替换底图的艺术图/摄影图就是背景（首页那张记 `role: cover`）；「内容图不进包」只指内容区里的图表、截图、配图。
-- **logo 宁缺勿错**——看图确认有品牌文字或标志图形才留；拿不准就把该条从 `manifest.yaml` 删掉，在 `gaps` 写一句，候选图留在 `media-out/`。
+- **图片按用途三分**——整幅替换底图的艺术图/摄影图属**背景族**；服务于具体内容的图表、截图、产品说明图是**内容图，不进包**；剩下既不是 logo、也不服务于内容的纹理、装饰插画、色块、几何点缀是**装饰图，标 `texture` 进 assets**。不透明满屏图默认走背景；局部图和半透明满屏叠加层结合候选图与整页语境逐张定性，避免把重要装饰误当内容丢弃。首页、末页优先保留样张，但是否为 `cover` 或 `closing` 仍按页面意图判断。
+- **logo 特指这份 deck 自己的品牌标志**——看图确认是本 PPT 的品牌文字或标志图形才留 `logo`；一页若是 logo 墙（客户/合作方 logo 罗列），那些是内容图、不当风格 logo。拿不准就保留该候选并填 `unknown`，在 `gaps` 写一句；不要删除或合并 `asset_vision_groups` 条目。
 - **anchors 是事实不是结论**——草案里每条只报测到的数（覆盖率、计数、占比），没有「这套风格的特征是 X」这种断言。这一段在 design.md 里读起来像总纲，消费端会照它建全局样式，所以脚本不敢替你下结论：一条 1/8 覆盖率的元素被描述成「跨页不动」，消费端就会每页都摆它。看过重建图后，把真正是这套模板特征的那几条改写成设计要点，不是特征的直接删掉。
 - **数值只改名不改值**——草案里的坐标/色值/字号来自普查；确需推导值（CJK 行高转译、投影尺度上抬）在 manifest 写 `derived:` 声明理由，机检认声明。
-- **页型命名**——模板自带版式名时草案已填好；只有靠样张聚类的模板（`names` 里还是 TODO）才需要按 BRIEF 的 slot 原文起中文名。
-- **页型角色**——`roles:` 段有 TODO 时，看 `layout-sheet.png` 上对应的代表页定 `cover|section|content|quote|closing|blank|custom`。草案只把客观事实摆在注释里（代表页页码、页数、文字块数、字号序列、图片数、有无满屏底图），不替你下结论：字号多大算章节页、文字块多少算密集页，每套模板的答案都不一样。
-- **文本角色**——`text_roles:` 段有 TODO 时，结合重建图和该行给出的来源、占位符、样例文字、box、字号与 CSS 判断标题、副标题、页眉、页脚或正文。这里仅改变已有文本槽的语义；所有文本槽、图片、容器与装饰仍由 `layouts:` 保留。标题、页眉或页脚已在背景中可见时，在 Hard Rules 写明对应页型只渲染已有 slots，不重复叠加文字。
-- **资产位置不要写成全局规则**——同一个 logo 常按页型换位换尺寸（封面一个位置一个尺寸、内容页另一个）。位置只存在于 `layouts.md` 各页型的 `slots`，正文里只说「按该页型的 slot 摆放，没有就不放」。
-- **背景和版式要配对**——真实背景不是纯色底。看 `contact-sheet.png` 判断每张背景的视觉主体/禁放区，看 `layout-sheet.png` 判断文字与卡片落点；`background` 草案已按版式直读填好，你只需在 `bg_rules` 里逐张背景补 `text_safe`、`avoid`、`pairing_rule`，避免消费 Agent 把文字、图表、卡片、时间线、标题容器、正文容器或宽透明容器的外接矩形压到金字塔、人物、产品图、强光斑或深色区域上。
+- **页型命名**——模板自带版式名时草案已填好；只有靠样张聚类的模板（`layout-controls.yaml` 的 `names` 里还是 TODO）才需要按 BRIEF 的 slot 原文起中文名。
+- **页型角色**——`layout-controls.yaml` 的 `roles:` 段有 TODO 时，看 `layout-sheet.png` 上对应的代表页定 `cover|section|content|quote|closing|blank|custom`。草案只把客观事实摆在注释里（代表页页码、页数、文字块数、字号序列、图片数、有无满屏底图），不替你下结论：字号多大算章节页、文字块多少算密集页，每套模板的答案都不一样。
+- **文本角色**——`layout-controls.yaml` 的 `text_roles:` 段有候选时，结合重建图和注释中的样例文字判断标题、副标题、页眉、页脚或正文。这里仅改变已有文本槽的语义；所有文本槽、图片、容器与装饰仍由 `layouts:` 保留。标题、页眉或页脚已在背景中可见时，在 Hard Rules 写明对应页型只渲染已有 slots，不重复叠加文字。
+- **资产位置不要写成全局规则**——同一个 logo 常按页型换位换尺寸（封面一个位置一个尺寸、内容页另一个）。位置只存在于 `layouts.md` 各页型的 `slots`，正文里只说「按该页型的 slot 摆放，没有就不放」。一张图只在 `manifest` 标了 `kind` 还不够：生成侧只摆 `slots` 里带 `asset:` 引用它的那些，没有任何页型引用它就不会被放出来。要它出现，就在对应页型的 `slots` 加一条 `asset:` 引用。
+- **背景和版式要配对**——真实背景不是纯色底。看 `layout-sheet.png` 判断每个页型上的视觉主体与文字、卡片落点；仅当代表页看不清时，才打开 `manifest.yaml` 已声明的那张背景资产核对。`background` 草案已按版式直读填好，你只需在 `layout-controls.yaml` 的 `bg_rules` 里逐张背景补 `text_safe`、`avoid`、`pairing_rule`，避免消费 Agent 把文字、图表、卡片、时间线、标题容器、正文容器或宽透明容器的外接矩形压到金字塔、人物、产品图、强光斑或深色区域上。
 - 双主题只认 BRIEF 的 `themes`；单主题包不写 `theme` 字段。
 
 判断单里的**结构事实**（每个页型上方的注释）是判「这页该用绝对坐标还是流式」的依据：栅格几列、垂直间距序列（突变处即区带边界）、样张里每个文字槽的实际字数、命中哪个容器样式配方。文件头另有容器样式配方清单，带出现次数与跨页数——跨页多的是共性风格，只在一处出现的多半不是。
 
-**页型给 `flow` 还是 `slots`，由你定**：内容长度会变的内容页（列表、表格、卡片组）优先用 `flow`，区带依次排，高度由实际内容决定；构图固定的页（封面、章节页）用 `slots` 绝对坐标。在扁平 `layout_modes:` 段为每个候选页型填 `flow` 或 `slots`，打包时按它落一份。判据就在该页型上方的结构事实里：规整多列栅格、等距重复的间距、成对出现的长文本槽都指向 `flow`。`flow` 中并列卡片以 `grid` 表达，每张卡片的容器、标题和正文放在同一个一层 `role: group` 中；logo、页码、页眉和页脚等固定锚点留在带 `box` 的 `free` 区带。模型结合实际内容判断纵向间距与留白，不机械照搬样张的 `y` 坐标。
+**页型给 `flow` 还是 `slots`，由你定**：内容长度会变的内容页（列表、表格、卡片组）优先用 `flow`，区带依次排，高度由实际内容决定；构图固定的页（封面、章节页）用 `slots` 绝对坐标。在 `layout-controls.yaml` 的扁平 `layout_modes:` 段为每个候选页型填 `flow` 或 `slots`，打包时按它落一份。判据就在该页型上方的结构事实里：规整多列栅格、等距重复的间距、成对出现的长文本槽都指向 `flow`。`flow` 中并列卡片以 `grid` 表达，每张卡片的容器、标题和正文放在同一个一层 `role: group` 中；logo、页码、页眉和页脚等固定锚点留在带 `box` 的 `free` 区带。模型结合实际内容判断纵向间距与留白，不机械照搬样张的 `y` 坐标。
 
 普查是有损的。判断不了时可以直接翻 `<outdir>/ref/source/` —— PPTX 解压后的原文都在那里（`ppt/slides/slideN.xml`、`ppt/slideLayouts/`、`ppt/theme/`）。它只在中间产物里，不进交付包。
 
@@ -105,9 +107,9 @@ mkdir -p tmp/pptx-style-extract/<unique-id> && PYTHONDONTWRITEBYTECODE=1 python3
 PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/package.py <outdir> <outdir>/l-out <包输出目录> --force
 ```
 
-exit 0 即交付。FAIL 会指名道姓（TODO 未改 / 数值不可追溯 / 枚举误用 / 引用断链 / 体量超标），改判断单后**用同一个包目录重跑**（`--force` 就是为回修准备的），不要去改产物；体量 FAIL 走降级链（审计出包 → sidecar 化 → archetype 收缩）。
+package.py exit 0 后才可交付、导出或供 deck 消费；成功即结束本次抽取，不再重读草案、打开 `layouts.yaml` 或追加检查。`media-out/`、`l-out/` 都是中间产物，不能作为风格来源。FAIL 会指名道姓（TODO 未改 / 数值不可追溯 / 枚举误用 / 引用断链 / 体量超标），改判断单后**用同一个包目录重跑**（`--force` 就是为回修准备的），不要去改产物；体量 FAIL 走降级链（审计出包 → sidecar 化 → archetype 收缩）。
 
-跑之前先确认判断单里 `TODO` 已经全部改完（`grep -rn TODO <outdir>/l-out`）——`body.md` 最容易漏。改完直接跑 package.py，不用先 `ls` 确认目录。
+跑之前先确认 `manifest.yaml`、`frontmatter.yaml`、`body.md` 和 `layout-controls.yaml`（旧草案没有该文件时才检查 `layouts.yaml`）的 `TODO` 已经全部改完。改完直接跑 package.py，不用先 `ls` 确认目录。
 
 ## 完成判据