docs(jupyter-notebook): document zmq transport fallback and disable_check_xsrf pitfalls

contributors/emails/upicat@users.noreply.github.com

@@ -0,0 +1 @@
+upicat

optional-skills/data-science/jupyter-notebook/SKILL.md

@@ -160,6 +160,17 @@ uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compac
 8. **Occasional websocket timeouts** — some operations may timeout on first try,
    especially after a kernel restart. Retry once before escalating.
 
+9. **If websocket consistently times out on this host**, force zmq transport:
+   `uv run "$SCRIPT" execute --transport zmq ...`. Symptom: every execute returns
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped". The kernel actually ran fine (REST shows execution_state=idle and
+   execution_count increments) — only the websocket reply channel is broken.
+   zmq transport uses jupyter_client directly and sidesteps the issue.
+
+10. **When starting a fresh server for REST-only use**, add
+    `--ServerApp.disable_check_xsrf=True` — otherwise POST /api/sessions returns
+    `"'_xsrf' argument missing from POST"` and kernel session creation fails.
+
 ## Timeout Defaults
 
 The script has a 30-second default timeout per execution. For long-running

website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md

@@ -177,6 +177,17 @@ uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compac
 8. **Occasional websocket timeouts** — some operations may timeout on first try,
    especially after a kernel restart. Retry once before escalating.
 
+9. **If websocket consistently times out on this host**, force zmq transport:
+   `uv run "$SCRIPT" execute --transport zmq ...`. Symptom: every execute returns
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped". The kernel actually ran fine (REST shows execution_state=idle and
+   execution_count increments) — only the websocket reply channel is broken.
+   zmq transport uses jupyter_client directly and sidesteps the issue.
+
+10. **When starting a fresh server for REST-only use**, add
+    `--ServerApp.disable_check_xsrf=True` — otherwise POST /api/sessions returns
+    `"'_xsrf' argument missing from POST"` and kernel session creation fails.
+
 ## Timeout Defaults
 
 The script has a 30-second default timeout per execution. For long-running

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md

@@ -164,6 +164,17 @@ uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compac
 
 8. **偶发的 websocket 超时** —— 某些操作（尤其是内核重启后）首次尝试可能超时。在上报问题前先重试一次。
 
+9. **如果 websocket 在此主机上持续超时**，强制使用 zmq 传输：
+   `uv run "$SCRIPT" execute --transport zmq ...`。症状：每次 execute 都返回
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped"。内核实际上运行正常（REST 显示 execution_state=idle 且
+   execution_count 递增）—— 只是 websocket 回复通道损坏。zmq 传输直接使用
+   jupyter_client，可绕过此问题。
+
+10. **为纯 REST 使用启动新服务器时**，添加
+    `--ServerApp.disable_check_xsrf=True` —— 否则 POST /api/sessions 会返回
+    `"'_xsrf' argument missing from POST"`，导致内核会话创建失败。
+
 ## 超时默认值
 
 脚本每次执行的默认超时为 30 秒。对于长时间运行的操作，传入 `--timeout 120`。初始设置或大量计算时，建议使用较宽松的超时值（60 秒以上）。