AstrBotDevs · Soulter · Sep 15, 2026 · Sep 15, 2026
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -27,6 +27,9 @@
 - [ ] 👀 My changes have been well-tested, **and "Verification Steps" and "Screenshots" have been provided above**.
   / 我的更改经过了良好的测试，**并已在上方提供了“验证步骤”和“运行截图”**。
 
+- [ ] 📚 I checked the affected WebUI instructions and screenshots in `docs/zh` and `docs/en` against the changed navigation, page structure, and labels, and updated them in this PR (or explained why no documentation update is needed). For renamed, moved, or merged entry points, I included an **old entry → new entry** mapping in the documentation and changelog.
+  / 我已对照变化后的 WebUI 入口、页面结构和术语，核对并在本 PR 中更新 `docs/zh` 和 `docs/en` 的相关操作说明与截图（或说明无需更新文档的原因）。入口改名、移动或合并时，已在文档和 changelog 中补充 **旧入口 → 新入口** 对照。
+
 - [ ] 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in `requirements.txt` and `pyproject.toml`.
   / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 `requirements.txt` 和 `pyproject.toml` 文件相应位置。
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -53,6 +53,7 @@ ruff check .
 8. When updating the project version, keep `[project].version` in `pyproject.toml` and `__version__` in `astrbot/__init__.py` in sync. `VERSION` in `astrbot/core/config/default.py` should derive from `astrbot.__version__` instead of hardcoding a separate version string.
 9. When designing WebUI dialogs, use `text-h3 pa-4 pb-0 pl-6` as the base class for dialog titles, and use `variant="text"` or `variant="tonal"` for dialog buttons.
 10. Consider cross-platform compatibility (e.g., Windows, macOS, and Linux, as well as Arm64 and x86 CPU architectures) and compatibility with Python 3.10+.
+11. When changing WebUI navigation, page structure, or terminology, update the affected instructions and screenshots in `docs/zh` and `docs/en` in the same PR. For renamed, moved, or merged entry points, include an old-to-new mapping in the relevant docs and changelog. Keep layout redesigns separate from feature additions where practical, and explain necessary navigation changes in the PR. See `CONTRIBUTING.md` for the review checklist.
 
 ### KISS and First Principles
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,6 +35,14 @@
 
 #### 代码规范
 
+##### WebUI 与文档同步
+
+- 修改菜单入口、页面结构或界面术语时，在同一个 PR 中更新 `docs/zh` 和 `docs/en` 的相关操作说明、链接与截图。没有对应英文页面时无需为此翻译整篇文档，但应检查已有英文说明。
+- 按当前默认侧边栏、实际按钮文案和完整操作流程核对文档。重点检查配置文件、模型提供商、机器人、插件和系统设置；仅通过链接检查不能证明入口说明仍然正确。
+- 入口改名、移动或合并时，在对应文档和 `changelogs/` 中写明「旧入口 → 新入口」，并同步维护 [WebUI 入口对照](docs/zh/use/webui.md#菜单与旧入口对照)。截图若仍展示旧结构，应更新或移除，并用可独立完成操作的文字步骤替代。
+- 将布局重设计与新增功能尽量拆成独立 PR。新增功能优先沿用现有页面结构；确需调整已有入口时，在 PR 中说明原因和受影响的流程，避免连续、无关的页面重排。
+- 提交前运行 `cd docs && pnpm run docs:build`，并按更新后的步骤核对相关 WebUI 页面。在 PR 中写明核对的页面和验证结果。
+
 ##### Core
 
 我们使用 Ruff 作为代码格式化和静态分析工具。在提交代码之前，请运行以下命令以确保代码符合规范：
@@ -106,6 +114,14 @@ We use the `fix/` prefix for bug fixes and the `feat/` prefix for new features.
 
 #### Code Style
 
+##### Keep WebUI and documentation in sync
+
+- When changing navigation, page structure, or UI labels, update the affected instructions, links, and screenshots in `docs/zh` and `docs/en` in the same PR. Check existing English instructions; translating an entire missing English page is not required.
+- Verify the default sidebar, actual button labels, and complete workflows. Pay particular attention to profiles, providers, platforms, extensions, and system settings. Passing link checks does not establish that navigation instructions are correct.
+- For renamed, moved, or merged entry points, include an **old entry → new entry** mapping in the relevant docs and `changelogs/`, and maintain the [WebUI navigation reference](docs/en/use/webui.md#navigation-and-previous-entry-points). Replace or remove screenshots showing outdated layouts, with text instructions sufficient to complete the task on their own.
+- Keep layout redesigns and feature additions in separate PRs where practical. Prefer the existing page structure for new features. Explain necessary navigation changes and affected workflows in the PR to avoid repeated, unrelated rearrangements.
+- Before submitting, run `cd docs && pnpm run docs:build` and check the affected WebUI pages against the updated steps. Include the checked pages and validation results in the PR.
+
 ##### Core
 
 We use Ruff as our code formatter and static analysis tool. Before submitting your code, please run the following commands to ensure your code adheres to the style guidelines:

diff --git a/changelogs/v4.28.0.md b/changelogs/v4.28.0.md
@@ -34,6 +34,18 @@ Each season brings its own beauty, and the joy is endless.
 - Preserved text in Lark mixed text-and-image messages. (#9841)
 - Displayed the create-folder button in the mobile persona manager. (#9812)
 
+### WebUI Upgrade Notes
+
+| Previous entry point | New entry point |
+| --- | --- |
+| Providers → Add Provider → Agent Runner | Config → Select a profile → AI → `…` → Change execution mode |
+| Data / Dashboard | Data & Logs → Statistics |
+| Conversation Management / Conversations | Data & Logs → Conversations |
+| Logs / Console | Data & Logs → Logs |
+| Trace | Data & Logs → Trace |
+
+Third-party Agent parameters are now configured within each profile instead of creating and selecting an Agent provider ID. Changing execution mode resets its parameters to the new mode's defaults; review the confirmation and save the profile after configuration. See the [Agent Runner guide](https://docs.astrbot.app/en/use/agent-runner.html) and [current WebUI navigation reference](https://docs.astrbot.app/en/use/webui.html#navigation-and-previous-entry-points).
+
 ## 中文
 
 ### 主要新增
@@ -67,6 +79,18 @@ Each season brings its own beauty, and the joy is endless.
 - 在移动端的人格管理器中显示新建文件夹按钮。 (#9812)
 
 
+### WebUI 升级提示
+
+| 旧入口 | 新入口 |
+| --- | --- |
+| 模型提供商 → 新增提供商 → Agent 执行器 | 配置文件 → 选择配置文件 → AI 配置 → `…` → 更换执行方式 |
+| 数据 / 数据统计 | 数据与日志 → 统计 |
+| 对话管理 / 对话数据 | 数据与日志 → 对话 |
+| 日志 / 平台日志 | 数据与日志 → 日志 |
+| 追踪 | 数据与日志 → 追踪 |
+
+第三方 Agent 参数现在直接保存在各配置文件中，无需创建和选择 Agent 提供商 ID。切换执行方式会将参数重置为新方式的默认值，请阅读确认提示，并在配置完成后保存配置文件。详见 [Agent 执行器指南](https://docs.astrbot.app/use/agent-runner.html) 和 [当前 WebUI 入口对照](https://docs.astrbot.app/use/webui.html#菜单与旧入口对照)。
+
 [4.28.0-beta.1]: https://github.com/AstrBotDevs/AstrBot/compare/v4.27.4...v4.28.0-beta.1
 
 ## Changes Since 4.28.0-beta.1

diff --git a/dashboard/README.md b/dashboard/README.md
@@ -2,9 +2,33 @@
 
 基于 CodedThemes/Berry 模板开发。
 
-## 环境变量
+## 本地开发
 
-- `VITE_ASTRBOT_RELEASE_BASE_URL`（可选）
-  - 默认值：`https://github.com/AstrBotDevs/AstrBot/releases`
-  - 用途：管理面板内“更新到最新版本”外部跳转所使用的 release 基地址。集成方可按需覆盖（例如 Desktop 指向其自身发布页）。
-  - 建议传入仓库的 `.../releases` 基地址（不带 `/latest`）。
+先在项目根目录启动后端：
+
+```bash
+uv sync
+uv run main.py
+```
+
+在另一个终端启动 WebUI：
+
+```bash
+cd dashboard
+pnpm install
+pnpm dev
+```
+
+开发服务器默认运行在 `http://localhost:3000`，将 `/api` 请求代理到 `http://127.0.0.1:6185`。后端地址不同时，请修改 `vite.config.ts` 中的 `server.proxy`。
+
+## 构建与 API 客户端
+
+```bash
+pnpm build
+```
+
+此命令检查 TypeScript 类型并生成 `dist/`。当后端 API 路由、请求/响应结构或 OpenAPI 定义发生变化时，在本目录运行 `pnpm generate:api` 重新生成前端客户端。
+
+## 发布更新入口
+
+WebUI 顶部的更新入口会打开更新对话框，通过后端 API 获取版本信息。`VITE_ASTRBOT_RELEASE_BASE_URL` 当前没有被前端代码读取，设置此变量不会改变更新入口。
diff --git a/docs/en/config/model-config.md b/docs/en/config/model-config.md
@@ -1,12 +1,10 @@
+# Configure Custom Model Parameters
 
-# 配置自定义的模型参数
+You can configure model parameters in the WebUI:
 
-请手动修改位于 `data/cmd_config.json` 下的配置文件。
+1. Open `Providers` and select the provider containing your model.
+2. In its configured models list, click the model name or its settings icon to open the model configuration dialog.
+3. Under `Custom request body parameters` (`custom_extra_body`), add the parameters required by your model, such as `temperature`, `top_p`, or `max_tokens`.
+4. Click `Save`.
 
-找到 `provider`，并找到你想要修改的提供商的模型配置：
-
-![alt text](https://files.astrbot.app/docs/source/images/model-config/image-2.png)
-
-然后在 `model_config` 中添加新的参数即可。
-
-具体的参数请参看对应的提供商的文档。
+Available fields depend on the provider. For example, Gemini exposes its own generation settings instead of the generic `custom_extra_body` field. Refer to your provider's documentation for supported parameters and values.
diff --git a/docs/en/deploy/astrbot/compshare.md b/docs/en/deploy/astrbot/compshare.md
@@ -33,8 +33,6 @@ You can find the public IP in Console -> Basic Network (Public).
 
 > It may take around 30 seconds before the page becomes reachable.
 
-![WebUI](https://www-s.ucloud.cn/2025/07/7e9fc6edc1dfa916abc069f4cecc24cf_1753940381771.png)
-
 Use the random password printed in startup logs for first-time login, and use the username shown in the logs (usually `astrbot`). Change it immediately after login.
 
 After logging in, you can reset your password and continue setup.
@@ -50,26 +48,21 @@ The image includes Ollama. You can pull any model and host it locally on the ins
 1. Choose a model from [Ollama Search](https://ollama.com/search).
 2. Connect to the instance terminal via SSH (from Compshare Console -> Instance List -> Console Command and Password).
 3. Run `ollama pull <model-name>` and wait for completion.
-4. In AstrBot Dashboard -> Providers, edit `ollama_deepseek-r1`, update the model name, and save.
-
-![image](https://files.astrbot.app/docs/source/images/compshare/image-1.png)
+4. Open `Providers → Chat Completion`, select the preconfigured Ollama source, click `Fetch Model List`, and click `+` beside the model you just pulled. If no source is preconfigured, click `Add`, select `Ollama`, enter the instance's Ollama URL, and click `Save and Fetch Models`.
 
 ### Use Compshare Model API
 
 AstrBot supports direct access to model APIs provided by Compshare.
 
 1. Find the model you want at [Compshare Model Center](https://console.compshare.cn/light-gpu/model-center).
-2. In AstrBot Dashboard -> Providers, click `+ Add Provider`, then choose Compshare.
-If Compshare is not listed, choose OpenAI-compatible access and set API Base URL to `https://api.modelverse.cn/v1`.
-Enter the model name in model configuration and save.
+2. Open `Providers → Chat Completion → Add`, select `OpenAI Compatible`, enter your Compshare API key, and set API Base URL to `https://api.modelverse.cn/v1`.
+3. Click `Save and Fetch Models`, then click `+` beside the model you want. If the API returns no model list, click `Save Configuration`, then `Custom Model`, and enter the exact model ID supplied by Compshare.
 
 ### Test
 
-In AstrBot Dashboard, click `Chat` and run `/provider` to view and switch your active provider.
-
-Then send a normal message to test whether the model works.
+Click `Test Model` on the configured model to check connectivity. Then open `Config`, select the profile used by your bot, choose the new model under `AI → Model → Chat Model`, and click `Save Configuration`.
 
-![image](https://files.astrbot.app/docs/source/images/compshare/image-2.png)
+Use the chat switch in the WebUI header or send a message to the bot on its connected messaging platform to test a reply.
 
 ## Connect to Messaging Platforms
 

diff --git a/docs/en/deploy/astrbot/kubernetes.md b/docs/en/deploy/astrbot/kubernetes.md
@@ -73,7 +73,7 @@ kubectl apply -f k8s/astrbot_with_napcat/02-deployment.yaml
 Since AstrBot and NapCat are in the same Pod, they can communicate directly via `localhost`.
 
 1.  **Add a message platform in AstrBot:**
-    *   Go to the AstrBot WebUI, select  `Platform` -> `Add`.
+    *   Go to the AstrBot WebUI, select  `Platforms` -> `Add Adapter`.
     *   **Select Message Platform Category**: `aiocqhttp`
     *   **Bot Name**: `napcat` (or custom)
     *   **Reverse Websocket Host**: `0.0.0.0`

diff --git a/docs/en/deploy/when-deployed.md b/docs/en/deploy/when-deployed.md
@@ -12,5 +12,5 @@ AstrBot Documentation: [![wakatime](https://wakatime.com/badge/user/915e5316-99c
 
 ## Next...
 
-If you're reading this, it means you have successfully deployed the messaging platform and sent/received your first command. Next, you can configure large language models or add plugins. Please refer to the `Configuration - Integrating LLM Services` section.
+If you're reading this, it means you have successfully deployed the messaging platform and sent/received your first command. Next, add a model under `Providers`, select it in the bot's configuration profile under `Config`, or install plugins under `Extensions → Plugins → AstrBot Plugin Market`. See [Model Providers](../providers/start.md) and [Plugins](../use/plugin.md).
 
diff --git a/docs/en/dev/astrbot-config.md b/docs/en/dev/astrbot-config.md
@@ -10,6 +10,8 @@ AstrBot's configuration file is a JSON format file. AstrBot reads this file at s
 
 > Since AstrBot v4.0.0, we introduced the concept of [multiple configuration files](https://blog.astrbot.app/posts/what-is-changed-in-4.0.0/#%E5%A4%9A%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6). `data/cmd_config.json` serves as the default configuration `default`. Other configuration files you create in the WebUI are stored in the `data/config/` directory, starting with `abconf_`.
 
+In the WebUI, manage bot and session behavior profiles under `Config`. Global runtime, logging, network, WebUI security, and text-to-image service settings are under `Settings`. Model connections and bot connections are managed under `Providers` and `Platforms`, respectively.
+
 The default AstrBot configuration is as follows:
 
 ```jsonc
@@ -548,7 +550,7 @@ Log level. Default is `INFO`. Can be set to `DEBUG`, `INFO`, `WARNING`, `ERROR`,
 
 ### `trace_enable`
 
-Whether to enable trace recording. Default is `false`. When enabled, AstrBot records execution traces, which can be viewed under `Data` -> `Trace` in the admin panel.
+Whether to enable trace recording. Default is `false`. When enabled, AstrBot records execution traces, which can be viewed under `Data & Logs → Trace` in the admin panel.
 
 ### `pip_install_arg`
 

diff --git a/docs/en/dev/openapi.md b/docs/en/dev/openapi.md
@@ -8,7 +8,7 @@ Starting from v4.18.0, AstrBot provides API Key based HTTP APIs for programmatic
 
 ## Quick Start
 
-1. Create an API key in WebUI - Settings.
+1. Open `Settings → OpenAPI` in the WebUI and click `Create API Key`.
 2. Include the API key in request headers:
 
 ```http

diff --git a/docs/en/dev/star/plugin-new.md b/docs/en/dev/star/plugin-new.md
@@ -86,7 +86,7 @@ your_plugin/
     SKILL.md
 ```
 
-In that case, the Skill name uses the plugin directory name. Plugin-provided Skills are managed by the plugin and appear as read-only sources in the WebUI Skills page. They can be enabled or disabled, but cannot be deleted or edited from Local Skills. When the plugin is uninstalled or updated, its bundled Skills change with the plugin files.
+In that case, the Skill name uses the plugin directory name. Plugin-provided Skills are managed by the plugin and appear as read-only sources under `Extensions → Skills` in the WebUI. They can be enabled or disabled, but cannot be deleted or edited from Local Skills. When the plugin is uninstalled or updated, its bundled Skills change with the plugin files.
 
 ### Declare Supported Platforms (Optional)
 
@@ -147,9 +147,9 @@ AstrBot uses a runtime plugin injection mechanism. Therefore, when debugging plu
 
 You can use AstrBot's hot reload feature to streamline the development process.
 
-After modifying the plugin code, you can find your plugin in the AstrBot WebUI's plugin management section, click the `...` button in the upper right corner, and select `Reload Plugin`.
+After modifying the plugin code, open `Extensions → Plugins` in the AstrBot WebUI, find your plugin, and click the refresh icon (`Reload Extension`) on its card.
 
-If the plugin fails to load due to code errors or other reasons, you can also click **"Try one-click reload fix"** in the error prompt on the admin panel to reload it.
+If the plugin fails to load due to code errors or other reasons, click its `Reload` button in the `Failed to Load Plugins` list on the same page.
 
 ### Plugin Dependency Management
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,5 +12,5 @@ AstrBot Documentation: [![wakatime](https://wakatime.com/badge/user/915e5316-99c

		## Next...

		If you're reading this, it means you have successfully deployed the messaging platform and sent/received your first command. Next, you can configure large language models or add plugins. Please refer to the `Configuration - Integrating LLM Services` section.
		If you're reading this, it means you have successfully deployed the messaging platform and sent/received your first command. Next, add a model under `Providers`, select it in the bot's configuration profile under `Config`, or install plugins under `Extensions → Plugins → AstrBot Plugin Market`. See [Model Providers](../providers/start.md) and [Plugins](../use/plugin.md).