Interlace

Interlace 是一个可扩展的 Python 编排微内核：Graph 内以 Output 和 Edge 传递局部数据，Graph 间以 Event 和 Runtime 连接领域工作流。

核心实现通过公开协议替换，功能通过插件和领域节点扩展，Graph 与 Execution 的公共契约保持稳定。 运行时没有第三方依赖；爬虫模型、下载器与下载节点由独立的 Bricks 提供。

安装

发行包名为 interlace-py，导入名为 interlace：

uv pip install interlace-py

开发本仓库可使用 uv sync。

发布到 PyPI

仓库的 .github/workflows/python-publish.yml 在 GitHub Release 发布后运行完整 CI、构建 wheel/sdist、 检查发行元数据，并通过 PyPI Trusted Publishing 上传同一批已验证产物。Release 标签必须是 v 加 pyproject.toml 中的版本号，例如 v0.2.0；同一版本号在 PyPI 上只能上传一次。

PyPI 项目 interlace-py（interlace 在 PyPI 禁用名单中）的 Trusted Publisher 绑定：

• GitHub owner：KKKKKKKEM
• GitHub repository：interlace
• Workflow filename：python-publish.yml
• Environment：pypi

发布工作流只在上传作业授予 OIDC id-token: write，不借用其他仓库的 PyPI Token。 维护者应在 GitHub 配置 pypi environment 的审批与标签限制，再发布对应 Release。 上传成功后先确认 PyPI 可安装该版本，再让下游更新依赖与锁文件；不要用本地目录替换下游正式依赖。

本地检查发行包：

uv build --no-sources
uv tool run twine check --strict dist/*

构建与元数据检查通过不代表已经上传，也不代表 PyPI 已授予项目发布权限。

Node -- Output / Edge --> Node
Graph -- Event / Runtime --> Graph

顶层 API 还提供进程内的 Slot 与 SlotPool：队列 Work 可以在同一进程中跨 Consumer 传递并复用代理、Cookie、 连接等执行状态，而不依赖具体线程。Slot 不跨进程或消息边界传输。

执行默认不限步数、时长和 Graph 内积压；run()、start() 和事件 route 可按需设置 max_steps、Graph timeout 与待消费输入上限 max_queued，单次 Node firing 的时限由该 Node 的 timeout 属性声明。start() 返回可查询和 协作式取消的 Execution。 Execution 可调用 result()、直接 await，也可同步或异步迭代 terminal Output；Runtime.iter() 和 Runtime.aiter() 提供对应便利入口。

所有节点统一继承 Node。execute() 可以使用普通 def 或 async def；普通函数返回的 Awaitable 也由 Engine 等待，再按相同的 Output 契约处理结果。

最小示例

from interlace import Graph, Node, Output, Runtime


class Upper(Node):
    inputs = {"text": str}
    outputs = {"result": str}
    timeout = 5

    def execute(self, inputs, context):
        del context
        return Output(inputs["text"].upper(), "result")


graph = Graph.compose(nodes={"upper": Upper()}, entrypoint="upper")

with Runtime() as runtime:
    runtime.register("upper.graph", graph)
    print(runtime.run("upper.graph", "interlace"))

完整内容按一本手册组织，从文档目录开始：

1. 设计哲学与心智模型
2. 第一张 Graph
3. Graph 数据流
4. Event 与跨图工作流
5. Execution、并发与失败
6. Runtime 内部架构
7. 插件、SPI 与适配器开发
8. 编排模式
9. RPC 与图服务
10. 指标与监控

可选 RPC 与图服务

官方服务 extra 提供 HTTP/JSON 调用、JSON-RPC 2.0、SSE 输出流，以及图编辑发布、项目管理与运行历史接口。 服务只提供数据接口，不托管前端页面；基础安装仍保持零运行时依赖，不自动启动服务。

uv pip install "interlace-py[service]"
uv run --extra service python examples/service.py

启动后在 http://127.0.0.1:8000/docs 查看 OpenAPI 文档。已有代码图直接支持远程调用和运行查看；登记节点工厂与 配置模型后，还可以通过编辑文档校验、保存草稿与发布不可变版本。

已有 Runtime 可直接接入：

from interlace.service import GraphService

# runtime 为已经注册 Graph 的运行时，由调用方管理生命周期。
service = GraphService(runtime, database=".interlace/service.sqlite3")
service.serve()

安装、节点目录、HTTP/JSON-RPC 调用及服务所有权见第九章。

可选指标

interlace.metrics 零依赖：Node 以 count(context.hooks, ...)、observe(context.hooks, ...) 记录样本， Metrics().plugin 汇总样本与执行、节点、Work、事件生命周期指标，提供快照、Prometheus 文本与服务的 GET /metrics；OpenTelemetry 桥接通过 interlace-py[otel] 安装。

from interlace import Runtime
from interlace.metrics import Metrics

metrics = Metrics()
runtime = Runtime(plugins=[metrics.plugin])

标签规则、生命周期指标与 OTel 导出见第十章。

当前范围

默认实现通过内建 LocalRuntimePlugin 提供内存事件分发、线程池队列并发和 Graph 执行；它与第三方扩展一样由 统一 PluginHost 装配。EventBus、任务传输、GraphExecutor、输入策略、Node Hook 和 Runtime Observer 均可受控 扩展，但 Graph 的类型、冻结和 Execution 语义保持固定。默认实现不提供持久化、broker ack、进程恢复、定时器、 死信队列或 exactly-once 语义。

源码按 engine、runtime、plugins、spi、adapters 和可复用 nodes 分层；各包职责、目录树和允许的 依赖方向见Runtime 内部架构。

uv run python examples/linear.py
uv run python examples/fan_in.py
uv run python examples/cycle.py
uv run python examples/event_routing.py
uv run python examples/async_node.py
uv run python examples/output_stream.py
uv run python examples/domain_context.py
uv run pytest -q