docs: make sandbox plugin guide developer focused

Author: zouyonghe

docs/en/dev/star/guides/plugin-config.md

@@ -226,9 +226,9 @@ Note that `default` is only applied when creating a new config file or when a fi
 
 ## Building a Sandbox Runtime Plugin
 
-Starting from the generic sandbox architecture, concrete runtimes such as `CUA`, `Shipyard`, `Shipyard Neo`, or `Boxlite` should be implemented as **separate plugins**, not hard-coded in AstrBot Core.
+A sandbox runtime plugin teaches AstrBot how to start and connect to a sandbox service. The plugin usually contains a provider, a booter/client, a config schema, and optional tools for features such as screenshots or browser control.
 
-Recommended structure:
+Start with this structure:
 
 ```text
 data/plugins/<plugin_name>/
@@ -240,17 +240,17 @@ data/plugins/<plugin_name>/
   tools/
 ```
 
-Typical responsibilities are split like this:
+Use the files like this:
 
-- `main.py`: plugin entrypoint, provider registration, and optional extra tool registration.
-- `provider.py`: sandbox provider implementation.
-- `booters/`: runtime-specific sandbox client / booter implementation.
-- `tools/`: optional runtime-specific tools, such as screenshot, mouse, keyboard, browser, or lifecycle helpers.
-- `_conf_schema.json`: provider-specific configuration shown in WebUI.
+- `main.py`: register the provider, and register any extra tools.
+- `provider.py`: adapt your runtime to AstrBot's sandbox provider methods.
+- `booters/`: put the client code that starts, connects to, and shuts down the sandbox.
+- `tools/`: add optional runtime tools such as screenshot, mouse, keyboard, browser, or lifecycle helpers.
+- `_conf_schema.json`: define the settings shown in WebUI.
 
-### 1. Register the sandbox provider
+### 1. Register the provider
 
-In your plugin entrypoint, register and unregister the provider through the generic sandbox APIs exposed by core:
+In `main.py`, create your provider and register it when the plugin loads. Pass the plugin config into the provider so `provider.py` can read values from `_conf_schema.json`.
 
 ```python
 from astrbot.api.star import Context, Star, register
@@ -274,11 +274,11 @@ class DemoSandboxPlugin(Star):
         unregister_sandbox_provider(self.provider.provider_id, force=True)
 ```
 
-Use a stable plugin name, directory name, and metadata `name`, ideally all aligned.
+Use a stable name for the plugin directory, `metadata.yaml`, and `@register(...)`. Keeping them aligned makes the generated config file easy to find.
 
-### 2. Implement the provider contract
+### 2. Implement `provider.py`
 
-Your provider should implement the generic sandbox protocol from core (`astrbot.core.computer.sandbox_provider.SandboxProvider`). In practice, that means defining:
+AstrBot calls the provider whenever it needs to create, reuse, rename, or destroy a sandbox. Implement these fields and methods:
 
 - `provider_id`
 - `capabilities`
@@ -290,7 +290,7 @@ Your provider should implement the generic sandbox protocol from core (`astrbot.
 - `create_booter(context, session_id, sandbox_id, config)`
 - `destroy_booter(booter, record)`
 
-Example skeleton:
+This is a minimal provider skeleton:
 
 ```python
 class MySandboxProvider:
@@ -329,14 +329,9 @@ class MySandboxProvider:
         await booter.shutdown()
 ```
 
-### 3. Put runtime-specific config in `_conf_schema.json`
+### 3. Add runtime config
 
-Core only keeps the generic selector:
-
-- `provider_settings.computer_use_runtime`
-- `provider_settings.sandbox.booter`
-
-All runtime-specific config belongs to the plugin schema, for example:
+Create `_conf_schema.json` for values that users should edit in WebUI, such as API endpoints, access tokens, profiles, image names, or timeouts.
 
 ```json
 {
@@ -355,33 +350,29 @@ All runtime-specific config belongs to the plugin schema, for example:
 }
 ```
 
-That schema will be stored under `data/config/<plugin_name>_config.json` and passed to the plugin constructor as `config`.
+AstrBot stores the saved values in `data/config/<plugin_name>_config.json` and passes them to the plugin constructor as `config`.
 
-If your provider needs session-level or legacy overrides from `provider_settings.sandbox`, read them in `build_create_config()` as overrides on top of the plugin config. Do not add runtime-specific fields to core config metadata.
+If your provider still supports older values under `provider_settings.sandbox`, read them in `build_create_config()` as overrides on top of the plugin config. New provider settings should normally live in `_conf_schema.json`.
 
-### 4. Expose optional runtime tools through `tool_names`
+### 4. Add optional tools
 
-If your runtime adds extra tools beyond the generic shell/python/filesystem stack, register them in the plugin and list their names in `tool_names`.
+If your runtime exposes extra abilities, register those tools in the plugin and list the tool names in `provider.tool_names`.
 
-Typical examples:
+Common examples:
 
 - screenshot tools
 - mouse / keyboard tools
 - browser tools
 - runtime-specific lifecycle helpers
 
-Core uses `tool_names` to mount those tools automatically in sandbox mode, so avoid hard-coding provider names in core.
-
-### 5. Keep runtime code out of core
-
-When building a sandbox plugin:
+AstrBot uses `tool_names` when mounting tools in sandbox mode. Make sure the names match the tools you register in `main.py`.
 
-- Put concrete runtime SDK imports in the plugin repo.
-- Put provider-specific defaults and config schema in the plugin repo.
-- Put runtime-specific tools in the plugin repo.
-- Keep AstrBot Core limited to generic sandbox registration, lifecycle, persistence, and dashboard/API surfaces.
+### 5. Try it locally
 
-If you are unsure whether something belongs in core or a plugin, the rule of thumb is:
+After adding the plugin under `data/plugins/<plugin_name>/`, start AstrBot and check these items:
 
-- generic behavior -> core
-- concrete runtime behavior -> plugin
+- The plugin loads without import errors.
+- The WebUI config page shows fields from `_conf_schema.json`.
+- The sandbox runtime selector includes your `provider_id`.
+- Creating a sandbox calls `create_booter()`.
+- Stopping or unloading the plugin calls `terminate()` and unregisters the provider.

docs/zh/dev/star/guides/plugin-config.md

@@ -225,9 +225,9 @@ class ConfigPlugin(Star):
 
 ## 制作沙盒运行时插件
 
-从通用沙盒架构开始，`CUA`、`Shipyard`、`Shipyard Neo`、`Boxlite` 这类具体 runtime 应当作为**独立插件**实现，而不是继续硬编码在 AstrBot Core 中。
+沙盒运行时插件负责告诉 AstrBot 如何启动并连接到一个沙盒服务。一个插件通常包含 provider、booter/client、配置 schema，以及截图、浏览器控制这类可选工具。
 
-推荐目录结构：
+可以先按这个结构创建目录：
 
 ```text
 data/plugins/<plugin_name>/
@@ -239,17 +239,17 @@ data/plugins/<plugin_name>/
   tools/
 ```
 
-通常可以这样分工：
+各文件大致这样分工：
 
-- `main.py`：插件入口、provider 注册，以及可选的额外工具注册。
-- `provider.py`：sandbox provider 实现。
-- `booters/`：runtime 具体的 sandbox client / booter。
-- `tools/`：可选的 runtime 专属工具，例如截图、鼠标、键盘、浏览器或生命周期工具。
-- `_conf_schema.json`：在 WebUI 中展示的 provider 专属配置。
+- `main.py`：注册 provider，也可以注册额外工具。
+- `provider.py`：把你的 runtime 适配成 AstrBot 的 sandbox provider。
+- `booters/`：放启动、连接、关闭沙盒的 client 代码。
+- `tools/`：放截图、鼠标、键盘、浏览器或生命周期这类可选工具。
+- `_conf_schema.json`：定义 WebUI 中展示的配置项。
 
-### 1. 注册 sandbox provider
+### 1. 注册 provider
 
-在插件入口中，通过 core 暴露的通用接口注册和注销 provider：
+在 `main.py` 中创建 provider，并在插件加载时注册它。把插件配置传给 provider，这样 `provider.py` 就能读取 `_conf_schema.json` 生成的配置。
 
 ```python
 from astrbot.api.star import Context, Star, register
@@ -273,11 +273,11 @@ class DemoSandboxPlugin(Star):
         unregister_sandbox_provider(self.provider.provider_id, force=True)
 ```
 
-建议插件目录名、metadata `name`、实际注册名保持一致，并使用稳定、可导入的命名。
+建议插件目录名、`metadata.yaml` 里的 `name`、`@register(...)` 的名字保持一致，后续查找生成的配置文件会更直观。
 
-### 2. 实现 provider 协议
+### 2. 实现 `provider.py`
 
-provider 需要实现 core 中定义的通用 sandbox 协议（`astrbot.core.computer.sandbox_provider.SandboxProvider`）。实践上至少要提供：
+AstrBot 在创建、复用、重命名、销毁沙盒时会调用 provider。你需要实现这些字段和方法：
 
 - `provider_id`
 - `capabilities`
@@ -289,7 +289,7 @@ provider 需要实现 core 中定义的通用 sandbox 协议（`astrbot.core.com
 - `create_booter(context, session_id, sandbox_id, config)`
 - `destroy_booter(booter, record)`
 
-示例骨架：
+下面是一个最小骨架：
 
 ```python
 class MySandboxProvider:
@@ -328,14 +328,9 @@ class MySandboxProvider:
         await booter.shutdown()
 ```
 
-### 3. 把 runtime 专属配置放进 `_conf_schema.json`
+### 3. 添加 runtime 配置
 
-Core 只保留通用选择项：
-
-- `provider_settings.computer_use_runtime`
-- `provider_settings.sandbox.booter`
-
-所有 runtime 专属配置都应该放在插件自己的 schema 中，例如：
+如果用户需要在 WebUI 中填写 API 地址、访问令牌、profile、镜像名或超时时间，把这些字段写进 `_conf_schema.json`。
 
 ```json
 {
@@ -354,33 +349,29 @@ Core 只保留通用选择项：
 }
 ```
 
-这个 schema 会持久化到 `data/config/<plugin_name>_config.json`，并在插件实例化时作为 `config` 传入。
+AstrBot 会把用户保存的值写到 `data/config/<plugin_name>_config.json`，并在插件实例化时作为 `config` 传入。
 
-如果 provider 需要从 `provider_settings.sandbox` 读取会话级或历史兼容覆盖项，请在 `build_create_config()` 中把它们作为插件配置之上的 override 处理。不要把 runtime 专属字段新增到 core 的配置 metadata 中。
+如果 provider 还需要兼容旧的 `provider_settings.sandbox` 配置，可以在 `build_create_config()` 中把它们作为插件配置之上的 override。新的 provider 配置通常放在 `_conf_schema.json` 即可。
 
-### 4. 通过 `tool_names` 暴露可选 runtime 工具
+### 4. 添加可选工具
 
-如果你的 runtime 除了通用 shell/python/filesystem 外，还提供额外工具，请在插件里注册这些工具，并把工具名放到 `tool_names` 中。
+如果你的 runtime 除了 shell/python/filesystem 外还提供其他能力，在插件里注册对应工具，并把工具名写进 `provider.tool_names`。
 
-常见例子：
+常见工具包括：
 
 - 截图工具
 - 鼠标 / 键盘工具
 - 浏览器工具
 - runtime 专属生命周期工具
 
-Core 会根据 `tool_names` 自动在 sandbox mode 下挂载这些工具，因此不要在 core 中硬编码 provider 名称。
-
-### 5. 让 runtime 代码留在插件里，不回流 core
-
-制作沙盒插件时，请遵循下面这条边界：
+AstrBot 在 sandbox mode 下挂载工具时会读取 `tool_names`。这里的名字要和 `main.py` 中注册的工具名一致。
 
-- 具体 runtime SDK import 放在插件仓库
-- provider 默认值和 schema 放在插件仓库
-- runtime 专属工具放在插件仓库
-- AstrBot Core 只负责通用注册、生命周期、持久化，以及 dashboard/API 表面
+### 5. 本地试跑
 
-如果不确定某段逻辑该放在 core 还是插件里，可以用这个经验规则：
+把插件放到 `data/plugins/<plugin_name>/` 后，启动 AstrBot，重点检查这些点：
 
-- 通用行为 -> core
-- 具体 runtime 行为 -> plugin
+- 插件加载时没有 import error。
+- WebUI 配置页能看到 `_conf_schema.json` 里的字段。
+- 沙盒 runtime 选择项里能看到你的 `provider_id`。
+- 创建沙盒时会调用 `create_booter()`。
+- 停止或卸载插件时会调用 `terminate()` 并注销 provider。