docs: clarify in-memory client contracts

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),
 )

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
+// The callback runs under the client's internal login serialization and must not
-// call Client methods other than AuthData or acquire a lock that may be held by any
+// use Client directly or indirectly, including by waiting for a goroutine, future,
-// goroutine calling Client. Callers must not call Client while holding a lock that
+// channel, or hook whose completion may call Client. It should perform only bounded,
-// the callback may acquire. Returning an error leaves authentication unchanged.
+// 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 {