Back to Details

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

核心概念

ConceptDetails
ParticipantsMin 2 required. Each has 
id
, 
name
. 
id
is referenced by 
action.sender
ActionsSequential IDs starting at 0. One must have 
isStartingAction: true
RoutesDefine flow between actions. 
nextActionIds: []
= workflow completion
DataSchemasJSON Schema for action payload. 
IEnumerable<JsonDocument>
in C#
ConditionsJSON Logic expressions for conditional routing
CalculationsJSON Logic for computed values (e.g., 
requiresApproval
)
CyclesAllowed 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

蓝图验证规则

  1. Participant references: Every 
    action.sender
    must reference a valid 
    participant.id
  2. Action count: At least 1 action required
  3. Participant count: At least 2 participants required (enforced by 
    BlueprintBuilder.Build()
    )
  4. Description length: Min 5 characters
  5. Title length: Min 3 characters
  6. Cycles: Detected but allowed — produce warnings, not errors
  1. 参与者引用：每个
    action.sender
    必须引用有效的
    participant.id
  2. 动作数量：至少需要1个动作
  3. 参与者数量：至少需要2个参与者（由
    BlueprintBuilder.Build()
    强制执行）
  4. 描述长度：最少5个字符
  5. 标题长度：最少3个字符
  6. 循环：会被检测但允许存在——仅生成警告，而非错误

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

蓝图发布流程

  1. POST /api/blueprints/
    — Create draft blueprint
  2. POST /api/blueprints/{id}/publish
    — Publish (validates, returns warnings for cycles)
  3. POST /api/instances/
    — Create instance with participant wallet mappings
  1. POST /api/blueprints/
    —— 创建草稿蓝图
  2. POST /api/blueprints/{id}/publish
    —— 发布（会进行验证，循环会返回警告）
  3. 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

文件位置

FilePurpose
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
启动时的模板初始化服务

See Also

另请参阅

  • patterns - Blueprint design patterns and examples
  • workflows - Publishing and execution workflows
  • patterns - 蓝图设计模式与示例
  • workflows - 发布与执行工作流

Related Skills

相关技能

  • dotnet - .NET 10 / C# 13 patterns
  • minimal-apis - Blueprint Service endpoint definitions
  • xunit - Testing blueprint validation
  • blazor - Template library UI pages
  • dotnet - .NET 10 / C# 13 模式
  • minimal-apis - 蓝图服务端点定义
  • xunit - 蓝图验证测试
  • blazor - 模板库UI页面