blueprint-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blueprint Builder Skill

Blueprint Builder 技能

Sorcha blueprints define multi-participant workflows as JSON documents. Each blueprint has participants, actions (with data schemas), and routes that determine the action flow. Templates wrap blueprints with parameterization for reuse.

Sorcha 蓝图将多参与者工作流定义为JSON文档。每个蓝图包含参与者、动作（附带数据模式）以及决定动作流转的路由。模板通过参数化封装蓝图，以实现复用。

Quick Start

快速开始

Minimal Blueprint (Two-Party, No Cycles)

最简蓝图（两方参与，无循环）

json

{
  "id": "my-blueprint",
  "title": "My Workflow",
  "description": "A simple two-participant workflow (min 5 chars)",
  "version": 1,
  "metadata": { "category": "demo" },
  "participants": [
    { "id": "sender", "name": "Sender", "description": "Initiates the workflow" },
    { "id": "receiver", "name": "Receiver", "description": "Receives and completes" }
  ],
  "actions": [
    {
      "id": 0,
      "title": "Submit",
      "sender": "sender",
      "isStartingAction": true,
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "message": { "type": "string", "minLength": 1 }
          },
          "required": ["message"]
        }
      ],
      "routes": [
        { "id": "to-receiver", "nextActionIds": [1], "isDefault": true }
      ]
    },
    {
      "id": 1,
      "title": "Complete",
      "sender": "receiver",
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "status": { "type": "string", "enum": ["accepted", "rejected"] }
          },
          "required": ["status"]
        }
      ],
      "routes": []
    }
  ]
}

json

{
  "id": "my-blueprint",
  "title": "My Workflow",
  "description": "A simple two-participant workflow (min 5 chars)",
  "version": 1,
  "metadata": { "category": "demo" },
  "participants": [
    { "id": "sender", "name": "Sender", "description": "Initiates the workflow" },
    { "id": "receiver", "name": "Receiver", "description": "Receives and completes" }
  ],
  "actions": [
    {
      "id": 0,
      "title": "Submit",
      "sender": "sender",
      "isStartingAction": true,
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "message": { "type": "string", "minLength": 1 }
          },
          "required": [ "message" ]
        }
      ],
      "routes": [
        { "id": "to-receiver", "nextActionIds": [1], "isDefault": true }
      ]
    },
    {
      "id": 1,
      "title": "Complete",
      "sender": "receiver",
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "status": { "type": "string", "enum": [ "accepted", "rejected" ] }
          },
          "required": [ "status" ]
        }
      ],
      "routes": []
    }
  ]
}

Cyclic Blueprint (Looping Workflow)

循环蓝图（循环工作流）

json

{
  "metadata": { "hasCycles": "true" },
  "actions": [
    {
      "id": 0, "title": "Ping", "sender": "ping", "isStartingAction": true,
      "routes": [{ "id": "ping-to-pong", "nextActionIds": [1], "isDefault": true }]
    },
    {
      "id": 1, "title": "Pong", "sender": "pong",
      "routes": [{ "id": "pong-to-ping", "nextActionIds": [0], "isDefault": true }]
    }
  ]
}

Cycle detection produces warnings (not errors). Cyclic blueprints publish with

metadata["hasCycles"] = "true"

json

{
  "metadata": { "hasCycles": "true" },
  "actions": [
    {
      "id": 0, "title": "Ping", "sender": "ping", "isStartingAction": true,
      "routes": [{ "id": "ping-to-pong", "nextActionIds": [1], "isDefault": true }]
    },
    {
      "id": 1, "title": "Pong", "sender": "pong",
      "routes": [{ "id": "pong-to-ping", "nextActionIds": [0], "isDefault": true }]
    }
  ]
}

循环检测会生成警告（而非错误）。循环蓝图发布时需设置

metadata["hasCycles"] = "true"

。

Key Concepts

核心概念

Concept	Details
Participants	Min 2 required. Each has `id` , `name` . `id` is referenced by `action.sender`
Actions	Sequential IDs starting at 0. One must have `isStartingAction: true`
Routes	Define flow between actions. `nextActionIds: []` = workflow completion
DataSchemas	JSON Schema for action payload. `IEnumerable<JsonDocument>` in C#
Conditions	JSON Logic expressions for conditional routing
Calculations	JSON Logic for computed values (e.g., `requiresApproval` )
Cycles	Allowed with warning. Set `metadata.hasCycles = "true"`

概念	详情
参与者	至少需要2个。每个参与者包含 `id` 和 `name` 。 `id` 会被 `action.sender` 引用
动作	从0开始的连续ID。必须有一个动作设置 `isStartingAction: true`
路由	定义动作间的流转。 `nextActionIds: []` 表示工作流结束
DataSchemas	动作负载的JSON Schema。对应C#中的 `IEnumerable<JsonDocument>`
条件	用于条件路由的JSON Logic表达式
计算	用于计算值的JSON Logic（例如 `requiresApproval` ）
循环	允许存在但会触发警告。需设置 `metadata.hasCycles = "true"`

Blueprint Validation Rules

蓝图验证规则

Participant references: Every
```
action.sender
```
must reference a valid
```
participant.id
```
Action count: At least 1 action required
Participant count: At least 2 participants required (enforced by
```
BlueprintBuilder.Build()
```
)
Description length: Min 5 characters
Title length: Min 3 characters
Cycles: Detected but allowed — produce warnings, not errors

参与者引用：每个
```
action.sender
```
必须引用有效的
```
participant.id
```
动作数量：至少需要1个动作
参与者数量：至少需要2个参与者（由
```
BlueprintBuilder.Build()
```
强制执行）
描述长度：最少5个字符
标题长度：最少3个字符
循环：会被检测但允许存在——仅生成警告，而非错误

Route Types

路由类型

Default Route (Always Taken)

默认路由（始终触发）

json

{ "id": "always", "nextActionIds": [1], "isDefault": true }

json

{ "id": "always", "nextActionIds": [1], "isDefault": true }

Conditional Route (JSON Logic)

条件路由（JSON Logic）

json

{
  "id": "approve-route",
  "nextActionIds": [2],
  "condition": { "==": [{ "var": "decision" }, "approved"] }
}

json

{
  "id": "approve-route",
  "nextActionIds": [2],
  "condition": { "==": [{ "var": "decision" }, "approved"] }
}

Terminal Route (Workflow Ends)

终止路由（工作流结束）

json

{ "id": "complete", "nextActionIds": [], "isDefault": true }

json

{ "id": "complete", "nextActionIds": [], "isDefault": true }

Parallel Branch (Multiple Next Actions)

并行分支（多个后续动作）

json

{
  "id": "parallel-review",
  "nextActionIds": [2, 3],
  "isDefault": true,
  "branchDeadline": "P7D"
}

json

{
  "id": "parallel-review",
  "nextActionIds": [2, 3],
  "isDefault": true,
  "branchDeadline": "P7D"
}

Route Precedence

路由优先级

Route-based routing (via

Action.Routes

) takes precedence over legacy condition-based routing (via

Action.Participants

). Always use

routes

for new blueprints.

基于

Action.Routes

的路由优先于基于

Action.Participants

的旧版条件路由。新蓝图请始终使用

routes

。

DataSchema Patterns

DataSchema 模式

String Field with Validation

带验证的字符串字段

json

{ "type": "string", "minLength": 1, "maxLength": 500, "title": "Message" }

json

{ "type": "string", "minLength": 1, "maxLength": 500, "title": "Message" }

Integer with Minimum

带最小值的整数

json

{ "type": "integer", "minimum": 1, "title": "Counter" }

json

{ "type": "integer", "minimum": 1, "title": "Counter" }

Enum (Fixed Choices)

枚举（固定选项）

json

{ "type": "string", "enum": ["approved", "rejected", "escalate"], "title": "Decision" }

json

{ "type": "string", "enum": [ "approved", "rejected", "escalate" ], "title": "Decision" }

Number with Threshold

带阈值的数字

json

{ "type": "number", "minimum": 0, "title": "Amount" }

json

{ "type": "number", "minimum": 0, "title": "Amount" }

Template Wrapper

模板封装器

Templates wrap blueprints for reuse with optional parameterization:

json

{
  "id": "template-id",
  "title": "Template Title",
  "description": "What this template does (min 5 chars)",
  "version": 1,
  "category": "demo|approval|finance|supply-chain",
  "tags": ["tag1", "tag2"],
  "author": "Sorcha Team",
  "published": true,
  "template": { /* raw blueprint JSON or JSON-e template */ },
  "parameterSchema": null,
  "defaultParameters": null,
  "examples": []
}

模板通过参数化封装蓝图以实现复用：

json

{
  "id": "template-id",
  "title": "Template Title",
  "description": "What this template does (min 5 chars)",
  "version": 1,
  "category": "demo|approval|finance|supply-chain",
  "tags": [ "tag1", "tag2" ],
  "author": "Sorcha Team",
  "published": true,
  "template": { /* raw blueprint JSON or JSON-e template */ },
  "parameterSchema": null,
  "defaultParameters": null,
  "examples": []
}

Fixed Template (No Parameters)

固定模板（无参数）

Set

parameterSchema: null

— the

template

field contains the raw blueprint JSON directly. Used for simple blueprints like Ping-Pong.

设置

parameterSchema: null

——

template

字段直接包含原始蓝图JSON。适用于Ping-Pong这类简单蓝图。

Parameterized Template (JSON-e)

参数化模板（JSON-e）

Uses JSON-e expressions (

$eval

$if

$flattenDeep

) in the

template

field. Requires

parameterSchema

(JSON Schema),

defaultParameters

, and

examples

JSON-e expressions:

```
{ "$eval": "paramName" }
```
— substitute parameter value

{ "$if": "condition", "then": ..., "else": ... }

— conditional inclusion

```
{ "$flattenDeep": [...] }
```
— flatten nested arrays (for conditional participants/actions)

在

template

字段中使用JSON-e表达式（

$eval

、

$if

、

$flattenDeep

）。需要

parameterSchema

（JSON Schema）、

defaultParameters

和

examples

。

JSON-e表达式：

```
{ "$eval": "paramName" }
```
—— 替换参数值

{ "$if": "condition", "then": ..., "else": ... }

—— 条件包含

```
{ "$flattenDeep": [...] }
```
—— 展平嵌套数组（用于条件性参与者/动作）

Blueprint Publishing Flow

蓝图发布流程

```
POST /api/blueprints/
```
— Create draft blueprint
```
POST /api/blueprints/{id}/publish
```
— Publish (validates, returns warnings for cycles)
```
POST /api/instances/
```
— Create instance with participant wallet mappings

```
POST /api/blueprints/
```
—— 创建草稿蓝图
```
POST /api/blueprints/{id}/publish
```
—— 发布（会进行验证，循环会返回警告）
```
POST /api/instances/
```
—— 创建实例并映射参与者钱包

Publish Response (with cycle warning)

发布响应（含循环警告）

json

{
  "blueprintId": "...",
  "version": 1,
  "publishedAt": "...",
  "warnings": ["Cyclic route detected: action 0 → action 1 → action 0. This blueprint will loop indefinitely unless routing conditions provide a termination path."]
}

json

{
  "blueprintId": "...",
  "version": 1,
  "publishedAt": "...",
  "warnings": [ "Cyclic route detected: action 0 → action 1 → action 0. This blueprint will loop indefinitely unless routing conditions provide a termination path." ]
}

Action Execution

动作执行

POST /api/instances/{id}/actions/{actionId}/execute
Headers: Authorization: Bearer <token>, X-Delegation-Token: <token>
Body: {
  "blueprintId": "string",
  "actionId": "string",
  "instanceId": "string",
  "senderWallet": "string",
  "registerAddress": "string",
  "payloadData": { "message": "hello", "counter": 1 }
}

Engine pipeline: validate (schema check) → calculate (JSON Logic) → route (determine next) → disclose (visibility rules)

POST /api/instances/{id}/actions/{actionId}/execute
Headers: Authorization: Bearer <token>, X-Delegation-Token: <token>
Body: {
  "blueprintId": "string",
  "actionId": "string",
  "instanceId": "string",
  "senderWallet": "string",
  "registerAddress": "string",
  "payloadData": { "message": "hello", "counter": 1 }
}

引擎流水线：验证（模式检查）→ 计算（JSON Logic）→ 路由（确定下一步）→ 披露（可见性规则）

Common Patterns

常见模式

Approval Chain (Linear)

审批链（线性）

Submit(requester) → Review(manager) → Approve(director) → Complete

Submit(requester) → Review(manager) → Approve(director) → Complete

Ping-Pong (Cyclic)

Ping-Pong（循环）

Ping(A) → Pong(B) → Ping(A) → Pong(B) → ... (indefinite)

Ping(A) → Pong(B) → Ping(A) → Pong(B) → ... (无限循环)

Conditional Branching

条件分支

Submit → [amount > 10000] → Director Approval
Submit → [amount <= 10000] → Manager Approval
Both → Complete

Submit → [金额 > 10000] → 总监审批
Submit → [金额 <= 10000] → 经理审批
两者最终都指向 → 完成

File Locations

文件位置

File	Purpose
`examples/templates/*.json`	Built-in template JSON files
`src/Common/Sorcha.Blueprint.Models/`	Blueprint, Action, Route, Participant models
`src/Common/Sorcha.Blueprint.Models/BlueprintTemplate.cs`	Template model
`src/Core/Sorcha.Blueprint.Engine/`	Execution engine (validate/calculate/route/disclose)
`src/Core/Sorcha.Blueprint.Fluent/`	Fluent API for programmatic blueprint creation
`src/Services/Sorcha.Blueprint.Service/Program.cs`	PublishService, ValidateBlueprint, DetectCycles
`src/Services/Sorcha.Blueprint.Service/Templates/TemplateSeedingService.cs`	Startup seeding

文件	用途
`examples/templates/*.json`	内置模板JSON文件
`src/Common/Sorcha.Blueprint.Models/`	蓝图、动作、路由、参与者模型
`src/Common/Sorcha.Blueprint.Models/BlueprintTemplate.cs`	模板模型
`src/Core/Sorcha.Blueprint.Engine/`	执行引擎（验证/计算/路由/披露）
`src/Core/Sorcha.Blueprint.Fluent/`	用于程序化创建蓝图的Fluent API
`src/Services/Sorcha.Blueprint.Service/Program.cs`	发布服务、蓝图验证、循环检测
`src/Services/Sorcha.Blueprint.Service/Templates/TemplateSeedingService.cs`	启动时的模板初始化服务

另请参阅

patterns - Blueprint design patterns and examples
workflows - Publishing and execution workflows

patterns - 蓝图设计模式与示例
workflows - 发布与执行工作流

blueprint-builder

Original

Translation

Blueprint Builder Skill

Blueprint Builder 技能

Quick Start

快速开始

Minimal Blueprint (Two-Party, No Cycles)

最简蓝图（两方参与，无循环）

Cyclic Blueprint (Looping Workflow)

循环蓝图（循环工作流）

Key Concepts

核心概念

Blueprint Validation Rules

蓝图验证规则

Route Types

路由类型

Default Route (Always Taken)

默认路由（始终触发）

Conditional Route (JSON Logic)

条件路由（JSON Logic）

Terminal Route (Workflow Ends)

终止路由（工作流结束）

Parallel Branch (Multiple Next Actions)

并行分支（多个后续动作）

Route Precedence

路由优先级

DataSchema Patterns

DataSchema 模式

String Field with Validation

带验证的字符串字段

Integer with Minimum

带最小值的整数

Enum (Fixed Choices)

枚举（固定选项）

Number with Threshold

带阈值的数字

Template Wrapper

模板封装器

Fixed Template (No Parameters)

固定模板（无参数）

Parameterized Template (JSON-e)

参数化模板（JSON-e）

Blueprint Publishing Flow

蓝图发布流程

Publish Response (with cycle warning)

发布响应（含循环警告）

Action Execution

动作执行

Common Patterns

常见模式

Approval Chain (Linear)

审批链（线性）

Ping-Pong (Cyclic)

Ping-Pong（循环）

Conditional Branching

条件分支

File Locations

文件位置

See Also

另请参阅

Related Skills

相关技能