编排指南
本页面向已经完成快速开始、准备组织多个计算步骤的 Go 开发者。它说明如何选择编排方式，并作为输入、分支、子图和流式处理的入口。
本站示例以 v0.5.0 的对象模型为基线；从 v0.4.1 升级时，先按迁移参考调整调用点并固定依赖版本。
从数据关系定义流程
Pulse 的节点声明 Requires（读取哪些键）和 Provides（写出哪些键）。引擎据此建立依赖关系；宿主不需要创建边对象或安排节点的执行顺序。
Key[T] 是带 Go 类型的数据标识。一个键在同一张图中只有一个来源：外部输入端口，或一个节点的输出。多个节点可以读取同一条普通值；需要多个结果时，让它们分别写出不同的键。
节点要等所有声明输入都到达后才能进入业务体。到达包括有值的 ready 和正常无值的 skipped。其中至少一条有值时，业务体可以执行；全部跳过时，节点也跳过。没有输入的源节点直接具备执行条件。详见分支与汇聚。
选择操作主题
| 目标 | 阅读页面 | 核心操作 |
|---|---|---|
| 从请求或宿主传入数据，运行后取得结果 | 输入与输出 | DeclareInput、Seed、DeclareOutput、ReadOutput |
| 按条件选择路径，合并部分或全部结果 | 分支与汇聚 | Only、Skip、FanOut、Join、WaitAll |
| 重试失败步骤，为执行设置时限 | 重试、超时与取消 | Retry、Timeout、Execution.Cancel |
| 将一个流程作为另一个流程的步骤 | 静态子图 | Sub、In、Out、Fix |
| 连续生产和消费数据 | 流式处理 | ProduceStream、ConsumeStream、TeeStream、SubscribeStream |
| 将拓扑移到声明文件 | YAML 装配 | Registry、Load、SeedPlan、Analyze |
| 检查进度、记录生命周期或生成图示 | 观测与诊断 | Observer、Snapshot、Topology.Mermaid |
建议的装配与运行顺序
- 定义键、图身份和说明，创建
Graph。 - 声明对外的输入和输出，添加节点或挂载已装配的子图。
- 装配完成后调用
Validate，尽早发现缺失来源、无效出口、依赖环和可见的流式问题。 - 为本次运行准备一份
Inputs，创建并启动Execution。 - 调用
Wait等全部节点结束，再通过声明出口读取结果。
Graph 保存可复用的定义，Execution 保存一次运行的输入、槽位、状态、错误和取消域。每次 g.Run(ctx, in) 都会创建新的执行。需要读取结果或检查运行进度时，使用分步的 NewExecution、Start、Wait。若根流仅由宿主消费，可先 Validate 冻结定义，再创建执行、SubscribeStream、Start。Validate/Topology 只对声明的 managed 根出口省略缺读者诊断，不算真实宿主，不放行未导出流，也不改变原生 channel；Start 仍按实际订阅严格检查缺读者与分流。宿主在 Wait 前持续读取和确认，或显式 Stop；Wait 同时等必需宿主读取义务。
成功的 Validate 或 Start 会封闭整棵定义树，使节点和端口不再变化。封闭后的定义仍能反复运行，也可以作为子图挂载到其他图中。校验失败不会封闭任何一层。不要把 Validate 当作完全无副作用的查询；只查看结构和问题时使用 Topology。
并发与配置
不同节点在输入到达后可以并行执行。WithMaxRunning(n) 限制同时持有业务额度的节点数；等待输入和 Sub 挂载本身不占额，受管流 Send/Receive 等阻塞等待会暂时让额，业务继续、取消返回或 panic 展开前取回。因此纯受管流水线额度 1 也可推进；原生 channel 糖仍整段持额并做保守容量检查。任意业务 I/O 不会自动让额。n <= 0 表示不限制。
未声明额度的子图继承父执行的同一份额度。子图自己声明额度时，这一支使用独立额度池，取代继承池；它不是同时受父、子两个上限约束。每个根执行有自己的额度池，多个根执行之间没有自动的全局并发上限。
观察者和额度的优先级为本次运行的 WithExec* 配置、定义中的 With* 声明、父执行环境。图级切面采用叠加方式：继承切面、定义切面、本次执行切面、节点切面，依次由外到内。需要只限制某一步时，应把切面放到该节点或子图挂载点，见重试、超时与取消。
常见装配错误
- 两个节点写同一条键：为不同结果定义不同键，再显式汇聚；不要依靠后写覆盖。
- 外部输入同时由图内节点生产：明确由宿主提供还是由图内计算，保留一个来源。
- 忘记提供本次必需输入：使用
Seed给值，或用SkipSeed明确表示本次没有值。 - 用循环依赖表达重复计算：依赖环无法启动；在节点内组织业务循环，或由宿主发起新的执行。
- 在已经校验成功后继续装配：先完成所有声明再校验；需要另一种拓扑时创建新定义。
下一步
先阅读输入与输出建立宿主与图的边界，再按照上表选择主题。精确的状态、回调次数和封闭规则见生命周期参考；检查点集成另见检查点参考。