# 场景：管道（NDJSON）与嵌套用法

把 `libtv` 当成"管道友好的 UNIX 小工具"来用：**每个上游在 stdout 吐出 NDJSON，下游读 stdin 取 `nodeKey` / `newNodeKey`**，靠 `&&` 把写入顺序钉死。本目录只收三类 case，其余 UNIX 常规技巧（jq、tee、trap、`2>`）按需自行组合。

## 概念速查（一次性读完再看具体 case）

### stdout / stderr

| 流     | 内容                                                                                                |
| ------ | --------------------------------------------------------------------------------------------------- |
| stdout | **业务结果 JSON / NDJSON**（可直接 `jq` 或接管道）。**只有**接到管道时才保证是单行 JSON（NDJSON）。 |
| stderr | **进度、上传百分比、生成轮询**等，常见前缀 `[run]` / `[run-group]` / `[upload]`。                   |

> 脚本里若把 stderr 丢掉（如 `2>/dev/null`），看不到失败原因；一般保留 stderr 或单独重定向到日志文件。

### NDJSON（管道串联的核心约定）

| 角色             | 约定                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| **上游**         | `stdout` 接到管道（非交互终端）时，成功输出为**一行一个 JSON 对象**。多节点写操作 → **多行**。                |
| **下游**         | 从 `stdin` 按行解析 JSON，取每行的 **`nodeKey`** 或 **`newNodeKey`** 作上游引用（等价 `--left`）。            |
| **左侧串联**     | 用 **`&&`**，只有左侧成功才执行右侧；希望左侧失败时整条管道非零退出，bash 里 **`set -o pipefail`**。          |
| **stdout 抑制**  | `create` 尾部加 `>/dev/null` 可把它自己的 NDJSON 扔掉；用于**终点节点**或**不想让这一支流到外层管道**的分支。 |
| **已有节点回放** | `libtv node "<名字>"`（不传写参数）只查询并吐一行 NDJSON，用来在管道后段**再次引用**早先建好的节点。          |

### `-p` / `-g` 与 stdin 的关系

- `stdin` 里的 `nodeKey` 用作"上游节点引用"，**不会**覆盖 `-p` / `-g`；当前项目 / 分组仍由 `.libtv/project.json`（[`project use`](../../commands/project.md) / [`group use`](../../commands/group.md)）或 `-p` / `-g` 本身决定。
- 下游（如 `libtv node`）从 stdin 收到的 key，默认接到 `<node>` 的**左侧入边**，语义同 `--left`。

## 三个核心 case

| 场景                                                               | 文件                                     |
| ------------------------------------------------------------------ | ---------------------------------------- |
| 普通嵌套 → 复杂 DAG（真实骨架，含旁路与 stdout 抑制）              | [nested-dag.md](./nested-dag.md)         |
| 中途报错的退出策略（`&&` / `pipefail` / 并行 `&` 反例 / 现场清理） | [error-handling.md](./error-handling.md) |
| `group` 与 `node` 的嵌套（建组绑定、组内串管道、终剪汇入）         | [group-and-node.md](./group-and-node.md) |