docs: add dataflow parameters detail

docs/guide/_meta.json

@@ -8,5 +8,10 @@
         "type": "dir",
         "name": "tutorial",
         "label": "基础"
+    },
+    {
+        "type": "dir",
+        "name": "topics",
+        "label": "主题"
     }
 ]

docs/guide/topics/_meta.json

@@ -0,0 +1 @@
+["dataflow"]

docs/guide/topics/dataflow.mdx

@@ -0,0 +1,212 @@
+# Dora 数据流节点终极指南
+
+## 引言：欢迎来到 Dora 的自动化工厂
+
+欢迎您，未来的数据流架构师！请将 **`dora`** 想象成一个高度智能的自动化工厂，而您，就是这家工厂的总设计师。您的核心任务是设计一条或多条高效的**流水线 (Dataflow)**，用于处理、转换和传输数据。
+
+在这条流水线上，每一个独立的工作站，我们称之为 **节点 (Node)**。
+
+### 什么是节点 (Node)？
+
+简单来说，一个节点就是一个**独立的工人**。它具备以下特征：
+
+  * **身份**：拥有唯一的**工牌号** (`id`) 和供人阅读的**职位描述**。
+  * **技能**：掌握一项特定的**技能** (`path` 或 `operator`)，即它要执行的程序逻辑。
+  * **协作**：能从上游工位**接收零件** (`inputs`)，并在完成自己的工作后，将**新产品**放到传送带上，交给下游工位 (`outputs`)。
+
+您的全部设计工作，都将体现在一份名为 `dataflow.yml` 的**工厂总蓝图**中。这份文档将是您学习如何绘制这份蓝图的终极指南。
+
+根据蓝图的设计，工人主要有两种工作模式：
+
+1.  **独立工人 (Standalone Process Node)**: 单独在一个工位上工作，拥有独立的进程空间。
+2.  **工人团队 (Runtime Node)**: 一位**工位管理员**带领着一队**操作符 (Operators)** 在一个大的共享工位里高效协作。
+
+现在，让我们深入每一个细节，解构节点的全部属性。
+
+
+## 节点属性深度解析
+
+我们将节点的所有属性划分为几个逻辑部分，并对每个属性进行“通俗讲解”和“参数详解”两个层面的分析。
+
+### 第一部分：身份与元数据 (Identity & Metadata)
+
+这些属性定义了工人的基本信息。
+
+#### `id`
+
+  * **通俗讲解** 📛
+    每个工人都必须有一个独一无二的“工牌号”，就像我们的身份证号码一样。这是工厂调度系统识别和找到他的唯一凭证。
+    ```yaml
+    id: camera_source_node
+    ```
+  * **参数详解**
+      * **类型**: `NodeId` (String)
+      * **含义**: 节点的唯一标识符，是其在数据流拓扑中的主键。
+      * **限制条件**: **必需字段**；在整个数据流中必须**唯一**；禁止包含正斜杠 (`/`) 字符。
+      * **配合参数**: 被其他节点的 `inputs` 字段引用，用于建立数据流连接。
+
+#### `name` & `description`
+
+  * **通俗讲解** 💬
+    除了工牌号，我们还可以给工人起一个好听的“花名” (`name`)，并写一份详细的“职位描述” (`description`)。这不会改变工人的技能，但能让工厂蓝图更容易被人类读懂。
+    ```yaml
+    name: "高清摄像头画面采集器"
+    description: "负责从 RealSense D435 深度相机捕获 1080p 的视频流。"
+    ```
+  * **参数详解**
+      * **类型**: `Option<String>`
+      * **含义**: `name` 是简短的可读名称，`description` 是详细的功能说明。主要用于增强文档、日志和监控的可读性。
+      * **限制条件**: 均为可选字段，不要求唯一性。
+
+
+### 第二部分：执行与行为 (Execution & Behavior)
+
+这些属性决定了工人如何工作，以及他具体执行什么任务。
+
+#### `path`
+
+  * **通俗讲解** 📜
+    这是“独立工人”的“技能手册”。它直接告诉工人应该运行哪个程序或脚本。如果一个节点有 `path`，它就是一个独立工作的工人。
+    ```yaml
+    path: nodes/video_processing.py
+    ```
+  * **参数详解**
+      * **类型**: `Option<String>`
+      * **含义**: 定义独立进程节点的可执行文件或脚本的路径。
+      * **限制条件**: 与 `operators` 和 `operator` 字段**互斥**。
+      * **配合参数**: `args`, `env`, `build`。若与 `git` 配合，此路径通常相对于 Git 仓库的根目录。
+
+#### `args`
+
+  * **通俗讲解** 🗣️
+    给工人下达的“临时指令”。就像你告诉他：“嘿，今天的工作，请按照'加急模式'来办！”
+    ```yaml
+    args: "--mode fast --quality high"
+    ```
+  * **参数详解**
+      * **类型**: `Option<String>`
+      * **含义**: 传递给 `path` 指定的可执行文件的命令行参数字符串。
+      * **限制条件**: 仅对定义了 `path` 的独立进程节点有效。
+
+#### `env`
+
+  * **通俗讲解** 📋
+    工厂里的“共享公告板”。你可以在上面写一些所有工人都需要知道的信息，比如“今天的生产目标：1000件”或“紧急出口在此方向”。
+    ```yaml
+    env:
+      API_KEY: "a_very_secret_key"
+      MAX_RETRIES: 5
+    ```
+  * **参数详解**
+      * **类型**: `Option<BTreeMap<String, EnvValue>>`
+      * **含义**: 为节点的构建和执行环境设置环境变量。
+      * **限制条件**: `EnvValue` 支持字符串、布尔值和数字。是传递敏感信息（如密钥）的最佳方式。
+
+#### `operators` & `operator`
+
+  * **通俗讲解** 👨‍👩‍👧‍👦
+    这是“工人团队”模式的核心。一个节点如果没有 `path`，但有 `operators` 或 `operator`，那它就不是一个干活的工人，而是一个“工位管理员”（运行时节点）。他负责管理一整个**操作符 (Operator)** 团队在同一个大工位里高效协作。`operator` 是 `operators` 只有一个成员时的简化写法。
+    ```yaml
+    # 一个管理员，带领两个操作符
+    operators:
+      - id: detector
+        python: detect.py
+      - id: tracker
+        python: track.py
+    ```
+  * **参数详解**
+      * **类型**: `Option<RuntimeNode>` / `Option<SingleOperatorDefinition>`
+      * **含义**: 定义在运行时节点内部署的一个或多个轻量级**操作符**。它的存在标志着该节点是一个算子宿主。
+      * **限制条件**: 与 `path` 字段**互斥**；`operators` 和 `operator` 自身也**互斥**。
+
+
+### 第三部分：数据流连接 (Dataflow Connectivity)
+
+这些属性定义了传送带，让零件在工人之间流动。
+
+#### `outputs`
+
+  * **通俗讲解** 📤
+    工人在这里“晒出”他能生产的所有产品类型清单。比如：“我能生产'切割好的钢板'和'废料'两种东西。”
+    ```yaml
+    outputs:
+      - processed_video
+      - detected_objects
+    ```
+  * **参数详解**
+      * **类型**: `BTreeSet<DataId>` (Set of Strings)
+      * **含义**: 声明该节点可以产生的所有数据输出流的唯一标识符 (ID)。
+      * **限制条件**: 必需，但可为空 `[]`。下游节点的 `inputs` 必须引用此列表中声明的 ID。
+
+#### `inputs`
+
+  * **通俗讲解** 📥
+    工人在这里“下订单”，说明他需要哪些上游工人的哪些产品来完成自己的工作。这是连接流水线的关键。
+    ```yaml
+    # 我需要一个叫 `raw_video` 的零件，它来自 `camera_node` 工人生产的 `video_stream`
+    inputs:
+      raw_video: camera_source_node/video_stream
+    ```
+  * **参数详解**
+      * **类型**: `BTreeMap<DataId, Input>` (Map)
+      * **含义**: 定义节点的输入订阅。将一个本地输入 ID 映射到一个上游输出。
+      * **语法**: `local_input_id: upstream_node_id/upstream_output_id`。
+      * **限制条件**: 引用的上游节点 ID 和输出 ID 必须在数据流中真实存在。
+
+#### `send_stdout_as`
+
+  * **通俗讲解** 🎤
+    给工人安装一个“工作日志麦克风”。它能捕获工人在工作时的所有“碎碎念”（程序打印的日志），并把这些“声音”也当作一种产品放到传送带上，供其他工人（如质检员）分析。
+    ```yaml
+    outputs:
+      - main_product
+      - work_logs # 别忘了在 outputs 里也声明这个日志产品
+    send_stdout_as: work_logs
+    ```
+  * **参数详解**
+      * **类型**: `Option<String>`
+      * **含义**: 将节点的标准输出 (`stdout`) 和标准错误 (`stderr`) 流重定向到一个具名的数据流输出通道。
+      * **限制条件**: 此处指定的名称**必须**同时在 `outputs` 列表中声明。
+      * **配合参数**: `outputs`。
+
+
+### 第四部分：源码管理与构建 (Source Management & Build)
+
+这些属性让你的工厂实现了“云采购”和“岗前自动化培训”。
+
+#### `git`, `branch`, `tag`, `rev`
+
+  * **通俗讲解** 📚
+    与其把技能手册 (`path`) 手动放到每个工位，不如让工人直接从中央“技能图书馆” (`git`) 下载。你可以指定下载最新的“草稿” (`branch`)，某个“发行版” (`tag`)，或者精确到某一页的“修订版” (`rev`)。
+    ```yaml
+    git: https://github.com/dora-rs/dora.git
+    tag: v0.4.0 # 推荐使用 tag 或 rev，保证版本稳定
+    ```
+  * **参数详解**
+      * **类型**: `Option<String>`
+      * **含义**: `git` 指定仓库 URL；`branch`, `tag`, `rev` 用于版本控制，分别对应分支、标签和提交哈希。
+      * **限制条件**: `branch`, `tag`, `rev` **互斥**，且必须与 `git` 配合使用。
+
+#### `build`
+
+  * **通俗讲解** 🛠️
+    “岗前培训”。有些技能手册是“散装的零件”（源代码），需要先“组装”（编译）成可用的工具。`build` 就是这个组装指令。
+    ```yaml
+    build: cargo build --release
+    ```
+  * **参数详解**
+      * **类型**: `Option<String>`
+      * **含义**: 在 `dora build` 阶段执行的构建命令。
+      * **限制条件**: `env` 中定义的环境变量对此命令生效。
+
+
+## 最佳实践与最终建议
+
+1.  **ID 清晰唯一**: 这是数据流的基石，请认真命名。
+2.  **文档即代码**: 善用 `name` 和 `description`，让你的数据流蓝图自己会说话。
+3.  **拥抱版本控制**: 在生产环境中，**永远使用 `git` + `tag` 或 `rev`** 的组合，杜绝不确定性。
+4.  **配置外部化**: 尽量使用 `env` 和 `args` 传入配置，保持代码的通用性。
+5.  **调试利器**: 对于关键或复杂的节点，毫不犹豫地使用 `send_stdout_as`，它会在未来为你节省大量调试时间。
+6.  **合理选择模式**: 从简单的**独立工人**模式开始。当遇到性能瓶颈或多个节点需要紧密、低延迟通信时，再重构为**工人团队**（运行时 + 操作符）模式。
+
+现在，您已经拥有了设计 `dora` 节点所需的所有知识，从高层概念到技术细节。是时候打开您的 `dataflow.yml`，开始构建属于您自己的、高效、智能的自动化数据工厂了！