From 6957feacb6a5defdc8794833de1985d2bd40aa76 Mon Sep 17 00:00:00 2001
From: m1saka <admin@misaka.ren>
Date: Wed, 22 Jul 2026 21:01:03 +0800
Subject: [PATCH] docs: clarify in-memory client contracts

---
 README.md |  3 ++-
 client.go | 10 ++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 27cf3cf..e68f953 100644
--- a/README.md
+++ b/README.md
@@ -117,7 +117,7 @@ _, err = client.RunActions(ctx, []mijia.ActionRequest{
 
 ## 高级 Device
 
-`NewDevice` 可通过 `DeviceSelector.DID` 或 `DeviceSelector.Name` 选择设备；名称匹配到多个设备时会返回 `MultipleDevicesFoundError`。设备描述默认缓存到认证文件所在目录，每次成功的 `Get`、`Set`、`RunAction` 后默认等待 `500ms`。
+`NewDevice` 可通过 `DeviceSelector.DID` 或 `DeviceSelector.Name` 选择设备；名称匹配到多个设备时会返回 `MultipleDevicesFoundError`。通过文件认证的 `NewClient` 默认把设备描述缓存到认证文件所在目录；`NewClientWithAuthData` 默认不启用缓存，调用方需要在创建 `Device` 时传入 `WithDeviceCacheDir` 才会缓存。每次成功的 `Get`、`Set`、`RunAction` 后默认等待 `500ms`。
 
 ```go
 device, err := mijia.NewDevice(ctx, client, mijia.DeviceSelector{DID: "设备 DID"})
@@ -149,6 +149,7 @@ device, err := mijia.NewDevice(
 	client,
 	mijia.DeviceSelector{Name: "客厅灯"},
 	mijia.WithDeviceDelay(0),
+	// 使用 NewClientWithAuthData 时，显式指定目录才能缓存设备描述。
 	mijia.WithDeviceCacheDir("./miot-cache"),
 	mijia.WithDeviceHTTPClient(http.DefaultClient),
 )
diff --git a/client.go b/client.go
index b34f2c6..56467db 100644
--- a/client.go
+++ b/client.go
@@ -137,10 +137,12 @@ func newClient(options ...ClientOption) (*Client, error) {
 }
 
 // WithAuthDataChanged configures synchronous persistence for in-memory auth updates.
-// The callback runs under the client's internal login serialization. It must not
-// call Client methods other than AuthData or acquire a lock that may be held by any
-// goroutine calling Client. Callers must not call Client while holding a lock that
-// the callback may acquire. Returning an error leaves authentication unchanged.
+// The callback runs under the client's internal login serialization and must not
+// use Client directly or indirectly, including by waiting for a goroutine, future,
+// channel, or hook whose completion may call Client. It should perform only bounded,
+// standalone persistence and return. The callback and Client callers must obey lock
+// ordering: neither may hold a lock needed by the other. Returning an error leaves
+// authentication unchanged.
 func WithAuthDataChanged(callback func(AuthData) error) ClientOption {
 	return func(client *Client) error {
 		if callback == nil {