nonebot-plugin-lingchu-bot 0.9.0.dev1__tar.gz → 0.10.0.dev1__tar.gz

{nonebot_plugin_lingchu_bot-0.9.0.dev1 → nonebot_plugin_lingchu_bot-0.10.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nonebot-plugin-lingchu-bot
-Version: 0.9.0.dev1
+Version: 0.10.0.dev1
 Summary: 由NoneBot2驱动，面向多平台的管理机器人
 Keywords: nonebot2,nonebot,bot,cross-platform,group-management
 Author: xinvxueyuan
@@ -72,29 +72,20 @@ Description-Content-Type: text/markdown
 
 [![DeepWiki Q&A][deepwiki-shield]][deepwiki-link]
 
-## Project status
+> **A qbot plugin** · Host repository: [xinvxueyuan/qbot](https://github.com/xinvxueyuan/qbot)
 
 Lingchu Bot has published its first `0.0.1` formal release. The project is still early and may make breaking changes before `1.0.0`, but the current release is intended to be installable, documented, and reproducible through the release workflow.
 
 Useful entry points:
 
 - [Online documentation](https://lingchu.zone.id/)
-- [User guide overview](apps/docs/src/content/docs/user-guide/overview.mdx)
-- [Quick start](apps/docs/src/content/docs/user-guide/quick-start.mdx)
-- [QQ command reference](apps/docs/src/content/docs/platforms/qq/command-reference.mdx)
-- [Architecture guide](apps/docs/src/content/docs/developer-guide/architecture/introduction.mdx)
+- [User guide overview](apps/docs/src/content/docs/explanation/overview.mdx)
+- [Quick start](apps/docs/src/content/docs/tutorials/getting-started.mdx)
+- [QQ command reference](apps/docs/src/content/docs/reference/commands.mdx)
+- [Architecture guide](apps/docs/src/content/docs/explanation/architecture/introduction.mdx)
 - [Contributing guide](CONTRIBUTING.md)
 
-## What is in this repository
-
-- `nonebot-plugin-lingchu-bot`: the Python package declared in `pyproject.toml`.
-- `src/plugins/nonebot_plugin_lingchu_bot`: the core NoneBot plugin, including metadata, startup hooks, platform registry, command handlers, permissions, i18n, repositories, and storage helpers.
-- `[tool.nonebot]` in `pyproject.toml`: local plugin loading configuration, installed adapter declarations, and dependency plugin declarations.
-- `apps/docs`: the Astro / Starlight documentation site, with Chinese and English content.
-- `Dockerfile` / `docker-compose.yml`: container runtime flow. The image generates `/tmp/bot.py` during build through `nb-cli`; the repository root does not ship a committed local `bot.py`.
-- `scripts/setup.sh`: cross-platform initialization script for local development.
-
-## Capabilities
+## Features
 
 | Capability | Description |
 | --- | --- |
@@ -112,7 +103,7 @@ Useful entry points:
 
 Future cross-platform and non-group-management features depend on later implementation and tests.
 
-## Adapter support
+### Adapter support
 
 The currently implemented platform profile is **QQ**, and the only active adapter is **OneBot V11**:
 
@@ -126,7 +117,7 @@ Only OneBot V11 is implemented. Configuring any other adapter ID (such as `~milk
 
 OneBot V11 currently has `default` and `NapCat` implementation paths. Some features are implementation-gated: for example, group announcement and group avatar entries are shown only when the selected implementation supports them, and remote announcement requires `NapCat.Onebot >= 4.18.0`.
 
-## Quick start
+## Installation
 
 ### Requirements
 
@@ -174,6 +165,8 @@ To load Lingchu Bot from an existing NoneBot project, point `plugin_dirs` at the
 plugin_dirs = ["path/to/lingchu-bot/src/plugins"]
 ```
 
+The [qbot](https://github.com/xinvxueyuan/qbot) host consumes this repository as the `vendor/lingchu-bot` git submodule pinned to a specific commit, and loads it through `plugin_dirs = ["vendor/lingchu-bot/src/plugins"]`.
+
 ### Option C — Run in Docker
 
 ```bash
@@ -202,6 +195,7 @@ Online-editable command, menu-trigger, and platform-permission overrides are sto
 | Lingchu Runtime | `LINGCHU_SUPERUSERS` | UID-to-platform account mapping for Lingchu superusers. |
 | Lingchu Runtime | `LINGCHU_LOCALE` | Runtime locale; available catalogs are `zh_CN` and `en_US`. |
 | Lingchu Runtime | `LINGCHU_SUPERUSER_KEY` | Superuser key string (`superuser_key`). |
+| WebUI | `LINGCHU_WEBUI_PASSWORD` | Password for the read-only WebUI endpoints; empty disables authentication. |
 | Localstore | `LOCALSTORE_USE_CWD` | Store localstore data / config / cache under the project directory when true. |
 | Message Store | `LINGCHU_MESSAGE_STORE_ENABLED` | Enable message-store runtime hooks. |
 | Message Store | `LINGCHU_MESSAGE_STORE_RETENTION_DAYS` | Retention window for message records; `0` disables day-based expiry. |
@@ -210,7 +204,7 @@ Online-editable command, menu-trigger, and platform-permission overrides are sto
 | Message Store | `LINGCHU_MESSAGE_STORE_CLEANUP_ENABLED` | Enable expired message cleanup. |
 | Recall | `LINGCHU_RECALL_MESSAGE_DEFAULT_COUNT` | Default count for the message recall command (`1`–`100`). |
 | Protected Subjects | `LINGCHU_PROTECTED_SUBJECT_FEATURE_KEYS` | Side-effect command keys blocked when their target user is protected. |
-| Database | `SQLALCHEMY_DATABASE_URL` | SQLAlchemy database URL; supports SQLite / PostgreSQL / MySQL / MariaDB / Oracle / SQL Server. Unset uses default SQLite. |
+| Database | `SQLALCHEMY_DATABASE_URL` | SQLAlchemy database URL; supports SQLite / PostgreSQL / MySQL / MariaDB. Unset uses default SQLite. |
 | Database | `ALEMBIC_STARTUP_CHECK` | Set to `true` in production to enforce schema migration checks on startup. |
 
 Example `runtime-overrides.toml`:
@@ -231,7 +225,7 @@ Runtime settings are read from the localstore-owned `runtime-overrides.toml` fil
 Deployment settings remain in NoneBot environment configuration; there is no
 project-specific configuration CLI or generated schema step.
 
-## Commands at a glance
+## Usage & Commands
 
 Main menu:
 
@@ -267,12 +261,23 @@ silence / speak
 boot / shutdown
 ```
 
-Command trigger language is locale-exclusive. Chinese locales enable Chinese triggers; English locales enable short hyphenated English triggers. They are not enabled at the same time. Full command behavior, permission pre-checks, implementation filters, and remote management details are documented in [QQ Commands](apps/docs/src/content/docs/platforms/qq/command-reference.mdx).
+Command trigger language is locale-exclusive. Chinese locales enable Chinese triggers; English locales enable short hyphenated English triggers. They are not enabled at the same time. Full command behavior, permission pre-checks, implementation filters, and remote management details are documented in [QQ Commands](apps/docs/src/content/docs/reference/commands.mdx).
 
-## Development and verification
+## Development & Testing
 
 CI checks Ruff, Markdown, Pyright, ty, pytest on multiple database backends, and docs site lint / test. Run the checks relevant to your change before committing.
 
+### Repository layout
+
+- `nonebot-plugin-lingchu-bot`: the Python package declared in `pyproject.toml`.
+- `src/plugins/nonebot_plugin_lingchu_bot`: the core NoneBot plugin, including metadata, startup hooks, platform registry, command handlers, permissions, i18n, repositories, and storage helpers.
+- `[tool.nonebot]` in `pyproject.toml`: local plugin loading configuration, installed adapter declarations, and dependency plugin declarations.
+- `apps/docs`: the Astro / Starlight documentation site, with Chinese and English content.
+- `Dockerfile` / `docker-compose.yml`: container runtime flow. The image generates `/tmp/bot.py` during build through `nb-cli`; the repository root does not ship a committed local `bot.py`.
+- `scripts/setup.sh`: cross-platform initialization script for local development.
+
+### Local checks
+
 Ruff:
 
 ```bash
@@ -318,13 +323,15 @@ Markdown:
 pnpm exec markdownlint-cli2 README.md README-zh.md
 ```
 
-## Contributing
+### Contributing
 
 Issues, tests, documentation, and code improvements are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before starting; it describes the current collaboration workflow, GitNexus impact analysis requirements, version validation system, and PR checklist.
 
 When participating in discussions and reviews, please follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). For security-related issues, please refer to [SECURITY.md](SECURITY.md).
 
-## License
+## License & Related repositories
+
+### License
 
 This project uses a **phased open-source license stack** (see
 [Repository-Policy.md](Repository-Policy.md) for the transition rules
@@ -352,7 +359,15 @@ For media file handling, sanitization requirements, REUSE compliance,
 and the official license texts, see [Repository-Policy.md](Repository-Policy.md)
 and the [`LICENSE-*`](LICENSE-code) files in the repository root.
 
-## Acknowledgments
+### Related repositories
+
+Lingchu Bot is one plugin of the [qbot](https://github.com/xinvxueyuan/qbot) ecosystem; these repositories are the ones it actually interacts with:
+
+- [xinvxueyuan/qbot](https://github.com/xinvxueyuan/qbot) — the NoneBot2 host that loads this repository as the `vendor/lingchu-bot` submodule.
+- [xinvxueyuan/nonebot-plugin-info](https://github.com/xinvxueyuan/nonebot-plugin-info) — the menu plugin that renders each plugin's `__plugin_meta__.extra`; Lingchu publishes its menu type, order, and command list there.
+- [xinvxueyuan/nonebot-plugin-llbot-alert](https://github.com/xinvxueyuan/nonebot-plugin-llbot-alert) — watches the LLBot / OneBot V11 connection Lingchu Bot runs on, and mails on heartbeat or disconnect failures.
+
+### Acknowledgments
 
 Lingchu Bot stands on a lot of good open-source shoulders. Thanks especially to these upstream projects and communities:
 
@@ -363,7 +378,7 @@ Lingchu Bot stands on a lot of good open-source shoulders. Thanks especially to
 
 For complete dependency lists, please refer to [pyproject.toml](pyproject.toml), [package.json](package.json), [apps/docs/package.json](apps/docs/package.json), and [uv.lock](uv.lock).
 
-## License compliance
+### License compliance
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fxinvxueyuan%2Flingchu-bot.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fxinvxueyuan%2Flingchu-bot?ref=badge_large)
 

{nonebot_plugin_lingchu_bot-0.9.0.dev1 → nonebot_plugin_lingchu_bot-0.10.0.dev1}/README.md

@@ -20,29 +20,20 @@
 
 [![DeepWiki Q&A][deepwiki-shield]][deepwiki-link]
 
-## Project status
+> **A qbot plugin** · Host repository: [xinvxueyuan/qbot](https://github.com/xinvxueyuan/qbot)
 
 Lingchu Bot has published its first `0.0.1` formal release. The project is still early and may make breaking changes before `1.0.0`, but the current release is intended to be installable, documented, and reproducible through the release workflow.
 
 Useful entry points:
 
 - [Online documentation](https://lingchu.zone.id/)
-- [User guide overview](apps/docs/src/content/docs/user-guide/overview.mdx)
-- [Quick start](apps/docs/src/content/docs/user-guide/quick-start.mdx)
-- [QQ command reference](apps/docs/src/content/docs/platforms/qq/command-reference.mdx)
-- [Architecture guide](apps/docs/src/content/docs/developer-guide/architecture/introduction.mdx)
+- [User guide overview](apps/docs/src/content/docs/explanation/overview.mdx)
+- [Quick start](apps/docs/src/content/docs/tutorials/getting-started.mdx)
+- [QQ command reference](apps/docs/src/content/docs/reference/commands.mdx)
+- [Architecture guide](apps/docs/src/content/docs/explanation/architecture/introduction.mdx)
 - [Contributing guide](CONTRIBUTING.md)
 
-## What is in this repository
-
-- `nonebot-plugin-lingchu-bot`: the Python package declared in `pyproject.toml`.
-- `src/plugins/nonebot_plugin_lingchu_bot`: the core NoneBot plugin, including metadata, startup hooks, platform registry, command handlers, permissions, i18n, repositories, and storage helpers.
-- `[tool.nonebot]` in `pyproject.toml`: local plugin loading configuration, installed adapter declarations, and dependency plugin declarations.
-- `apps/docs`: the Astro / Starlight documentation site, with Chinese and English content.
-- `Dockerfile` / `docker-compose.yml`: container runtime flow. The image generates `/tmp/bot.py` during build through `nb-cli`; the repository root does not ship a committed local `bot.py`.
-- `scripts/setup.sh`: cross-platform initialization script for local development.
-
-## Capabilities
+## Features
 
 | Capability | Description |
 | --- | --- |
@@ -60,7 +51,7 @@ Useful entry points:
 
 Future cross-platform and non-group-management features depend on later implementation and tests.
 
-## Adapter support
+### Adapter support
 
 The currently implemented platform profile is **QQ**, and the only active adapter is **OneBot V11**:
 
@@ -74,7 +65,7 @@ Only OneBot V11 is implemented. Configuring any other adapter ID (such as `~milk
 
 OneBot V11 currently has `default` and `NapCat` implementation paths. Some features are implementation-gated: for example, group announcement and group avatar entries are shown only when the selected implementation supports them, and remote announcement requires `NapCat.Onebot >= 4.18.0`.
 
-## Quick start
+## Installation
 
 ### Requirements
 
@@ -122,6 +113,8 @@ To load Lingchu Bot from an existing NoneBot project, point `plugin_dirs` at the
 plugin_dirs = ["path/to/lingchu-bot/src/plugins"]
 ```
 
+The [qbot](https://github.com/xinvxueyuan/qbot) host consumes this repository as the `vendor/lingchu-bot` git submodule pinned to a specific commit, and loads it through `plugin_dirs = ["vendor/lingchu-bot/src/plugins"]`.
+
 ### Option C — Run in Docker
 
 ```bash
@@ -150,6 +143,7 @@ Online-editable command, menu-trigger, and platform-permission overrides are sto
 | Lingchu Runtime | `LINGCHU_SUPERUSERS` | UID-to-platform account mapping for Lingchu superusers. |
 | Lingchu Runtime | `LINGCHU_LOCALE` | Runtime locale; available catalogs are `zh_CN` and `en_US`. |
 | Lingchu Runtime | `LINGCHU_SUPERUSER_KEY` | Superuser key string (`superuser_key`). |
+| WebUI | `LINGCHU_WEBUI_PASSWORD` | Password for the read-only WebUI endpoints; empty disables authentication. |
 | Localstore | `LOCALSTORE_USE_CWD` | Store localstore data / config / cache under the project directory when true. |
 | Message Store | `LINGCHU_MESSAGE_STORE_ENABLED` | Enable message-store runtime hooks. |
 | Message Store | `LINGCHU_MESSAGE_STORE_RETENTION_DAYS` | Retention window for message records; `0` disables day-based expiry. |
@@ -158,7 +152,7 @@ Online-editable command, menu-trigger, and platform-permission overrides are sto
 | Message Store | `LINGCHU_MESSAGE_STORE_CLEANUP_ENABLED` | Enable expired message cleanup. |
 | Recall | `LINGCHU_RECALL_MESSAGE_DEFAULT_COUNT` | Default count for the message recall command (`1`–`100`). |
 | Protected Subjects | `LINGCHU_PROTECTED_SUBJECT_FEATURE_KEYS` | Side-effect command keys blocked when their target user is protected. |
-| Database | `SQLALCHEMY_DATABASE_URL` | SQLAlchemy database URL; supports SQLite / PostgreSQL / MySQL / MariaDB / Oracle / SQL Server. Unset uses default SQLite. |
+| Database | `SQLALCHEMY_DATABASE_URL` | SQLAlchemy database URL; supports SQLite / PostgreSQL / MySQL / MariaDB. Unset uses default SQLite. |
 | Database | `ALEMBIC_STARTUP_CHECK` | Set to `true` in production to enforce schema migration checks on startup. |
 
 Example `runtime-overrides.toml`:
@@ -179,7 +173,7 @@ Runtime settings are read from the localstore-owned `runtime-overrides.toml` fil
 Deployment settings remain in NoneBot environment configuration; there is no
 project-specific configuration CLI or generated schema step.
 
-## Commands at a glance
+## Usage & Commands
 
 Main menu:
 
@@ -215,12 +209,23 @@ silence / speak
 boot / shutdown
 ```
 
-Command trigger language is locale-exclusive. Chinese locales enable Chinese triggers; English locales enable short hyphenated English triggers. They are not enabled at the same time. Full command behavior, permission pre-checks, implementation filters, and remote management details are documented in [QQ Commands](apps/docs/src/content/docs/platforms/qq/command-reference.mdx).
+Command trigger language is locale-exclusive. Chinese locales enable Chinese triggers; English locales enable short hyphenated English triggers. They are not enabled at the same time. Full command behavior, permission pre-checks, implementation filters, and remote management details are documented in [QQ Commands](apps/docs/src/content/docs/reference/commands.mdx).
 
-## Development and verification
+## Development & Testing
 
 CI checks Ruff, Markdown, Pyright, ty, pytest on multiple database backends, and docs site lint / test. Run the checks relevant to your change before committing.
 
+### Repository layout
+
+- `nonebot-plugin-lingchu-bot`: the Python package declared in `pyproject.toml`.
+- `src/plugins/nonebot_plugin_lingchu_bot`: the core NoneBot plugin, including metadata, startup hooks, platform registry, command handlers, permissions, i18n, repositories, and storage helpers.
+- `[tool.nonebot]` in `pyproject.toml`: local plugin loading configuration, installed adapter declarations, and dependency plugin declarations.
+- `apps/docs`: the Astro / Starlight documentation site, with Chinese and English content.
+- `Dockerfile` / `docker-compose.yml`: container runtime flow. The image generates `/tmp/bot.py` during build through `nb-cli`; the repository root does not ship a committed local `bot.py`.
+- `scripts/setup.sh`: cross-platform initialization script for local development.
+
+### Local checks
+
 Ruff:
 
 ```bash
@@ -266,13 +271,15 @@ Markdown:
 pnpm exec markdownlint-cli2 README.md README-zh.md
 ```
 
-## Contributing
+### Contributing
 
 Issues, tests, documentation, and code improvements are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before starting; it describes the current collaboration workflow, GitNexus impact analysis requirements, version validation system, and PR checklist.
 
 When participating in discussions and reviews, please follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). For security-related issues, please refer to [SECURITY.md](SECURITY.md).
 
-## License
+## License & Related repositories
+
+### License
 
 This project uses a **phased open-source license stack** (see
 [Repository-Policy.md](Repository-Policy.md) for the transition rules
@@ -300,7 +307,15 @@ For media file handling, sanitization requirements, REUSE compliance,
 and the official license texts, see [Repository-Policy.md](Repository-Policy.md)
 and the [`LICENSE-*`](LICENSE-code) files in the repository root.
 
-## Acknowledgments
+### Related repositories
+
+Lingchu Bot is one plugin of the [qbot](https://github.com/xinvxueyuan/qbot) ecosystem; these repositories are the ones it actually interacts with:
+
+- [xinvxueyuan/qbot](https://github.com/xinvxueyuan/qbot) — the NoneBot2 host that loads this repository as the `vendor/lingchu-bot` submodule.
+- [xinvxueyuan/nonebot-plugin-info](https://github.com/xinvxueyuan/nonebot-plugin-info) — the menu plugin that renders each plugin's `__plugin_meta__.extra`; Lingchu publishes its menu type, order, and command list there.
+- [xinvxueyuan/nonebot-plugin-llbot-alert](https://github.com/xinvxueyuan/nonebot-plugin-llbot-alert) — watches the LLBot / OneBot V11 connection Lingchu Bot runs on, and mails on heartbeat or disconnect failures.
+
+### Acknowledgments
 
 Lingchu Bot stands on a lot of good open-source shoulders. Thanks especially to these upstream projects and communities:
 
@@ -311,7 +326,7 @@ Lingchu Bot stands on a lot of good open-source shoulders. Thanks especially to
 
 For complete dependency lists, please refer to [pyproject.toml](pyproject.toml), [package.json](package.json), [apps/docs/package.json](apps/docs/package.json), and [uv.lock](uv.lock).
 
-## License compliance
+### License compliance
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fxinvxueyuan%2Flingchu-bot.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fxinvxueyuan%2Flingchu-bot?ref=badge_large)
 

{nonebot_plugin_lingchu_bot-0.9.0.dev1 → nonebot_plugin_lingchu_bot-0.10.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nonebot-plugin-lingchu-bot"
-version = "0.9.0.dev1"
+version = "0.10.0.dev1"
 description = "由NoneBot2驱动，面向多平台的管理机器人"
 keywords = [
     "nonebot2",
@@ -276,6 +276,7 @@ allowed-confusables = [
 "src/plugins/nonebot_plugin_lingchu_bot/core/subplugins/loader.py" = ["TC002"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/napcat/announcement.py" = ["ARG001"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/default/bot_state.py" = ["ARG001"]
+"src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/default/webui.py" = ["ARG001"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/default/announcement.py" = ["ARG001"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/default/mute.py" = ["ARG001"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/default/profile.py" = ["ARG001"]
@@ -408,6 +409,10 @@ allowed-confusables = [
     "E402",
     "TC002",
 ]
+"src/plugins/nonebot_plugin_lingchu_bot/handle/qq/commands/webui.py" = [
+    "E402",
+    "TC002",
+]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/commands/common.py" = [
     "E402",
     "TC002",

{nonebot_plugin_lingchu_bot-0.9.0.dev1 → nonebot_plugin_lingchu_bot-0.10.0.dev1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "nonebot-plugin-lingchu-bot"
-version = "0.9.0.dev1"
+version = "0.10.0.dev1"
 # dynamic = ["version"]
 description = "由NoneBot2驱动，面向多平台的管理机器人"
 keywords = ["nonebot2", "nonebot", "bot", "cross-platform", "group-management"]
@@ -303,6 +303,8 @@ allowed-confusables = [
 # ARG001: NoneBot handler signatures require bot/event params even when unused
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/napcat/announcement.py" = ["ARG001"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/default/bot_state.py" = ["ARG001"]
+# ARG001: WebUI 启动命令不依赖 bot/event 载荷，但 NoneBot 仍按签名注入。
+"src/plugins/nonebot_plugin_lingchu_bot/handle/qq/adapters/onebot11/default/webui.py" = ["ARG001"]
 # ARG001: session injected via Depends(async_scoped_session) for consistent DI shape
 # even when the handler does not currently issue DB queries (keeps handler signatures
 # uniform across the adapter and ready for future repository calls).
@@ -434,6 +436,7 @@ allowed-confusables = [
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/commands/announcement.py" = ["E402"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/commands/block.py" = ["E402", "TC002"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/commands/bot_state.py" = ["E402", "TC002"]
+"src/plugins/nonebot_plugin_lingchu_bot/handle/qq/commands/webui.py" = ["E402", "TC002"]
 "src/plugins/nonebot_plugin_lingchu_bot/handle/qq/commands/common.py" = [
     "E402",  # plugin imports must follow nonebot.require calls
     "TC002",  # NoneBot inspects Bot, Event, and ORM DI annotations at runtime

{nonebot_plugin_lingchu_bot-0.9.0.dev1 → nonebot_plugin_lingchu_bot-0.10.0.dev1}/src/plugins/nonebot_plugin_lingchu_bot/core/config.py

@@ -102,6 +102,55 @@ class UnexpectedInContainersTypeError(ConfigError):
         )
 
 
+def _coerce_positive_int(value: Any, *, fallback: int) -> int:
+    """把配置值转成正整数，非法时回退默认值。
+
+    `.env` 里的值一律是字符串，NoneBot 也不会替我们做 `int` 转换，
+    因此显式收口，避免 `LINGCHU_WEBUI_SESSION_TTL=abc` 在运行期变成死配置。
+
+    Args:
+        value: 原始配置值（str / int / None）。
+        fallback: 非法或非正数时的回退值。
+
+    Returns:
+        int: 正整数或回退值。
+
+    """
+    if isinstance(value, bool):
+        return fallback
+    if isinstance(value, int):
+        return value if value > 0 else fallback
+    if isinstance(value, str):
+        try:
+            parsed = int(value.strip())
+        except ValueError:
+            return fallback
+        return parsed if parsed > 0 else fallback
+    return fallback
+
+
+def _coerce_bool(value: Any) -> bool:
+    """把配置值转成布尔。
+
+    NoneBot 的 model_dump() 对未知键常保留字符串形态，因此统一接受
+    `true/1/yes/on` 这几种常见真值写法。
+
+    Args:
+        value: 原始配置值。
+
+    Returns:
+        bool: 解析结果；无法识别时视为 False。
+
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value != 0
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return False
+
+
 @dataclass(frozen=True, slots=True)
 class Config(DeploymentSettings):
     """lingchu-bot核心配置类。
@@ -115,7 +164,10 @@ class Config(DeploymentSettings):
         data_dir: 数据存储目录路径。
         config_dir: 配置文件存储目录路径。
         cache_dir: 缓存文件存储目录路径。
-        lingchu_webui_password: WebUI 只读端点的简易字符串密码（默认空，空则不鉴权）。
+        lingchu_webui_password: WebUI 登录口令（默认空，空则拒绝一切登录）。
+        lingchu_webui_base_path: WebUI 挂载前缀，默认 `/lc/webui`，可自定义。
+        lingchu_webui_session_ttl: WebUI 会话有效期（秒），默认 43200（12 小时）。
+        lingchu_webui_automount: 是否随 NoneBot 启动自动挂载 WebUI，默认 False。
         superuser_key: 运行时超级用户密钥。
         message_store_enabled: 是否启用消息存储。
         lingchu_superusers: 结构化超级用户平台账号绑定。
@@ -123,12 +175,15 @@ class Config(DeploymentSettings):
 
     """
 
-    core_version: str = "0.9.0.dev1"
+    core_version: str = "0.10.0.dev1"
     data_dir: Path = field(default_factory=get_plugin_data_dir)
     config_dir: Path = field(default_factory=get_plugin_config_dir)
     cache_dir: Path = field(default_factory=get_plugin_cache_dir)
     in_containers: bool = False
     lingchu_webui_password: str = ""
+    lingchu_webui_base_path: str = "/lc/webui"
+    lingchu_webui_session_ttl: int = 43200
+    lingchu_webui_automount: bool = False
 
     @classmethod
     def from_nonebot(cls) -> Config:
@@ -177,6 +232,34 @@ class Config(DeploymentSettings):
                     ),
                 )
             ),
+            lingchu_webui_base_path=str(
+                values.get(
+                    "LINGCHU_WEBUI_BASE_PATH",
+                    values.get(
+                        "lingchu_webui_base_path",
+                        os.environ.get("LINGCHU_WEBUI_BASE_PATH", "/lc/webui"),
+                    ),
+                )
+            ),
+            lingchu_webui_session_ttl=_coerce_positive_int(
+                values.get(
+                    "LINGCHU_WEBUI_SESSION_TTL",
+                    values.get(
+                        "lingchu_webui_session_ttl",
+                        os.environ.get("LINGCHU_WEBUI_SESSION_TTL", "43200"),
+                    ),
+                ),
+                fallback=43200,
+            ),
+            lingchu_webui_automount=_coerce_bool(
+                values.get(
+                    "LINGCHU_WEBUI_AUTOMOUNT",
+                    values.get(
+                        "lingchu_webui_automount",
+                        os.environ.get("LINGCHU_WEBUI_AUTOMOUNT", "false"),
+                    ),
+                )
+            ),
         )
 
     # --- 平台检测 Properties ---

{nonebot_plugin_lingchu_bot-0.9.0.dev1 → nonebot_plugin_lingchu_bot-0.10.0.dev1}/src/plugins/nonebot_plugin_lingchu_bot/core/handle_config_defaults/__init__.py

@@ -65,4 +65,8 @@ def register_handle_defaults(command_key: str, factory: HandleDefaultsFactory) -
     HANDLE_DEFAULTS_REGISTRY[command_key] = factory
 
 
-__all__ = ["HANDLE_DEFAULTS_REGISTRY", "register_handle_defaults"]
+# 各命令的默认值模块在导入时通过 register_handle_defaults() 自行注册；
+# 必须放在文件末尾，此时 register_handle_defaults 已定义、注册表已就绪。
+from . import webui as webui
+
+__all__ = ["HANDLE_DEFAULTS_REGISTRY", "register_handle_defaults", "webui"]

nonebot_plugin_lingchu_bot-0.10.0.dev1/src/plugins/nonebot_plugin_lingchu_bot/core/handle_config_defaults/webui.py

@@ -0,0 +1,24 @@
+"""「启动WebUI」handle 的默认配置。
+
+WebUI 由 NoneBot 同进程托管且挂载幂等，没有可调默认字段；这里注册一份空
+`defaults`，让 `HandleConfigManager` 能读写 `webui_start.toml`。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import register_handle_defaults
+
+
+def _webui_start_defaults() -> dict[str, Any]:
+    """返回「启动WebUI」的默认配置。
+
+    Returns:
+        dict[str, Any]: 启用状态、空默认值表与空策略表。
+
+    """
+    return {"enabled": True, "defaults": {}, "policies": {}}
+
+
+register_handle_defaults("webui_start", _webui_start_defaults)