materials-cli

使用声明渲染和 AI 将 JSON 模式渲染为图像并根据提示生成模式。

# Materials CLI

Use this skill when the user wants to render JSON schemas to images (PNG/JPG), validate render-data schemas, or generate schemas from natural-language prompts and then render them.

## Commands

- **render** — Render a JSON schema file to an image.
- **generate** — Use AI (OpenAI) to generate a schema from a prompt, then render it.
- **validate** — Validate a JSON schema against the declare-render data schema.

## When to use

- User asks to "render a schema to image", "turn JSON into a picture", or "draw from schema".
- User wants to "generate an image from a description" or "create a schema from a prompt" and render it.
- User wants to "validate" a JSON file against the render data schema.

## Usage

Run via Node (from the project or after `npm install -g materials-cli`):

```bash
materials render <schema-path> [options]
materials generate "<prompt>" [options]
materials validate <schema-path> [options]
```

### Render

- `materials render schema.json -o output.png`
- Options: `-s, --schema <path>`, `-o, --output <path>` (default `./output.png`), `-f, --format <png|jpg>`, `-w, --width`, `-h, --height`, `--output-schema <path>`, `-i, --interactive`

### Generate (AI)

- `materials generate "A red circle with text Hello" -o out.png`
- Options: `-o, --output`, `-f, --format`, `-w, --width`, `-h, --height`, `--output-schema`, `--model`, `--api-key`, `--base-url`, `-i, --interactive`
- Uses `OPENAI_API_KEY` (and optionally `OPENAI_MODEL`, `OPENAI_BASE_URL`) if not passed via flags.

### Validate

- `materials validate schema.json`
- Options: `-s, --schema <path>`, `-i, --interactive`

## CLI help

```
Usage: materials <command> [options]

Commands:
  render <schema>     Render a JSON schema file to an image
  generate <prompt>   Use AI to generate a schema, then render
  validate <schema>   Validate a schema against the render data schema

Examples:
  materials render schema.json -o output.png
  materials generate "A red circle with text Hello"
  materials validate schema.json
```

## Schema format

The JSON schema follows the declare-render format: root has `id`, `width`, `height`, and `layers`. Layer types include text, image, container, shape, etc. Use `materials validate <file>` to check a schema before rendering.

---

## 中文说明

# Materials CLI

当用户想要将 JSON schema 渲染为图像（PNG/JPG）、校验 render-data schema，或根据自然语言提示生成 schema 并随后渲染时，使用此技能。

## 命令

- **render** —— 将 JSON schema 文件渲染为图像。
- **generate** —— 使用 AI（OpenAI）根据提示生成 schema，然后渲染。
- **validate** —— 根据 declare-render 数据 schema 校验 JSON schema。

## 何时使用

- 用户要求“render a schema to image”（将 schema 渲染为图像）、“turn JSON into a picture”（把 JSON 变成图片）或“draw from schema”（根据 schema 绘制）。
- 用户想要“generate an image from a description”（根据描述生成图像）或“create a schema from a prompt”（根据提示创建 schema）并渲染它。
- 用户想要根据 render data schema “validate”（校验）一个 JSON 文件。

## 用法

通过 Node 运行（在项目中或在 `npm install -g materials-cli` 之后）：

```bash
materials render <schema-path> [options]
materials generate "<prompt>" [options]
materials validate <schema-path> [options]
```

### Render

- `materials render schema.json -o output.png`
- 选项：`-s, --schema <path>`、`-o, --output <path>`（默认 `./output.png`）、`-f, --format <png|jpg>`、`-w, --width`、`-h, --height`、`--output-schema <path>`、`-i, --interactive`

### Generate (AI)

- `materials generate "A red circle with text Hello" -o out.png`
- 选项：`-o, --output`、`-f, --format`、`-w, --width`、`-h, --height`、`--output-schema`、`--model`、`--api-key`、`--base-url`、`-i, --interactive`
- 如果未通过参数传入，则使用 `OPENAI_API_KEY`（以及可选的 `OPENAI_MODEL`、`OPENAI_BASE_URL`）。

### Validate

- `materials validate schema.json`
- 选项：`-s, --schema <path>`、`-i, --interactive`

## CLI 帮助

```
Usage: materials <command> [options]

Commands:
  render <schema>     Render a JSON schema file to an image
  generate <prompt>   Use AI to generate a schema, then render
  validate <schema>   Validate a schema against the render data schema

Examples:
  materials render schema.json -o output.png
  materials generate "A red circle with text Hello"
  materials validate schema.json
```

## Schema 格式

该 JSON schema 遵循 declare-render 格式：根节点包含 `id`、`width`、`height` 和 `layers`。图层类型包括 text、image、container、shape 等。在渲染前使用 `materials validate <file>` 来检查 schema。