diff --git a/.vuepress/configs/sidebar/zh-CN.ts b/.vuepress/configs/sidebar/zh-CN.ts
index 8db194312f4..851b6445b94 100644
--- a/.vuepress/configs/sidebar/zh-CN.ts
+++ b/.vuepress/configs/sidebar/zh-CN.ts
@@ -64,6 +64,7 @@ export const sidebarZhCN: SidebarConfig = {
         '/zh-CN/book/overlays.md',
         '/zh-CN/book/sorting.md',
         '/zh-CN/book/testing.md',
+        '/zh-CN/book/debugging.md',
         '/zh-CN/book/style_guide.md',
       ],
     },
@@ -93,6 +94,7 @@ export const sidebarZhCN: SidebarConfig = {
       children: [
         '/zh-CN/book/coming_from_bash.md',
         '/zh-CN/book/coming_from_cmd.md',
+        '/zh-CN/book/coming_from_powershell.md',
         '/zh-CN/book/nushell_map.md',
         '/zh-CN/book/nushell_map_imperative.md',
         '/zh-CN/book/nushell_map_functional.md',
@@ -117,6 +119,8 @@ export const sidebarZhCN: SidebarConfig = {
         '/zh-CN/book/parallelism.md',
         '/zh-CN/book/plugins.md',
         '/zh-CN/book/explore.md',
+        '/zh-CN/book/tui.md',
+        '/zh-CN/book/mcp.md',
       ],
     },
   ],
diff --git a/tools/i18n-meta.json b/tools/i18n-meta.json
index 5f693d46cda..ff2ac9abcf5 100644
--- a/tools/i18n-meta.json
+++ b/tools/i18n-meta.json
@@ -116,6 +116,19 @@
     "ru": "-",
     "ko": "-"
   },
+  {
+    "name": "coming_from_powershell.md",
+    "en": "Completed",
+    "zh-CN": "e9317a86@passionworkeer",
+    "fr": "-",
+    "de": "-",
+    "tr": "-",
+    "ja": "-",
+    "es": "-",
+    "pt-BR": "-",
+    "ru": "-",
+    "ko": "-"
+  },
   {
     "name": "coming_to_nu.md",
     "en": "In progress",
@@ -207,6 +220,19 @@
     "ru": "-",
     "ko": "-"
   },
+  {
+    "name": "debugging.md",
+    "en": "Completed",
+    "zh-CN": "ff1c4786@passionworkeer",
+    "fr": "-",
+    "de": "-",
+    "tr": "-",
+    "ja": "-",
+    "es": "-",
+    "pt-BR": "-",
+    "ru": "-",
+    "ko": "-"
+  },
   {
     "name": "dataframes.md",
     "en": "Completed",
@@ -376,6 +402,19 @@
     "ru": "-",
     "ko": "-"
   },
+  {
+    "name": "mcp.md",
+    "en": "Completed",
+    "zh-CN": "ff1c4786@passionworkeer",
+    "fr": "-",
+    "de": "-",
+    "tr": "-",
+    "ja": "-",
+    "es": "-",
+    "pt-BR": "-",
+    "ru": "-",
+    "ko": "-"
+  },
   {
     "name": "metadata.md",
     "en": "Completed",
@@ -701,6 +740,19 @@
     "ru": "-",
     "ko": "-"
   },
+  {
+    "name": "tui.md",
+    "en": "Completed",
+    "zh-CN": "ff1c4786@passionworkeer",
+    "fr": "-",
+    "de": "-",
+    "tr": "-",
+    "ja": "-",
+    "es": "-",
+    "pt-BR": "-",
+    "ru": "-",
+    "ko": "-"
+  },
   {
     "name": "types_of_data.md",
     "en": "Completed",
diff --git a/zh-CN/book/advanced.md b/zh-CN/book/advanced.md
index 3dbadfbdaf0..eb55f4c5d86 100644
--- a/zh-CN/book/advanced.md
+++ b/zh-CN/book/advanced.md
@@ -14,7 +14,9 @@ Nushell 中的值包含一些额外的[元数据](metadata.md)。
 
 由于 Nushell 严格的作用域规则，[并行迭代集合](parallelism.md)非常容易，这可以帮助你通过只输入几个字符来加速长时间运行的脚本。
 
-你可以使用 [`explore`](/commands/docs/explore.md) 命令[交互式地探索数据](explore.md)。
+你可以使用 [`explore`](/commands/docs/explore.md) 命令[交互式地探索数据](explore.md)，也可以通过 `tui` 命令族[构建你专属的终端用户界面](tui.md)（如选择器、对话框和监控仪表盘）。
 
-最后，你可以使用[插件](plugins.md)来扩展 Nushell 的功能。
+你可以使用[插件](plugins.md)来扩展 Nushell 的功能。
 几乎任何东西都可以成为插件，只要它以 Nushell 理解的协议与 Nushell 通信。
+
+最后，Nushell 可以作为 [MCP 服务器](mcp.md)运行，使 AI Agent 和其他 Model Context Protocol 客户端能够查询其命令并执行 Nushell 代码。
diff --git a/zh-CN/book/coming_from_powershell.md b/zh-CN/book/coming_from_powershell.md
new file mode 100644
index 00000000000..ad7aad6f317
--- /dev/null
+++ b/zh-CN/book/coming_from_powershell.md
@@ -0,0 +1,82 @@
+# 从 PowerShell 到 Nu
+
+::: tip
+PowerShell 管道传递的是丰富的 **.NET 对象**，支持通过 `$process.Name` 等语法直接访问属性，或者直接将对象通过管道传递给支持该对象的 cmdlet。
+
+相比之下，Nushell 管道传递的是表格、列表和值等**结构化数据**。  
+这意味着：
+
+- 不支持 `.PropertyName` 语法访问属性
+- 改用 `get column`、`select`、`$it.column` 或表格操作
+- 命令始终接收可预测的结构化输入，而非字符串或 .NET 类型
+  :::
+
+## 等价命令参考：
+
+| PowerShell                                                      | Nu                                           | 任务                               |
+| --------------------------------------------------------------- | -------------------------------------------- | ---------------------------------- |
+| `Get-ChildItem`                                                 | `ls`                                         | 列出当前目录中的文件               |
+| `Get-ChildItem <dir>`                                           | `ls <dir>`                                   | 列出指定目录中的文件               |
+| `Get-ChildItem pattern*`                                        | `ls pattern*`                                | 模式匹配文件                       |
+| `Get-ChildItem -Force -File -Hidden`                            | `ls --long --all` 或 `ls -la`                | 详细列出文件（包含隐藏文件）       |
+| `Get-ChildItem \| Where-Object { $_.PSIsContainer }`            | `ls \| where type == dir`                    | 仅列出目录                         |
+| `Get-ChildItem -Recurse -Filter *.rs`                           | `ls **/*.rs`                                 | 递归搜索文件                       |
+| `Get-ChildItem -Recurse Makefile \| Select-Object -Expand Name` | `ls **/Makefile \| get name \| vim ...$in`   | 将匹配的文件路径传递给命令         |
+| `Set-Location <dir>`                                            | `cd <dir>`                                   | 切换目录                           |
+| `Set-Location`                                                  | `cd`                                         | 返回主目录                         |
+| `Set-Location -`                                                | `cd -`                                       | 返回上一个目录                     |
+| `New-Item -ItemType Directory <path>`                           | `mkdir <path>`                               | 创建目录                           |
+| `New-Item test.txt`                                             | `touch test.txt`                             | 创建文件                           |
+| `command \| Out-File <path>`                                    | `out> <path>` 或 `o> <path>`                 | 保存输出到文件（原始文本）         |
+| `command \| Set-Content <path>`                                 | `\| save <path>`                             | 保存输出到文件（结构化）           |
+| `command \| Out-File -Append <path>`                            | `out>> <path>` 或 `o>> <path>`               | 追加输出到文件                     |
+|                                                                 | `\| save --append <path>`                    | 追加结构化输出                     |
+| `command \| Out-Null`                                           | `\| ignore`                                  | 丢弃输出                           |
+| `cmd1 \| Tee-Object -FilePath log.txt \| cmd2`                  | `cmd1 \| tee { save log.txt } \| cmd2`       | 将输出同时保存到文件               |
+| `command \| Select-Object -First 5`                             | `command \| first 5`                         | 限制输出前 N 行                    |
+| `Get-Content <path>`                                            | `open --raw <path>`                          | 显示文件内容                       |
+| `Move-Item <source> <dest>`                                     | `mv <source> <dest>`                         | 移动文件                           |
+| `Get-ChildItem *.md \| ForEach-Object { $_.Name }`              | `ls *.md \| each { $in.name }`               | 遍历列表值                         |
+| `foreach ($i in 1..10) { $i }`                                  | `for i in 1..10 { print $i }`                | 遍历指定范围                       |
+| `Copy-Item <source> <dest>`                                     | `cp <source> <dest>`                         | 复制文件                           |
+| `Copy-Item -Recurse <source> <dest>`                            | `cp -r <source> <dest>`                      | 递归复制目录                       |
+| `Remove-Item <path>`                                            | `rm <path>`                                  | 删除文件                           |
+|                                                                 | `rm -t <path>`                               | 将文件移至回收站                   |
+| `Remove-Item -Recurse -Force <path>`                            | `rm -r <path>`                               | 递归删除目录                       |
+| `Get-Date "<date>"`                                             | `"<date>" \| into datetime -f <format>`      | 解析日期                           |
+| `"<str>" -replace 'a','b'`                                      | `str replace "a" "b"`                        | 替换子字符串                       |
+| `Select-String <pattern>`                                       | `where $it =~ <pattern>` 或 `find <pattern>` | 搜索文本                           |
+| `Get-Help <command>`                                            | `help <command>`                             | 查看命令帮助                       |
+| `Get-Command`                                                   | `help commands`                              | 列出所有命令                       |
+| `Get-Command "*<string>*"`                                      | `help --find <string>`                       | 搜索命令                           |
+| `command1; if ($?) { command2 }`                                | `command1; command2`                         | 仅在第一个命令成功时运行第二个命令 |
+| `/tmp/$((Get-Random))`                                          | `$"/tmp/(random int)"`                       | 字符串插值                         |
+| `$env:Path`                                                     | `$env.PATH` 或 `$env.Path`                   | 显示 PATH                          |
+| `$LASTEXITCODE`                                                 | `$env.LAST_EXIT_CODE`                        | 上一个外部命令的退出码             |
+| `$env:PATH += ":/usr/bin"`                                      | `$env.PATH = ($env.PATH \| append /usr/bin)` | 更新 PATH（临时生效）              |
+| `Get-ChildItem Env:`                                            | `$env`                                       | 列出环境变量                       |
+| `$env:FOO`                                                      | `$env.FOO`                                   | 访问环境变量                       |
+| `Remove-Item Env:FOO`                                           | `hide-env FOO`                               | 取消设置环境变量                   |
+| `Set-Alias s "git status -sb"`                                  | `alias s = git status -sb`                   | 临时别名                           |
+| `Get-Command FOO`                                               | `which FOO`                                  | 检查命令 / 别名 / 二进制文件       |
+| `powershell -Command "<commands>"`                              | `nu -c <commands>`                           | 运行内联管道                       |
+| `.\script.ps1`                                                  | `nu <script file>`                           | 运行脚本文件                       |
+| `Get-Location` 或 `$PWD`                                        | `pwd` 或 `$env.PWD`                          | 显示当前工作目录                   |
+| `Read-Host`                                                     | `let var = input`                            | 读取用户输入                       |
+| `Read-Host -AsSecureString`                                     | `let secret = input -s`                      | 读取私密输入                       |
+
+## 按 ESC 键清空命令行缓冲区
+
+在旧版本的 PowerShell 中，支持通过按 ESC 键清空命令行缓冲区。
+
+虽然 Nu 默认并未提供完全一致的按键行为，但你可以在 `config.nu` 中添加快捷键绑定以实现类似的功能：
+
+```nu
+$env.config.keybindings ++= [{
+    name: 'esc_clear'
+    modifier: 'None'
+    keycode: 'Esc'
+    mode: ['Emacs', 'Vi_Normal']
+    event: {edit: 'Clear'}
+}]
+```
diff --git a/zh-CN/book/debugging.md b/zh-CN/book/debugging.md
new file mode 100644
index 00000000000..e15ed9fd13f
--- /dev/null
+++ b/zh-CN/book/debugging.md
@@ -0,0 +1,93 @@
+# 脚本调试
+
+Nushell 内置了脚本调试器。运行 `nu --dap` 会启动一个 [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)（DAP）服务器，VS Code、Neovim 和 Zed 等编辑器正是通过该协议来驱动调试器的。当你的编辑器配置好使用该调试器后，你可以在 `.nu` 文件中设置断点、逐行单步执行脚本并深入管道阶段、查看变量和 `$env`、在脚本暂停时评估表达式，甚至可以沿已执行路径向后单步回溯。
+
+## 配置你的编辑器
+
+编辑器会自行启动 `nu --dap` 并通过进程的标准输入和输出流与其通信，因此它只需知道要运行的命令（`nu`，附带参数 `--dap`）以及要启动哪个脚本。调试器是默认构建的一部分（即 `dap` [Cargo 特性](./installation.md)）。
+
+例如，在 Neovim 中配合 [nvim-dap](https://github.com/mfussenegger/nvim-dap) 使用：
+
+```lua
+local dap = require('dap')
+
+dap.adapters.nu = {
+  type = 'executable',
+  command = 'nu',
+  args = { '--dap' },
+}
+
+dap.configurations.nu = {
+  {
+    type = 'nu',
+    request = 'launch',
+    name = 'Debug this script',
+    program = '${file}',
+  },
+}
+```
+
+VS Code 则需要一个为 Nushell 注册调试器的扩展，随后从 `launch.json` 中读取相同的启动设置。
+
+调试器在运行脚本前会加载你的 `env.nu` 和 `config.nu`，因此脚本能看到与你的 shell 相同的自定义命令、别名和环境。在参数中添加 `-n`（`args = { '--dap', '-n' }`）可改为从默认配置启动。在解析配置文件期间，[`$nu.is-dap`](./special_variables.md#nu) 的值为 `true`。
+
+### 启动配置项
+
+启动配置支持以下设置项：
+
+| 配置项               | 默认值  | 说明                                                                                               |
+| -------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `program`            |         | 待调试的 `.nu` 脚本的绝对路径。必填。                                                              |
+| `args`               | `[]`    | 传递给 `main` 或 `entryPoint` 命令的参数字符串列表。其解析方式与 `nu <script> ...args` 相同。      |
+| `cwd`                |         | 运行脚本的工作目录。                                                                               |
+| `stopOnEntry`        | `false` | 是否在第一行代码运行前暂停。                                                                       |
+| `entryPoint`         |         | 在脚本顶层执行完毕后运行的命令，适用于仅定义命令的文件。若未指定且脚本包含 `main`，则运行 `main`。 |
+| `timeTravel`         | `true`  | 记录运行的每一行，以便能够[向后单步回溯](#向后单步回溯)。若为 `false`，则仅记录脚本暂停的位置。    |
+| `timeTravelMaxSteps` | `10000` | 保留的记录步数。较早的记录将被丢弃。                                                               |
+
+脚本的运行方式与 `nu <script> ...args` 一致：先执行顶层代码，然后使用 `args` 中的参数执行 `main`，或者执行 `entryPoint` 中指定的命令。
+
+## 断点与单步执行
+
+在某一行设置断点，脚本就会在该行暂停。如果在无法暂停的行（例如注释行）设置断点，断点会自动移至下一行可暂停的代码处。
+
+一行代码通常包含多个步骤。在 `let doubled = ($nums | each {|n| $n * 2 })` 中，`let`、`each` 调用以及闭包体各自独立运行。普通断点会在其中的第一步暂停，随后在闭包体针对每个元素执行时再次暂停。而在特定列设置的*行内断点*（在 VS Code 中为 <kbd>Shift</kbd>+<kbd>F9</kbd>）则仅会在该特定步骤处暂停。
+
+断点还可以是：
+
+- **条件断点**：条件是一个 Nushell 表达式，例如 `$n == 3`，脚本仅在表达式为 `true` 时暂停。
+- **日志断点（Logpoints）**：断点不会暂停执行，而是向调试控制台输出一条消息。花括号中的表达式会被求值，例如 `names has {$names | length} items` 会输出 `names has 2 items`。
+
+**运行时错误（Runtime errors）**异常过滤器默认处于开启状态，当某个命令引发错误时（包括会被 `try` 块捕获的错误），调试器会暂停脚本。编辑器会显示该错误的代码和消息。
+
+脚本暂停时，你可以继续执行、单步跳过整行、单步进入命令调用或管道阶段，或者单步跳出当前命令。调用栈（Call Stack）会展示通往当前行的命令和闭包调用层级。
+
+## 检查变量与值
+
+当脚本暂停时，编辑器的变量视图会展示：
+
+- **Locals（局部变量）**：当前作用域内的变量、`$in`，以及 `return`（最后一步的值）。
+- **Pipeline（管道值）**：在两个管道阶段的分界处，流入下一个命令的值。
+- **Globals（全局变量）**：`$nu` 和 `$env`，包含脚本对环境所做的任何更改。
+- **Registers（寄存器）**：求值器的内部工作值，用于查看 Nushell 底层执行细节。
+- **Process（进程输出）**：脚本运行的外部命令的最新输出。
+
+嵌套的记录、列表和表格在你展开时会逐级加载，因此在查看内部结构之前，庞大的数据结构不会拖慢任何操作。数据流（Stream）仅作描述而不予读取，因此查看数据流不会消耗其内容。
+
+监视表达式（Watch expressions）、调试控制台以及将鼠标悬停在变量上，都会使用暂停时的值来对 Nushell 表达式求值。它们在脚本状态的副本上运行，因此不会修改脚本的变量。
+
+来自 [`print`](/commands/docs/print.md) 和外部命令的输出会发送到编辑器的调试控制台。脚本没有附加终端，因此外部命令不会接收标准输入。
+
+## 向后单步回溯
+
+Nushell 无法反向执行代码，因此调试器会在每一行记录当时的状态（当 `timeTravel` 开启时，默认开启）。**单步后退（Step Back）**和**反向继续（Reverse Continue）**会沿这些历史记录向后回退，移动到上一行或上一个断点，并展示当时的变量和调用栈。从回退位置向前单步执行会沿着记录向前推进，直至到达最新的执行步骤，随后脚本恢复正常运行。已经执行过的命令不会被撤销：脚本已写入的文件依然保持写入状态。
+
+**重启（Restart）**会在同一个会话中从头再次运行脚本，重新从磁盘读取脚本内容并保留你的断点。
+
+## 使用限制
+
+- 调试器目前只能启动新脚本，无法附加到已在运行的 Nushell 进程。
+- 脚本暂停时无法修改变量的值。
+- 暂不支持函数断点和命中计数断点。
+- 变量视图始终显示最内层的命令或闭包。在调用栈中选择调用方会跳转到其所在行，但变量视图仍保持为最内层帧的状态。
+- [`input`](/commands/docs/input.md) 和 [`input list`](/commands/docs/input_list.md) 需要支持调试器提示对话框的客户端。在其他编辑器中，脚本会在提示处等待，并在 10 分钟后失败。`input listen` 在调试器中无法正常工作。
diff --git a/zh-CN/book/mcp.md b/zh-CN/book/mcp.md
new file mode 100644
index 00000000000..c3c244ad7b3
--- /dev/null
+++ b/zh-CN/book/mcp.md
@@ -0,0 +1,103 @@
+# MCP 服务器
+
+[Model Context Protocol](https://modelcontextprotocol.io)（MCP）是 AI Agent 与其他基于大语言模型（LLM）的工具调用本地运行工具的标准协议。Nushell 内置了 MCP 服务器。使用 `nu --mcp` 启动后，MCP 客户端可以查询 Nushell 命令并执行 Nushell 代码；得益于 Nushell 返回的是结构化数据，客户端接收到的是表格（table）和记录（record），而无需自行解析纯文本。
+
+::: warning
+服务器的 `evaluate` 工具会以当前用户的权限执行传入的任意 Nushell 代码，包括外部命令。请仅连接你信任的客户端。HTTP 传输方式没有任何身份验证，因此任何能够访问该端口的人都可以以你的身份执行命令。
+:::
+
+## 启动服务器
+
+MCP 服务器是默认构建的一部分（即 `mcp` [Cargo 特性](./installation.md)）。运行 `nu --mcp` 会在标准输入和输出流上启动它，这也是大多数 MCP 客户端启动本地服务器的方式。客户端通常接受类似如下的配置；有关放置位置请参阅相应客户端的文档：
+
+```json
+{
+  "mcpServers": {
+    "nushell": {
+      "command": "nu",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+服务器会像交互式会话一样加载你的 `env.nu` 和 `config.nu`，因此你的自定义命令、别名和环境变量对客户端都是可用的。在参数中添加 `-n`（`--no-config-file`）可改为从默认配置启动。在解析配置文件期间，[`$nu.is-mcp`](./special_variables.md#nu) 的值为 `true`，因此可以在配置中针对服务器进行单独设置：
+
+```nu
+if $nu.is-mcp {
+    $env.NU_MCP_OUTPUT_LIMIT = 50kb
+}
+```
+
+该会话为非交互式（`$nu.is-interactive` 为 `false`）：
+
+- 外部命令不会获取标准输入，因此等待输入的命令不会挂起。在 Linux、macOS 和 BSD 系统上，服务器还会与终端分离，因此像 `ssh` 或 `sudo` 这类在终端上请求密码的程序会立即失败而不是一直等待。
+- [`print`](/commands/docs/print.md) 输出到 stderr，因此不会干扰 stdout 上的协议消息。
+- 输出不带颜色。
+
+## 工具
+
+该服务器提供了三个工具：
+
+| 工具            | 参数    | 功能说明                                                                                         |
+| --------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `list_commands` | `find`  | 列出可用命令及其签名和描述。`find` 可按名称、描述或搜索词筛选列表。                              |
+| `command_help`  | `name`  | 显示单个命令的帮助信息。传入的名称为你调用它时所使用的名称，因此别名或从模块导入的命令同样适用。 |
+| `evaluate`      | `input` | 执行 Nushell 代码并返回结果。                                                                    |
+
+`evaluate` 返回一个 NUON 记录，其中包含代码运行所在的目录（`cwd`）、其在 `$history` 中的索引（见下文）以及运行时间。结果本身位于 `output` 字段中：
+
+```nu
+{cwd:"/home/me/project",history_index:1,timestamp:2026-10-16T14:03:42.606465+00:00,output:43}
+```
+
+当代码执行失败时，响应会被标记为错误，其内容是一个包含错误 `code`、`msg` 和 `labels` 的 NUON 记录：
+
+```nu
+{code:"nu::shell::division_by_zero",msg:"Division by zero.",labels:[[text,span,line,column];["division by zero",/,1,3]]}
+```
+
+服务器还会向客户端发送指令，解释这些工具的使用方法以及 Nushell 与 Bash 的不同之处。
+
+## 调用之间的状态保持
+
+每次调用 `evaluate` 都在同一个会话中运行，就像在 REPL 中逐行输入一样。在一次调用中定义的变量、自定义命令、别名或环境变量在下一次调用中依然存在。通过 HTTP 方式时，每个客户端会话都有自己独立的状态。
+
+每次调用的结果还会存储在 `$history` 列表中，位于响应中给出的 `history_index` 处。客户端可以只执行一次命令，随后通过 `$history.<index>` 进行筛选或分页，而无需重新运行命令。有几个环境变量控制保留和返回的数据量。你可以像上面那样在配置文件中设置它们，也可以从客户端通过 `evaluate` 进行设置：
+
+| 变量                   | 默认值   | 说明                                                                                                                                                  |
+| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NU_MCP_OUTPUT_LIMIT`  | `10kb`   | 超出此大小的结果将不在响应中直接返回，而是在原 `output` 处替换为 `note` 字段：`output truncated, full result in $history.0`。设置为 `0b` 可关闭截断。 |
+| `NU_MCP_HISTORY_LIMIT` | `100`    | `$history` 保留的结果数量。较早的结果将被丢弃。                                                                                                       |
+| `NU_MCP_PROMOTE_AFTER` | `120sec` | 运行时间超过此阈值的调用将转为[后台任务](./background_jobs.md)。响应将返回带有任务 ID 的错误，后续可通过 `job recv` 获取结果。                        |
+
+## HTTP 传输
+
+若要允许客户端通过网络连接，请使用支持流式传输的 HTTP 传输模式启动服务器：
+
+```nu
+nu --mcp --mcp-transport http --mcp-port 3000
+```
+
+服务器默认监听 `127.0.0.1`（除非指定 `--mcp-port`，否则端口为 `8080`），客户端连接到形如 `http://127.0.0.1:3000/mcp` 的 URL。闲置超过 30 分钟的客户端会话将被关闭。
+
+若要接收来自其他机器的连接，请使用 `--mcp-host` 绑定到其他地址。为了防范 DNS 重绑定攻击，服务器仅接受 `Host` 标头为 `localhost`、`127.0.0.1` 或 `::1` 的请求，因此还需要使用 `--mcp-allowed-hosts` 列出客户端将使用的主机名。该列表会替换默认值，因此如果本地客户端仍需连接，请一并包含 `localhost`：
+
+```nu
+nu --mcp --mcp-transport http --mcp-host 0.0.0.0 --mcp-allowed-hosts nu.example.com localhost
+```
+
+任何携带其他 `Host` 标头的请求都将被拒绝并返回 `403 Forbidden`。基于浏览器的客户端还会发送 `Origin` 标头。除非使用 `--mcp-allowed-origins` 列出允许的源（例如 `--mcp-allowed-origins https://app.example.com`），否则不会检查该标头。
+
+## 命令行选项
+
+| 选项                                 | 说明                                                            |
+| ------------------------------------ | --------------------------------------------------------------- |
+| `--mcp`                              | 启动 MCP 服务器。                                               |
+| `--mcp-transport <stdio\|http>`      | 要使用的传输方式。默认值：`stdio`。                             |
+| `--mcp-port <port>`                  | HTTP 传输的端口。默认值：`8080`。                               |
+| `--mcp-host <address>`               | HTTP 传输绑定的地址。默认值：`127.0.0.1`。                      |
+| `--mcp-allowed-hosts <hosts...>`     | 接受的 `Host` 标头值。默认值：`localhost`、`127.0.0.1`、`::1`。 |
+| `--mcp-allowed-origins <origins...>` | 接受的 `Origin` 标头值。默认值：任意。                          |
+
+`--mcp-allowed-hosts` 和 `--mcp-allowed-origins` 接受一个或多个值，既可以作为多个独立参数传递，也可以作为单个逗号分隔的列表传递。
diff --git a/zh-CN/book/special_variables.md b/zh-CN/book/special_variables.md
index 404b83528e6..f499f80288a 100644
--- a/zh-CN/book/special_variables.md
+++ b/zh-CN/book/special_variables.md
@@ -41,6 +41,11 @@ Nushell 提供并使用了一系列特殊变量和常量。其中许多在本手
 - `is-login`: 指示 Nushell 是否作为登录 shell 启动
 - `history-enabled`: 可以通过 `nu --no-history` 禁用历史记录，此时该常量将为 `false`
 - `current-exe`: 当前运行的 `nu` 二进制文件的完整路径。可以与 `path dirname`(也是常量)结合使用来确定二进制文件所在的目录
+- `is-lsp`: 当 Nushell 通过 `nu --lsp` 作为语言服务器协议（LSP）服务器启动时为 `true`。
+- `is-mcp`: 当 Nushell 通过 `nu --mcp` 作为模型上下文协议（MCP）服务器运行时为 `true`。参见 [MCP 服务器](./mcp.md)。
+- `is-dap`: 当 Nushell 通过 `nu --dap` 作为调试适配器协议（DAP）服务器启动时为 `true`。参见[脚本调试](./debugging.md)。
+
+  在这三种模式下，`print` 都会输出到 stderr，以免干扰 stdout 上的协议消息。
 
 ## `$env`
 
diff --git a/zh-CN/book/tui.md b/zh-CN/book/tui.md
new file mode 100644
index 00000000000..0c7444d4300
--- /dev/null
+++ b/zh-CN/book/tui.md
@@ -0,0 +1,1092 @@
+# 使用 `tui` 构建终端用户界面
+
+`tui` 命令族允许你直接从 Nushell 管道构建交互式终端用户界面（TUI）和弹出式对话框，而无需编写任何 Rust 代码。你可以组合各种部件（如表格、树形视图、搜索框、预览窗格、菜单、文本输入框和按钮），然后将结果传递给 [`tui run`](/commands/docs/tui_run.md)。当用户退出或做出选择时，`tui run` 会返回一条记录，描述用户选择的内容以及每个部件的状态。
+
+```nu
+ls | tui label --titlebar "files" | tui table | tui run
+```
+
+仅需上面这一行命令，即可打开一个全屏、可滚动的文件列表。使用方向键（或 `j`/`k`）移动光标，按 `Enter` 返回高亮选中的行，或者按 `q` 或 `Esc` 不做任何选择直接退出。
+
+::: tip `tui` 还是 `explore`？
+[`explore`](explore.md) 是一个开箱即用的分页器，用于浏览任意结构化值。而 `tui` 则是一套用于构建专属界面的工具包：文件选择器、确认对话框、历史搜索器、仪表盘或小型表单。两者使用相同的颜色转换规则，因此 Nushell 的样式在两个命令中看起来一致。
+:::
+
+`tui run` 始终在终端的备用屏幕（alternate screen）上绘制，因此在 TUI 关闭后，你的 shell 和回滚缓冲区都会完好无损地恢复。[`tui debug`](/commands/docs/tui_debug.md) 会将相同的界面渲染为字符串而非终端画面，这在脚本和自动化测试中非常有用，本页面展示输出的所有示例均基于该命令。
+
+## 命令速览
+
+除了 `tui run` 和 `tui debug` 之外，每个 `tui` 命令都是一个*构建器（builder）*：它向 `tui` 值中添加一个部件，并返回更新后的值。
+
+| 命令                                             | 位置参数            | 重要选项                                                              | 功能说明                                             |
+| ------------------------------------------------ | ------------------- | --------------------------------------------------------------------- | ---------------------------------------------------- |
+| [`tui label`](/commands/docs/tui_label.md)       | 文本或闭包          | `--titlebar`, `--status`                                              | 静态文本、标题栏或状态栏。闭包可跟随选中行动态求值。 |
+| [`tui table`](/commands/docs/tui_table.md)       | 数据源闭包          | `--columns`, `--multi`, `--index`, `--capture-keys`, `--on-select`    | 可导航的表格。标量数据显示为单列 `item`。            |
+| [`tui tree`](/commands/docs/tui_tree.md)         | 数据源闭包          | `--walk`, `--column`, `--multi`, `--on-select`                        | 嵌套记录与列表，或目录树遍历。                       |
+| [`tui select`](/commands/docs/tui_select.md)     | 元素列表            | `--display`, `--multi`, `--index`, `--on-select`                      | 单选列表，配合 `--multi` 则为复选框列表。            |
+| [`tui log`](/commands/docs/tui_log.md)           | 数据源闭包          | `--max-lines`                                                         | 仅追加的日志视图，始终跟随数据流末尾。               |
+| [`tui progress`](/commands/docs/tui_progress.md) | 数据源闭包          | `--value`, `--total`, `--label`                                       | 进度条。                                             |
+| [`tui preview`](/commands/docs/tui_preview.md)   | 闭包                | `--from`, `--max-bytes`                                               | 显示高亮行的文本：文件内容或由闭包返回的任意内容。   |
+| [`tui search`](/commands/docs/tui_search.md)     |                     | `--bind`, `--placeholder`, `--fuzzy`, `--case-sensitive`, `--columns` | 搜索框，可在输入时动态过滤其作用域内的列表。         |
+| [`tui textbox`](/commands/docs/tui_textbox.md)   |                     | `--placeholder`, `--value`                                            | 可编辑的文本输入框。                                 |
+| [`tui button`](/commands/docs/tui_button.md)     | 标签（label），hook |                                                                       | 激活时运行 hook 或提交其标签。                       |
+| [`tui menu`](/commands/docs/tui_menu.md)         | 菜单项列表          |                                                                       | 带有助记快捷键、下拉列表和操作行为的菜单栏。         |
+| [`tui split`](/commands/docs/tui_split.md)       | 子部件列表          | `--vertical`, `--sizes`, `--ratio`                                    | 并排（或纵向堆叠）的窗格，带有可拖动的手柄。         |
+| [`tui box`](/commands/docs/tui_box.md)           | 标题，子部件        |                                                                       | 带边框和标题的部件分组。                             |
+| [`tui tab`](/commands/docs/tui_tab.md)           | 标题，子部件        |                                                                       | 标签页中的一个页面。                                 |
+| [`tui bind`](/commands/docs/tui_bind.md)         | 按键，hook          |                                                                       | 在任意位置按下指定按键时触发运行 hook。              |
+| [`tui run`](/commands/docs/tui_run.md)           | hook                | `--dialog`, `--size`, `--refresh`, `--no-mouse`                       | 持续运行界面，直至用户提交选择或退出。               |
+| [`tui debug`](/commands/docs/tui_debug.md)       | hook                | `--keys`, `--until`, `--size`, `--dialog`                             | 无需终端直接渲染，并报告布局、焦点顺序和页面。       |
+
+此外，所有构建器均支持 `--id`（为部件指定固定的标识符）和 `--focus`（启动时默认聚焦该部件）。数据部件（`label`、`table`、`tree`、`select`、`log` 和 `progress`）还接受 `--data` 和 `--from` 选项，详见[部件的数据来源](#部件的数据来源)。绘制带标题边框的部件（`table`、`tree`、`select`、`log`、`preview`、`search` 和 `textbox`）接受 `--title` 和 `--border`，详见[边框标题](#边框标题)和[边框线型](#边框线型)。`tui box` 和 `tui menu` 同样支持 `--border`。
+
+## 创建你的第一个 TUI
+
+### 检查 `tui` 值
+
+因为构建器仅描述界面，所以在运行之前，你可以查看构建出来的结构：
+
+```nu
+tui label --titlebar "App" | tui table | describe
+# => tui
+
+tui label --titlebar "App" | tui table | get widgets.type
+# => ╭───┬───────╮
+# => │ 0 │ label │
+# => │ 1 │ table │
+# => ╰───┴───────╯
+```
+
+每个部件记录都包含 `id`、`type`，对于容器还包含 `children`。其他字段则取决于部件的种类。例如，标签的 `slot` 可以是 `titlebar`（标题栏）、`status`（状态栏）或 `content`（内联文本）；使用 `--title` 或 `--border` 构建的部件则具有 `title` 或 `border` 字段。
+
+### 无终端渲染
+
+`tui debug` 返回一条记录，其 `screen` 字段保存了绘制出的纯文本界面：
+
+```nu
+tui label --titlebar "hello" | tui label --status "ready" | tui debug --size [40 6] | get screen
+# =>  hello
+# =>
+# =>
+# =>
+# =>
+# =>  ready  tab:focus  [:page  q:quit
+```
+
+状态栏会自动追加可用快捷键的简要提示。默认画布尺寸为 80×24；可通过 `--size [width height]` 进行修改。
+
+### 获取选择结果
+
+将数据行管道传输给 [`tui table`](/commands/docs/tui_table.md) 并运行，按 `Enter` 即可提交当前高亮的行：
+
+```nu
+let picked = ls | tui table --columns [name type size] | tui run
+if $picked.action == "submit" {
+    $picked.selected
+}
+```
+
+`tui debug --keys` 可以重放按键序列，方便你在脚本或测试中验证交互行为：
+
+```nu
+[{name: a}, {name: b}] | tui table | tui debug --keys [down enter] | get selected.name
+# => b
+```
+
+如果不传递 `--columns`，表格会展示输入数据的所有列。标量列表或范围（range）则展示为单列 `item`：
+
+```nu
+1..20 | tui table | tui run
+```
+
+## 布局
+
+### 堆叠部件
+
+外层管道中的部件按添加顺序从上到下垂直堆叠。相邻的 [`tui button`](/commands/docs/tui_button.md) 是个例外：它们会在同一行内从左到右水平排布。
+
+```nu
+tui label "Delete everything?" | tui button Yes | tui button No | tui debug --size [30 4] | get screen
+# => Delete everything?
+# =>  [ Yes ]  [ No ]
+```
+
+部分部件属于界面的*全局装饰（chrome）*，只能在外层管道中使用：
+
+- `tui label --titlebar`（顶部标题栏）
+- `tui label --status`（底部状态栏）
+- `tui menu`（菜单栏）
+- `tui tab`（标签页）
+
+在容器内部使用上述部件会导致错误。
+
+### 分割窗格
+
+[`tui split`](/commands/docs/tui_split.md) 将其所在区域划分给一组子部件：默认横向并排，添加 `--vertical` 则为纵向堆叠。子部件放在括号内进行构建：
+
+```nu
+ls | tui split [ (tui table --columns [name type]) (tui preview) ] | tui run
+```
+
+`--sizes` 为每个子部件指定尺寸。未显式指定的项默认为 `1fr`：
+
+| 尺寸                   | 含义                                                  |
+| ---------------------- | ----------------------------------------------------- |
+| `20`                   | 20 个单元格（字符宽/高）                              |
+| `"30%"` 或 `30%`       | 占分割区域的 30%                                      |
+| `"1fr"`, `"2fr"`       | 剩余空间的分配比例；`2fr` 所分得的空间是 `1fr` 的两倍 |
+| `"min:10"`, `"max:40"` | 至少或最多占用这么多单元格                            |
+
+`--ratio 60` 是 `--sizes [60% 1fr]` 的简写。分割窗格支持嵌套：
+
+```nu
+ls
+| tui split --sizes [30 1fr] [
+    (tui tree --walk)
+    (tui split --vertical --ratio 70 [ (tui preview) (tui log) ])
+  ]
+| tui run
+```
+
+每对窗格之间都有一个单元格宽度的拖动手柄。使用鼠标拖动任意手柄，手柄会移动到尽可能贴近鼠标指针的位置（以相邻窗格所允许的极限为准）。若使用键盘，可通过 `Tab` 切换焦点至 split，然后使用方向键（或 `hjkl`）移动第一个分割线。每按一次移动一个单元格；在宽度或高度超过 100 单元格的大分割窗格中，每次移动若干单元格。每个窗格至少保留一个单元格。`tui debug` 在 `values` 字段下报告各窗格的当前尺寸：
+
+```nu
+ls | tui split --ratio 60 [ (tui table) (tui preview) ] | tui debug | get values.split-0
+# => ╭───┬─────╮
+# => │ 0 │ 60% │
+# => │ 1 │ 1fr │
+# => ╰───┴─────╯
+```
+
+如果某个 split 的所有子部件都具有固定高度（按钮、标签、文本输入框和进度条），则不会将其划分为可调节窗格。它会严格按子部件所需的高度渲染，不绘制拖动手柄，也无法通过键盘调整大小。这可用于垂直排列按钮，或将文本框与按钮并排摆放：
+
+```nu
+tui split --vertical [ (tui button Yes) (tui button No) ] | tui debug --size [30 4] | get screen
+# =>  [ Yes ]
+# =>  [ No ]
+
+tui label "name" | tui split [ (tui textbox --id name) (tui button Go) ] | tui debug --size [40 4] | get screen
+# => name
+# => ┌ input ───────────┐ [ Go ]
+# => │▌                 │
+# => └──────────────────┘
+```
+
+### 分组框
+
+[`tui box`](/commands/docs/tui_box.md) 为其子部件绘制带标题的边框，可放置在任意位置，包括 split 内部：
+
+```nu
+ls | tui split [ (tui box "list" [ (tui search) (tui table) ]) (tui preview) ] | tui run
+```
+
+### 边框标题
+
+具有边框的部件会在顶部边框中显示其名称，随后在括号中显示当前状态（例如行数）。`--title` 会替换该名称，同时保留状态信息：
+
+```nu
+[a b c] | tui table --title letters | tui debug --size [30 6] | get screen
+# => ┌ letters (3) ───────────────┐
+# => │  item                      │
+# => │▶ a                         │
+# => │  b                         │
+# => │  c                         │
+# => └────────────────────────────┘
+```
+
+| 部件         | 默认标题                              | 指定 `--title files` 后                   |
+| ------------ | ------------------------------------- | ----------------------------------------- |
+| table        | `table (12)`, `table (12, 3 checked)` | `files (12)`, `files (12, 3 checked)`     |
+| select, tree | `select (4)`, `tree (40)`             | `files (4)`, `files (40)`                 |
+| log          | `log`, `log (live)`, `log (paused)`   | `files`, `files (live)`, `files (paused)` |
+| search       | `search`, `search (fuzzy)`            | `files`, `files (fuzzy)`                  |
+| textbox      | `input`                               | `files`                                   |
+| preview      | 预览文件的名称，或 `preview`          | `files (Cargo.toml)` 或 `files`           |
+
+预览部件没有固定的名称，因为其边框会直接显示正在预览的文件名。使用 `--title` 时，指定的标题在前，文件名跟在括号中。搜索框也会将 `--title` 作为占位提示符，除非额外指定了 `--placeholder`。传入空的 `--title` 会报错。
+
+`tui box` 将标题作为其第一个位置参数，而 `tui label --titlebar` 用于设置整个界面顶部的标题栏。
+
+::: tip
+`tui label --titlebar` 以前写作 `tui label --title`。旧写法目前仍可使用但会打印弃用警告，并将在 0.118.0 版本中移除。
+:::
+
+### 标签页
+
+[`tui tab`](/commands/docs/tui_tab.md) 将一组部件组合为一个独立页面。只要存在至少一个顶层 tab，界面就会显示标签栏：
+
+```nu
+ls
+| tui tab "table" [ (tui table --columns [name type size]) ]
+| tui tab "tree" [ (tui split [ (tui tree --walk) (tui preview) ]) ]
+| tui run
+```
+
+切换页面的方式有：直接点击标签页、按 `[` 和 `]` 键、按 `Ctrl+Left` 和 `Ctrl+Right`、按 `Ctrl+Tab` 和 `Ctrl+Shift+Tab`，或者直接按数字键（`1` 到 `9`）快速跳转到对应页面。标签页不支持嵌套。
+
+```nu
+ls | tui tab "a" [ (tui table) ] | tui tab "b" [ (tui table) ] | tui debug --keys ["2"] | get page
+# => 1
+```
+
+### 部件标识符
+
+每个部件都会自动分配一个由其类型和序号构成的 ID，例如 `table-0` 或 `search-0`，不同种类的部件分别计数。当两个容器各自包含一个 `table-0` 时，第二个会被自动重编号为 `table-1`：
+
+```nu
+tui split [ (tui box "a" [(tui table)]) (tui box "b" [(tui table)]) ] | tui debug | get focus.order
+# => ╭───┬─────────╮
+# => │ 0 │ table-0 │
+# => │ 1 │ table-1 │
+# => │ 2 │ split-0 │
+# => ╰───┴─────────╯
+```
+
+通过显式 `--id` 指定的名称绝不会被自动重编号，两次使用相同的显式 ID 将抛出错误。当其他部件需要引用该部件（例如通过 `--from` 选项），或者你希望从结果记录中通过可预测的名称读取其状态时，请务必使用 `--id` 为其命名。
+
+## 部件的数据来源
+
+每个数据部件按优先级显示以下首个存在的数据：
+
+1. 由其 `--from` 数据源或闭包产生的内容（参见[跟随选中行](#跟随选中行)）。
+2. 部件自带的 `--data`，或者在容器子列表中直接通过管道传给它的值，如 `[(ls | tui table)]`。
+3. 最近外层封闭容器的数据。
+4. 传给最外层管道的数据。
+
+`--data` 不能与 `--from` 或闭包同时使用，因为部件将永远无法展示它。`tui progress --value` 也遵循该规则。
+
+这意味着一条管道可以为所有部件提供数据，也可以让每个窗格拥有独立的数据行：
+
+```nu
+ls | tui split [ (tui table) (tui tree) ] | tui run           # 两者均展示 ls 的结果
+tui split [ (ps | tui table) (ls | tui table) ] | tui run      # 各自展示独立的数据行
+tui split [ (tui table --data (ps)) (tui table --data (ls)) ] | tui run   # 显式书写的等价形式
+```
+
+```nu
+tui split [ ([1 2] | tui table) ([3] | tui table) ] | tui debug | get widgets.0.children.rows
+# => ╭───┬───╮
+# => │ 0 │ 2 │
+# => │ 1 │ 1 │
+# => ╰───┴───╯
+```
+
+传给子部件的数据必须有能够展示它的部件。如果子列表中的每个部件都自带 `--data`，则管道传入的数据行无处展示，`tui run` 和 `tui debug` 将报错停止：
+
+```nu
+tui split [ ([1 2] | tui table --data [a b]) ] | tui debug
+# => Error: nu::shell::error
+# =>
+# =>   × piped data has no widget to show it
+# =>    ╭─[repl_entry #1:1:1]
+# =>  1 │ tui split [ ([1 2] | tui table --data [a b]) ] | tui debug
+# =>    · ────┬────
+# =>    ·     ╰── no widget in this child can show the data piped into it: each has its own --data, or there are none
+# =>    ╰────
+```
+
+### 数据流
+
+构建器不会提前读取管道传给它们的数据流。在界面打开后，`tui run` 会在后台线程中读取每个数据流，使新数据到达时能够实时呈现。这包括外部命令输出、范围序列以及较慢的 `each` 管道：
+
+```nu
+# 每秒输出一行新内容，直到按 q 退出
+1.. | each {|n| sleep 1sec; $"tick ($n)" } | tui log | tui run
+
+# 跟踪持续增长的日志文件
+^tail -f app.log | tui label --titlebar "app.log" | tui log | tui run
+
+# 随数据流推进的动态进度条
+1..100 | each {|n| sleep 50ms; $n } | tui progress --total 100 | tui run
+```
+
+传给子列表内部件的数据流同样是实时的，因此每个窗格都可以跟踪各自的数据源：
+
+```nu
+tui split [ (^tail -f app.log | tui log) (ls | tui table) ] | tui run
+```
+
+如果在外部命令仍在运行时关闭界面，该外部命令会被终止。
+
+每个数据流大约保留最新的 100,000 行。较早的数据会以每批 12,500 行进行丢弃，因此在两次丢弃之间最多可能会多出 12,499 行数据。`tui log --max-lines` 可以为日志部件调高该上限。
+
+构建器不预读数据流会带来以下几点特性：
+
+- 构建器始终返回 `tui` 值，即使输入是数据流。例如 `1.. | tui table | first` 会报错，而不是返回第一行输入。
+- 通过 `let` 保存的 `tui` 值在首次运行时读取数据流。如果流已结束，后续运行会展示相同的数据行；如果界面在流结束前关闭，后续运行将不展示任何数据。
+- 当 hook 返回新数据时（参见 [Hook 契约](#hook-契约)），该数据将在后续运行中替换原管道数据，且原数据流不再追加新行。
+
+`tui debug` 会在绘制前读取管道流直到结束（最多等待 5 秒），并像 `tui run` 一样保留最新数据。其结果中的 `live` 字段指明数据流是否仍在产生新行。请勿向其传入无限制的无限数据流。
+
+## 跟随选中行
+
+### 预览窗格
+
+[`tui preview`](/commands/docs/tui_preview.md) 显示列表中高亮选中行的文本。如果不提供闭包，它会读取该行 `name` 列所指定的文件。目录和二进制文件会显示简要提示，且最多读取 `--max-bytes` 字节（默认为 65536 字节）：
+
+```nu
+ls | tui split [ (tui table --columns [name type]) (tui preview) ] | tui run
+```
+
+键盘方向键保持在表格上，预览内容会随光标移动实时联动。预览跟随获得焦点的列表，或者同容器内最近的列表，或者首个可见的列表。可以使用 `--from <id>` 显式指定要跟随的列表 ID。
+
+**不带参数**的闭包用于转换文件内容文本，内容通过 `$in` 传入闭包。结果中的 ANSI 颜色代码会被正常渲染，因此可以使用 `nu-highlight` 或 `bat` 实现语法高亮：
+
+```nu
+ls | tui split [ (tui table) (tui preview { nu-highlight }) ] | tui run
+```
+
+**带一个参数**的闭包接收当前高亮选中的行。此时不会从磁盘读取任何文件，而是直接展示闭包返回的内容：
+
+```nu
+$env.config.keybindings
+| tui split [ (tui table --columns [name modifier keycode]) (tui preview {|row| $row.event | to nuon }) ]
+| tui run
+```
+
+### 详情视图与说明文字
+
+任何数据部件都可以通过这种方式跟随选中行。使用 `--from <id>` 指定源列表，并通过位置闭包将该列表的高亮行转换为当前部件的数据。这样表格就能作为详情视图使用：
+
+```nu
+[{name: a, kids: [1 2]}, {name: b, kids: [3 4 5]}]
+| tui split [ (tui table --id src --columns [name]) (tui table --from src {|r| $r.kids }) ]
+| tui debug --keys [down] --size [50 7]
+| get screen
+# => ┌ table (2) ────────────┐│┌ table (3) ───────────┐
+# => │  name                 │││  item                │
+# => │  a                    │││▶ 3                   │
+# => │▶ b                    │││  4                   │
+# => │                       │││  5                   │
+# => │                       │││                      │
+# => └───────────────────────┘│└──────────────────────┘
+```
+
+标签部件可以作为高亮行的说明：
+
+```nu
+[{name: a, size: 1kb} {name: b, size: 2kb}]
+| tui table --columns [name]
+| tui label {|row| $"size: ($row.size)" }
+| tui debug --keys [down] --size [40 6]
+| get screen
+# => ┌ table (2) ───────────────────────────┐
+# => │  name                                │
+# => │  a                                   │
+# => │▶ b                                   │
+# => └──────────────────────────────────────┘
+# => size: 2.0 kB
+```
+
+若未指定 `--from`，带有数据源闭包的部件会像预览窗格一样跟随最近的列表。如果当前显示的页面没有表格、树形视图或选择列表，它会跟随其它 [`tui tab`](#标签页) 页面上的列表。若不带闭包，高亮行本身直接成为该部件的数据。数据源闭包仅在高亮行发生变化或窗格大小调整时重新运行。
+
+当闭包无可跟随的目标时，`tui run` 和 `tui debug` 会报错停止：界面完全没有表格、树形视图或选择列表、`--from` 指向不存在或无数据的部件、`--from` 指向部件自身，或者部件之间存在循环跟随。例如，为流式日志附加了闭包却没有任何可跟随的列表：
+
+```nu
+1..5 | each {|n| $"tick ($n)"} | tui label --titlebar "ticks" | tui log { $in } | tui run
+# => Error: nu::shell::error
+# =>
+# =>   × nothing for the closure to follow
+# =>    ╭─[repl_entry #1:1:65]
+# =>  1 │ 1..5 | each {|n| $"tick ($n)"} | tui label --titlebar "ticks" | tui log { $in } | tui run
+# =>    ·                                                                 ───┬───
+# =>    ·                                                                    ╰── `log-0` runs its closure on the highlighted row of a table, tree, or select, but none can be followed: a widget never follows its own row, or one that follows it. Add one, or drop the closure
+# =>    ╰────
+```
+
+去掉闭包（改用 `tui log`）即可在管道数据到达时正常展示。
+
+### 让输出适配窗格大小
+
+预览和数据源闭包可以通过环境变量 `$env.TUI_WIDTH` 和 `$env.TUI_HEIGHT` 获取当前窗格的内部可用尺寸：
+
+```nu
+[{name: a}]
+| tui split [ (tui table) (tui preview {|row| $"w=($env.TUI_WIDTH) h=($env.TUI_HEIGHT)" }) ]
+| tui debug --size [60 6]
+| get screen
+# => ┌ table (1) ─────────────────┐│┌ a ────────────────────────┐
+# => │  name                      │││w=27 h=4                   │
+# => │▶ a                         │││                           │
+# => │                            │││                           │
+# => │                            │││                           │
+# => └────────────────────────────┘│└───────────────────────────┘
+```
+
+这对于根据终端尺寸自适应排版的命令至关重要。例如不加 `-w` 的 [`table`](/commands/docs/table.md) 会使用完整终端宽度，从而在窗格内溢出，此时应传入窗格宽度：
+
+```nu
+ps | tui split [ (tui table --columns [pid name]) (tui preview {|p| $p | table -e -w $env.TUI_WIDTH }) ] | tui run
+```
+
+## 搜索与筛选
+
+[`tui search`](/commands/docs/tui_search.md) 用于添加搜索框。在输入时，它会实时筛选表格、日志、树形视图和选择列表：
+
+```nu
+ls
+| tui label --titlebar "files"
+| tui search --placeholder "filter" --bind /
+| tui table --columns [name type size]
+| tui label --status "enter: pick  /: filter  q: quit"
+| tui run
+```
+
+- 按下 `--bind` 绑定的按键（此处为 `/`）可以从除文本框外的任何位置将焦点切换至搜索框。为搜索框指定 `--focus` 可以在启动时直接聚焦，方便立即键入筛选。
+- 按 `Enter` 提交筛选后列表中的高亮行。
+- 按 `Esc` 清空当前搜索词；再次按 `Esc` 退出搜索框焦点。在搜索框内输入时，`q` 仅作为普通的字母字符输入。
+
+默认情况下，搜索会对每个字段进行不区分大小写的子字符串匹配。`--fuzzy` 使用与 `input list --fuzzy` 相同的模糊匹配器，`--case-sensitive` 区分大小写，`--columns` 则将匹配范围限制在指定列：
+
+```nu
+[{name: alpha}, {name: gamma}]
+| tui search --fuzzy --columns [name] --bind /
+| tui table
+| tui debug --keys "/,type:gm,enter"
+| get selected.name
+# => gamma
+```
+
+### 搜索作用域
+
+搜索框的位置决定了它的筛选范围。在外层管道中，它会筛选所有列表；在 `tui split` 或 `tui box` 内部，它只筛选该容器内的列表，且每个搜索框保留各自独立的搜索词：
+
+```nu
+ls
+| tui split [
+    (tui box "files" [ (tui search --bind /) (tui table --id files) ])   # 仅筛选 `files` 表格
+    (tui table --id other)                                               # 绝不被筛选
+  ]
+| tui run
+```
+
+`tui debug` 会在各列表的 `search_scope` 字段中显示其关联的搜索框。
+
+### 按按键组合筛选
+
+使用 `--capture-keys` 选项，当表格获得焦点时，按下的组合键将直接作为筛选查询。包含 reedline 风格 `modifier` 和 `keycode` 字段的数据行可与按键组合匹配，例如 `$env.config.keybindings` 中的 `control` + `char_r` 行即可匹配 `Ctrl+R`：
+
+```nu
+[
+    {name: "history", modifier: "control", keycode: "char_r", mode: "emacs"}
+    {name: "clear", modifier: "control", keycode: "char_l", mode: "emacs"}
+]
+| tui table --capture-keys
+| tui debug --keys "ctrl+r,enter"
+| get selected.name
+# => history
+```
+
+这可以用来快速实现一个快捷键查看器：
+
+```nu
+def "keys ui" [] {
+    $env.config.keybindings
+    | tui label --titlebar "keybindings"
+    | tui search --placeholder "type to filter, or focus the list and press a chord" --bind /
+    | tui table --capture-keys --columns [name modifier keycode]
+    | tui label --status "/: search  chord: filter list  enter: pick  q: quit"
+    | tui run
+}
+```
+
+`Tab`、`Enter`、`Esc`、`q`、`[`、`]` 以及页面数字键仍保持其原有的快捷键功能。
+
+## 列表、树形视图与选择器
+
+### 多行选择
+
+`--multi` 将表格、树形视图或选择列表转换为复选清单。按 `Space` 勾选高亮行，按 `Enter` 提交所有已勾选的行（如果未勾选任何行，则提交当前高亮行）。`--index`（适用于表格和选择列表）可改为提交元素位置索引而非数据行：
+
+```nu
+[a b c] | tui table --multi | tui debug --keys [space down space enter] | get selected
+# => ╭───┬───╮
+# => │ 0 │ a │
+# => │ 1 │ b │
+# => ╰───┴───╯
+
+[a b c] | tui table --index | tui debug --keys [down enter] | get selected
+# => 1
+```
+
+### 选择列表
+
+[`tui select`](/commands/docs/tui_select.md) 从其参数、`--data` 或管道输入展示单选列表：
+
+```nu
+tui select [small medium large] | tui debug --keys [down enter] | get selected
+# => medium
+```
+
+`--display` 用于指定每个选项的显示标签：可以是列名或闭包。最终返回的依然是原始元素，与 `input list --display` 表现一致：
+
+```nu
+[{n: 1, label: one} {n: 2, label: two}] | tui select --display label | tui debug --keys [down enter] | get selected
+# => ╭───────┬─────╮
+# => │ n     │ 2   │
+# => │ label │ two │
+# => ╰───────┴─────╯
+```
+
+配合 `--multi`，它会变成复选框列表：
+
+```nu
+tui select --multi [a b c] | tui debug --keys [space down] --size [26 5] | get screen
+# => ┌ select (3, 1 checked) ─┐
+# => │[x] a                   │
+# => │[ ] b                   │
+# => │[ ] c                   │
+# => └────────────────────────┘
+```
+
+### 树形视图
+
+[`tui tree`](/commands/docs/tui_tree.md) 用于展示嵌套的记录和列表。顶层键作为根节点，叶子节点显示为 `key: value`。按 `Right`（或 `l`）展开节点，按 `Left`（或 `h`）折叠节点，按 `Enter` 提交选中节点：
+
+```nu
+{a: {b: 1, c: 2}, d: [3, 4]} | tui tree | tui debug --keys [right down down down right] --size [30 9] | get screen
+# => ┌ tree (6) ──────────────────┐
+# => │▾ a                         │
+# => │    b: 1                    │
+# => │    c: 2                    │
+# => │▾ d                         │
+# => │    3                       │
+# => │    4                       │
+# => │                            │
+# => └────────────────────────────┘
+```
+
+任何记录都会展开为其各个字段，因此 `ls` 输出的数据行展开后会显示 `name`、`type`、`size` 和 `modified`。
+
+添加 `--walk` 后，`type` 为 `dir` 的行会被视为文件夹，展开时会实时从磁盘读取目录内容。相对路径基于当前工作目录解析，`--column` 用于指定路径列（默认为 `name`）：
+
+```nu
+ls | tui split [ (tui tree --walk) (tui preview) ] | tui run
+```
+
+### 日志视图
+
+[`tui log`](/commands/docs/tui_log.md) 是一个仅追加视图，始终跟随其最新数据末尾。向上滚动（使用方向键、`PageUp`/`PageDown` 或鼠标滚轮）会暂停自动滚动，标题变为 `log (paused)`。滚动回底部或按 `End` 即可恢复自动跟随。`--max-lines`（默认为 10000 行）限制日志最多展示多少行最新数据：
+
+```nu
+1..30 | each {|n| $"tick ($n)" } | tui log | tui debug --size [30 6] | get screen
+# => ┌ log ───────────────────────┐
+# => │tick 27                     │
+# => │tick 28                     │
+# => │tick 29                     │
+# => │tick 30                     │
+# => └────────────────────────────┘
+```
+
+### 进度条
+
+[`tui progress`](/commands/docs/tui_progress.md) 展示 `--value`，或者从其数据中读取数值：支持单个数字、记录中的 `value` 字段或列表中的最后一个数字。小于等于 1 的值按整体比例解释（例如 0.4 表示 40%）；大于 1 的值则基于 `--total`（默认为 100）计算比例：
+
+```nu
+tui progress --value 0.4 --label copying | tui debug --size [40 4] | get screen
+# => ██████████████copying 40%
+
+[10 20 30] | tui progress --label done | tui debug --size [30 4] | get screen
+# => █████████  done 30%
+```
+
+由于默认提取列表中的最后一个数字，因此数字流可以直接驱动进度条动画，例如 `1..100 | each {|n| sleep 50ms; $n } | tui progress --total 100`。配合 `--from` 和闭包，进度条还可以跟随其它部件的高亮行展示对应进度。
+
+## 打造交互式界面
+
+### Hook 契约
+
+响应用户操作的所有闭包均遵循统一的交互契约。这包括 `tui bind`、`tui button`、菜单操作、`--on-select` 以及传递给 `tui run` 或 `tui debug` 的闭包。hook 会同时通过 `$in` 以及声明的第一个形参接收状态记录（与 `tui run` 返回的记录结构相同，详见[结果记录](#结果记录)）。hook 的返回值决定下一步操作：
+
+| hook 返回值                       | 产生效果                                                           |
+| --------------------------------- | ------------------------------------------------------------------ |
+| 无返回值                          | 不发生任何状态改变                                                 |
+| `{action: submit, selected: ...}` | TUI 退出并返回该选择内容                                           |
+| `{action: quit}`                  | TUI 直接退出，不返回选择内容                                       |
+| 其它任何数据                      | 替换共享数据列表，管道数据流不再追加新行；读取该数据的所有部件重绘 |
+
+如果 hook 抛出错误，错误信息会在状态栏显示为 `error:...`，且 TUI 保持打开状态：
+
+```nu
+[a b] | tui table | tui bind x {|| error make {msg: boom} } | tui label --status "ready" | tui debug --keys [x] --size [50 6] | get screen
+# => ┌ table (2) ─────────────────────────────────────┐
+# => │  item                                          │
+# => │▶ a                                             │
+# => │  b                                             │
+# => └────────────────────────────────────────────────┘
+# =>  ready  error:boom  focus:table-0  rows:2  tab:foc
+```
+
+### 快捷键绑定
+
+[`tui bind`](/commands/docs/tui_bind.md) 用于在 TUI 内任何位置按下特定按键时触发运行 hook。按键可以是类似 `ctrl+s`、`alt+r`、`f5` 或 `x` 的组合键字符串，或者是 `$env.config.keybindings` 中的 reedline 风格记录：
+
+```nu
+ls
+| tui table --columns [name type size]
+| tui bind ctrl+r {|| ls }                                                  # 重新加载
+| tui bind s {|state| {action: submit, selected: $state.selected.name} }    # 仅提交名称
+| tui run
+```
+
+```nu
+[a b] | tui table | tui bind ctrl+r {|| [x y z] } | tui debug --keys ctrl+r | get rows
+# => 3
+
+[a b] | tui table | tui bind {modifier: control, keycode: char_q} {|| {action: quit} } | tui debug --keys ctrl+q | get action
+# => quit
+```
+
+自定义按键绑定的优先级高于内置按键（`Ctrl+C` 除外）。不带修饰键的绑定在搜索框或文本框输入时不会被触发。
+
+### 响应选择变更
+
+在表格、树形视图或选择列表上添加 `--on-select` 可以在光标高亮移动时触发运行 hook。可用于在界面外部执行副作用；请勿在 hook 中执行打印，否则会破坏终端绘制画面：
+
+```nu
+ls | tui table --on-select {|s| $s.selected.name | save -f last-picked.txt } | tui run
+```
+
+若要在屏幕上展示有关当前选中的信息，应改用[跟随选中行](#跟随选中行)的部件：
+
+```nu
+ls | tui table --columns [name] | tui label {|row| $"selected: ($row.name)  ($row.size)" } | tui run
+```
+
+### 定时刷新
+
+传递给 `tui run` 的闭包是一个在首帧渲染前运行一次的 hook。添加 `--refresh` 选项后，它会在每个时间间隔重复运行，其输出将替换共享数据列表（原管道数据流随之停止追加）。高亮状态和搜索词均会予以保留；若刷新操作失败，界面会保留上一批正常数据：
+
+```nu
+ls | tui table | tui run --refresh 1sec { ls }
+```
+
+`tui debug` 在绘制前会执行一次该闭包：
+
+```nu
+[{name: old}] | tui table --columns [name] | tui debug { [{name: new}] } --size [30 4] | get screen
+# => ┌ table (1) ─────────────────┐
+# => │  name                      │
+# => │▶ new                       │
+# => └────────────────────────────┘
+```
+
+### 菜单栏
+
+[`tui menu`](/commands/docs/tui_menu.md) 用于添加菜单栏。每个菜单项可以是字符串，或者形如 `{name, items?, action?}` 的记录。`items` 展开为下拉菜单，`action` 是一个 hook：
+
+```nu
+ls
+| tui label --titlebar "Files"
+| tui menu [
+    {name: "&File", items: [
+        {name: "&Reload", action: {|| ls }}
+        {name: "&Parent", action: {|| ls .. }}
+        "&Quit"
+    ]}
+    {name: "&Sort", items: [
+        {name: "by &Name", action: {|| ls | sort-by name }}
+        {name: "by &Size", action: {|| ls | sort-by size }}
+        {name: "by &Modified", action: {|| ls | sort-by modified }}
+    ]}
+    "&Help"
+  ]
+| tui table --columns [name type size modified]
+| tui label --status "alt+f: file  alt+s: sort  q: quit"
+| tui run
+```
+
+- **助记符（Mnemonics）：** 字母前的 `&` 会将该字母设为快捷键并在界面上加下划线标示。若未指定 `&`，则默认使用第一个字母。`Alt+F` 可在除文本框外的任意位置打开 File 菜单。下拉菜单打开后，直接按单个字母即可触发菜单项，例如 `Alt+S` 后按 `N` 即可按名称排序。
+- **按键导航：** `Left`/`Right`（或 `h`/`l`）在菜单栏上左右切换。`Down` 或 `Enter` 打开下拉菜单（或直接触发无下拉菜单的项）。`Esc` 关闭下拉菜单。各菜单项亦支持鼠标直接点击。
+- **操作（Actions）：** 带有 `action` 的菜单项在激活时会将其作为 hook 运行。
+- **提交选择：** 不带 action 的菜单项会提交并关闭 TUI。对于下拉项，`selected` 为 `{menu, item, row}`，其中 `row` 为表格的高亮行，方便对其进行针对性处理；对于没有下拉菜单的顶层菜单项，`selected` 为其名称。
+
+```nu
+[{name: x.txt}] | tui menu [{name: "&File", items: ["&Open" "&Quit"]}] | tui table | tui debug --keys "alt+f,o" | get selected | to nuon
+# => {menu: File, item: Open, row: {name: "x.txt"}}
+
+[a b] | tui menu [{name: "&File", items: [{name: "&Reload", action: {|| [x y z] }} "&Quit"]}] | tui table | tui debug --keys "alt+f,r" | get rows
+# => 3
+```
+
+### 表单：文本框与按钮
+
+[`tui textbox`](/commands/docs/tui_textbox.md) 是可编辑字段，[`tui button`](/commands/docs/tui_button.md) 是可获取焦点的操作标签。使用 `Tab` 和 `Shift+Tab` 在它们之间切换焦点：
+
+```nu
+tui label --titlebar "rename"
+| tui label "new name"
+| tui textbox --id name --placeholder "type a name"
+| tui button Save {|s| $s.values.name | save name.txt; {action: quit} }
+| tui button Cancel {|| {action: quit} }
+| tui label --status "tab: next  enter: activate  esc: cancel"
+| tui run
+```
+
+当文本框获得焦点时，`q` 仅代表输入普通字符，按 `Esc` 离开该输入框。按 `Enter` 提交，输入的文本作为 `selected` 返回。文本亦可通过 ID 在 `values` 中读取，`--value` 可设置初始文本：
+
+```nu
+tui textbox --id name | tui debug --keys "type:bob,enter" | select action selected values | to nuon
+# => {action: submit, selected: bob, values: {name: bob}}
+```
+
+在聚焦的按钮上按 `Enter`、`Space` 或直接鼠标点击即可激活。带 hook 的按钮行为与 `tui bind` 一致；不带 hook 的按钮则直接提交其自身的标签文本，因此两个普通按钮即可构成一个简易确认对话框。在同一行内的多个按钮间可用 `Left`/`Right`（或 `h`/`l`）切换焦点：
+
+```nu
+tui label "Delete?" | tui button Yes | tui button No | tui debug --keys [right enter] | get selected
+# => No
+```
+
+## 运行 TUI
+
+### 弹出式对话框
+
+`tui run --dialog`（`-d`）会在备用屏幕上以居中的浮动小窗口展示该界面。若未指定 `--size`，对话框尺寸约为终端画面的四分之三，且不小于 40×12。拖动标题栏可移动位置，拖动右下角可调整大小，点击 `x` 即可关闭：
+
+```nu
+[a b c] | tui label --titlebar "pick" | tui table | tui debug --dialog --size [40 10] | get screen
+# => ┌ pick ───────────────────────────── x ┐
+# => │ pick                                 │
+# => │┌ table (3) ─────────────────────────┐│
+# => ││  item                              ││
+# => ││▶ a                                 ││
+# => ││  b                                 ││
+# => ││  c                                 ││
+# => ││                                    ││
+# => │└────────────────────────────────────┘│
+# => └──────────────────────────────────────┘
+```
+
+`--no-mouse` 可关闭鼠标捕获，使终端原生的文本划选与复制功能恢复生效。
+
+### 键盘与鼠标操作
+
+| 按键                                                                          | 操作行为                                                                                                                |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `Tab` / `Shift+Tab`                                                           | 切换焦点。当前聚焦的部件呈现 `border_focused` 颜色。焦点优先落在由 `--focus` 指定的部件上，或首个列表、输入框或按钮上。 |
+| 文本键入                                                                      | 直接输入到聚焦的搜索框或文本框中。                                                                                      |
+| `Enter`                                                                       | 提交聚焦部件的当前选择内容。若在菜单上，则打开下拉项或执行菜单动作。                                                    |
+| `Space`                                                                       | 在 `--multi` 列表中勾选高亮行，或激活按钮。                                                                             |
+| `Esc`                                                                         | 在搜索框内先清空查询再退出搜索；在文本框内离开当前输入框；在下拉菜单展开时关闭下拉项；其它情况下退出 TUI。              |
+| 方向键、`hjkl`、`PageUp`/`PageDown`、`Home`/`End`                             | 在表格、树形视图和选择列表中移动；滚动日志；在菜单项或同一行按钮间移动；移动 split 的首个分割线。                       |
+| `Alt+`字母                                                                    | 打开对应助记快捷键的菜单项。                                                                                            |
+| `q`（非输入状态下）或 `Ctrl+C`                                                | 退出 TUI。此时 `selected` 为 `null`。                                                                                   |
+| `[` / `]`、`Ctrl+Left` / `Ctrl+Right`、`Ctrl+Tab` / `Ctrl+Shift+Tab`、`1`-`9` | 切换标签页面。                                                                                                          |
+| 鼠标操作                                                                      | 单击聚焦并选定、滚轮滚动内容、拖拽 split 分隔手柄、单击菜单项与按钮。                                                   |
+
+可聚焦的部件包括：菜单、表格、选择列表、树形视图、日志、搜索框、文本输入框、按钮和 split 分隔手柄。标签、预览窗格、进度条、分组框和标签页本身不可聚焦。
+
+### 结果记录
+
+`tui run` 返回一条记录，所有 hook 接收到的也是相同结构的记录：
+
+| 字段       | 含义                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------ |
+| `action`   | `submit`、`quit`，或者（仅在 `tui debug` 且未发生退出/提交时）`render`                           |
+| `focused`  | 当前获得焦点的部件 ID                                                                            |
+| `selected` | 聚焦部件的选择结果：单行、勾选行列表、索引、树节点、`{menu, item, row}` 记录、输入文本或按钮标签 |
+| `page`     | 当前标签页面的索引                                                                               |
+| `values`   | 所有部件的状态信息，以 ID 为键                                                                   |
+| `rows`     | 共享数据列表的总行数                                                                             |
+| `live`     | 数据流是否仍在产生新数据行                                                                       |
+
+`tui debug` 还会额外包含 `screen`（渲染画面）、解析后的 `widgets` 树、`focus`（焦点遍历顺序 `order` 和默认部件 `default`）以及 `pages`。
+
+`values` 中各个部件的取值结构因部件类型而异：
+
+| 部件             | 取值结构                                                             |
+| ---------------- | -------------------------------------------------------------------- |
+| 搜索框、文本框   | 当前输入的文本                                                       |
+| 表格、选择列表   | `{index, row}`（配合 `--multi` 时额外包含 `checked`）                |
+| 树形视图         | `{index, path, value}`                                               |
+| 日志             | `{rows, follow}`                                                     |
+| 预览窗格         | `{title, text}`，其中 `title` 为预览文件的名称，未预览任何内容时为空 |
+| 分割窗格 (split) | 窗格尺寸列表                                                         |
+| 进度条           | 当前进度数值                                                         |
+| 按钮             | 按钮标签文本                                                         |
+
+```nu
+[{name: alpha} {name: beta}] | tui search | tui table | tui debug --keys "tab,type:be" | get values | to nuon
+# => {"search-0": be, "table-0": {index: 0, row: {name: beta}}}
+```
+
+你也可以直接通过赋予部件的 ID 读取其状态：
+
+```nu
+tui textbox --id name | tui run | get values.name
+```
+
+## 使用 `tui debug` 进行测试
+
+`tui debug --keys` 可以重放一组按键令牌（支持列表或逗号分隔的字符串）并返回结果记录（包含 `screen`）：
+
+| 按键令牌                                                           | 含义                     |
+| ------------------------------------------------------------------ | ------------------------ |
+| `enter`, `esc`, `tab`, `shift+tab`                                 | 对应控制键               |
+| `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown` | 移动导航键               |
+| `backspace`, `delete`, `space`, `insert`                           | 文本编辑键               |
+| `ctrl+c`, `ctrl+r`, `alt+f`, `f1`                                  | 修饰键与功能键           |
+| 单个字符（如 `q` 或 `/`）                                          | 输入该字符按键           |
+| `type:hello`                                                       | 输入指定字符串           |
+| `click:COL,ROW`                                                    | 在指定行列处鼠标左键单击 |
+| `drag:COL,ROW`                                                     | 鼠标左键拖拽至指定行列   |
+| `scroll-up`, `scroll-down`                                         | 鼠标滚轮滚动             |
+
+在字符串格式中，`click:10,5` 保留其内部逗号。`--until` 可以在其闭包对状态记录返回 `true` 时立即停止重放：
+
+```nu
+[a b c d] | tui table | tui debug --keys [down down down] --until {|s| $s.values.table-0.index == 1 } | get values.table-0.index
+# => 1
+```
+
+`--size` 设置画布尺寸（限制在 16-400 列与 4-200 行之间），`--dialog` 会绘制弹窗外框。这使得 `tui debug` 非常适合用于编写自动化测试：
+
+```nu
+use std/assert
+
+def pick-size [] { tui select [small medium large] }
+
+assert equal (pick-size | tui debug --keys [down enter] | get selected) "medium"
+assert equal (pick-size | tui debug --keys [esc] | get action) "quit"
+```
+
+## 主题定制
+
+主题配色源自 `$env.config.tui`，为界面的各个构成部分提供了独立设置项。除 `border_type` 外，每个键的配置格式与 [`color_config`](coloring_and_theming.md) 完全相同：支持颜色名称、`#RRGGBB` 十六进制代码或 `{fg, bg, attr}` 记录。`border_type` 则是用于选取边框线型的名称（参见[边框线型](#边框线型)）。
+
+| 配置键                        | 绘制对象                                                     | 默认值                                         |
+| ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------- |
+| `title_bar`                   | 由 `tui label --titlebar` 创建的标题栏                       | `{ fg: white, bg: blue, attr: b }`             |
+| `status_bar`                  | 由 `tui label --status` 创建的状态栏                         | `{ fg: white, bg: dark_gray }`                 |
+| `border` / `border_focused`   | 部件边框以及聚焦部件的边框                                   | `{ fg: dark_gray }` / `{ fg: cyan }`           |
+| `border_type`                 | 所有边框的线型（线型名称而非颜色）                           | `"single"`                                     |
+| `selected`                    | 表格、树形视图、选择列表和菜单中的高亮行                     | `{ attr: r }`                                  |
+| `header`                      | 表格列标题栏                                                 | `{ fg: green, attr: b }`                       |
+| `muted`                       | 占位提示符与空状态文本                                       | `{ fg: dark_gray }`                            |
+| `highlight`                   | 搜索查询词高亮和勾选标记                                     | `{ fg: yellow, attr: b }`                      |
+| `tab_active` / `tab_inactive` | 标签栏激活与未激活标签                                       | `{ fg: cyan, attr: bu }` / `{ fg: dark_gray }` |
+| `progress`                    | 进度条已填充部分                                             | `{ fg: green }`                                |
+| `button`                      | 按钮标签文本                                                 | `{ fg: white, bg: blue }`                      |
+| `surface` / `backdrop`        | 部件背后的底色以及 `--dialog` 背后的底色（仅使用 `bg` 属性） | 未设置（近黑底色）                             |
+
+```nu
+$env.config.tui.title_bar = { fg: black, bg: yellow, attr: b }
+$env.config.tui.border_focused = { fg: "#ff8800" }
+```
+
+运行 `config nu --doc` 可以查看所有配置键的完整文档。
+
+表格和树形视图单元格的配色与 `table` 和 `ls` 输出一致：普通值通过 `color_config` 按数据类型着色，路径列则通过 `LS_COLORS`（遵循 `$env.config.ls.use_ls_colors`）着色。当 `$env.config.use_ansi_coloring` 关闭时，TUI 会以单色模式绘制，并使用反色显示当前选中的行。
+
+### 边框线型
+
+边框线型的命名与 [`table --theme`](/commands/docs/table.md) 的主题名称保持一致。`$env.config.tui.border_type` 为所有边框设置默认线型，包括菜单下拉列表和 `--dialog` 弹窗外框。部件的 `--border` 选项可单独覆盖该部件的线型。该选项支持与 `table --theme` 相同的名称补全：
+
+```nu
+[a b c] | tui table --border rounded | tui debug --size [30 6] | get screen
+# => ╭ table (3) ─────────────────╮
+# => │  item                      │
+# => │▶ a                         │
+# => │  b                         │
+# => │  c                         │
+# => ╰────────────────────────────╯
+
+$env.config.tui.border_type = "double"
+[a b c] | tui table | tui debug --size [30 6] | get screen
+# => ╔ table (3) ═════════════════╗
+# => ║  item                      ║
+# => ║▶ a                         ║
+# => ║  b                         ║
+# => ║  c                         ║
+# => ╚════════════════════════════╝
+```
+
+`--border` 支持用于 `tui table`、`tui tree`、`tui select`、`tui log`、`tui preview`、`tui search`、`tui textbox` 以及 `tui box`。在 `tui menu` 上，它用于设置下拉菜单周围的边框。默认线型为 `single`。每种名称绘制该表格主题最贴近的边框样式：
+
+| 线型名称                                                 | 外观样式                                      |
+| -------------------------------------------------------- | --------------------------------------------- |
+| `single`, `thin`                                         | `┌─┐ │ └─┘`                                   |
+| `rounded`                                                | `╭─╮ │ ╰─╯`                                   |
+| `double`                                                 | `╔═╗ ║ ╚═╝`                                   |
+| `heavy`                                                  | `┏━┓ ┃ ┗━┛`                                   |
+| `reinforced`                                             | `┏─┓ │ ┗─┛`                                   |
+| `basic`, `basic_compact`                                 | `+-+ \| +-+`                                  |
+| `ascii_rounded`                                          | `.-. \| '-'`                                  |
+| `dots`                                                   | 顶部 `.`，侧边 `:`，底部 `:..:`               |
+| `compact`, `compact_double`, `restructured`, `with_love` | 顶底为 `─`、`═`、`=` 或 `❤` 边框线，侧边留空 |
+| `markdown`                                               | 侧边为 `\|`，顶部和底部留空                   |
+| `frameless`, `light`, `psql`                             | 全四周均无线条                                |
+
+边框始终占据 1 个单元格宽度，因此 `none` 和 `default` 不是合法的边框名称。如需完全无线条的边框轮廓，请使用 `frameless`。它依然保留所占单元格，且部件的标题保持可见。
+
+## 实用范例
+
+### 带有预览与搜索的文件选择器
+
+```nu
+ls
+| tui label --titlebar "files"
+| tui search --bind /
+| tui split [ (tui table --columns [name type size]) (tui preview { nu-highlight }) ]
+| tui label --status "enter: pick  /: filter  q: quit"
+| tui run
+```
+
+### 主从联动视图
+
+表格展示树形视图中高亮选中的目录内容，右侧预览窗格跟随当前获得焦点的列表：
+
+```nu
+ls
+| tui split --sizes [30 1fr] [
+    (tui tree --walk --id dirs)
+    (tui split --vertical [
+        (tui table --from dirs {|node| ls $node.name } --columns [name size modified])
+        (tui preview)
+    ])
+  ]
+| tui run
+```
+
+### 操作确认对话框
+
+```nu
+def confirm [question: string]: nothing -> bool {
+    let r = tui label $question | tui button Yes | tui button No | tui run --dialog --size [40 8]
+    $r.action == "submit" and $r.selected == "Yes"
+}
+
+if (confirm "Delete build output?") {
+    print "Deleting..."
+}
+```
+
+### 多文件勾选器
+
+针对 `ls` 输出的复选清单：按 `Space` 勾选文件，按 `Enter` 返回所有已勾选的数据行。在未勾选任何文件时，按 `Enter` 仅返回当前高亮行，因此该选择器对单选和多选场景同样适用：
+
+```nu
+def "pick files" [] {
+    let r = ls
+        | tui label --titlebar "pick files"
+        | tui search --bind / --columns [name]
+        | tui table --multi --columns [name type size modified]
+        | tui label --status "space: check  /: filter  enter: accept  q: cancel"
+        | tui run
+    if $r.action == "submit" { $r.selected } else { [] }
+}
+
+pick files | each {|f| cp $f.name backup/ }
+```
+
+### 快捷键历史命令选择器
+
+使用模糊搜索查找历史执行过的命令，并直接回填至命令行。该命令本身由原生 Nushell 编写，通过快捷键绑定分配给 `Ctrl+H`：
+
+```nu
+def "history ui" [] {
+    let r = history
+        | get command
+        | reverse
+        | uniq
+        | wrap command
+        | tui label --titlebar "history"
+        | tui search --focus --bind / --fuzzy --columns [command] --placeholder "fuzzy filter"
+        | tui table --columns [command]
+        | tui label --status "type to filter  enter: put on the command line  esc esc: cancel"
+        | tui run --dialog --size [100 24]
+    if $r.action == "submit" {
+        commandline edit --replace $r.selected.command
+    }
+}
+
+$env.config.keybindings ++= [{
+    name: history_ui
+    modifier: control
+    keycode: char_h
+    mode: [emacs vi_insert vi_normal]
+    event: { send: executehostcommand, cmd: "history ui" }
+}]
+```
+
+最新的命令排在最前，并自动剔除重复项。因为搜索框指定了 `--focus`，键入内容将直接输入模糊过滤器，按 `Enter` 会用选中的匹配项直接替换当前命令行内容。
+
+::: tip
+在不支持 kitty 键盘协议的终端中，`Ctrl+H` 发送的键码与 `Backspace` 相同。在这些终端中请配置其它组合键。
+:::
+
+### Git 分支切换器
+
+左侧显示分支名称及其更新时间和最新提交说明，右侧展示该分支的最近日志，按 `Enter` 快速切换分支：
+
+```nu
+def "git switch-ui" [] {
+    let branches = ^git branch --format="%(refname:short)|%(committerdate:relative)|%(subject)"
+        | lines
+        | parse "{name}|{when}|{subject}"
+    let r = $branches
+        | tui label --titlebar "branches"
+        | tui search --bind / --fuzzy --columns [name]
+        | tui split --sizes [45% 1fr] [
+            (tui table --columns [name when subject])
+            (tui preview {|b| ^git log --color=always --oneline -20 $b.name })
+          ]
+        | tui label --status "/: filter  enter: switch  q: cancel"
+        | tui run
+    if $r.action == "submit" {
+        ^git switch $r.selected.name
+    }
+}
+```
+
+预览闭包接收当前高亮行，因此随着光标移动日志窗格会联动刷新，`--color=always` 保留 git 原生彩色输出。
+
+::: tip
+在类似脚本中请优先使用 `^git`。如果你加载了 git 自动补全脚本，`git branch` 可能会被定义为带参数列表的 [`extern`](externs.md)，Nushell 随后会根据该签名严格校验 `--format=`。使用 `^git` 可确保始终直接调用外部原生二进制程序。
+:::
+
+### 进程监控器
+
+一个每两秒自动刷新一次的 `ps` 监视器，支持按名称筛选，展示当前高亮进程的完整记录，并支持通过 `Ctrl+K` 终止进程：
+
+```nu
+def "ps ui" [] {
+    let snapshot = {|| ps | compact cpu | sort-by cpu -r | update cpu { math round -p 1 } | first 200 }
+    do $snapshot
+    | tui label --titlebar "processes"
+    | tui search --bind / --columns [name]
+    | tui split --sizes [1fr 44] [
+        (tui table --columns [pid name cpu mem])
+        (tui preview {|p| $p | transpose field value | table -w $env.TUI_WIDTH })
+      ]
+    | tui bind ctrl+k {|s| kill $s.selected.pid; do $snapshot }
+    | tui label --status "/: filter  ctrl+k: kill  enter: pick  q: quit"
+    | tui run --refresh 2sec $snapshot
+    | get selected?
+}
+```
+
+同一闭包同时驱动首帧渲染、定时器刷新以及终止进程后的重新加载，因此列表始终以相同规则排序。`compact cpu` 会过滤掉操作系统未报告 CPU 使用率的进程（例如 macOS 上其他用户的进程），以防止 `math round` 因遇到 `null` 而报错。
+
+### 浏览结构化数据文件
+
+将 JSON、TOML、YAML 或 NUON 文件作为树形视图打开，筛选其键名，并将当前高亮节点以表格形式渲染：
+
+```nu
+def "explore-data" [file: path] {
+    open $file
+    | tui label --titlebar ($file | path basename)
+    | tui search --bind /
+    | tui split --sizes [40% 1fr] [
+        (tui tree)
+        (tui preview {|node| $node | table -e -w $env.TUI_WIDTH })
+      ]
+    | tui label --status "right/left: open and close  /: filter  enter: pick  q: quit"
+    | tui run
+    | get selected?
+}
+
+explore-data Cargo.toml
+```
+
+按 `Enter` 会返回当前高亮节点的值，因此只需定位到任意嵌套字段并按 `Enter` 即可提取该值。