zilliz 1.4.2

# generate-plugin

`generate_plugin` is an internal dev tool (Cargo example) that generates the [zilliztech/zilliz-plugin](https://github.com/zilliztech/zilliz-plugin) repository content from zilliz-tui's JSON model definitions. It is not included in release builds or `cargo install`.

It reads `control-plane.json` and `data-plane.json`, combines them with `scripts/skill_config.yaml` and hand-written overlay files, and produces the complete plugin directory structure (skills, commands, manifest, README).

## Prerequisites

- Rust toolchain (build via Cargo)
- Working directory: `vdc/zilliz-tui/`

## Usage

All commands are run from the `vdc/zilliz-tui/` directory.

### Preview (dry run)

Print all generated SKILL.md content to stdout without writing any files:

```bash
cargo run --example generate_plugin
```

### Preview a single skill

```bash
cargo run --example generate_plugin -- --skill cluster
```

### Generate the full plugin

Write the complete plugin directory to a target path:

```bash
cargo run --example generate_plugin -- --output /path/to/zilliz-plugin

# The following command is usually run locally to generate plugin
cd vdc/zilliz-tui
cargo run --example generate_plugin -- --output ../../../zilliz-plugin
```

This creates:

```
/path/to/zilliz-plugin/
  .claude-plugin/plugin.json
  marketplace.json
  README.md
  commands/
    quickstart.md
    status.md
  skills/
    backup/SKILL.md
    billing/SKILL.md
    cluster/SKILL.md
    collection/SKILL.md
    database/SKILL.md
    import/SKILL.md
    index/SKILL.md
    job/SKILL.md
    monitoring/SKILL.md
    partition/SKILL.md
    project-region/SKILL.md
    setup/SKILL.md
    user-role/SKILL.md
    vector/SKILL.md
```

### Check for drift (CI mode)

Compare generated output against an existing plugin directory. Exits with status 1 if any files differ:

```bash
cargo run --example generate_plugin -- --check /path/to/zilliz-plugin
```

Example output:

```
OK:      /path/to/zilliz-plugin/skills/cluster/SKILL.md
OK:      /path/to/zilliz-plugin/skills/collection/SKILL.md
DRIFT:   /path/to/zilliz-plugin/skills/backup/SKILL.md
MISSING: /path/to/zilliz-plugin/skills/new-skill/SKILL.md
```

## How it works

### Data sources

| Source | Path | Description |
|--------|------|-------------|
| JSON models | `src/model/builtin_models/{control,data}-plane.json` | API resource and operation definitions (embedded at compile time) |
| Skill config | `scripts/skill_config.yaml` | Maps JSON model resources to plugin skills |
| Overlays | `scripts/skill_overlays/<skill>/` | Hand-written guidance, extra commands, full SKILL.md |
| Templates | `scripts/plugin_template/` | Static files copied as-is (plugin.json, commands, README) |

### Generation pipeline

1. Load JSON models via `model::loader` (same types as the main TUI binary)
2. Parse `skill_config.yaml` to get skill definitions
3. For each skill:
   - **Hand-written** (`hand_written: true`): copy `skill_overlays/<skill>/SKILL.md` as-is
   - **Auto-generated**: build SKILL.md from frontmatter + prerequisites + header + extra_commands overlay + model-driven command blocks + guidance overlay
4. For `--output` mode: copy template files first, then write generated skills into `skills/`

### Skill config format

Each entry in `scripts/skill_config.yaml` defines a skill:

```yaml
cluster:
  description: >-
    Use when the user wants to create, list, describe...
  resources:
    - plane: control        # "control" or "data"
      resource: cluster     # resource key in JSON model
  prerequisites: |
    1. CLI installed and logged in (see setup skill).
  header: >-                # optional text before command blocks
    Additional context...
```

For hand-written skills (no JSON model counterpart):

```yaml
setup:
  hand_written: true
  description: >-
    Use when the user needs to install zilliz-cli...
```

### Overlay files

Place overlay files in `scripts/skill_overlays/<skill-name>/`:

| File | When used | Purpose |
|------|-----------|---------|
| `SKILL.md` | `hand_written: true` | Complete skill content (used as-is) |
| `guidance.md` | Auto-generated skills | Appended after command blocks |
| `extra_commands.md` | Auto-generated skills | Inserted before auto-generated command blocks |

## Common workflows

### Update the plugin after model changes

When `control-plane.json` or `data-plane.json` changes:

```bash
cargo run --example generate_plugin -- --output /path/to/zilliz-plugin
cd /path/to/zilliz-plugin
git diff  # review changes
```

### Add a new skill

1. Add the resource to `control-plane.json` or `data-plane.json`
2. Add a skill entry in `scripts/skill_config.yaml`
3. Optionally create `scripts/skill_overlays/<skill>/guidance.md`
4. Regenerate: `cargo run --example generate_plugin -- --output /path/to/zilliz-plugin`

### Add guidance to an existing skill

1. Create or edit `scripts/skill_overlays/<skill>/guidance.md`
2. Regenerate

### CI drift detection

Add to CI pipeline to ensure the plugin repo stays in sync:

```bash
cargo run --example generate_plugin -- --check /path/to/zilliz-plugin
```

Non-zero exit code means the plugin needs regeneration.