docs: update for AstrBotDevs/AstrBot#4787

Author: astrbot-docs-agent[bot]

.vitepress/config.mjs

@@ -106,6 +106,7 @@ export default defineConfig({
                       { text: "使用 server-satori", link: "/server-satori" },
                     ],
                   },
+                  { text: "CLI 测试器", link: "/cli-tester" },
                 ],
               },
               {
@@ -191,6 +192,7 @@ export default defineConfig({
                   { text: "存储", link: "/guides/storage" },
                   { text: "文转图", link: "/guides/html-to-pic" },
                   { text: "会话控制器", link: "/guides/session-control" },
+                  { text: "使用 CLI Tester 调试", link: "/guides/test-with-cli" },
                   { text: "杂项", link: "/guides/other" },
                   { text: "发布插件", link: "/plugin-publish" },
                   { text: "插件指南（旧）", link: "/plugin" },
@@ -325,6 +327,7 @@ export default defineConfig({
                       { text: "Using server-satori", link: "/server-satori" },
                     ],
                   },
+                  { text: "CLI Tester", link: "/cli-tester" },
                 ],
               },
               {
@@ -410,6 +413,7 @@ export default defineConfig({
                   { text: "Storage", link: "/guides/storage" },
                   { text: "HTML to Image", link: "/guides/html-to-pic" },
                   { text: "Session Control", link: "/guides/session-control" },
+                  { text: "Debugging with CLI Tester", link: "/guides/test-with-cli" },
                   { text: "Publish Plugin", link: "/plugin-publish" },
                 ],
               },

en/deploy/platform/cli-tester.md

@@ -0,0 +1,16 @@
+# CLI Tester
+
+CLI Tester is a built-in platform adapter specifically designed for quickly testing and debugging AstrBot plugins via the command line without connecting to a real messaging platform.
+
+## How to Enable
+
+1. Go to the AstrBot Management Panel.
+2. Navigate to **Settings** -> **Platform Access**.
+3. Click **Add Adapter** and select **CLI Tester** (Type: `cli`).
+4. Toggle **Enable** in the configuration.
+
+## Detailed Guide
+
+For instructions on how to use CLI Tester for plugin development and debugging, please refer to:
+
+👉 [Debugging Plugins with CLI Tester](/en/dev/star/guides/test-with-cli)

en/dev/star/guides/test-with-cli.md

@@ -0,0 +1,76 @@
+# Debugging Plugins with CLI Tester
+
+CLI Tester is a built-in platform adapter designed to provide a fast feedback loop for plugin developers. With CLI Tester, you can test and debug your plugin logic directly from the command line without connecting to any messaging platforms (like QQ, WeChat, etc.).
+
+## Core Values
+
+- ⚡ **Instant Feedback**: No need to log into IM platforms; send messages and see results directly in the terminal.
+- 🔄 **Fast Iteration**: Shortens the "edit code -> restart -> test" cycle.
+- 🎯 **Focused Development**: Focus on plugin logic without platform interaction overhead.
+- 🧪 **Independent Testing**: Supports concurrent testing and session isolation.
+
+## Enabling CLI Tester
+
+1. Go to the AstrBot Management Panel.
+2. Navigate to **Settings** -> **Platform Access**.
+3. Find **CLI Tester** (Type: `cli`).
+4. Toggle the **Enable** switch.
+5. The default configuration is usually sufficient:
+   - **Mode**: `socket` (Recommended)
+   - **Socket Path**: `/tmp/astrbot.sock`
+   - **Session Isolation**: `false` (Enable if you need to simulate multi-user concurrent tests)
+
+## Usage
+
+### 1. Basic Testing
+
+You can use the `astrbot-cli` tool inside the container to send messages:
+
+```bash
+# Test inside the Docker container
+docker exec -it astrbot python3 /AstrBot/astrbot-cli "Hello"
+
+# Test plugin commands
+docker exec -it astrbot python3 /AstrBot/astrbot-cli "/help"
+```
+
+### 2. Viewing Rich Media Responses
+
+If your plugin returns rich media content like images, you can use the `-j` flag to view the raw JSON response (including Base64 encoded image data):
+
+```bash
+docker exec -it astrbot python3 /AstrBot/astrbot-cli -j "/time"
+```
+
+### 3. Creating a Host Shortcut (Optional)
+
+For convenience, you can create a wrapper script on your host machine:
+
+```bash
+# Execute on the host machine
+cat > /usr/local/bin/astrbot-cli << 'EOF'
+#!/bin/bash
+docker exec -i astrbot python3 /AstrBot/astrbot-cli "$@"
+EOF
+
+chmod +x /usr/local/bin/astrbot-cli
+
+# Now you can use it directly on the host
+astrbot-cli "Test message"
+```
+
+## Running Modes
+
+CLI Tester supports several modes, which can be modified in the configuration:
+
+- **socket** (Default): Communicates via Unix Socket, supporting concurrency and structured responses.
+- **tty**: Interactive mode, input/output directly in the terminal where AstrBot is running (not recommended for Docker production environments).
+- **file**: File polling mode, reads input from a specified file.
+
+## Advanced: Session Isolation
+
+When `use_isolated_sessions` is enabled in the configuration, every request sent via `astrbot-cli` is treated as an independent session. This is useful for testing plugins that require context memory or for concurrent scenarios.
+
+::: tip NOTE
+CLI Tester is automatically exempted from whitelist checks, so you don't have to worry about test messages being blocked.
+:::

en/dev/star/plugin-new.md

@@ -59,6 +59,8 @@ AstrBot uses a runtime plugin injection mechanism. Therefore, when debugging plu
 
 You can use AstrBot's hot reload feature to streamline the development process.
 
+Additionally, AstrBot provides the **CLI Tester** tool, allowing you to quickly test plugin logic from the command line without connecting to a real IM platform. See [Debugging Plugins with CLI Tester](/en/dev/star/guides/test-with-cli) for details.
+
 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`.
 
 ### Plugin Dependency Management

zh/deploy/platform/cli-tester.md

@@ -0,0 +1,16 @@
+# CLI 测试器 (CLI Tester)
+
+CLI 测试器是一个内置的平台适配器，专门用于在不连接真实即时通讯平台的情况下，通过命令行快速测试和调试 AstrBot 插件。
+
+## 启用方法
+
+1. 进入 AstrBot 管理面板。
+2. 导航至 **设置** -> **平台接入**。
+3. 点击 **新增适配器**，选择 **CLI测试器** (Type: `cli`)。
+4. 在配置中开启 **启用**。
+
+## 详细指南
+
+关于如何使用 CLI 测试器进行插件开发和调试，请参考：
+
+👉 [使用 CLI Tester 调试插件](/dev/star/guides/test-with-cli)

zh/dev/star/guides/test-with-cli.md

@@ -0,0 +1,76 @@
+# 使用 CLI Tester 调试插件
+
+CLI Tester 是一个内置的平台适配器，旨在为插件开发者提供快速的反馈循环。通过 CLI Tester，你可以在不连接任何即时通讯平台（如 QQ、微信等）的情况下，直接在命令行中测试和调试你的插件逻辑。
+
+## 核心价值
+
+- ⚡ **即时反馈**：无需登录 IM 平台，命令行直接发送消息并查看结果。
+- 🔄 **快速迭代**：缩短“修改代码 -> 重启 -> 测试”的周期。
+- 🎯 **专注开发**：专注于插件逻辑，不受平台交互限制。
+- 🧪 **独立测试**：支持并发测试和会话隔离。
+
+## 启用 CLI Tester
+
+1. 进入 AstrBot 管理面板。
+2. 导航至 **设置** -> **平台接入**。
+3. 找到 **CLI测试器** (Type: `cli`)。
+4. 开启 **启用** 开关。
+5. 默认配置通常即可使用：
+   - **模式**: `socket` (推荐)
+   - **Socket 路径**: `/tmp/astrbot.sock`
+   - **会话隔离**: `false` (如果需要模拟多用户并发测试可开启)
+
+## 使用方法
+
+### 1. 基础测试
+
+你可以使用容器内的 `astrbot-cli` 工具发送消息：
+
+```bash
+# 在 Docker 容器内测试
+docker exec -it astrbot python3 /AstrBot/astrbot-cli "你好"
+
+# 测试插件指令
+docker exec -it astrbot python3 /AstrBot/astrbot-cli "/help"
+```
+
+### 2. 查看富媒体响应
+
+如果你的插件返回了图片等富媒体内容，可以使用 `-j` 参数查看原始 JSON 响应（包含 Base64 编码的图片数据）：
+
+```bash
+docker exec -it astrbot python3 /AstrBot/astrbot-cli -j "/time"
+```
+
+### 3. 创建宿主机快捷命令（可选）
+
+为了更方便地使用，你可以在宿主机上创建一个包装脚本：
+
+```bash
+# 在宿主机执行
+cat > /usr/local/bin/astrbot-cli << 'EOF'
+#!/bin/bash
+docker exec -i astrbot python3 /AstrBot/astrbot-cli "$@"
+EOF
+
+chmod +x /usr/local/bin/astrbot-cli
+
+# 现在可以直接在宿主机使用
+astrbot-cli "测试消息"
+```
+
+## 运行模式
+
+CLI Tester 支持多种运行模式，可在配置中修改：
+
+- **socket** (默认): 通过 Unix Socket 通信，支持并发和结构化响应。
+- **tty**: 交互式模式，直接在 AstrBot 运行的终端进行输入输出（不推荐在 Docker 生产环境使用）。
+- **file**: 轮询文件模式，通过读取指定文件的内容作为输入。
+
+## 进阶技巧：会话隔离
+
+在配置中开启 `use_isolated_sessions` 后，每个通过 `astrbot-cli` 发送的请求都会被视为一个独立的会话。这对于测试需要上下文记忆的插件或并发场景非常有用。
+
+::: tip 提示
+CLI Tester 自动豁免白名单检查，因此你无需担心测试消息被拦截。
+:::

zh/dev/star/plugin-new.md

@@ -59,6 +59,8 @@ AstrBot 采用在运行时注入插件的机制。因此，在调试插件时，
 
 您可以使用 AstrBot 的热重载功能简化开发流程。
 
+此外，AstrBot 提供了 **CLI Tester** 工具，允许你在命令行中快速测试插件逻辑，而无需连接真实的 IM 平台。详见 [使用 CLI Tester 调试插件](/dev/star/guides/test-with-cli)。
+
 插件的代码修改后，可以在 AstrBot WebUI 的插件管理处找到自己的插件，点击右上角 `...` 按钮，选择 `重载插件`。
 
 ### 插件依赖管理