AgentSkillsCN

synapse-action-development

讲解如何创建 Synapse 插件动作。当用户询问“创建一个动作”、“编写一个动作”、使用“@action 装饰器”、“BaseAction 类”、“基于函数的动作”、“基于类的动作”、“Pydantic 参数”、“ActionPipeline”、“DataType”、“input_type”、“output_type”、“语义类型”、“YOLO 数据集”、“模型权重”、“管道串联”,或需要帮助进行 Synapse 插件动作开发时,可选用此技能。

SKILL.md
--- frontmatter
name: synapse-action-development
description: Explains how to create Synapse plugin actions. Use when the user asks to "create an action", "write an action", uses "@action decorator", "BaseAction class", "function-based action", "class-based action", "Pydantic params", "ActionPipeline", "DataType", "input_type", "output_type", "semantic types", "YOLODataset", "ModelWeights", "pipeline chaining", or needs help with synapse plugin action development.

Synapse Action Development

Synapse SDK provides two patterns for plugin actions: function-based (simple, stateless) and class-based (complex, stateful).

Quick Start: Function-Based Action

python
from pydantic import BaseModel
from synapse_sdk.plugins.decorators import action
from synapse_sdk.plugins.context import RuntimeContext

class TrainParams(BaseModel):
    epochs: int = 10
    learning_rate: float = 0.001

@action(name='train', description='Train a model', params=TrainParams)
def train(params: TrainParams, ctx: RuntimeContext) -> dict:
    for epoch in range(params.epochs):
        ctx.set_progress(epoch + 1, params.epochs)
    return {'status': 'completed'}

Quick Start: Class-Based Action

python
from pydantic import BaseModel
from synapse_sdk.plugins.action import BaseAction

class InferParams(BaseModel):
    model_path: str
    threshold: float = 0.5

class InferAction(BaseAction[InferParams]):
    action_name = 'inference'

    def execute(self) -> dict:
        self.set_progress(0, 100)
        # Implementation here
        return {'predictions': []}

When to Use Each Pattern

CriteriaFunction-BasedClass-Based
ComplexitySimple, single-purposeComplex, multi-step
StateStatelessCan use helper methods
Semantic typesLimitedFull support

Recommendation: Start with function-based. Use class-based when needing helper methods or semantic type declarations.

@action Decorator Parameters

ParameterRequiredDescription
nameNoAction name (defaults to function name)
descriptionNoHuman-readable description
paramsNoPydantic model for parameter validation
resultNoPydantic model for result validation
categoryNoPluginCategory for grouping

Category Parameter Examples

python
from synapse_sdk.plugins.decorators import action
from synapse_sdk.plugins.constants import PluginCategory

# Training action
@action(
    name='train',
    category=PluginCategory.NEURAL_NET,
    description='Train object detection model'
)
def train(params, ctx):
    ...

# Export action
@action(
    name='export_coco',
    category=PluginCategory.EXPORT,
    description='Export to COCO format'
)
def export_coco(params, ctx):
    ...

# Smart tool (AI-assisted annotation)
@action(
    name='auto_segment',
    category=PluginCategory.SMART_TOOL,
    description='Auto-segmentation tool'
)
def auto_segment(params, ctx):
    ...

# Pre-annotation
@action(
    name='pre_label',
    category=PluginCategory.PRE_ANNOTATION,
    description='Pre-label with model predictions'
)
def pre_label(params, ctx):
    ...

Available Categories: NEURAL_NET, EXPORT, UPLOAD, SMART_TOOL, PRE_ANNOTATION, POST_ANNOTATION, DATA_VALIDATION, CUSTOM

BaseAction Class Attributes

AttributeDescription
action_nameAction name for invocation
categoryPluginCategory
input_typeSemantic input type for pipelines
output_typeSemantic output type for pipelines
params_modelAuto-extracted from generic
result_modelOptional result schema

Available Methods in BaseAction

  • self.params - Validated parameters
  • self.ctx - RuntimeContext
  • self.logger - Logger shortcut
  • self.set_progress(current, total, category) - Progress tracking
  • self.set_metrics(value, category) - Metrics recording
  • self.log(event, data, file) - Event logging

Additional Resources

For detailed patterns and advanced techniques: