DSL 参考

底层状态机 DSL 完整语法

基础结构

{
    "name": "状态机名称",
    "initial": "初始状态名",
    "event_sources": ["message_queue"],
    "states": { ... }
}

字段	类型	必需	说明
name	string	✅	状态机名称
initial	string	✅	初始状态
event_sources	string[]	❌	事件源列表，默认 ["message_queue"]
states	object	✅	状态定义字典

状态定义

字段	类型	说明
transitions	array	转换规则列表
on_enter	string	进入此状态时执行的动作名
on_exit	string	离开此状态时执行的动作名
compound	bool	是否复合状态
states	object	子状态定义（compound: true 时需要）
concurrent_tasks	array	并发后台任务

Transition

{
    "event": "EVENT_NAME",
    "target": "目标状态",
    "action": "动作名",
    "guard": "守卫函数名",
    "timeout": 5.0,
    "on_timeout": "动作名"
}

字段	类型	必需	说明
event	string	✅	触发事件
target	string	✅	目标状态
action	string	❌	转换时执行的动作
guard	string	❌	守卫函数，返回 True 才允许转换
timeout	float	❌	超时秒数
on_timeout	string	❌	超时回调动作

守卫

async def only_if_ready(ctx):
    return ctx.get("is_ready", False)

{"event": "NEXT", "target": "working", "guard": "only_if_ready"}

并发任务

进入状态时自动启动，离开时自动取消：

{
    "concurrent_tasks": [
        {"task": "heartbeat", "interval": 5.0}
    ]
}

async def heartbeat(ctx):
    logger.info(f"[{ctx['agent_id']}] 心跳...")

事件冒泡

复合状态中子状态未匹配的事件自动冒泡到父状态。

Parent (compound: true)         ← 冒泡
├── Child_A
├── Child_B
└── transitions: [PARENT_EVENT]

完整 DSL 示例

{
    "name": "Negotiator",
    "initial": "idle",
    "states": {
        "idle": {
            "transitions": [
                {"event": "START", "target": "negotiating", "action": "start_nego"}
            ]
        },
        "negotiating": {
            "on_enter": "decide",
            "concurrent_tasks": [
                {"task": "heartbeat", "interval": 5.0}
            ],
            "transitions": [
                {"event": "PROPOSE", "target": "negotiating", "action": "decide"},
                {"event": "ACCEPT",  "target": "completed",  "action": "on_accept"},
                {"event": "REJECT",  "target": "failed",     "action": "on_reject"},
                {"event": "TIMEOUT", "target": "failed",     "timeout": 30.0}
            ]
        },
        "completed": {"on_enter": "log_end"},
        "failed":    {"on_enter": "log_end"}
    }
}