luma-material

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Luma Material

Luma 素材

Use this skill for Luma / 拾光 local material libraries, cloud material understanding, material search, and PIP matching preparation.

Read

../luma-shared/SKILL.md

first for common project and output rules.

本技能适用于Luma/拾光本地素材库、云端素材理解、素材搜索以及PIP匹配准备。

请先阅读

../luma-shared/SKILL.md

了解通用项目规则和输出规范。

When To Use

使用场景

The user provides a local material group, for example
```
data/material_library/groups/vlm_ai
```
.
Reusable groups should be imported into the default Luma material library at
```
~/.luma/material-library
```
.

A workflow needs

step4_materials_enriched.json

step4_material_matches.json

The agent needs to inspect which materials are available before PIP rendering.
The user wants to upload or understand a material through the backend.

用户提供了本地素材组，例如
```
data/material_library/groups/vlm_ai
```
。
可复用的素材组应导入到默认的Luma素材库路径
```
~/.luma/material-library
```
中。

工作流需要

step4_materials_enriched.json

或

step4_material_matches.json

文件。

Agent需要在PIP渲染前检查可用的素材。
用户希望通过后端上传或理解某一素材。

Local Material Group Flow

本地素材组流程

List available groups:

bash

luma-cli material library path
luma-cli material group list --output material_groups.json

Import a reusable material group into the default library when needed:

bash

luma-cli material library import ./material_library/groups/vlm_ai --replace

Describe one group into a standard materials file:

bash

luma-cli material group describe vlm_ai --output step4_materials_enriched.json

Search candidate materials before planning:

bash

luma-cli material search --materials step4_materials_enriched.json --query "<script_or_scene_text>" --limit 8 --output step4_material_matches.json

列出可用的素材组：

bash

luma-cli material library path
luma-cli material group list --output material_groups.json

按需将可复用素材组导入默认素材库：

bash

luma-cli material library import ./material_library/groups/vlm_ai --replace

将单个素材组描述为标准素材文件：

bash

luma-cli material group describe vlm_ai --output step4_materials_enriched.json

在规划前搜索候选素材：

bash

luma-cli material search --materials step4_materials_enriched.json --query "<script_or_scene_text>" --limit 8 --output step4_material_matches.json

Cloud Understanding

云端素材理解

If local metadata is missing or weak, understand useful materials one by one:

bash

luma-cli material understand ./materials/a.jpg --output a.meta.json --descriptor-output a.material.json
luma-cli material merge --materials step4_materials.json --meta ./materials_meta --output step4_materials_enriched.json

如果本地元数据缺失或信息不足，可逐个解析有用素材：

bash

luma-cli material understand ./materials/a.jpg --output a.meta.json --descriptor-output a.material.json
luma-cli material merge --materials step4_materials.json --meta ./materials_meta --output step4_materials_enriched.json

PIP Matching

PIP匹配

After subtitles are segmented and scene units are ready:

bash

luma-cli pip scene --segments step4_segments.json --output step4_scene_units.json
luma-cli pip match --scenes step4_scene_units.json --materials step4_materials_enriched.json --mode auto --output step4_material_matches.json

Use

--mode cloud

when semantic matching must be backend-only. Use

--mode local

only as a deterministic fallback.

在字幕分段和场景单元准备完成后：

bash

luma-cli pip scene --segments step4_segments.json --output step4_scene_units.json
luma-cli pip match --scenes step4_scene_units.json --materials step4_materials_enriched.json --mode auto --output step4_material_matches.json

当必须仅通过后端进行语义匹配时，使用

--mode cloud

参数。仅将

--mode local

作为确定性回退方案使用。

Agent Rules

Agent规则

Prefer the default material library and
```
material group describe <group_name>
```
for local material libraries.
Do not upload an entire local library unless the user explicitly asks; upload only materials that need cloud understanding.
If matching returns zero inserts, report that no suitable materials were found and continue without PIP.
Keep
```
materials.json
```
, scene units, matches, and PIP plan as separate artifacts.
Do not expose backend object storage implementation details to the user unless a command explicitly requires them.

对于本地素材库，优先使用默认素材库和
```
material group describe <group_name>
```
命令。
除非用户明确要求，否则不要上传整个本地素材库；仅上传需要云端解析的素材。
如果匹配结果返回零个插入项，需告知未找到合适素材，并跳过PIP继续执行。
将
```
materials.json
```
、场景单元、匹配结果和PIP计划作为独立产物保存。
除非命令明确要求，否则不要向用户暴露后端对象存储的实现细节。