主要特性

节点即原语

在 AmritaSense 中，一切皆是节点。条件判断、循环体、异常处理器、跳转目标——它们都是普通的 Python 函数或协程，由 @Node() 装饰器包装而成，无需特殊继承。

每个节点都被视为原子执行单元：它要么完全执行，要么完全不执行。工作流解释器通过指针向量（PointerVector）和调用栈管理节点间的跳转与嵌套，而非依赖图结构。所有高级控制流在编译期被展开为线性指令序列，运行时只有整数运算和函数调用。

流式优先

AmritaSense 内建了全双工流控基座 SuspendObjectStream，让流式控制流的编写像普通迭代一样自然：

• 原生挂起/恢复：工作流可在任意节点之间精确挂起，等待外部输入或异步操作完成后恢复执行。这套机制完全基于 Python 的 asyncio.Future，零阻塞开销
• 双向控制通道：支持外部系统通过 push_object 主动向工作流注入消息或指令，实现中断调用与上下文注入
• 与 LLM 流式生成天然适配：无论是工具调用循环、嵌套子工作流，还是挂起等待用户输入，都能以最直接的方式表达

原生控制流

AmritaSense 提供了一级公民的控制流指令集，无需依赖外部图引擎或状态机：

• 条件分支：IF / ELIF / ELSE，无需强制配对 ELSE，支持链式组合
• 循环结构：WHILE（前置条件）和 DO...WHILE（后置条件），支持 BreakLoop 跳出
• 跳转指令：JMP 配合 ALIAS 实现无条件跳转，INVOKE 配合 ARCHIVED_NODES 实现子程序调用与返回
• 异常处理：Try…CATCH…THEN…FINALLY，完整对齐 Python 的异常处理语义，支持异常穿透控制

原生控制流指令 NATIVE_IF / NATIVE_WHILE / NATIVE_DO / BREAK_LOOP 是传统指令的正交扩展，提供基于 PUSH/JMP/CONTINUE/BREAK_LOOP 的更底层控制流，可在需要精确指针控制的场景中使用。循环体统一以 CONTINUE() 结尾，BREAK_LOOP() / CONTINUE() 均为工厂函数。

所有控制流指令在编译期展开为底层节点组合，运行时完全通过指针偏移完成，无需图遍历、字符串路由或状态字典查找。

异步原生

• 全程支持 async/await，与 Python 现代异步生态无缝融合
• 工作流执行器基于 asyncio，所有 I/O 密集型操作均可非阻塞执行
• 挂起/恢复机制完全异步，不会阻塞事件循环
• 同步函数可通过 wrap_to_async 自动在线程池中执行，避免阻塞事件循环

声明式依赖注入

• 节点和事件处理器通过函数签名声明所需参数，框架自动从工作流上下文中解析
• 基于关键词优先 + 类型匹配的解析策略，告别位置参数的脆弱性
• 支持 Depends 声明自定义依赖工厂，灵活控制对象的创建与作用域
• 依赖清单（DependencyMeta）是纯数据结构，可缓存、可动态生成

自包含运行时

• 内建事件系统：工作流节点可触发自定义事件，事件处理器与节点共享同一套依赖注入机制。事件系统是发散式的，与工作流中断机制明确分工
• 内建日志系统：基于 loguru 的高性能日志器，支持环境变量控制日志级别、自动桥接标准库 logging
• 零外部强制依赖：核心引擎仅数千行代码，无重型抽象，仅依赖 aiologic 和 anyio
• 编译时展开高级结构：运行时开销几乎为零，可嵌入任何 Python 项目

解释器树与子图隔离

• FUN_BLOCK 指令 — 将已编译的 NodeCompose 作为隔离子工作流在子解释器中执行，拥有独立的中间件、I/O 流和生命周期。
• 解释器树模型 — fork_interpreter() 创建子解释器形成树结构；parent / top_interpreter / sub_interpreters 属性提供完整可见性。
• 并行执行 — 通过 asyncio.gather 或 wait_all 并发运行多个子解释器。
• 生命周期管理 — terminate() / terminate_all() 优雅关闭；is_running / pending_stop 状态查询。
• Unsafe 配置标志 — _unsafe.__flags__ 提供内部开关（FORCE_NOT_WRAP_TO_ASYNC、DISABLE_EXC_IGNORED 等），用于少数极端场景下调整引擎行为。

原生 Debugger 实现

AmritaSense 内置了一套完整的 REPL 调试器——无需额外安装插件或工具。它利用解释器原生的 Panic/Recover 机制和中间件注入，直接在 Python REPL 中实现断点、步进和状态检查。

• 双 API 设计 — 同步 API（step、cont）用于交互式 REPL；异步 API（step_async、cont_async）用于调试脚本和已有事件循环的程序
• 断点系统 — 按标签（break_at_tag）或地址（break_at_addr）设置断点，支持条件表达式
• 步进控制 — step()、step_over()、step_out()、cont()，支持同步/异步双 API
• 崩溃恢复 — 节点异常后 panic 状态完整保留，inspect() 查看现场，advance_pointer() 跳过崩溃节点后 cont() 恢复执行
• GDB 风格反汇编 — dis() 把编译后的图渲染为带地址的分段清单，=> 标记程序计数器；节点可通过 __sdb_dis__ / __sdb_cmt__ 魔术属性描述自己的助记符，stdout 为终端时清单会着色