diff --git a/docs/ui-maximum-update-depth.md b/docs/ui-maximum-update-depth.md
new file mode 100644
index 0000000..1f719c2
--- /dev/null
+++ b/docs/ui-maximum-update-depth.md
@@ -0,0 +1,58 @@
+# UI 故障说明：Maximum update depth exceeded
+
+**适用版本：** 0.1.8
+**状态：** 已修复
+
+## 现象
+
+在对话运行过程中，浏览器控制台可能出现以下 React 错误：
+
+```text
+Maximum update depth exceeded
+```
+
+调用栈通常会经过 LangGraph SDK 的
+`StreamManager.notifyListeners()`、`setStreamValues()` 和 React 的
+`forceStoreRerender()`。发生错误后，页面可能停止更新，或者只能在刷新
+线程后看到本轮完整回答。
+
+## 根因
+
+LangGraph SDK 的流对象使用外部状态存储。以下读取会启用高频订阅：
+
+- 读取 `stream.messages` 会订阅 `messages-tuple`。
+- 读取 `stream.values` 会隐式订阅 `values`。
+- 读取 `stream.getMessagesMetadata()` 同样会建立相关消息状态读取。
+
+流式响应中的每个消息块或状态快照都会调用
+`StreamManager.setStreamValues()` 并同步通知 React。组件在通知期间继续
+读取流状态、向子组件透传流对象，或在流式回调中额外更新 React 状态时，会
+造成连续嵌套的外部 Store 更新。更新深度超过 React 限制后，即触发
+`Maximum update depth exceeded`。
+
+## 修复方案
+
+- 不再读取或向子组件传递 `stream.messages`、`stream.values`、
+  `stream.getMessagesMetadata()`。
+- 提交请求时仅使用 `streamMode: ["updates"]`，避免请求高频
+  `values` 或 `messages-tuple` 流。
+- 提交后先在本地追加用户消息，用于乐观显示。
+- 当对话完成，或运行进入审批中断状态时，通过
+  `client.threads.get()` 和 `client.threads.getState()` 读取服务端已
+  持久化的 thread record，并刷新消息、待办、文件和中断状态。
+- 对 Context 使用稳定的空数组和空对象常量，避免每次渲染产生新引用。
+- 移除流式回调中额外的 React 状态更新，以及工具组件对 SDK stream 对象的
+  透传。
+
+## 修复后的显示行为
+
+运行期间，UI 保留已发送的用户消息和加载状态。服务端完成该轮对话或暂停等待
+审批后，前端再刷新完整的持久化结果。因此，回答不会逐 token 显示，但可避免
+高频外部状态通知造成的嵌套更新循环，并确保消息、待办、文件与审批状态来自
+同一份服务端持久化数据。
+
+## 验证结论
+
+- 对话运行期间不再触发 React 的最大更新深度错误。
+- 完成或审批中断后，完整对话及关联状态可正常刷新。
+- 不再对 LangGraph SDK 建立 `values` 或 `messages-tuple` 高风险订阅。