Skip to content

Commit 553096b

Browse files
authored
docs: sync guides with current WebUI navigation (#10093)
1 parent 5950d7c commit 553096b

135 files changed

Lines changed: 606 additions & 614 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@
2727
- [ ] 👀 My changes have been well-tested, **and "Verification Steps" and "Screenshots" have been provided above**.
2828
/ 我的更改经过了良好的测试,**并已在上方提供了“验证步骤”和“运行截图”**。
2929

30+
- [ ] 📚 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.
31+
/ 我已对照变化后的 WebUI 入口、页面结构和术语,核对并在本 PR 中更新 `docs/zh` 和 `docs/en` 的相关操作说明与截图(或说明无需更新文档的原因)。入口改名、移动或合并时,已在文档和 changelog 中补充 **旧入口 → 新入口** 对照。
32+
3033
- [ ] 🤓 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`.
3134
/ 我确保没有引入新依赖库,或者引入了新依赖库的同时将其添加到 `requirements.txt` 和 `pyproject.toml` 文件相应位置。
3235

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ ruff check .
5353
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.
5454
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.
5555
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+.
56+
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.
5657

5758
### KISS and First Principles
5859

‎CONTRIBUTING.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,14 @@
3535

3636
#### 代码规范
3737

38+
##### WebUI 与文档同步
39+
40+
- 修改菜单入口、页面结构或界面术语时,在同一个 PR 中更新 `docs/zh` 和 `docs/en` 的相关操作说明、链接与截图。没有对应英文页面时无需为此翻译整篇文档,但应检查已有英文说明。
41+
- 按当前默认侧边栏、实际按钮文案和完整操作流程核对文档。重点检查配置文件、模型提供商、机器人、插件和系统设置;仅通过链接检查不能证明入口说明仍然正确。
42+
- 入口改名、移动或合并时,在对应文档和 `changelogs/` 中写明「旧入口 → 新入口」,并同步维护 [WebUI 入口对照](docs/zh/use/webui.md#菜单与旧入口对照)。截图若仍展示旧结构,应更新或移除,并用可独立完成操作的文字步骤替代。
43+
- 将布局重设计与新增功能尽量拆成独立 PR。新增功能优先沿用现有页面结构;确需调整已有入口时,在 PR 中说明原因和受影响的流程,避免连续、无关的页面重排。
44+
- 提交前运行 `cd docs && pnpm run docs:build`,并按更新后的步骤核对相关 WebUI 页面。在 PR 中写明核对的页面和验证结果。
45+
3846
##### Core
3947

4048
我们使用 Ruff 作为代码格式化和静态分析工具。在提交代码之前,请运行以下命令以确保代码符合规范:
@@ -106,6 +114,14 @@ We use the `fix/` prefix for bug fixes and the `feat/` prefix for new features.
106114

107115
#### Code Style
108116

117+
##### Keep WebUI and documentation in sync
118+
119+
- 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.
120+
- 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.
121+
- 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.
122+
- 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.
123+
- 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.
124+
109125
##### Core
110126

111127
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:

‎changelogs/v4.28.0.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,18 @@ Each season brings its own beauty, and the joy is endless.
3434
- Preserved text in Lark mixed text-and-image messages. (#9841)
3535
- Displayed the create-folder button in the mobile persona manager. (#9812)
3636

37+
### WebUI Upgrade Notes
38+
39+
| Previous entry point | New entry point |
40+
| --- | --- |
41+
| Providers → Add Provider → Agent Runner | Config → Select a profile → AI → `…` → Change execution mode |
42+
| Data / Dashboard | Data & Logs → Statistics |
43+
| Conversation Management / Conversations | Data & Logs → Conversations |
44+
| Logs / Console | Data & Logs → Logs |
45+
| Trace | Data & Logs → Trace |
46+
47+
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).
48+
3749
## 中文
3850

3951
### 主要新增
@@ -67,6 +79,18 @@ Each season brings its own beauty, and the joy is endless.
6779
- 在移动端的人格管理器中显示新建文件夹按钮。 (#9812)
6880

6981

82+
### WebUI 升级提示
83+
84+
| 旧入口 | 新入口 |
85+
| --- | --- |
86+
| 模型提供商 → 新增提供商 → Agent 执行器 | 配置文件 → 选择配置文件 → AI 配置 → `…` → 更换执行方式 |
87+
| 数据 / 数据统计 | 数据与日志 → 统计 |
88+
| 对话管理 / 对话数据 | 数据与日志 → 对话 |
89+
| 日志 / 平台日志 | 数据与日志 → 日志 |
90+
| 追踪 | 数据与日志 → 追踪 |
91+
92+
第三方 Agent 参数现在直接保存在各配置文件中,无需创建和选择 Agent 提供商 ID。切换执行方式会将参数重置为新方式的默认值,请阅读确认提示,并在配置完成后保存配置文件。详见 [Agent 执行器指南](https://docs.astrbot.app/use/agent-runner.html) 和 [当前 WebUI 入口对照](https://docs.astrbot.app/use/webui.html#菜单与旧入口对照)。
93+
7094
[4.28.0-beta.1]: https://github.com/AstrBotDevs/AstrBot/compare/v4.27.4...v4.28.0-beta.1
7195

7296
## Changes Since 4.28.0-beta.1

‎dashboard/README.md‎

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,33 @@
22

33
基于 CodedThemes/Berry 模板开发。
44

5-
## 环境变量
5+
## 本地开发
66

7-
- `VITE_ASTRBOT_RELEASE_BASE_URL`(可选)
8-
- 默认值:`https://github.com/AstrBotDevs/AstrBot/releases`
9-
- 用途:管理面板内“更新到最新版本”外部跳转所使用的 release 基地址。集成方可按需覆盖(例如 Desktop 指向其自身发布页)。
10-
- 建议传入仓库的 `.../releases` 基地址(不带 `/latest`)。
7+
先在项目根目录启动后端:
8+
9+
```bash
10+
uv sync
11+
uv run main.py
12+
```
13+
14+
在另一个终端启动 WebUI:
15+
16+
```bash
17+
cd dashboard
18+
pnpm install
19+
pnpm dev
20+
```
21+
22+
开发服务器默认运行在 `http://localhost:3000`,将 `/api` 请求代理到 `http://127.0.0.1:6185`。后端地址不同时,请修改 `vite.config.ts` 中的 `server.proxy`。
23+
24+
## 构建与 API 客户端
25+
26+
```bash
27+
pnpm build
28+
```
29+
30+
此命令检查 TypeScript 类型并生成 `dist/`。当后端 API 路由、请求/响应结构或 OpenAPI 定义发生变化时,在本目录运行 `pnpm generate:api` 重新生成前端客户端。
31+
32+
## 发布更新入口
33+
34+
WebUI 顶部的更新入口会打开更新对话框,通过后端 API 获取版本信息。`VITE_ASTRBOT_RELEASE_BASE_URL` 当前没有被前端代码读取,设置此变量不会改变更新入口。

‎docs/en/config/model-config.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
1+
# Configure Custom Model Parameters
12

2-
# 配置自定义的模型参数
3+
You can configure model parameters in the WebUI:
34

4-
请手动修改位于 `data/cmd_config.json` 下的配置文件。
5+
1. Open `Providers` and select the provider containing your model.
6+
2. In its configured models list, click the model name or its settings icon to open the model configuration dialog.
7+
3. Under `Custom request body parameters` (`custom_extra_body`), add the parameters required by your model, such as `temperature`, `top_p`, or `max_tokens`.
8+
4. Click `Save`.
59

6-
找到 `provider`,并找到你想要修改的提供商的模型配置:
7-
8-
![alt text](https://files.astrbot.app/docs/source/images/model-config/image-2.png)
9-
10-
然后在 `model_config` 中添加新的参数即可。
11-
12-
具体的参数请参看对应的提供商的文档。
10+
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.

‎docs/en/deploy/astrbot/compshare.md‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,6 @@ You can find the public IP in Console -> Basic Network (Public).
3333

3434
> It may take around 30 seconds before the page becomes reachable.
3535
36-
![WebUI](https://www-s.ucloud.cn/2025/07/7e9fc6edc1dfa916abc069f4cecc24cf_1753940381771.png)
37-
3836
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.
3937

4038
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
5048
1. Choose a model from [Ollama Search](https://ollama.com/search).
5149
2. Connect to the instance terminal via SSH (from Compshare Console -> Instance List -> Console Command and Password).
5250
3. Run `ollama pull <model-name>` and wait for completion.
53-
4. In AstrBot Dashboard -> Providers, edit `ollama_deepseek-r1`, update the model name, and save.
54-
55-
![image](https://files.astrbot.app/docs/source/images/compshare/image-1.png)
51+
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`.
5652

5753
### Use Compshare Model API
5854

5955
AstrBot supports direct access to model APIs provided by Compshare.
6056

6157
1. Find the model you want at [Compshare Model Center](https://console.compshare.cn/light-gpu/model-center).
62-
2. In AstrBot Dashboard -> Providers, click `+ Add Provider`, then choose Compshare.
63-
If Compshare is not listed, choose OpenAI-compatible access and set API Base URL to `https://api.modelverse.cn/v1`.
64-
Enter the model name in model configuration and save.
58+
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`.
59+
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.
6560

6661
### Test
6762

68-
In AstrBot Dashboard, click `Chat` and run `/provider` to view and switch your active provider.
69-
70-
Then send a normal message to test whether the model works.
63+
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`.
7164

72-
![image](https://files.astrbot.app/docs/source/images/compshare/image-2.png)
65+
Use the chat switch in the WebUI header or send a message to the bot on its connected messaging platform to test a reply.
7366

7467
## Connect to Messaging Platforms
7568

‎docs/en/deploy/astrbot/kubernetes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ kubectl apply -f k8s/astrbot_with_napcat/02-deployment.yaml
7373
Since AstrBot and NapCat are in the same Pod, they can communicate directly via `localhost`.
7474

7575
1. **Add a message platform in AstrBot:**
76-
* Go to the AstrBot WebUI, select `Platform` -> `Add`.
76+
* Go to the AstrBot WebUI, select `Platforms` -> `Add Adapter`.
7777
* **Select Message Platform Category**: `aiocqhttp`
7878
* **Bot Name**: `napcat` (or custom)
7979
* **Reverse Websocket Host**: `0.0.0.0`

‎docs/en/deploy/when-deployed.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,5 @@ AstrBot Documentation: [![wakatime](https://wakatime.com/badge/user/915e5316-99c
1212

1313
## Next...
1414

15-
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.
15+
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).
1616

‎docs/en/dev/astrbot-config.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ AstrBot's configuration file is a JSON format file. AstrBot reads this file at s
1010

1111
> 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_`.
1212
13+
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.
14+
1315
The default AstrBot configuration is as follows:
1416

1517
```jsonc
@@ -548,7 +550,7 @@ Log level. Default is `INFO`. Can be set to `DEBUG`, `INFO`, `WARNING`, `ERROR`,
548550

549551
### `trace_enable`
550552

551-
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.
553+
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.
552554

553555
### `pip_install_arg`
554556

0 commit comments

Comments
 (0)