Interlace

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

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

安装

发行包名为 interlace-py，导入名为 interlace。当前通过 Git 安装，尚未发布到 PyPI：

uv pip install "interlace-py @ git+https://github.com/KKKKKKKEM/interlace.git"

生产项目应将 Git 依赖固定到经过验证的提交。开发本仓库可使用 uv sync。

发布到 PyPI

仓库的 .github/workflows/python-publish.yml 在 GitHub Release 发布后运行完整 CI、构建 wheel/sdist、 检查发行元数据，并通过 PyPI Trusted Publishing 上传同一批已验证产物。Release 标签必须与项目版本一致： 当前版本为 0.2.0，对应标签 v0.2.0。尚未完成首次上传，不能把上述 Git 安装命令改成索引安装。

首次发布前，在 PyPI 的 Publishing 页面添加 pending publisher：

• PyPI 项目：interlace-py（interlace 在 PyPI 禁用名单中）
• 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 与图服务

可选 RPC 与图服务

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

uv pip install "interlace-py[service] @ git+https://github.com/KKKKKKKEM/interlace.git"
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 调用及服务所有权见第九章。

当前范围

默认实现通过内建 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