@lark-apaas/coding-steering 0.1.28 → 0.1.30-alpha.20260809164221

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.28",
+  "version": "0.1.30-alpha.20260809164221",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/design-html/skills/animated-video/SKILL.md

@@ -13,7 +13,7 @@ Create an animated video or motion design piece rendered as an HTML page. Build
 
 START by calling `copy_starter_component` with `kind: "animations.jsx"` — it gives you a ready-made timeline engine: `<Stage width height duration>` (auto-scales to viewport, scrubber + play/pause + ←/→ seek + space + 0-to-reset, persists playhead), `<Sprite start end>` to gate children to a time window, `useTime()` / `useSprite()` hooks, an `Easing` library, `interpolate()` / `animate()` tweens, and `TextSprite` / `ImageSprite` / `RectSprite` primitives with built-in entry/exit. Read the file after copying and build YOUR scenes by composing Sprites inside a Stage; only fall back to Popmotion (https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/popmotion@11.0.5/dist/popmotion.min.js) if the starter genuinely can't do what you need.
 
-Animations are complex code! Make reusable JSX components for each visual element and each scene. Every moment gets ONE definition; sprite-local times and offsets derive from it, never stored separately. The failure: `cardSelectStart = 1.2` inside a scene while the cursor holds `{ t: 9.2 }` for the same beat. Timing shared with nothing else — entry stagger, easing durations — stays local.
+Animations are complex code! Make reusable JSX components for each visual element and each scene. Invest in tweaking the timeline iteratively.
 
 Animation tips:
 - Storytelling is KEY! Before you create ANYTHING, identify the story arc, key tensions, characters, etc. Align on the message you want to convey. Run it by the user.

package/steering/design-html/skills/charts/SKILL.md

@@ -48,7 +48,7 @@ metadata:
 
 5. **编写 ECharts 代码。** 挂载模式和 API 约束见下方技术参考。
 
-6. **自检。** 按文末清单逐项检查你写出的 option 代码（源码级自查，不用打开浏览器截图）。然后回到视觉编码步骤：这套配置渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？
+6. **自检。** 按文末清单验证渲染结果。然后回到视觉编码步骤：渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？
 
 ## 图表类型映射
 

package/steering/design-html/skills/data-viz/SKILL.md

@@ -139,7 +139,7 @@ metadata:
 
 ### 6. 自检
 
-读一遍自己写出的代码（源码级自查），逐项验证以下几点：
+检查渲染结果，验证以下几点：
 
 - 报表是否回答了步骤 1 确定的核心问题。
 - 信息层级是否清晰（读者能在 5 秒内抓到主要结论）。

package/steering/design-html/skills/frontend-design/SKILL.md

@@ -24,7 +24,7 @@ metadata:
 - **配色（Palette）**——哪些颜色承担语义或品牌职责，哪些是中性的支撑色，哪一个唯一的强调色赢得注意力？
 - **签名元素（Signature）**——整个页面靠它被记住的那一个手法。它必须只可能属于这个主题；一个换到下份 brief 也能复用的签名元素，是默认值，不是选择。
 
-风格不是版式排完后再涂上去的装饰。这个方向决定字体排印、间距、图表处理、图像质感、章节节奏、边框、图标风格，以及哪些组件值得强调。
+风格不是版式排完后再涂上去的装饰。这个方向决定字体排印、间距、图表处理、章节节奏、边框、图标风格，以及哪些组件值得强调。
 
 ## 设计原则
 
@@ -54,7 +54,7 @@ metadata:
 
 ## 克制与自我评审
 
-把大胆花在一个地方。让签名元素成为唯一被记住的东西，它周围的一切保持安静、克制，砍掉任何不服务于 brief 的装饰。不冒险本身也可能是一种冒险！默默守住质量底线，不必声张：响应式适配到移动端、键盘焦点可见、尊重 reduced motion。边构建边评审自己的作品——读你写出的代码，在脑子里过一遍它渲染成什么样。想想香奈儿的忠告：出门前照照镜子，摘掉一件配饰。人类创作者有记忆，总在尝试新东西；如果你有地方快速记下自己试过什么，会对后续迭代有帮助。
+把大胆花在一个地方。让签名元素成为唯一被记住的东西，它周围的一切保持安静、克制，砍掉任何不服务于 brief 的装饰。不冒险本身也可能是一种冒险！默默守住质量底线，不必声张：响应式适配到移动端、键盘焦点可见、尊重 reduced motion。边构建边评审自己的作品，环境支持就截图看——一图胜千 token。想想香奈儿的忠告：出门前照照镜子，摘掉一件配饰。人类创作者有记忆，总在尝试新东西；如果你有地方快速记下自己试过什么，会对后续迭代有帮助。
 
 ## 再谈设计中的写作
 

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

@@ -0,0 +1,87 @@
+---
+name: pptx-style-extract
+description: 从 PPTX/POTX 模板抽取 deck 风格包 v2（design.md + layouts.md + assets/ + ref/）。当用户上传 PPTX/POTX 并要求按附件模板、参考 PPT 风格、保持同款视觉、生成演示/PPT/deck 时，必须先用本 skill 抽取风格；不要只读附件文本摘要后开工。
+---
+
+# pptx-style-extract（PPT 模板风格抽取）
+
+一份 PPTX → 一个风格包。**机械动作全部由脚本承担**（解析、普查、聚类、草案、落盘、门禁），你只做机器做不了的三件事：**认图、命名、写气质**。
+
+脚本路径相对本 skill 根目录；不做环境检测，依赖缺失脚本自己降级并在输出里报。
+
+## When To Use This Skill
+
+Use this skill before making a slide deck when a `.pptx` or `.potx` attachment is meant as a template, visual reference, brand/style source, or "make it like this" example.
+
+Do not treat `SummarizeAttachmentOrFile` output as a substitute for this skill. Attachment text summaries lose theme colors, fonts, slide master geometry, layout coordinates, and reusable visual assets.
+
+If the user only asks to summarize, translate, extract text, or review an existing PPTX, do not run this skill unless they also ask to reuse its visual style.
+
+## Runtime Contract
+
+- Required dependency boundary: Python 3 standard library only.
+- Pillow may be present and improves image hashing, palette extraction, contact sheets, and asset transcoding. If Pillow is missing or fails, continue with degraded extraction and record the degradation in outputs.
+- Do not run `pip install`, `uv pip install`, `npm install`, or any other dependency installation in the user session.
+- Run Python with bytecode disabled: `PYTHONDONTWRITEBYTECODE=1 python3 -B ...`.
+- Default working directory: `/tmp/pptx-style-extract/<unique-id>/`.
+- Do not write extraction intermediates into `/home/gem/workspace/code` or the user app source tree. Only the final deck assets copied by the deck authoring step should enter the project.
+- `package.py` only runs v1 checks when `--check-v1 <path>` is passed or `DSM_V1_DIR` points to a sibling checker. It must not rely on developer-machine paths in the sandbox.
+
+## 1. 抽取
+
+```bash
+mkdir -p /tmp/pptx-style-extract/<unique-id>
+PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/extract.py <pptx_path> /tmp/pptx-style-extract/<unique-id>/stage1
+```
+
+一条命令出全部：`extract.json`（普查数值）、`media-out/`（候选图）、`ref/`（审计层）、`l-out/`（**四件判断单草案 + BRIEF.md + contact-sheet.png**）。
+
+非 OOXML / 损坏 / 加密 → 报告调用方，不产半成品。
+
+## 2. 判断
+
+1. 读 `<outdir>/l-out/BRIEF.md` —— 事实、草案依据、待判断清单一页看完。
+2. 看 `<outdir>/l-out/contact-sheet.png` —— 所有候选图带编号拼在一张图上，对应 BRIEF 的候选表。
+3. 用 Edit 改掉四件草案里的每一处 `TODO`：风格命名与气质、页型中文名、logo 与封面归属、Colors 用途列、模板特有硬规则。
+
+判断口径：
+
+- **满屏图默认属背景族**——整幅替换底图的艺术图/摄影图就是背景（首页那张记 `role: cover`）；「内容图不进包」只指内容区里的图表、截图、配图。
+- **logo 宁缺勿错**——看图确认有品牌文字或标志图形才留；拿不准就把该条从 `manifest.yaml` 删掉，在 `gaps` 写一句，候选图留在 `media-out/`。
+- **数值只改名不改值**——草案里的坐标/色值/字号来自普查；确需推导值（CJK 行高转译、投影尺度上抬）在 manifest 写 `derived:` 声明理由，机检认声明。
+- **页型按用途命名**——草案按背景+结构聚类，名字（`cover`/`section`/`content-dense`）只是占位，按 BRIEF 里的 slot 原文改成表意的中文名，role 跟着改。
+- 双主题只认 BRIEF 的 `themes`；单主题包不写 `theme` 字段。
+
+要更多依据时用 `PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/query.py <outdir> <子命令>`（`shapes` / `colors` / `fonts` / `text-scale` / `images` / `clusters` / `media` / `slides` / `layouts` / `recipes` / `grids` / `get <点路径>`）。读数一律走它，**不写解析脚本、不读 XML、不开浏览器**。
+
+## 3. 打包
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/package.py <outdir> <outdir>/l-out <包输出目录>
+```
+
+exit 0 即交付。FAIL 会指名道姓（TODO 未改 / 数值不可追溯 / 枚举误用 / 引用断链 / 体量超标），改判断单重跑，不要去改产物；体量 FAIL 走降级链（审计出包 → sidecar 化 → archetype 收缩）。
+
+## 完成判据
+
+- [ ] package.py exit 0
+- [ ] design.md 的 Usage 能回答消费三问：封面底图是哪个文件？logo 每页放哪、用哪个文件？版式坐标去哪查？
+- [ ] 抽不出的都在 `gaps`，无编造
+
+配套 `v2-format-spec.md`（包形态与 schema）、`font-fallback.yaml`（商业字体降级表）只在你要偏离草案结构时才需要读——草案已经是最终格式。
+
+## Consume The Style Pack In A Deck
+
+After `package.py` succeeds, the output package is for immediate model consumption.
+
+Read `<pack_dir>/design.md` first, especially `## Usage`, `## Hard Rules`, colors, typography, components, assets, and safe-area. Then read `<pack_dir>/layouts.md`; its `canvas` and `slots[].box` are the geometry source for deck-stage sections.
+
+When generating a deck:
+
+1. Call `copy_starter_component` with `kind: "deck-stage.js"`.
+2. Build `<deck-stage width="1920" height="1080">`; each slide is one static `<section>`.
+3. Inline CSS variables from `design.md` into the HTML `<style>` block using a `--ppt-*` prefix.
+4. Map `layouts.md` slots `[x,y,w,h]` to absolute-positioned elements inside each section. Do not reflow them as generic web grids.
+5. Copy `<pack_dir>/assets/` into the project, for example `assets/pptx-style/<pack-name>/`, and reference those copied files with relative URLs. Never reference `/tmp/pptx-style-extract/...` from final HTML.
+6. Use the font stacks and fallback rules from `design.md`; do not install fonts or dependencies at runtime.
+7. Run the slide preflight checks: no resource failures, no section overflow, and sampled screenshots follow the package colors, typography, layouts, assets, and Hard Rules.

package/steering/design-html/skills/pptx-style-extract/font-fallback.yaml

@@ -0,0 +1,129 @@
+# 商业字体降级映射表（随 skill 分发，E5：初始 20+ 族）
+#
+# 消费方：L4 字体角色分配。直读本文件文本即可，不依赖 yaml 库。
+# 命中 families[].match 中任一名字（含碎片化变体）→ 降级链写进 fontFamily 栈：
+# 原始名留栈首，fallback 依序追加，末位永远可加系统兜底
+# `"PingFang SC", "Microsoft YaHei", sans-serif`。
+# 查无对应 → 按 dsm-v1-spec.md 的气质候选清单选近似体 + 记 gaps，不编造。
+# 匹配纪律：先做字体名归一化聚类（中文名/拉丁名、weight 后缀剥离、31 字符截断），
+# 再拿聚类后的 family 与 match 逐条比对（大小写不敏感、忽略空格/连字符）。
+
+version: 2
+
+# fallback 用到的 web 字体实测状态（镜像 https://miaoda.feishu.cn/fonts/css2）。
+# verified: true = 该镜像已 curl 实测返回 @font-face（2026-08-06）。
+# 状态过期不影响正确性：L4 对 verified 为 false 或存疑的字体按 dsm-v1-spec 字体条款
+# 重新 curl 实测后再用，加载不到降到下一档。
+web-fonts:
+  "Noto Sans SC":         {verified: true}
+  "Noto Serif SC":        {verified: true}
+  "ZCOOL XiaoWei":        {verified: true}
+  "ZCOOL QingKe HuangYou": {verified: true}
+  "Ma Shan Zheng":        {verified: true}
+  "Inter":                {verified: true}
+  "Montserrat":           {verified: true}
+  "Barlow":               {verified: true}
+  "Jost":                 {verified: true}
+  "Nunito Sans":          {verified: true}
+  "Roboto Condensed":     {verified: true}
+  "Arial":                {verified: system}   # 系统字体，不走镜像
+
+families:
+  # ---- 方正系 ----
+  - family: 方正兰亭黑
+    match: [方正兰亭黑Pro_GB18030, FZLanTingHeiPro, FZLanTingHeiPro_GB18030, FZLTHProS-R--GB1-0, FZLTHProS, 方正兰亭黑]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 方正兰亭圆
+    match: [方正兰亭圆, FZLanTingYuan, FZLTYuanS]
+    category: rounded
+    fallback: ["ZCOOL XiaoWei", "Noto Sans SC"]
+  - family: 方正准圆
+    match: [方正准圆, FZZhunYuan, FZY3JW]
+    category: rounded
+    fallback: ["ZCOOL XiaoWei", "Noto Sans SC"]
+  - family: 方正书宋/宋体系
+    match: [方正书宋, FZShuSong, 方正宋体, FZSongS]
+    category: serif
+    fallback: ["Noto Serif SC"]
+
+  # ---- 汉仪系 ----
+  - family: 汉仪旗黑
+    match: [汉仪旗黑, HYQiHei, HYQiHeiX]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 汉仪文黑
+    match: [汉仪文黑, HYWenHei]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 汉仪菱心体
+    match: [汉仪菱心体, HYLingXin]
+    category: display
+    fallback: ["ZCOOL QingKe HuangYou", "Noto Sans SC"]
+  - family: 汉仪粗黑
+    match: [汉仪粗黑, HYCuHei]
+    category: display
+    fallback: ["Noto Sans SC"]
+    weight-hint: 900
+
+  # ---- 系统/厂商中文 ----
+  - family: 苹方
+    match: [苹方, PingFang SC, PingFangSC, 苹方-简]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 微软雅黑
+    match: [微软雅黑, Microsoft YaHei, MicrosoftYaHei, 微软雅黑 UI]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 等线
+    match: [等线, DengXian, 等线 Light, DengXian Light]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 华文黑体
+    match: [华文黑体, STHeiti, 华文细黑, STXihei]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 华文宋体/楷体
+    match: [华文宋体, STSong, 华文楷体, STKaiti, 楷体, KaiTi]
+    category: serif
+    fallback: ["Noto Serif SC"]   # 手写楷气质另可选 Ma Shan Zheng，按场景判断
+  - family: 思源黑体
+    match: [思源黑体, Source Han Sans, Source Han Sans SC, SourceHanSansSC, 思源黑体 CN]
+    category: sans
+    fallback: ["Noto Sans SC"]    # 同源设计，无损替换
+  - family: 思源宋体
+    match: [思源宋体, Source Han Serif, Source Han Serif SC, SourceHanSerifSC]
+    category: serif
+    fallback: ["Noto Serif SC"]   # 同源设计，无损替换
+
+  # ---- 互联网厂商定制体 ----
+  - family: 阿里巴巴普惠体
+    match: [阿里巴巴普惠体, Alibaba PuHuiTi, AlibabaPuHuiTi]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 字节跳动定制体
+    match: [Byte Sans, ByteDance Sans, Douyin Sans]
+    category: sans
+    fallback: ["Noto Sans SC"]
+  - family: 小米/OPPO/荣耀定制体
+    match: [MiSans, OPPO Sans, HarmonyOS Sans, HONOR Sans]
+    category: sans
+    fallback: ["Noto Sans SC"]
+
+  # ---- 拉丁商业体 ----
+  - family: Helvetica Neue
+    match: [Helvetica Neue, HelveticaNeue, Helvetica Neue Medium, Helvetica]
+    category: sans-latin
+    fallback: ["Inter", "Arial"]
+  - family: Gotham / Proxima Nova
+    match: [Gotham, Proxima Nova, ProximaNova]
+    category: sans-latin
+    fallback: ["Montserrat", "Inter"]
+  - family: DIN
+    match: [DIN, DIN Pro, DIN Next, FF DIN]
+    category: sans-latin
+    fallback: ["Barlow", "Roboto Condensed"]
+  - family: Futura / Avenir
+    match: [Futura, Avenir, Avenir Next]
+    category: sans-latin
+    fallback: ["Jost", "Nunito Sans"]