merge: resolve conflicts from upstream

Conflict resolution: accepted HEAD versions for all conflicted files.

docs/.vitepress/config.mjs

@@ -163,6 +163,7 @@ export default defineConfig({
               { text: "内置指令", link: "/command" },
               { text: "工具使用 Tools", link: "/function-calling" },
               { text: "技能 Skills", link: "/skills" },
+              { text: "使用电脑能力", link: "/computer" },
               { text: "SubAgent 编排", link: "/subagent" },
               { text: "主动型 Agent 能力", link: "/proactive-agent" },
               { text: "MCP", link: "/mcp" },
@@ -404,6 +405,7 @@ export default defineConfig({
               { text: "Built-in Commands", link: "/command" },
               { text: "Tool Use", link: "/function-calling" },
               { text: "Anthropic Skills", link: "/skills" },
+              { text: "Computer Use", link: "/computer" },
               { text: "SubAgent Orchestration", link: "/subagent" },
               { text: "Proactive Tasks", link: "/proactive-agent" },
               { text: "MCP", link: "/mcp" },

docs/en/deploy/astrbot/package.md

@@ -12,11 +12,13 @@ If `uv` is not installed, install it first by following the official guide:
 ## Important Notes
 
 > [!WARNING]
-> AstrBot deployed via `uv` **does not support upgrading through the WebUI**. To update, run `uv tool upgrade astrbot` from the command line.
+> AstrBot deployed via `uv` **does not support upgrading through the WebUI**. To update, run `uv tool upgrade astrbot --python 3.12` from the command line.
+
+AstrBot requires Python 3.12 or later. Use `--python 3.12` to ensure that `uv` creates the tool environment with Python 3.12; if Python downloads are enabled, `uv` will download Python 3.12 automatically when it is missing.
 
 ## Install and Start
 
 ```bash
-uv tool install astrbot
+uv tool install astrbot --python 3.12
 astrbot
 ```

docs/en/dev/star/guides/listen-message-event.md

@@ -289,6 +289,94 @@ async def on_llm_resp(self, event: AstrMessageEvent, resp: LLMResponse): # Note
 
 > You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
 
+#### On Agent Begin
+
+> Requires AstrBot version > v4.23.1
+
+When the Agent starts running, the `on_agent_begin` hook is triggered.
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+@filter.on_agent_begin()
+async def on_agent_begin(self, event: AstrMessageEvent, run_context: ContextWrapper[AstrAgentContext]): # Note there are three parameters
+    print("Agent started")
+```
+
+> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
+
+#### Before LLM Tool Call
+
+> Requires AstrBot version > v4.23.1
+
+When the Agent is about to call an LLM tool, the `on_using_llm_tool` hook is triggered.
+
+You can obtain the `FunctionTool` object and tool call arguments.
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.tool import FunctionTool
+
+@filter.on_using_llm_tool()
+async def on_using_llm_tool(
+    self,
+    event: AstrMessageEvent,
+    tool: FunctionTool,
+    tool_args: dict | None,
+):
+    print(tool.name, tool_args)
+```
+
+> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
+
+#### After LLM Tool Call
+
+> Requires AstrBot version > v4.23.1
+
+After the LLM tool call completes, the `on_llm_tool_respond` hook is triggered.
+
+You can obtain the `FunctionTool` object, tool call arguments, and tool call result.
+
+```python
+from mcp.types import CallToolResult
+
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.tool import FunctionTool
+
+@filter.on_llm_tool_respond()
+async def on_llm_tool_respond(
+    self,
+    event: AstrMessageEvent,
+    tool: FunctionTool,
+    tool_args: dict | None,
+    tool_result: CallToolResult | None,
+):
+    print(tool.name, tool_args, tool_result)
+```
+
+> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
+
+#### On Agent Done
+
+> Requires AstrBot version > v4.23.1
+
+After the Agent finishes running, the `on_agent_done` hook is triggered. This hook is triggered after `on_llm_response`.
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.api.provider import LLMResponse
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+@filter.on_agent_done()
+async def on_agent_done(self, event: AstrMessageEvent, run_context: ContextWrapper[AstrAgentContext], resp: LLMResponse): # Note there are four parameters
+    print(resp)
+```
+
+> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
+
 #### Before Sending Message
 
 Before sending a message, the `on_decorating_result` hook is triggered.

docs/en/use/command.md

@@ -1,5 +1,110 @@
 # Built-in Commands
 
-AstrBot has many built-in commands that are imported as plugins. They are located in the `packages/astrbot` directory.
+AstrBot commands are registered through the plugin system. To keep the core lightweight, only a small set of basic commands are loaded with AstrBot itself. Other management and extended commands have been moved into a separate plugin.
 
-Use `/help` to view all built-in commands.
+Use `/help` to view currently enabled commands.
+
+> [!NOTE]
+> 1. `/help`, `/set`, and `/unset` are not shown in the `/help` command list by default, but they are still available.
+> 2. If you change the wake prefix and remove the default `/`, commands must use the new wake prefix as well. For example, after changing the wake prefix to `!`, use `!help` and `!reset` instead of `/help` and `/reset`.
+
+## Core Built-in Commands
+
+The following commands are shipped with AstrBot and loaded by default:
+
+- `/help`: View currently enabled commands and AstrBot version information.
+- `/sid`: View current message source information, including UMO, user ID, platform ID, message type, and session ID. This is commonly used when configuring admins, allowlists, or routing rules.
+- `/reset`: Reset the current conversation's LLM context.
+- `/stop`: Stop Agent tasks currently running in the current session.
+- `/new`: Create and switch to a new conversation.
+- `/dashboard_update`: Update AstrBot WebUI. This command requires admin permission.
+- `/set`: Set a session variable, commonly used for Agent Runner input variables such as Dify, Coze, or DashScope.
+- `/unset`: Remove a session variable.
+
+These commands are located in:
+
+```text
+astrbot/builtin_stars/builtin_commands
+```
+
+## Core Command Details
+
+### `/sid`
+
+`/sid` shows information about the current message source. It mainly returns:
+
+- `UMO`: The unified message origin of the current message. It is commonly used for allowlists and per-session config routing.
+- `UID`: The sender's user ID. It is commonly used when adding AstrBot admins.
+- `Bot ID`: The platform instance ID of the current bot.
+- `Message Type`: The message type, such as private chat or group chat.
+- `Session ID`: The platform-side session ID.
+
+In group chats, if `unique_session` is enabled, `/sid` also shows the current group ID. This group ID can be used to allowlist the entire group.
+
+Common uses:
+
+- Add an admin: run `/sid` to get the `UID`, then add it in WebUI under `Config -> Other Config -> Admin ID`.
+- Configure allowlists: use `UMO` or group ID to control which sessions can use the bot.
+- Configure routing rules: use `UMO` to distinguish different platforms, groups, or private chats.
+
+### `/reset`
+
+`/reset` resets the LLM context of the current session.
+
+For AstrBot's built-in Agent Runner, it:
+
+- Stops running tasks in the current session.
+- Clears the context messages of the current conversation.
+- Notifies long-term memory to clear the current session state.
+
+For third-party Agent Runners such as `dify`, `coze`, `dashscope`, and `deerflow`, it:
+
+- Stops running tasks in the current session.
+- Removes the saved third-party conversation ID for this session, so the next turn starts a new conversation.
+
+Permission notes:
+
+- In private chat, regular users can use it by default.
+- In group chat with `unique_session` enabled, regular users can use it by default.
+- In group chat without `unique_session`, admin permission is required by default.
+- If command permission settings have been customized, the actual configuration takes precedence.
+
+### `/stop`
+
+`/stop` stops Agent tasks currently running in the current session.
+
+It does not clear conversation history and does not create a new conversation. It only sends a stop request to tasks currently executing in this session.
+
+For the built-in Agent Runner, `/stop` asks the Agent Runner to stop the current task.  
+For third-party Agent Runners such as `dify`, `coze`, `dashscope`, and `deerflow`, `/stop` directly stops registered running tasks in the current session.
+
+If there are no running tasks in the current session, AstrBot will report that no task is running.
+
+## Built-in Commands Extension
+
+Other commands that were previously shipped with the core have been moved to a separate plugin:
+
+- [builtin_commands_extension](https://github.com/AstrBotDevs/builtin_commands_extension)
+
+This plugin provides extended commands for plugin management, Provider management, model switching, Persona management, and conversation management. Examples include:
+
+- `/plugin`: View, enable, disable, or install plugins.
+- `/op`, `/deop`: Add or remove admins.
+- `/provider`: View or switch LLM Providers.
+- `/model`: View or switch models.
+- `/history`: View current conversation history.
+- `/ls`: View the conversation list.
+- `/groupnew`: Create a new conversation for a specified group.
+- `/switch`: Switch to a specified conversation.
+- `/rename`: Rename the current conversation.
+- `/del`: Delete the current conversation.
+- `/persona`: View or switch Persona.
+- `/llm`: Enable or disable LLM chat.
+
+Install or enable the `builtin_commands_extension` plugin if you need these extended commands.
+
+## Permission Notes
+
+Some commands require AstrBot admin permission, such as `/dashboard_update`, `/op`, `/deop`, `/provider`, `/model`, and `/persona`.
+
+You can use `/sid` to get a user ID, then add it in WebUI under `Config -> Other Config -> Admin ID`.

docs/en/use/computer.md

@@ -0,0 +1,139 @@
+# Computer Use
+
+Computer Use controls whether an Agent can execute code, access files, run Shell commands.
+
+## Mode Selection
+
+In WebUI, open:
+
+- `Config -> General Config -> Use Computer Capabilities`
+
+The key option is `Computer Use Runtime`:
+
+- `none`: disables Computer Use; Shell, Python, filesystem, and related tools are not mounted.
+- `local`: executes on the host machine where AstrBot is running. Use this when the Agent needs local files, command-line tools, or local dependencies.
+- `sandbox`: executes inside an isolated sandbox. Use this when you want to reduce host risk or provide automation capabilities to multiple users.
+
+If you are not sure which mode to choose, prefer `sandbox`. Use `local` only when direct host access is required.
+
+## Local Mode
+
+`local` mode mounts Computer Use tools into the host environment where AstrBot runs. The Agent can call the host Shell, host Python, and host filesystem tools.
+
+This means the Agent's boundary is close to the AstrBot process itself. What it can access depends on the system permissions, runtime user, working directory, and operating-system restrictions of the AstrBot process.
+
+### Workspace
+
+In `local` mode, AstrBot prepares a workspace for each session:
+
+```text
+data/workspaces/{normalized_umo}
+```
+
+`{normalized_umo}` is derived from the current session's `unified_msg_origin`; characters unsuitable for filenames are replaced with `_`.
+
+Relative paths passed to local filesystem tools are resolved under this workspace. For example:
+
+```text
+notes/todo.txt
+```
+
+is resolved as:
+
+```text
+data/workspaces/{normalized_umo}/notes/todo.txt
+```
+
+The local Shell tool also runs with this workspace as its current working directory.
+
+> [!NOTE]
+> The local Python tool executes code through AstrBot's current Python environment. When Python code reads or writes files, use explicit absolute paths or prepare files through filesystem tools in the workspace first.
+
+### Local Tools
+
+`local` mode mainly provides:
+
+- `Shell`: executes host shell commands. Windows follows `cmd.exe` semantics; Linux/macOS follow Unix-like shell semantics.
+- `Python`: executes Python code in AstrBot's current Python environment.
+- `File read`: reads text, image, spreadsheet, and other supported files.
+- `File write`: writes UTF-8 text files; relative paths default to the current workspace.
+- `File edit`: replaces exact text in files.
+- `Grep search`: searches file contents through ripgrep.
+
+`local` mode does not mount sandbox upload/download tools, and it does not provide browser automation. Browser automation belongs to the sandbox runtime and requires a sandbox profile with the `browser` capability.
+
+The local Shell tool includes basic blocking for dangerous commands such as `rm -rf`, `sudo`, `shutdown`, `reboot`, and `kill -9`. This is not a complete security sandbox and should not be treated as one.
+
+### Permission Model
+
+Computer Use has a separate option:
+
+- `Require AstrBot admin permission`
+
+This option is enabled by default.
+
+When enabled:
+
+- Admin users can use Shell, Python, file read, file write, file edit, and Grep search in `local` mode.
+- Non-admin users cannot use Shell or Python.
+- Non-admin users can only use file read, write, edit, and search inside restricted directories.
+
+Allowed directories for non-admin users in `local` mode include:
+
+- `data/skills`
+- Current session's `data/workspaces/{normalized_umo}`
+- AstrBot temporary directories
+- `.astrbot` under the system temporary directory
+
+If `Require AstrBot admin permission` is disabled, regular users behave much closer to admins for Computer Use tools. Do not disable it unless you understand the risk.
+
+Admin IDs can be configured in:
+
+- `Config -> Other Config -> Admin ID`
+
+Users can get their own ID with `/sid`.
+
+## Sandbox Mode
+
+`sandbox` mode runs execution actions inside an isolated environment instead of directly on the AstrBot host.
+
+Inside the sandbox, the Agent can still use Shell, Python, and filesystem tools. If the selected sandbox profile supports the `browser` capability, AstrBot also mounts browser automation tools.
+
+With Shipyard Neo, the sandbox workspace root is usually:
+
+```text
+/workspace
+```
+
+Filesystem tools should usually receive relative paths, for example:
+
+```text
+result.txt
+```
+
+instead of:
+
+```text
+/workspace/result.txt
+```
+
+For sandbox deployment, profiles, TTL, persistence, and browser capabilities, see [Agent Sandbox Environment](/en/use/astrbot-agent-sandbox).
+
+> [!NOTE]
+> Even in `sandbox` mode, `Require AstrBot admin permission` still affects access to Shell, Python, browser, upload/download, and related tools. The exact behavior depends on your configuration.
+
+## Skills
+
+Skills are reusable instruction bundles for Agents. They are usually stored under `data/skills`, and each Skill contains a `SKILL.md`.
+
+The relationship between Skills and Computer Use is:
+
+- Skills tell the Agent what to do.
+- Computer Use decides whether the Agent can execute those steps.
+
+For example, a Skill may ask the Agent to read files, run scripts, and generate a report. If `Computer Use Runtime` is `none`, the Agent may see the Skill instructions, but it cannot call Shell or Python to execute them.
+
+In `local` mode, the Agent reads local Skills.
+In `sandbox` mode, AstrBot attempts to sync local Skills into the sandbox so the Agent can execute them there.
+
+For more details, see [Anthropic Skills](/en/use/skills).

docs/zh/deploy/astrbot/package.md

@@ -11,12 +11,14 @@
 ## 注意事项
 
 > [!WARNING]
-> 通过 `uv` 部署的 AstrBot **不支持在 WebUI 中进行版本升级**。如需更新，请在命令行中执行 `uv tool upgrade astrbot`。
+> 通过 `uv` 部署的 AstrBot **不支持在 WebUI 中进行版本升级**。如需更新，请在命令行中执行 `uv tool upgrade astrbot --python 3.12`。
+
+AstrBot 需要 Python 3.12 或更高版本。使用 `--python 3.12` 可以确保 `uv` 使用 Python 3.12 创建 tool 环境；如果启用了 Python 自动下载，`uv` 会在缺少 Python 3.12 时自动下载。
 
 ## 安装并启动
 
 ```bash
-uv tool install astrbot
+uv tool install astrbot --python 3.12
 astrbot init # 只需要在第一次部署时执行，后续启动不需要执行
 astrbot run
 ```

docs/zh/dev/star/guides/listen-message-event.md

@@ -305,6 +305,94 @@ async def on_llm_resp(self, event: AstrMessageEvent, resp: LLMResponse): # 请
 
 > 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
 
+#### Agent 开始运行时
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 Agent 开始运行时，会触发 `on_agent_begin` 钩子。
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+@filter.on_agent_begin()
+async def on_agent_begin(self, event: AstrMessageEvent, run_context: ContextWrapper[AstrAgentContext]):
+    print("Agent 开始运行")
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
+#### LLM 工具调用前
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 Agent 准备调用 LLM 工具时，会触发 `on_using_llm_tool` 钩子。
+
+可以获取到 `FunctionTool` 对象和工具调用参数。
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.tool import FunctionTool
+
+@filter.on_using_llm_tool()
+async def on_using_llm_tool(
+    self,
+    event: AstrMessageEvent,
+    tool: FunctionTool,
+    tool_args: dict | None,
+):
+    print(tool.name, tool_args)
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
+#### LLM 工具调用后
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 LLM 工具调用完成后，会触发 `on_llm_tool_respond` 钩子。
+
+可以获取到 `FunctionTool` 对象、工具调用参数和工具调用结果。
+
+```python
+from mcp.types import CallToolResult
+
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.tool import FunctionTool
+
+@filter.on_llm_tool_respond()
+async def on_llm_tool_respond(
+    self,
+    event: AstrMessageEvent,
+    tool: FunctionTool,
+    tool_args: dict | None,
+    tool_result: CallToolResult | None,
+):
+    print(tool.name, tool_args, tool_result)
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
+#### Agent 运行完成时
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 Agent 运行完成后，会触发 `on_agent_done` 钩子。这个钩子会在 `on_llm_response` 之后触发。本质上和 `on_llm_response` 一样。
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.api.provider import LLMResponse
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+@filter.on_agent_done()
+async def on_agent_done(self, event: AstrMessageEvent, run_context: ContextWrapper[AstrAgentContext], resp: LLMResponse):
+    print(resp)
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
 #### 发送消息前
 
 在发送消息前，会触发 `on_decorating_result` 钩子。

docs/zh/dev/star/plugin.md

@@ -507,6 +507,96 @@ async def on_llm_resp(self, event: AstrMessageEvent, resp: LLMResponse): # 请
 
 > 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
 
+##### Agent 开始运行时
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 Agent 开始运行时，会触发 `on_agent_begin` 钩子。
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+@filter.on_agent_begin()
+async def on_agent_begin(self, event: AstrMessageEvent, run_context: ContextWrapper[AstrAgentContext]): # 请注意有三个参数
+    print("Agent 开始运行")
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
+##### LLM 工具调用前
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 Agent 准备调用 LLM 工具时，会触发 `on_using_llm_tool` 钩子。
+
+可以获取到 `FunctionTool` 对象和工具调用参数。
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.tool import FunctionTool
+
+@filter.on_using_llm_tool()
+async def on_using_llm_tool(
+    self,
+    event: AstrMessageEvent,
+    tool: FunctionTool,
+    tool_args: dict | None,
+):
+    print(tool.name, tool_args)
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
+##### LLM 工具调用后
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 LLM 工具调用完成后，会触发 `on_llm_tool_respond` 钩子。
+
+可以获取到 `FunctionTool` 对象、工具调用参数和工具调用结果。
+
+```python
+from mcp.types import CallToolResult
+
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.core.agent.tool import FunctionTool
+
+@filter.on_llm_tool_respond()
+async def on_llm_tool_respond(
+    self,
+    event: AstrMessageEvent,
+    tool: FunctionTool,
+    tool_args: dict | None,
+    tool_result: CallToolResult | None,
+):
+    print(tool.name, tool_args, tool_result)
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
+##### Agent 运行完成时
+
+> 适用于 AstrBot 版本 > v4.23.1
+
+在 Agent 运行完成后，会触发 `on_agent_done` 钩子。这个钩子会在 `on_llm_response` 之后触发。
+
+可以获取到 `LLMResponse` 对象，可以对其进行修改。
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.api.provider import LLMResponse
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+@filter.on_agent_done()
+async def on_agent_done(self, event: AstrMessageEvent, run_context: ContextWrapper[AstrAgentContext], resp: LLMResponse): # 请注意有四个参数
+    print(resp)
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
 ##### 发送消息前
 
 在发送消息前，会触发 `on_decorating_result` 钩子。

docs/zh/providers/agent-runners/deerflow.md

@@ -2,6 +2,8 @@
 
 在 v4.19.2 及之后，AstrBot 支持接入 [DeerFlow](https://github.com/bytedance/deer-flow) Agent Runner。
 
+当前适配面向 DeerFlow **2.0 `main` 分支**。DeerFlow 官方已将原始 Deep Research 框架迁移到 `main-1.x` 分支持续维护，因此如果你使用的是 2.0，请以 `main` 分支文档和后端 API 为准。
+
 ## 预备工作：部署 DeerFlow
 
 如果你还没有部署 DeerFlow，请先参考 DeerFlow 官方文档完成安装和启动：
@@ -25,12 +27,12 @@
 - `API Base URL`：DeerFlow API 网关地址，默认为 `http://127.0.0.1:2026`
 - `DeerFlow API Key`：可选。若你的 DeerFlow 网关使用 Bearer 鉴权，可在此填写
 - `Authorization Header`：可选。自定义 Authorization 请求头，优先级高于 `DeerFlow API Key`
-- `Assistant ID`：对应 LangGraph 的 `assistant_id`，默认为 `lead_agent`
+- `Assistant ID`：对应 DeerFlow 2.0 LangGraph 的 `assistant_id`，默认为 `lead_agent`
 - `模型名称覆盖`：可选。覆盖 DeerFlow 默认模型
 - `启用思考模式`：是否启用 DeerFlow 的思考模式
-- `启用计划模式`：对应 DeerFlow 的 `is_plan_mode`
-- `启用子智能体`：对应 DeerFlow 的 `subagent_enabled`
-- `子智能体最大并发数`：对应 `max_concurrent_subagents`，仅在启用子智能体时生效，默认 `3`
+- `启用计划模式`：对应 DeerFlow 2.0 运行时 `config.configurable.is_plan_mode`
+- `启用子智能体`：对应 DeerFlow 2.0 运行时 `config.configurable.subagent_enabled`
+- `子智能体最大并发数`：对应 DeerFlow 2.0 运行时 `config.configurable.max_concurrent_subagents`，仅在启用子智能体时生效，默认 `3`
 - `递归深度上限`：对应 LangGraph 的 `recursion_limit`，默认 `1000`
 
 填写完成后点击「保存」。
@@ -38,6 +40,7 @@
 > [!TIP]
 > - 如果 DeerFlow 侧已经配置了默认模型，可以将 `模型名称覆盖` 留空。
 > - 只有在 DeerFlow 侧已经启用了相应能力时，才建议开启 `计划模式` 或 `子智能体` 相关选项。
+> - AstrBot 会同时发送 DeerFlow 2.0 推荐的 `config.configurable` 运行时参数，并保留兼容字段，便于对接上游近期版本。
 
 ## 选择 Agent 执行器
 
@@ -51,3 +54,4 @@
 - `API Base URL` 是否能从 AstrBot 所在环境访问
 - 鉴权配置是否填写正确
 - `Assistant ID` 是否与 DeerFlow 中实际可用的 assistant 一致
+- 如果通过 `/reset`、`/new`、`/del` 重置 DeerFlow 会话，AstrBot 会尝试同步清理 DeerFlow 远端 thread；若 DeerFlow 网关不可达，则只会清理 AstrBot 本地会话标识

docs/zh/use/command.md

@@ -1,5 +1,106 @@
 # 内置指令
 
-AstrBot 具有很多内置指令，它们通过插件的形式被导入。位于 `packages/astrbot` 目录下。
+AstrBot 的指令通过插件机制注册。为了保持主程序轻量，当前只有少量基础指令随 AstrBot 主程序内置加载；更多管理类、扩展类指令已经迁移到独立插件中维护。
 
-使用 `/help` 可以查看所有内置指令。
+使用 `/help` 可以查看当前已经启用的指令。
+
+> [!NOTE]
+> 1. `/help`、`/set`、`/unset` 默认不会显示在 `/help` 输出的指令清单中，但这些指令仍然可用。
+> 2. 如果您修改了唤醒前缀，去掉了默认的 `/`，那么指令也需要使用新的唤醒前缀触发。例如将唤醒前缀改为 `!` 后，应使用 `!help`、`!reset`，而不是 `/help`、`/reset`。
+
+## 主程序内置指令
+
+以下指令由 AstrBot 主程序自带，默认随 AstrBot 加载：
+
+- `/help`：查看当前启用的指令和 AstrBot 版本信息。
+- `/sid`：查看当前消息来源信息，包括 UMO、用户 ID、平台 ID、消息类型和会话 ID。常用于配置管理员、白名单或路由规则。
+- `/reset`：重置当前会话的 LLM 上下文。
+- `/stop`：停止当前会话中正在运行的 Agent 任务。
+- `/new`：创建并切换到一个新对话。
+- `/dashboard_update`：更新 AstrBot WebUI。该指令需要管理员权限。
+- `/set`：设置当前会话变量，常用于 Dify、Coze、DashScope 等 Agent 执行器的输入变量。
+- `/unset`：移除当前会话变量。
+
+## 核心指令详解
+
+### `/sid`
+
+`/sid` 用于查看当前消息来源信息，主要输出：
+
+- `UMO`：当前消息来源的统一标识。它通常用于白名单、配置文件路由等按会话生效的配置。
+- `UID`：当前发送者的用户 ID。它通常用于添加 AstrBot 管理员。
+- `Bot ID`：当前机器人所在平台实例的 ID。
+- `Message Type`：消息类型，例如私聊或群聊。
+- `Session ID`：平台侧会话 ID。
+
+在群聊中，如果开启了 `unique_session`（会话隔离），`/sid` 还会额外提示当前群 ID。这个群 ID 可用于把整个群加入白名单。
+
+常见用途：
+
+- 添加管理员：先发送 `/sid` 获取 `UID`，再在 WebUI 的 `配置 -> 其他配置 -> 管理员 ID` 中添加。
+- 配置白名单：使用 `UMO` 或群 ID 控制哪些会话可以使用机器人。
+- 配置路由规则：使用 `UMO` 区分不同平台、群聊或私聊来源。
+
+### `/reset`
+
+`/reset` 用于重置当前会话的 LLM 上下文。
+
+对于 AstrBot 内置 Agent Runner，它会：
+
+- 停止当前会话中正在运行的任务。
+- 清空当前对话的上下文消息。
+- 通知长期记忆会话清理当前上下文状态。
+
+对于第三方 Agent Runner，例如 `dify`、`coze`、`dashscope`、`deerflow`，它会：
+
+- 停止当前会话中正在运行的任务。
+- 删除当前会话保存的第三方会话 ID，让下一轮对话重新开始。
+
+权限说明：
+
+- 私聊中默认普通用户可使用。
+- 群聊开启会话隔离时，默认普通用户可使用。
+- 群聊未开启会话隔离时，默认需要管理员权限。
+- 如果管理员修改过指令权限配置，则以实际配置为准。
+
+### `/stop`
+
+`/stop` 用于停止当前会话中正在运行的 Agent 任务。
+
+它不会清空对话历史，也不会创建新对话。它只对当前会话正在执行的任务发出停止请求。
+
+对于内置 Agent Runner，`/stop` 会请求 Agent Runner 停止当前任务。  
+对于第三方 Agent Runner，例如 `dify`、`coze`、`dashscope`、`deerflow`，`/stop` 会直接停止当前会话中登记的运行任务。
+
+如果当前会话没有正在运行的任务，AstrBot 会提示当前会话没有运行中的任务。
+
+## 内置指令扩展
+
+除上述基础指令外，其他原本随主程序提供的内置指令已经迁移到独立插件：
+
+- [builtin_commands_extension](https://github.com/AstrBotDevs/builtin_commands_extension)
+
+可直接在插件市场搜索安装。
+
+该插件提供插件管理、Provider 管理、模型切换、Persona 管理、对话列表管理等扩展指令，例如：
+
+- `/plugin`：查看、启用、停用或安装插件。
+- `/op`、`/deop`：添加或移除管理员。
+- `/provider`：查看或切换 LLM Provider。
+- `/model`：查看或切换模型。
+- `/history`：查看当前对话历史。
+- `/ls`：查看对话列表。
+- `/groupnew`：为指定群聊创建新对话。
+- `/switch`：切换到指定对话。
+- `/rename`：重命名当前对话。
+- `/del`：删除当前对话。
+- `/persona`：查看或切换 Persona。
+- `/llm`：开启或关闭 LLM 聊天功能。
+
+如果你需要这些扩展指令，请安装或启用 `builtin_commands_extension` 插件。
+
+## 权限说明
+
+部分指令需要 AstrBot 管理员权限，例如 `/dashboard_update`、`/op`、`/deop`、`/provider`、`/model`、`/persona` 等。
+
+可以通过 `/sid` 获取用户 ID，然后在 WebUI 的 `配置 -> 其他配置 -> 管理员 ID` 中添加管理员。

docs/zh/use/computer.md

@@ -0,0 +1,137 @@
+# 使用电脑能力
+
+电脑能力（Computer Use）决定 Agent 是否可以在 AstrBot 运行环境中执行代码、访问文件、调用 Shell。
+
+## 模式选择
+
+在 WebUI 中进入：
+
+- `配置 -> 普通配置 -> 使用电脑能力`
+
+核心配置项是 `Computer Use Runtime`：
+
+- `none`：不启用电脑能力，不给 Agent 挂载 Shell、Python、文件系统等工具。
+- `local`：在 AstrBot 所在机器上执行，适合需要访问本机文件、命令行工具或本地依赖的场景。
+- `sandbox`：在隔离沙盒中执行，适合希望降低本机风险、或让多用户使用自动化能力的场景。
+
+## Local 模式
+
+`local` 模式会把电脑能力挂载到 AstrBot 所在的主机环境。Agent 可以调用本机 Shell、本机 Python，以及本机文件系统工具。
+
+这意味着 Agent 的能力边界接近 AstrBot 进程本身：它能访问什么，取决于 AstrBot 进程的系统权限、运行用户、工作目录和操作系统限制。
+
+### Workspace
+
+在 `local` 模式下，AstrBot 会为每个会话准备一个 workspace：
+
+```text
+data/workspaces/{normalized_umo}
+```
+
+其中 `{normalized_umo}` 来自当前会话的 `unified_msg_origin`，并会将不适合文件名的字符替换为 `_`。
+
+本地文件工具的相对路径会解析到这个 workspace 下。例如：
+
+```text
+notes/todo.txt
+```
+
+会被解析为：
+
+```text
+data/workspaces/{normalized_umo}/notes/todo.txt
+```
+
+本地 Shell 工具执行时，也会把当前工作目录设置为这个 workspace。
+
+> [!NOTE]
+> 本地 Python 工具会调用 AstrBot 当前 Python 环境执行代码。编写会读写文件的 Python 代码时，建议使用明确的绝对路径，或先通过文件工具在 workspace 中准备文件。
+
+### 本地工具
+
+`local` 模式主要提供以下工具：
+
+- `Shell`：执行本机 shell 命令。Windows 下使用 `cmd.exe` 语义，Linux/macOS 下使用类 Unix shell 语义。
+- `Python`：使用 AstrBot 当前 Python 环境执行 Python 代码。
+- `文件读取`：读取 workspace 或允许路径中的文本、图片、表格等文件。
+- `文件写入`：写入 UTF-8 文本文件；相对路径默认落在当前 workspace。
+- `文件编辑`：按精确字符串替换文件内容。
+- `Grep 搜索`：使用 ripgrep 能力搜索文件内容。
+
+`local` 模式不会挂载沙盒上传/下载工具，也不会提供浏览器自动化工具。浏览器能力属于沙盒运行时，需要使用支持 `browser` capability 的沙盒 profile。
+
+本地 Shell 内置了基础危险命令拦截，例如 `rm -rf`、`sudo`、`shutdown`、`reboot`、`kill -9` 等。但这不是完整安全沙箱，不能把它当作安全边界。
+
+### 权限模型
+
+电脑能力还有一个独立开关：
+
+- `需要 AstrBot 管理员权限`
+
+默认情况下这个开关是开启的。
+
+开启后：
+
+- 管理员可以使用 `local` 模式下的 Shell、Python、文件读取、文件写入、文件编辑和 Grep 搜索。
+- 非管理员不能使用 Shell 和 Python。
+- 非管理员只能在受限目录内使用文件读取、写入、编辑和搜索。
+
+非管理员在 `local` 模式下允许访问的目录包括：
+
+- `data/skills`
+- 当前会话的 `data/workspaces/{normalized_umo}`
+- AstrBot 的临时目录
+- 系统临时目录中的 `.astrbot`
+
+关闭“需要 AstrBot 管理员权限”后，普通用户在电脑能力工具上的行为会接近管理员。除非你非常清楚风险，否则不建议关闭。
+
+管理员 ID 可在：
+
+- `配置 -> 其他配置 -> 管理员 ID`
+
+中配置。用户可通过 `/sid` 获取自己的 ID。
+
+## Sandbox 模式
+
+`sandbox` 模式会把执行动作放到隔离环境中，而不是直接在 AstrBot 主机上运行。
+
+在沙盒中，Agent 仍然可以使用 Shell、Python、文件系统工具；如果所选沙盒 profile 支持 `browser` capability，还会挂载浏览器自动化工具。
+
+使用 Shipyard Neo 时，沙盒 workspace 根目录通常是：
+
+```text
+/workspace
+```
+
+文件工具一般应传入相对路径，例如：
+
+```text
+result.txt
+```
+
+而不是：
+
+```text
+/workspace/result.txt
+```
+
+沙盒部署、profile、TTL、数据持久化、浏览器能力等内容请参考：[Agent 沙盒环境](/use/astrbot-agent-sandbox)。
+
+> [!NOTE]
+> 即使在 `sandbox` 模式下，“需要 AstrBot 管理员权限”仍会影响 Shell、Python、浏览器、上传下载等工具的调用权限。具体权限取决于你的配置。
+
+## Skills
+
+Skills 是给 Agent 使用的“任务说明书”，通常存放在 `data/skills` 下，每个 Skill 都包含一个 `SKILL.md`。
+
+电脑能力和 Skills 的关系可以理解为：
+
+- Skills 告诉 Agent 应该怎么做。
+- 电脑能力决定 Agent 能不能执行这些步骤。
+
+例如，一个 Skill 可能要求 Agent 读取文件、运行脚本、生成报告。如果 `Computer Use Runtime` 是 `none`，Agent 可以看到 Skill 的说明，但无法真正调用 Shell 或 Python 完成执行。
+
+在 `local` 模式下，Agent 会读取本地 Skills。
+在 `sandbox` 模式下，AstrBot 会尝试把本地 Skills 同步到沙盒中，让 Agent 在沙盒内按 Skill 指令执行。
+
+更多内容请参考：[技能 Skills](/use/skills)。