[v1] update docs (#10684)

docs/zh/developer-guide/core/callback.md

@@ -0,0 +1,39 @@
+# Callback
+
+Callback 系统位于 `utils/callbacks/`，用于把日志和生命周期通知从训练循环中分离。
+
+## Callback 组件
+
+- `TrainerCallback`：事件接口
+- `CallbackHandler`：按注册顺序广播事件
+- `LoggingCallback`：输出 loss、learning rate、grad norm 等指标
+
+## 事件如何传递
+
+BaseTrainer 创建 CallbackHandler，并先加入默认 LoggingCallback，再加入构造参数 `callbacks` 中的实例。训练循环在固定位置调用 handler；handler 按列表顺序同步调用每个实例的同名方法，不经过 BasePlugin 注册表。
+
+```text
+on_train_begin
+  → on_epoch_begin
+    → on_step_begin
+    → 前向、反向与更新
+    → on_step_end
+    → on_log（到达 logging_steps 时）
+    → on_save（checkpoint 写入后）
+  → on_epoch_end
+on_train_end
+```
+
+事件位置由 Trainer 和 checkpoint 协调器决定。Callback 无需自行判断什么时候保存模型或推进优化器，只响应已经发生的生命周期事件。
+
+## Callback 能读取什么
+
+每个事件接收训练参数 `args`、进度对象 `state` 和额外关键字参数。TrainerState 保存 step、epoch、最近一次损失、梯度范数和学习率等；Handler 还通过关键字参数传入当前 model、optimizer、lr_scheduler 和批次生成器。
+
+在 `on_step_begin` 时，本步计算尚未发生，损失等指标仍来自此前的更新；本步指标在 `on_step_end` 前写入 state。`on_log` 额外接收本次日志字典。
+
+## 扩展边界
+
+自定义 Callback 继承 TrainerCallback，仅覆盖关心的事件，并将实例传给 Trainer 的 `callbacks` 参数。它适合记录指标、连接外部观察工具等附加行为。需要改变损失、更新规则或 checkpoint 格式时，使用 Trainer 或对应插件。
+
+接口约定将 state 作为供观察的进度信息，不通过修改它来控制训练流程；代码没有把这个 dataclass 冻结。事件也不会统一限制到 rank 0，涉及单次输出的 Callback 需要自行判断 rank，默认 LoggingCallback 就在自身内部处理这个条件。