interlace-py 0.2.0__tar.gz

interlace_py-0.2.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+logs/
+
+# Database
+*.db
+*.sqlite3
+
+# uv
+.python-version
+
+# Project specific
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.interlace/

interlace_py-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

interlace_py-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: interlace-py
+Version: 0.2.0
+Summary: An extensible microkernel for typed graphs and event workflows
+Project-URL: Homepage, https://github.com/KKKKKKKEM/interlace
+Project-URL: Repository, https://github.com/KKKKKKKEM/interlace.git
+Author-email: Kem <531144129@qq.com>
+License: MIT
+License-File: LICENSE
+Keywords: automation,engine,graph,state-machine,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.10
+Provides-Extra: service
+Requires-Dist: fastapi<1,>=0.115; extra == 'service'
+Requires-Dist: jsonrpcserver<6,>=5; extra == 'service'
+Requires-Dist: pydantic<3,>=2.9; extra == 'service'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'service'
+Description-Content-Type: text/markdown
+
+# Interlace
+
+Interlace 是一个可扩展的 Python 编排微内核：Graph 内以 `Output` 和 `Edge` 传递局部数据，Graph 间以
+`Event` 和 `Runtime` 连接领域工作流。
+
+核心实现通过公开协议替换，功能通过插件和领域节点扩展，Graph 与 Execution 的公共契约保持稳定。
+运行时没有第三方依赖；爬虫模型、下载器与下载节点由独立的 [Bricks](https://github.com/KKKKKKKEM/bricks) 提供。
+
+## 安装
+
+发行包名为 `interlace-py`，导入名为 `interlace`。当前通过 Git 安装，尚未发布到 PyPI：
+
+```bash
+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 可安装该版本，再让下游更新依赖与锁文件；不要用本地目录替换下游正式依赖。
+
+本地检查发行包：
+
+```bash
+uv build --no-sources
+uv tool run twine check --strict dist/*
+```
+
+构建与元数据检查通过不代表已经上传，也不代表 PyPI 已授予项目发布权限。
+
+```text
+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 契约处理结果。
+
+## 最小示例
+
+```python
+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"))
+```
+
+完整内容按一本手册组织，从[文档目录](https://github.com/KKKKKKKEM/interlace/blob/main/docs/README.md)开始：
+
+1. [设计哲学与心智模型](https://github.com/KKKKKKKEM/interlace/blob/main/docs/01-design-philosophy.md)
+2. [第一张 Graph](https://github.com/KKKKKKKEM/interlace/blob/main/docs/02-first-graph.md)
+3. [Graph 数据流](https://github.com/KKKKKKKEM/interlace/blob/main/docs/03-graph-dataflow.md)
+4. [Event 与跨图工作流](https://github.com/KKKKKKKEM/interlace/blob/main/docs/04-events-and-workflows.md)
+5. [Execution、并发与失败](https://github.com/KKKKKKKEM/interlace/blob/main/docs/05-execution.md)
+6. [Runtime 内部架构](https://github.com/KKKKKKKEM/interlace/blob/main/docs/06-runtime-architecture.md)
+7. [插件、SPI 与适配器开发](https://github.com/KKKKKKKEM/interlace/blob/main/docs/07-plugins.md)
+8. [编排模式](https://github.com/KKKKKKKEM/interlace/blob/main/docs/08-patterns.md)
+9. [RPC 与图服务](https://github.com/KKKKKKKEM/interlace/blob/main/docs/09-service.md)
+
+## 可选 RPC 与图服务
+
+官方服务 extra 提供 HTTP/JSON 调用、JSON-RPC 2.0、SSE 输出流，以及图编辑发布、项目管理与运行历史接口。
+服务只提供数据接口，不托管前端页面；基础安装仍保持零运行时依赖，不自动启动服务。
+
+```bash
+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 可直接接入：
+
+```python
+from interlace.service import GraphService
+
+# runtime 为已经注册 Graph 的运行时，由调用方管理生命周期。
+service = GraphService(runtime, database=".interlace/service.sqlite3")
+service.serve()
+```
+
+安装、节点目录、HTTP/JSON-RPC 调用及服务所有权见[第九章](https://github.com/KKKKKKKEM/interlace/blob/main/docs/09-service.md)。
+
+## 当前范围
+
+默认实现通过内建 `LocalRuntimePlugin` 提供内存事件分发、线程池队列并发和 Graph 执行；它与第三方扩展一样由
+统一 `PluginHost` 装配。EventBus、任务传输、GraphExecutor、输入策略、Node Hook 和 Runtime Observer 均可受控
+扩展，但 Graph 的类型、冻结和 Execution 语义保持固定。默认实现不提供持久化、broker ack、进程恢复、定时器、
+死信队列或 exactly-once 语义。
+
+源码按 `engine`、`runtime`、`plugins`、`spi`、`adapters` 和可复用 `nodes` 分层；各包职责、目录树和允许的
+依赖方向见[Runtime 内部架构](https://github.com/KKKKKKKEM/interlace/blob/main/docs/06-runtime-architecture.md#源码目录与包职责)。
+
+```bash
+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
+```

interlace_py-0.2.0/README.md

@@ -0,0 +1,142 @@
+# Interlace
+
+Interlace 是一个可扩展的 Python 编排微内核：Graph 内以 `Output` 和 `Edge` 传递局部数据，Graph 间以
+`Event` 和 `Runtime` 连接领域工作流。
+
+核心实现通过公开协议替换，功能通过插件和领域节点扩展，Graph 与 Execution 的公共契约保持稳定。
+运行时没有第三方依赖；爬虫模型、下载器与下载节点由独立的 [Bricks](https://github.com/KKKKKKKEM/bricks) 提供。
+
+## 安装
+
+发行包名为 `interlace-py`，导入名为 `interlace`。当前通过 Git 安装，尚未发布到 PyPI：
+
+```bash
+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 可安装该版本，再让下游更新依赖与锁文件；不要用本地目录替换下游正式依赖。
+
+本地检查发行包：
+
+```bash
+uv build --no-sources
+uv tool run twine check --strict dist/*
+```
+
+构建与元数据检查通过不代表已经上传，也不代表 PyPI 已授予项目发布权限。
+
+```text
+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 契约处理结果。
+
+## 最小示例
+
+```python
+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"))
+```
+
+完整内容按一本手册组织，从[文档目录](https://github.com/KKKKKKKEM/interlace/blob/main/docs/README.md)开始：
+
+1. [设计哲学与心智模型](https://github.com/KKKKKKKEM/interlace/blob/main/docs/01-design-philosophy.md)
+2. [第一张 Graph](https://github.com/KKKKKKKEM/interlace/blob/main/docs/02-first-graph.md)
+3. [Graph 数据流](https://github.com/KKKKKKKEM/interlace/blob/main/docs/03-graph-dataflow.md)
+4. [Event 与跨图工作流](https://github.com/KKKKKKKEM/interlace/blob/main/docs/04-events-and-workflows.md)
+5. [Execution、并发与失败](https://github.com/KKKKKKKEM/interlace/blob/main/docs/05-execution.md)
+6. [Runtime 内部架构](https://github.com/KKKKKKKEM/interlace/blob/main/docs/06-runtime-architecture.md)
+7. [插件、SPI 与适配器开发](https://github.com/KKKKKKKEM/interlace/blob/main/docs/07-plugins.md)
+8. [编排模式](https://github.com/KKKKKKKEM/interlace/blob/main/docs/08-patterns.md)
+9. [RPC 与图服务](https://github.com/KKKKKKKEM/interlace/blob/main/docs/09-service.md)
+
+## 可选 RPC 与图服务
+
+官方服务 extra 提供 HTTP/JSON 调用、JSON-RPC 2.0、SSE 输出流，以及图编辑发布、项目管理与运行历史接口。
+服务只提供数据接口，不托管前端页面；基础安装仍保持零运行时依赖，不自动启动服务。
+
+```bash
+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 可直接接入：
+
+```python
+from interlace.service import GraphService
+
+# runtime 为已经注册 Graph 的运行时，由调用方管理生命周期。
+service = GraphService(runtime, database=".interlace/service.sqlite3")
+service.serve()
+```
+
+安装、节点目录、HTTP/JSON-RPC 调用及服务所有权见[第九章](https://github.com/KKKKKKKEM/interlace/blob/main/docs/09-service.md)。
+
+## 当前范围
+
+默认实现通过内建 `LocalRuntimePlugin` 提供内存事件分发、线程池队列并发和 Graph 执行；它与第三方扩展一样由
+统一 `PluginHost` 装配。EventBus、任务传输、GraphExecutor、输入策略、Node Hook 和 Runtime Observer 均可受控
+扩展，但 Graph 的类型、冻结和 Execution 语义保持固定。默认实现不提供持久化、broker ack、进程恢复、定时器、
+死信队列或 exactly-once 语义。
+
+源码按 `engine`、`runtime`、`plugins`、`spi`、`adapters` 和可复用 `nodes` 分层；各包职责、目录树和允许的
+依赖方向见[Runtime 内部架构](https://github.com/KKKKKKKEM/interlace/blob/main/docs/06-runtime-architecture.md#源码目录与包职责)。
+
+```bash
+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
+```

interlace_py-0.2.0/docs/01-design-philosophy.md

@@ -0,0 +1,128 @@
+# 第一章：设计哲学与心智模型
+
+本章先回答两个问题：Interlace 试图解决什么，以及为什么它选择现在这组概念。理解这两个问题后，后续 API 会更容易
+记忆，因为它们都从同一套边界推导出来。
+
+## 一句话定义
+
+Interlace 是一个 typed graph runtime：一张 Graph 描述一次局部计算，多张 Graph 通过领域 Event 连接成工作流。
+
+```mermaid
+flowchart LR
+    subgraph Local[Graph 内：静态 typed dataflow]
+        A[Node A] -->|Output / Edge| B[Node B]
+        B -->|terminal Output| Result[调用方]
+    end
+
+    subgraph Workflow[Graph 间：异步领域工作流]
+        G1[Graph A] -->|Event| R[Runtime route]
+        R -->|Work| G2[Graph B]
+    end
+```
+
+核心设计原则是：
+
+> 内核语义固定，非本质能力可插拔；局部计算用 Graph，跨图协作用 Event。
+
+## 为什么要区分两种流动
+
+数据在同一张 Graph 内流动时，连接关系是静态的，类型可以提前校验，执行过程也可以从图结构推导。这里使用
+`Output` 和 `Edge`。
+
+跨 Graph 协作表达的是领域事实，例如“订单已创建”或“页面已抓取”。它可能启动零个、一个或多个后续工作，部署
+位置和执行时间也不属于源 Graph。这里使用 `Event`。
+
+两条通路不会隐式转换：
+
+- Node 返回的 Output 不会自动发布成 Event；
+- Event payload 不会自动进入某条 Edge；
+- Graph 不直接引用或调用另一张 Graph；
+- 目标 Graph 不在源 Node 的 `emit()` 调用栈中执行。
+
+这个边界让单张 Graph 保持可推理，也让跨 Graph 工作流可以独立扩展和部署。
+
+## 按层暴露的概念
+
+概念是“必须知道才能用”的东西：能做成方法、参数或返回值的，就不要求用户导入一个类名。能力靠组合少数原语获得，
+不为每个场景新增机制。每一层只比上一层多一两个概念：
+
+| 层次 | 读者 | 需要理解的概念 | 其余能力从哪里来 |
+| --- | --- | --- | --- |
+| 写业务 | 所有人 | `Graph`、`Node`、`Output`、`Runtime` | `Context` 作为参数传入，跨图事实经 `context.emit()` 发出 |
+| 编排 | 所有人 | 不新增 | `connect`、`on`、`emit`、`plan()`、`iter()` 与 `options=`、`slots=`、`timeout=` 等参数 |
+| 扩展 | 插件作者 | 钩子点、插件 | 插件是 `setup(api)`，只有 `on`、`provide`、`wrap`、`require`、`defer` 五个动作 |
+| 换基础设施 | 适配器作者 | SPI 协议 | `interlace.spi` 中的窄协议，普通用户看不到 |
+
+顶层 `interlace` 因此只有 `Graph`、`Node`、`Output`、`Runtime`、`Context`、`Event` 六个名字。汇聚策略
+`InputPolicy`、显式连接 `Edge`、执行计划 `ExecutionPlan`、执行句柄 `Execution` 与跨队列共享的 `SlotPool` 位于
+`interlace.engine`，只在需要时导入。
+
+## 微内核：哪些东西不能被插件改变
+
+以下语义共同定义了“什么是 Interlace Graph”，因此属于微内核：
+
+- 端口的类型约束；
+- Graph 的冻结、可达性和 Edge 校验；
+- InputPolicy 的 token 消费规则；
+- Output 的局部传播；
+- Event 与 Graph 数据流的边界；
+- Execution 的状态、步数、超时、取消和错误语义。
+
+如果插件可以改写这些规则，同一张 Graph 在不同环境中就可能具有不同含义，静态校验也会失去价值。
+稳定的是公共契约，不是默认实现。满足相同契约的执行器、Router、Worker、Slot 池、输出存储和通知机制都可以
+通过公开协议替换；应用仍使用同一套 Graph、Event 和 Execution 模型。
+
+## 可插拔能力：哪些东西允许变化
+
+部署环境和横切能力变化频繁，适合通过窄协议或统一的扩展机制变化：
+
+- EventBus 与任务传输；
+- GraphExecutor；
+- RouterRole、WorkerRole 和 SlotProvider；
+- ExecutionFactory、OutputStore 和 ExecutionNotifier；
+- 按名称提供的输入 selector 等具名值；
+- 核心钩子点上的处理函数：事件改写、Work 路由、交付与执行中间件、节点中间件、只读生命周期事实；
+- 插件为领域定义的钩子点，以及领域 Node 和状态适配器。
+
+扩展只有一套机制：两种钩子点（只读 Notice 与中间件 Wrap）加按名称提供、可装饰的具名值，核心与插件以同一方式
+定义和使用。默认内存实现也由 `LocalInfrastructurePlugin` 与 `LocalRuntimePlugin` 通过 `PluginHost` 安装，与应用插件
+走同一套依赖、具名值和清理路径。插件只能通过钩子点与具名值扩展，不能访问 Runtime 私有状态或改写微内核规则；
+钩子点也不能吞掉执行控制异常或产生违反端口契约的结果。
+
+```mermaid
+flowchart TB
+    App[应用 Graph 与 Node]
+    Contributions[插件：钩子点 / 具名值]
+    Kernel[微内核语义]
+
+    App --> Kernel
+    Contributions -->|只能通过 capability| Kernel
+
+    subgraph Fixed[稳定契约]
+        Kernel --> Types[端口 / Edge 类型]
+        Kernel --> Freeze[Graph freeze]
+        Kernel --> Exec[Execution 状态机]
+        Kernel --> Boundary[Output / Event 边界]
+    end
+```
+
+## Less is more
+
+顶层 API 只保留建立和运行工作流所需的对象。Work、Delivery、Router、Worker、Backend 和 PluginHost 虽然在实现中
+存在，但普通用户不需要逐项组装。
+
+这条原则也决定了框架的失败方式：错误配置应尽早、明确地失败，而不是通过隐式转换、默认重试或兼容分支猜测
+调用方意图。
+
+## 可靠性边界
+
+默认实现是单进程内存运行时，不宣称持久化、broker ack、跨进程恢复、定时调度、死信队列或 exactly-once。
+事件被接受后不会因为源 Graph 随后失败而撤回。外部副作用的幂等、领域去重和业务重试应由领域 Graph、Store 或
+明确声明这些语义的后端实现。
+
+## 接下来怎么读
+
+下一章会运行第一张 Graph。之后分别深入 Graph 内的数据流和 Graph 间的事件流，再讨论 Execution、内部架构与
+插件开发。
+
+[下一章：第一张 Graph](02-first-graph.md)

interlace_py-0.2.0/docs/02-first-graph.md

@@ -0,0 +1,76 @@
+# 第二章：第一张 Graph
+
+上一章建立了 Output、Event 和插件边界的整体模型。本章只做一件事：定义并运行一张最小 Graph。
+
+下面的例子把一个字符串转换为大写。它展示 Interlace 的最小闭环：声明 Node、构建并注册 Graph、再执行它。
+
+```python
+from interlace import Graph, Node, Output, Runtime
+
+
+class Upper(Node):
+    inputs = {"text": str}
+    outputs = {"result": str}
+    timeout = 5  # None 表示该 Node 的单次执行不限时
+
+    def execute(self, inputs, context):
+        del context
+        return Output(inputs["text"].upper(), port="result")
+
+
+graph = Graph.compose(nodes={"upper": Upper()}, entrypoint="upper")
+
+with Runtime() as runtime:
+    runtime.register("upper.graph", graph)  # register() 会冻结并校验 Graph
+    outputs = runtime.run("upper.graph", "interlace")
+
+assert outputs == (Output("INTERLACE", port="result"),)
+```
+
+这段程序经历了一个完整但很短的生命周期：
+
+```mermaid
+flowchart LR
+    NodeDef[定义 Upper Node] --> GraphDef[绑定到 Graph]
+    GraphDef --> Register[Runtime.register]
+    Register --> Freeze[冻结并校验]
+    Freeze --> Run[Runtime.run]
+    Run --> Execute[Upper.execute]
+    Execute --> Output[terminal Output]
+```
+
+单节点没有下游 Edge，因此它产生的 `Output` 会作为 `Runtime.run()` 的返回值。若把 output port 连接给另一个
+Node，它只在同一张 Graph 内传播。
+
+`Graph.compose()` 将节点映射、显式入口和可选的 `edges` 集合集中声明；单节点示例可以省略边。
+返回的图仍可继续修改，注册时统一冻结校验。多节点组装见下一章的 [Graph 与 Edge](03-graph-dataflow.md#graph-与-edge)。
+
+默认不限制执行步数和时长。需要约束循环或外部调用时，可以显式配置：
+
+```python
+outputs = runtime.run(
+    "upper.graph",
+    "interlace",
+    max_steps=10,       # 0 表示无限步
+    timeout=30,         # None 表示 Graph 总时长不限
+)
+```
+
+## 运行仓库中的示例
+
+项目没有运行时第三方依赖；使用 uv 可直接执行示例：
+
+```bash
+uv run python examples/linear.py
+uv run python examples/fan_in.py
+uv run python examples/event_routing.py
+uv run python examples/async_node.py
+```
+
+测试工具位于 `pyproject.toml` 的 `dev` 依赖组，`uv run` 默认同步该组：
+
+```bash
+uv run pytest -q
+```
+
+[上一章：设计哲学与心智模型](01-design-philosophy.md) · [下一章：Graph 数据流](03-graph-dataflow.md)