Divooka SDK

Divooka 中的每个节点都是 .NET。一个包就是一个 .NET 库，一个节点类别就是其中的一个类型，而一个节点就是这些类型的一个方法、构造函数或属性：Audio Processing 中的 Tone 就是方法 AudioGenerators.Tone。Divooka SDK 就是从代码中使用这些库，并配合 Divooka Compute 为此附带的工具：可以导入 Divooka 的包和文档的 C# 和 Python、用于构建的 .NET SDK，以及运行文档或将其构建为程序的工具。

代码能做图所做的事，调用的也是同样的函数，而且还能用到包没有放在节点面板上的内容。反过来也行得通：代码可以把文档的图当作函数来调用，而你用 C# 编写的库可以变成节点。

Divooka Compute 附带的内容

	用途
包	Divooka Compute 提供的每个包，各自是其文件夹中的一个 .NET 库；该文件夹中的 `divooka.distribution.json` 列出了它们。
`pure`	Divooka Pure：C# 脚本和交互式提示符，可导入 Divooka 的工作负载、包和文档。
`spy`	SteelPython：Python 3.12，同样可以导入它们。
`luna`	Lua 5.2 脚本和交互式提示符。
`dotnet`	一个 .NET SDK，位于 `Tools\dotnet10`：它用于构建 C# 项目，以及 Publish 生成的程序。
`stew`	从命令行运行文档——请参阅 Stewer。
`AviatorBeta`	像 Publish 一样，将文档构建为独立的程序——请参阅导出程序。
`divooka-mcp`	让 AI 助手通过 Model Context Protocol 编写、检查和运行 Divooka 文档；`divooka-mcp --help` 会列出 `--config` 能为哪些助手打印配置。
`dvn`	将笔记本文档作为网页提供服务——请参阅 Divooka Notebook。

在 Divooka Compute 的 Terminal（终端）标签页（Ctrl+Shift+`）中，无论使用哪种 shell，都可以直接按名称启动它们：每个会话的 PATH 都以 Divooka Compute 的文件夹开头，其后是它的 .NET SDK。在编辑器之外的命令行中，请从该文件夹运行它们，或者将该文件夹添加到你的 PATH 中。

C#：Divooka Pure

pure script.cs 运行一个 C# 脚本——从第一行起就是语句，不需要项目，也不需要 Main——而单独运行 pure 会打开一个交互式提示符。Import 用于引入 Divooka：

Import(Divooka.Workloads.AudioProcessing)
var tone = AudioGenerators.Tone(440, 0.5);         // the node Tone
Console.WriteLine(AudioAnalysis.Duration(tone));    // 0.5

Import("Examples/Computational Algorithms/Euclidean Algorithm.dvk")
EuclideanAlgorithm.Run("48", "18");                // the document, run as stew runs it

要导入	写法
一个包：以其节点为方法的那些类型	`Import(Divooka.Workloads.AudioProcessing)`——使用其库的名称，或 Divooka Compute 显示它时所用的名称
一个工作负载：它列出的每个包	`Import(audio-processing)`——使用其 id 或名称
一个文档：以文档命名的类，其中的每个 Function、Routine 和 Construct 各对应一个方法，并有一个运行整个文档的 `Run`	`Import("Examples/Audio/Tones and Noise.dvk")`——位于脚本旁边、工作文件夹中或 Divooka Compute 文件夹中的路径

节点要通过其类型来调用——写 AudioGenerators.Tone，而不是单独的 Tone——因为两个类型可能各自有一个同名节点。在提示符中输入 :packages 会列出 Divooka Compute 附带的工作负载和包。其余功能属于 Pure 本身：用 Include 引入另一个脚本、通过 Import 使用 NuGet 包，以及提示符的按键操作。

Python：SteelPython

import Divooka.Workloads.AudioProcessing as audio

tone = audio.AudioGenerators.Tone(440, 0.5)
print(audio.AudioAnalysis.Duration(tone))          # 0.5

spy script.py 运行一个脚本，单独运行 spy 则打开一个交互式提示符。Divooka 的包、工作负载和文档可以作为 Python 模块导入，而机器上无需安装 Python：请参阅 Python。

编辑器中的脚本

在 Divooka Compute 中打开一个 .cs 或 .lua 文件，它的工具栏提供两种运行方式：

Run（运行，F5）以终端的方式运行它，使用 pure 或 luna，在文件所在的文件夹中运行；它打印的内容会显示在停靠栏的 Console 中。
Automate Editor 在编辑器内部运行它，并提供 Editor 供其操作：打开的文档、文档中的图、节点和连线、当前选择、视图以及状态栏。它所做的每项更改都与你亲手编辑的效果相同，整个运行过程在文档历史中算作一步——Run script GridLayout.cs——按一次 Ctrl+Z 即可撤消；运行失败或被中止时，所有文档都保持原样。断点（F9）会让它暂停，其变量显示在 Locals 中。

下面的脚本会运行一个文件夹中的每个文档，并报告每个文档的运行情况：

var documents = Editor.FindDocuments("Documents");   // a folder beside this script
int failed = 0;
for (int index = 0; index < documents.Length; index++)
{
    Editor.Status($"Running {index + 1} of {documents.Length}: {Path.GetFileName(documents[index])}");
    var result = Editor.Run(documents[index]);
    Console.WriteLine(result);
    if (!result.Succeeded)
        failed++;
}
Console.WriteLine($"{documents.Length - failed} of {documents.Length} ran to the end.");

Lua 拥有相同的成员，使用冒号调用：graph:AddNode("Print Line", 0, 0)。New from examples 中的 Editor Automation 下还有更多示例，其中包括两种语言版本的 Grid Layout。

C# 项目

你自己的程序或库就是一个普通的 C# 项目，它从 Divooka Compute 的文件夹中引用 Divooka 的库——请将下面的 DivookaCompute 设置为你的安装位置。终端中的 dotnet 无需安装其他任何东西即可构建它；dotnet new console -n ToneLength 可以新建一个项目。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <DivookaCompute>C:\Divooka Compute</DivookaCompute>
  </PropertyGroup>

  <ItemGroup>
    <Reference Include="$(DivookaCompute)\Divooka.Audio.Operations.dll" />
    <Reference Include="$(DivookaCompute)\Divooka.Multimedia.Audio.dll" />
    <Reference Include="$(DivookaCompute)\Divooka.Sounds.Procedural.dll" />
  </ItemGroup>

</Project>

using Divooka.Audio.Operations;

var tone = AudioGenerators.Tone(440, 0.5);
Console.WriteLine(AudioAnalysis.Duration(tone));     // 0.5

dotnet run 会构建它（同时从同一文件夹复制这些库所用到的内容）并运行它。你的代码用到了哪个库中的类型，就要引用哪个库；缺少某个库时，编译器会指出是哪一个：The type 'WAVAudioPayload' is defined in an assembly that is not referenced. You must add a reference to assembly 'Divooka.Multimedia.Audio'。Divooka 的库是为 .NET 10 构建的，因此项目的目标框架为 net10.0。其中一些库也发布在 NuGet 上。

把你自己的库做成节点

反过来，你用 C# 编写的内容也可以变成节点。Add reference（添加引用，Ctrl+Shift+L）通过 Script 添加 C# 文件，通过 DLL 添加你构建好的库——请参阅引用。两者在 Divooka Compute 和 Divooka Engine 中都适用；Divooka Engine 只内置了必不可少的节点，其余节点需要你通过这种方式自行引入。

Add reference 卡片：筛选框、各工作负载及其带来的包，以及 DLL、Script、Document 和 NuGet 按钮

using System;

namespace Geometry;

/// <summary>Measures of a circle.</summary>
public static class Circles
{
    /// <summary>The area of a circle.</summary>
    /// <param name="radius">How far the edge is from the centre.</param>
    public static double Area(double radius) => Math.PI * radius * radius;

    /// <summary>The length of a circle's edge.</summary>
    /// <name>Circumference</name>
    /// <returns name="Length">The length.</returns>
    public static double EdgeLength(double radius) => 2 * Math.PI * radius;
}

使用 <GenerateDocumentationFile>true</GenerateDocumentationFile> 构建为 Geometry.dll，并在旁边放置 Geometry.xml 后引用，它会提供一个 Geometry 分区，其中包含一个 Circles 类别：Area 接受半径，其工具提示为 The area of a circle.；Circumference 的输出为 Length。

库中的内容	变成
公共类型	一个同名类别，位于以文件命名的分区中。
公共静态方法	一个在所有图中都可用的节点：其参数是节点的输入，其返回值是节点的输出。
`out` 参数	多一个输出。
公共构造函数	一个创建该类型对象的节点，名称为 Make 加类型名——Make Tally。
公共属性	一个读取该属性的节点，在所有图中都可用。
公共实例方法	一个以对象作为第一个输入的节点，在 Routine、Events 图和状态中可用，这些地方的操作是一个接一个发生的。如果方法不改变任何东西，可以将其标记为 `<const>true</const>`，这样它在所有图中都可用。
泛型方法	一个为每个类型实参各带一个选择块的节点：在其上选择类型，或者由连入的值来决定。
`<summary>`	节点的工具提示。
`<name>`	节点的标题，用来代替其成员名——否则成员名会被拆分为单词显示：`DiameterOf` 显示为 Diameter Of。
`<returns name="...">`	其输出的名称。
`<hidden>true</hidden>`	使该节点不出现在节点面板上；已经使用它的文档仍可正常打开和运行。

对于库，只有当其文档文件放在旁边时，文档注释中的标签才会生效。通过 Script 引用的 C# 文件会在文档打开时编译，无需 .NET SDK，其节点名称取自代码。在其旁边放置文档文件的译本——采用相同格式的 Geometry.zh.xml——即可为节点提供中文文字。C# 技巧中介绍了更多标签。

插件

编辑器插件会在编辑器工具栏的扳手图标下添加命令，也可以提供节点。插件是一个文件夹，位于程序旁边的 Plugins 中，或位于你自己的 %AppData%\DivookaCompute\Plugins 中（Divooka Engine 为 %AppData%\DivookaEngine\Plugins），右键单击扳手即可打开该文件夹；当你的文件夹中的插件与程序旁边的插件同名时，以你的为准。该文件夹包含 C# 文件（编辑器在启动时编译它们，无需项目，也无需 .NET SDK），或者包含一个以文件夹命名的库。随附的示例 Plugins\SayHello\SayHello.cs 就是一个完整的插件：

[DivookaPlugin("Hello Plugin", Category = PluginMenuCategories.Samples)]
public static class SayHello
{
    [PluginCommand("Say hello", Tooltip = "Writes a line in the status bar, to show that a plugin's command ran.")]
    [PluginText("Chinese", "打个招呼")]
    public static void Greet(PluginMenuContext context)
        => context.Status("Hello from the sample plugin.");
}

它的命令位于扳手下的 Samples ▸ Hello Plugin ▸ Say hello。插件会在编辑器下次启动时被加载；请参阅插件。

另请参阅

Python——SteelPython，以及作为 Python 模块导入的 Divooka。
引用——文档在语言之外所使用的内容，以及如何添加它们。
导出程序——Publish、stew，以及将文档打包交给他人。
Divooka Engine——只带有必不可少节点的编辑器，用于构建你自己的发行版。