📝 补充runtime文档

docs/api/configured-logger-file-set-append-mode.md

@@ -2,7 +2,7 @@
 name: configured-logger-file-set-append-mode
 group: api
 category: runtime
-update-time: 20260512
+update-time: 20260707
 description: Update the append-mode policy used by the configured runtime file sink for later reopen behavior.
 key-word:
     - logger
@@ -35,9 +35,10 @@ pub fn ConfiguredLogger::file_set_append_mode(self : ConfiguredLogger, append :
 Detailed rules explaining key parameters and behaviors
 
 - File-backed sinks update their stored append policy through the wrapped `RuntimeSink`.
-- Queued file sinks forward the policy update to the wrapped inner file sink.
+- Queued file sinks forward the policy update to the wrapped inner file sink only when no queued records are pending.
 - This helper updates policy only; it does not force immediate reopen.
 - Non-file sinks return `false`.
+- If a queued file sink still has pending records, the update is rejected and returns `false` so already queued records are not later written under a different append policy than the one they were queued under.
 
 ### How to Use
 
@@ -69,8 +70,10 @@ e.g.:
 
 - If callers need an immediate reopen as part of the same operation, one of the reopen helpers should be used afterward.
 
+- If a queued file sink still has pending records, callers should flush or close it first before changing append mode.
+
 ### Notes
 
 1. This helper changes stored policy, not live file-handle state by itself.
 
-2. It is useful when recovery logic wants to stage reopen behavior in advance.
+2. On queued file sinks, clear pending records first so staged reopen policy does not retroactively affect already queued writes.