什么是 vvvv Spreads？

Spread 是 vvvv gamma 中基础的不可变集合类型，在概念上类似于 ImmutableArray。该技能为 AI 代理提供了编写地道 vvvv 代码所需的特定技术约束和模式，例如强制执行值语义、循环索引以及集合严格非空的原则。通过利用 Openclaw Skills，开发人员可以确保其 AI 生成的 C# 代码与 vvvv 的可视化编程架构无缝集成。

该技能通过引导代理使用 SpreadBuilder 进行集合构建以及使用 ReadOnlySpan 进行热路径数据处理，将性能和内存管理放在首位。它确保集合得到高效处理，避免了常见的陷阱，如不必要的 LINQ 分配或在数据流上下文中不当的空值处理。

下载入口:https://github.com/openclaw/skills/tree/main/skills/tebjan/vvvv-spreads

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

vvvv Spreads 应用场景

• 实现需要高效集合处理的自定义 C# ProcessNode。
• 将标准 .NET 列表或数组转换为 vvvv 兼容的 Spread 结构。
• 创建最小化垃圾回收的高性能仿真数据流水线。
• 使用 Openclaw Skills 开发用于在 vvvv gamma 中映射、过滤和压缩多个数据流的逻辑。

1. AI 代理在 vvvv 开发上下文中检测与集合相关的关键词，如“数组”或“列表”。
2. 该技能强制要求使用 Spread 作为主要的集合类型，以确保不可变性和值等价性。
3. 对于集合创建，代理采用 SpreadBuilder 模式，根据预期计数预分配内存。
4. 映射、过滤或压缩等逻辑操作通过优化的 foreach 循环或基于索引的访问来实现。
5. 代理应用性能规则，例如用于更改检测的引用相等性检查，以及在性能关键部分避免使用 LINQ。

vvvv Spreads 配置指南

要在开发工作流中利用此技能，请确保您的 AI 代理已配置 vvvv gamma 的 Openclaw Skills 上下文。您可以通过确保 C# 项目引用核心 vvvv 库来初始化环境。

# 确保您的 VL 项目环境处于活动状态
# 代理使用这些模式进行代码生成：
# - 使用 Spread.Empty 进行初始化
# - 为所有变更实现 SpreadBuilder

vvvv Spreads 数据架构与分类体系

该技能专注于通过以下不可变结构和模式管理数据：

name: vvvv-spreads
description: "Helps write code using vvvv gamma's Spread immutable collection type and SpreadBuilder. Use when working with Spreads, SpreadBuilder, collections, arrays, iteration, mapping, filtering, zipping, accumulating, or converting between Span and Spread. Trigger whenever the user writes collection-processing C# code in vvvv — even if they say 'list', 'array', or 'IEnumerable' instead of Spread, this skill likely applies."
license: CC-BY-SA-4.0
compatibility: Designed for coding AI agents assisting with vvvv gamma development
metadata:
  author: Tebjan Halm
  version: "1.1"

vvvv Spreads

What Are Spreads

Spread is vvvv's immutable collection type, conceptually similar to ImmutableArray. It is the primary way to pass collections between nodes.

Key properties:

• Immutable — never modify in place, always create new spreads
• Value semantics — two spreads with same elements are considered equal
• Cyclic indexing — in visual patches, indexing wraps around (not in C# API)
• Never null — use Spread.Empty instead of null

Creating Spreads

SpreadBuilder (Primary Method)

var builder = new SpreadBuilder(expectedCount);
for (int i = 0; i < count; i++)
    builder.Add(ComputeValue(i));
Spread result = builder.ToSpread();

From Existing Data

// From array (extension method)
Spread fromArray = new int[] { 1, 2, 3 }.ToSpread();

// From array (static factory)
Spread fromResult = Spread.Create(resultArray);

// Empty spread (NEVER use null)
Spread empty = Spread.Empty;

// Single element
var single = new SpreadBuilder(1);
single.Add(42f);
Spread one = single.ToSpread();

Accessing Elements

// Always check Count before indexing
if (spread.Count > 0)
{
    float first = spread[0];
    float last = spread[spread.Count - 1];
}

// Iterate (preferred — no allocation)
foreach (var item in spread)
    Process(item);

// Index access in loop
for (int i = 0; i < spread.Count; i++)
    Process(spread[i]);

Common Patterns in C#

Map (Transform Each Element)

public static Spread Scale(Spread input, float factor = 1f)
{
    var builder = new SpreadBuilder(input.Count);
    foreach (var value in input)
        builder.Add(value * factor);
    return builder.ToSpread();
}

Filter

public static Spread FilterAbove(Spread input, float threshold = 0.5f)
{
    var builder = new SpreadBuilder();
    foreach (var value in input)
    {
        if (value > threshold)
            builder.Add(value);
    }
    return builder.ToSpread();
}

Zip (Process Two Spreads Together)

public static Spread Add(Spread a, Spread b)
{
    int count = Math.Max(a.Count, b.Count);
    var builder = new SpreadBuilder(count);
    for (int i = 0; i < count; i++)
    {
        float va = a.Count > 0 ? a[i % a.Count] : 0f;
        float vb = b.Count > 0 ? b[i % b.Count] : 0f;
        builder.Add(va + vb);
    }
    return builder.ToSpread();
}

Accumulate (Running Total)

public static Spread RunningSum(Spread input)
{
    var builder = new SpreadBuilder(input.Count);
    float sum = 0f;
    foreach (var value in input)
    {
        sum += value;
        builder.Add(sum);
    }
    return builder.ToSpread();
}

ReadOnlySpan as High-Performance Alternative

For hot-path output (e.g., per-frame simulation data), ReadOnlySpan avoids allocation entirely:

[ProcessNode]
public class ParticleSimulator
{
    private ParticleState[] _states;

    public ReadOnlySpan Update(SimulationConfig config, float deltaTime)
    {
        // Simulate into pre-allocated array — zero allocation
        Simulate(_states, config, deltaTime);
        return _states.AsSpan();
    }
}

Use Spread for infrequent config inputs; use ReadOnlySpan for high-frequency frame data.

Performance Rules

• Pre-allocate builder: new SpreadBuilder(expectedCount) when count is known
• No LINQ in hot paths: .Where(), .Select(), .ToList() create hidden allocations
• Cache spreads: If output doesn't change, return the cached spread reference
• Avoid repeated .ToSpread(): Build once, output the result
• For large spreads: Consider Span internally, convert to Spread at the API boundary
• Spread change detection: Since Spreads are immutable, reference equality (!= or ReferenceEquals) is sufficient — if the reference changed, the content changed

Spreads in ProcessNodes

[ProcessNode]
public class SpreadProcessor
{
    private Spread _lastInput = Spread.Empty;
    private Spread _cachedOutput = Spread.Empty;

    public void Update(
        out Spread output,
        Spread input = default)
    {
        input ??= Spread.Empty;

        if (!ReferenceEquals(input, _lastInput))
        {
            var builder = new SpreadBuilder(input.Count);
            foreach (var v in input)
                builder.Add(v * 2f);
            _cachedOutput = builder.ToSpread();
            _lastInput = input;
        }

        output = _cachedOutput;
    }
}

For more code examples, see examples.md.