sub_flow 子流程

适用版本：v4.0.8.3

sub_flow 的定位不是“自动继承父上下文”，而是把子流程当成一个隔离的组合节点接入父流程。

1. 核心心智模型

如何阅读这张图

capture 发生在父流程执行到该节点时。
子流程拿到的是一次性快照，不是 live binding。
write_back 只发生在子流程成功结束后。

2. 公开接口

python

parent.to_sub_flow(
    child_flow,
    capture={
        "input": "value",
        "runtime_data": {
            "draft": "runtime_data.draft",
        },
        "flow_data": {
            "locale": "flow_data.locale",
        },
        "resources": {
            "logger": "resources.logger",
        },
    },
    write_back={
        "value": "result.summary",
        "runtime_data": {
            "child_report": "result",
        },
        "flow_data": {
            "last_topic": "result.topic",
        },
    },
)

也可以直接：

python

parent.to(child_flow)

这等价于：

父 value 作为子流程输入
子流程 result 回到父 value

3. `capture` 的语义

可用目标 scope：

input
runtime_data
flow_data
resources

可用源路径根：

value
runtime_data.*
flow_data.*
resources.*

关键边界：

只捕获直接父流程当前可见上下文
只在执行到该节点时抓一次快照
不自动追溯“父的父”
不自动回写父流程

4. `write_back` 的语义

可用目标 scope：

value
runtime_data
flow_data

可用源路径根：

result
result.*

关键边界：

只根据子流程最终 result 回写
不直接暴露子流程内部 runtime_data / flow_data
不支持把资源对象写回父流程

5. 运行隔离

v4.0.8.3 的子流程执行模型是：

每次调用都会实例化一份隔离 child flow
child flow_state 不会串到下一次调用
child 修改自己的 state / flow_state，不会自动影响父流程
父子之间的数据关系由 capture / write_back 显式声明

这意味着 sub_flow 更像“可组合函数节点”，而不是“共享上下文的嵌套作用域”。

6. runtime stream 行为

默认情况下，child execution 的 runtime stream 会桥接到 parent execution。

这意味着：

子流程中 put_into_stream(...) 的事件，父流程消费者可以直接收到
父流程可以把整条执行链的流式输出汇总到一个 stream 里

但要注意：

stream 是旁路观察通道，不是 recoverable state
它不替代 write_back

7. Mermaid 与导出

to_mermaid() 现在对 sub_flow 的呈现是：

外层是一个虚线、浅底色的子流程框
框内直接内联 child flow 的完整结构
if_condition / for_each 等内部节点会继续展开

这让导出的图可以同时表达：

父流程主链
子流程内部结构
子流程内部的分支和循环

8. 当前限制

子流程内部如果进入 pause_for()，目前不会自动级联恢复到父流程
这类场景当前会显式报错，而不是静默挂起

如果需要人类中断、跨请求恢复，仍建议把 pause/resume 放在父流程边界设计。

9. 示例

最推荐直接看两个源码示例：

examples/step_by_step/11-triggerflow-18_sub_flow_capture_write_back.py
examples/trigger_flow/sub_flow_capture_write_back.py

sub_flow 子流程 ​

1. 核心心智模型 ​

如何阅读这张图 ​

2. 公开接口 ​

3. capture 的语义 ​

4. write_back 的语义 ​

5. 运行隔离 ​

6. runtime stream 行为 ​

7. Mermaid 与导出 ​

8. 当前限制 ​

9. 示例 ​