diff --git a/README.md b/README.md
index 0f654ee..e8233e2 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,26 @@ node scripts/package.mjs
 
 输出 `dist/php-support-<版本>-darwin.zip`（同时适用 Apple Silicon 与 Intel Mac）和它的 SHA-256。
 
+## 诊断日志
+
+在启用结构化日志 v2 的 Lithe macOS preview 中，宿主按语言服务身份将 Intelephense 的生命周期、
+`window/logMessage` 和有界 stderr 诊断送入当前会话的 `lsp/php` 通道。
+保留 `--stdio` 启动方式，由宿主统一进行脱敏、截断、写入和保留；插件不创建自己的日志 writer。
+PHP 程序与 PHPUnit 的输出仍属于运行/测试控制台，不复制进诊断日志。
+
+Intelephense 由插件声明、宿主执行，插件没有自己的进程发送 `lithe/log`。宿主因此替插件把每次启动尝试
+记成与 SDK 插件同一组的操作事实，写入 `plugins/io.github.lithe-idea.php-support/host` 通道，
+操作名为 `languageServer/start`：`initialize` 成功记 `plugins.operation.finished`（INFO，含耗时）；
+失败记 `plugins.operation.failed`（ERROR），失败码只取自启动阶段——`host.executableUnavailable`
+（无法解析 Intelephense 启动命令）、`host.launchFailed`（进程拉起失败）、`host.exitedEarly`（就绪前退出）、
+`host.initializeFailed`（初始化握手失败）、`host.timedOut`（初始化超时）。取消、停止和被新启动取代的
+尝试不记录；事实不含 Intelephense 输出、路径或命令行。插件不需要任何日志代码，宿主实现见
+https://github.com/1lck/Lithe-IDEA/pull/1720。
+
+排障时使用 Lithe 的独立日志窗口和诊断导出，详细诊断仅临时开启。
+不要把 PHP 源码、HTTP/数据库内容、环境变量、凭据或完整协议载荷写入诊断日志。
+Windows 的日志实现仍为 v1；本文没有声明 Windows 已完成 v2 验收。
+
 ## 发布新版本
 
 1. 修改 `io.github.lithe-idea.php-support/plugin.json` 的 `version`，合入 `main`。