fix: detect desktop runtime without frozen python

[zouyonghe]

Summary

• treat ASTRBOT_DESKTOP_CLIENT=1 as the desktop backend runtime signal even when Python is not frozen
• restore desktop plugin installs to use data/site-packages and keep desktop root resolution aligned with the launcher contract
• add regression tests for runtime detection, explicit ASTRBOT_ROOT override, and PipInstaller target-site-packages behavior

Test Plan

• .venv/bin/python -m pytest tests/test_runtime_env.py tests/test_pip_installer.py tests/test_dashboard.py -q
• .venv/bin/ruff check astrbot/core/utils/runtime_env.py tests/test_runtime_env.py tests/test_pip_installer.py

Summary by Sourcery

将 ASTRBOT_DESKTOP_CLIENT 环境变量视为桌面后端运行时的规范信号，并围绕桌面插件安装和根路径解析添加回归覆盖和文档说明。

Bug 修复：

• 仅基于 ASTRBOT_DESKTOP_CLIENT=1 来检测打包后的桌面运行时，使桌面行为不再依赖 Python 是否被冻结（frozen）。

文档：

• 添加设计和实现方案文档，描述 Linux 桌面插件安装行为以及更新后的桌面运行时检测约定。

测试：

• 添加桌面运行时检测的回归测试、在显式设置与未设置 ASTRBOT_ROOT 两种情况下的 AstrBot 根路径解析测试，以及 PipInstaller 行为测试，以确保桌面安装目标为 data/site-packages 目录。

Original summary in English

Summary by Sourcery

Treat the ASTRBOT_DESKTOP_CLIENT environment variable as the canonical signal for desktop backend runtime and add regression coverage and documentation around desktop plugin installs and root resolution.

Bug Fixes:

• Detect packaged desktop runtime based solely on ASTRBOT_DESKTOP_CLIENT=1 so desktop behavior no longer depends on Python being frozen.

Documentation:

• Add design and implementation plan documents describing Linux desktop plugin install behavior and the updated desktop runtime detection contract.

Tests:

• Add regression tests for desktop runtime detection, AstrBot root resolution with and without explicit ASTRBOT_ROOT, and PipInstaller behavior to ensure desktop installs target the data/site-packages directory.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines AstrBot's desktop backend runtime detection to ensure that plugin installations and root path resolutions behave correctly, even when Python is not frozen. By simplifying the is_packaged_desktop_runtime logic to depend only on the ASTRBOT_DESKTOP_CLIENT environment variable, it resolves an issue where Linux desktop plugin installs were not using the designated data/site-packages path. The changes are supported by new regression tests to validate the updated runtime detection and installer behavior.

Highlights

• Desktop Runtime Detection Improved: The is_packaged_desktop_runtime function no longer requires Python to be frozen, now relying solely on the ASTRBOT_DESKTOP_CLIENT environment variable.
• Plugin Installation Alignment: Desktop plugin installations will now correctly use the data/site-packages path, aligning with the launcher contract and ensuring proper dependency management.
• Comprehensive Regression Tests: New tests were added to cover runtime detection, explicit ASTRBOT_ROOT overrides, and PipInstaller's target-site-packages behavior.

Changelog

• astrbot/core/utils/runtime_env.py
  • Modified is_packaged_desktop_runtime to remove the is_frozen_runtime() check.
• docs/plans/2026-03-07-linux-desktop-plugin-install-design.md
  • Added a design document outlining the context, decision, scope, non-goals, risks, mitigations, and validation for improving Linux desktop plugin installation.
• docs/plans/2026-03-07-linux-desktop-plugin-install.md
  • Added a detailed implementation plan with step-by-step instructions for adding runtime detection and plugin installer regression coverage, and verifying root-path behavior.
• tests/test_pip_installer.py
  • Added test_install_targets_site_packages_for_desktop_client to verify PipInstaller uses --target site-packages in desktop environments.
• tests/test_runtime_env.py
  • Added test_desktop_client_env_marks_desktop_runtime_without_frozen to confirm desktop runtime detection without sys.frozen.
  • Added test_desktop_client_uses_home_root_without_explicit_astrbot_root to test default ASTRBOT_ROOT behavior.
  • Added test_explicit_astrbot_root_overrides_desktop_default to verify ASTRBOT_ROOT override functionality.

Activity

• A design document (docs/plans/2026-03-07-linux-desktop-plugin-install-design.md) was created to detail the problem, proposed solution, and scope.
• A comprehensive implementation plan (docs/plans/2026-03-07-linux-desktop-plugin-install.md) was added, outlining a test-driven development approach with specific steps for writing failing tests, implementing minimal changes, and verifying results.
• The pull request description includes a test plan, indicating that the author has performed local validation using pytest and ruff.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[sourcery-ai]

Hey - 我已经审查了你的更改，一切看起来都很棒！

---

Sourcery 对开源项目是免费的——如果你喜欢我们的代码审查，请考虑分享给更多人 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据你的反馈来改进后续的代码审查。}

Original comment in English

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request correctly adjusts the desktop runtime detection to be independent of whether the Python interpreter is frozen. This is achieved by making is_packaged_desktop_runtime rely solely on the ASTRBOT_DESKTOP_CLIENT environment variable. The change is well-supported by comprehensive regression tests for runtime detection, PipInstaller behavior, and root path resolution. The inclusion of design and implementation plan documents is also a good practice. I have one minor suggestion regarding a leftover instruction in one of the documentation files.

[gemini-code-assist]

This line appears to be a leftover instruction for an AI assistant. It should be removed to keep the documentation clean and focused for developers.