docs: update for AstrBotDevs/AstrBot#4822

Author: astrbot-docs-agent[bot]

en/config/astrbot-config.md

@@ -91,6 +91,19 @@ llm_resp = await self.context.tool_loop_agent(
 
 `tool_loop_agent()` method automatically handles the loop of tool invocations and LLM requests until the model stops calling tools or the maximum number of steps is reached.
 
+## Call Tracing (Trace)
+
+> [!TIP]
+> Added in v4.5.8
+
+AstrBot provides a Call Tracing (Trace) feature to record model call paths. In a plugin, you can record custom information via `event.trace.record`.
+
+```py
+event.trace.record("action_name", key1="value1", key2="value2")
+```
+
+These records can be viewed on the "Call Tracing" page in the WebUI.
+
 ## Multi-Agent
 
 > [!TIP]
@@ -257,7 +270,7 @@ curr_cid = await conv_mgr.get_curr_conversation_id(uid)
 conversation = await conv_mgr.get_conversation(uid, curr_cid)  # Conversation
 ```
 
-::: details Conversation 类型定义
+::: details Conversation Type Definition
 
 ```py
 @dataclass
@@ -438,7 +451,7 @@ persona_mgr = self.context.persona_manager
 - **Returns**  
   `Personality` – Default persona object in v3 format
 
-::: details Persona / Personality 类型定义
+::: details Persona / Personality Type Definition
 
 ```py
 

en/dev/star/guides/ai.md

@@ -49,6 +49,15 @@ Filter by plugin, type (command / command group / subcommand), permission, and s
 
 You can enable/disable and rename each command.
 
+## Call Tracing (Trace)
+
+Use the `Call Tracing` menu on the left to view AstrBot's model call paths. This is very useful for debugging Agent behavior.
+
+In the top right corner of the page, you can enable or disable trace recording. When enabled, AstrBot records key information during the model call process, such as tool calls and model responses.
+
+> [!NOTE]
+> Currently, only some model call paths of the main AstrBot Agent are recorded; this will be continuously improved.
+
 ## Updating the Admin Panel
 
 When AstrBot starts, it automatically checks if the admin panel needs updating. If it does, the first log entry (in yellow) will prompt you.

en/use/webui.md

@@ -138,6 +138,10 @@ AstrBot 默认配置如下：
     "callback_api_base": "",
     "default_kb_collection": "",  # 默认知识库名称
     "plugin_set": ["*"],  # "*" 表示使用所有可用的插件, 空列表表示不使用任何插件
+    "trace_enable": False,
+    "trace_log_enable": False,
+    "trace_log_path": "logs/astrbot.trace.log",
+    "trace_log_max_mb": 20,
 }
 ```
 
@@ -550,3 +554,19 @@ AstrBot API 的基础地址。用于文件服务和插件回调等功能。如 `
 ### `plugin_set`
 
 已启用的插件列表。`*` 表示启用所有可用的插件。默认为 `["*"]`。
+
+### `trace_enable`
+
+是否启用调用追踪。默认为 `false`。启用后，AstrBot 会记录模型调用路径，可以在 WebUI 的“调用追踪”页面查看。
+
+### `trace_log_enable`
+
+是否将追踪记录保存到文件。默认为 `false`。
+
+### `trace_log_path`
+
+追踪日志文件的路径。默认为 `logs/astrbot.trace.log`。
+
+### `trace_log_max_mb`
+
+追踪日志文件的最大大小（MB）。默认为 `20`。

zh/config/astrbot-config.md

@@ -1,4 +1,3 @@
-
 # AI
 
 AstrBot 内置了对多种大语言模型（LLM）提供商的支持，并且提供了统一的接口，方便插件开发者调用各种 LLM 服务。
@@ -125,6 +124,19 @@ llm_resp = await self.context.tool_loop_agent(
 
 `tool_loop_agent()` 方法会自动处理工具调用和大模型请求的循环，直到大模型不再调用工具或者达到最大步骤数为止。
 
+## 调用追踪 (Trace)
+
+> [!TIP]
+> 在 v4.5.8 时加入
+
+AstrBot 提供了调用追踪（Trace）功能，用于记录模型调用路径。在插件中，你可以通过 `event.trace.record` 记录自定义信息。
+
+```py
+event.trace.record("action_name", key1="value1", key2="value2")
+```
+
+这些记录可以在 WebUI 的“调用追踪”页面查看。
+
 ## Multi-Agent
 
 > [!TIP]
@@ -297,7 +309,7 @@ curr_cid = await conv_mgr.get_curr_conversation_id(uid)
 conversation = await conv_mgr.get_conversation(uid, curr_cid)  # Conversation
 ```
 
-::: details Conversation 类型定义
+::: details Conversation 类型 definition
 
 ```py
 @dataclass
@@ -502,7 +514,7 @@ persona_mgr = self.context.persona_manager
 - __Returns__  
   `Personality` – v3 格式的默认人格对象
 
-::: details Persona / Personality 类型定义
+::: details Persona / Personality 类型 definition
 
 ```py
 

zh/dev/star/guides/ai.md

@@ -25,7 +25,7 @@ AstrBot 管理面板具有管理插件、查看日志、可视化配置、查看
 
 使用右下角第一个圆形按钮可以切换至 `代码编辑配置`。在 `代码编辑配置` 中，你可以直接编辑配置文件。
 
-编辑完后首先点击`应用此配置`，此时配置将应用到可视化配置中，然后再点击右下角`保存`按钮来保存配置。如果你不点击`应用此配置`，那么你的修改将不会生效。
+编辑完后首先点击`应用此配置`，此时配置将应用到可视化配置中，然后再点击`保存`按钮来保存配置。如果你不点击`应用此配置`，那么你的修改将不会生效。
 
 ![alt text](/source/images/webui/image-5.png)
 
@@ -49,6 +49,15 @@ AstrBot 管理面板具有管理插件、查看日志、可视化配置、查看
 
 可以对每个指令 启用/禁用、重命名。
 
+## 调用追踪 (Trace)
+
+通过左侧菜单 `调用追踪`，可以查看 AstrBot 的模型调用路径。这对于调试 Agent 的行为非常有用。
+
+在页面右上角，你可以开启或关闭调用追踪记录。开启后，AstrBot 会记录模型调用过程中的关键信息，如工具调用、模型响应等。
+
+> [!NOTE]
+> 当前仅记录部分 AstrBot 主 Agent 的模型调用路径，后续会不断完善。
+
 ## 更新管理面板
 
 在 AstrBot 启动时，会自动检查管理面板是否需要更新，如果需要，第一条日志（黄色）会进行提示。