miao-plugin for Yunzai-Bot: Installation, Panels, and Update Constraints

Why miao-plugin belongs inside Yunzai-Bot

miao-plugin is a JavaScript extension for Yunzai-Bot, not a bot framework of its own. It targets administrators and users of Yunzai V2 or V3 who want game-character information exposed through chat commands. Its documented feature set includes character panels, character queries, damage calculation, and artifact scoring. The plugin also provides a command for updating itself and a settings command for changing its behavior.

The intended interaction happens inside the chat environment managed by Yunzai-Bot. After installation, a user can send `#喵喵帮助` to see the available plugin commands, while an administrator can send `#喵喵设置` to manage settings. Character-panel users can start with `#面板帮助`, which the README identifies as the source for detailed usage instructions. This command-oriented design makes the plugin most suitable for an existing Yunzai deployment rather than a server-independent dashboard.

The repository layout supports that interpretation. It contains `index.js`, `apps/`, `components/`, `models/`, `config/`, `resources/`, and `tools/`, while `package.json` defines internal imports for component, model, and path utilities. The package metadata identifies version 2.3.3 and uses ES modules through `"type": "module"`. This is an extension organized around an existing bot runtime, not a packaged service with its own process or web interface documented in the README.

Panel, damage, and artifact data paths

The character-panel feature has an important external dependency. The command `#更新面板` retrieves panel data through a panel query API, and the README identifies Enka at `http://enka.network/` as the documented service. It also states that the query function is authorized by Enka. This means the plugin is not documented as generating the complete panel from its own repository. Character-panel freshness and availability can therefore depend on the selected external service.

A documented alternative service is `MiniGG-Api`. The command below changes panel queries for the China server and Bilibili server so that they are handled by `MiniGG-Api`:

#喵喵设置面板服务332

The plugin exposes a service selection rather than requiring every deployment to use the same upstream. However, the README does not explain `MiniGG-Api` architecture, availability guarantees, rate limits, or failover behavior. It is a configurable provider, not evidence that panel queries continue when both services are unavailable.

Damage calculation follows a different path. The README states that the character panel's damage calculation is performed locally by miao-plugin. If the displayed result appears incorrect, `#雷神伤害` exposes the damage bonus information used by the calculation. The project asks for a recording and UID when reporting an apparent error. That distinction matters operationally: panel retrieval relies on an API, while damage computation is described as local. Artifact scoring is also local in the sense that the README says it uses a Miao-specific scoring rule, but the rule itself is not included in the README.

Git installation and the first Yunzai commands

The README recommends installation with Git because that preserves the remote configuration needed by `#喵喵更新`. Run one of the following command pairs from the Yunzai-Bot root directory. The GitCode variant points the plugin's `origin` remote at GitCode, while the GitHub variant uses the repository named in this review:

git clone --depth=1 https://github.com/yoimiya-kokomi/miao-plugin plugins/miao-plugin
pnpm install -P

The GitCode command is also documented, but the repository page points to GitHub and GitCode as separate sources:

git clone --depth=1 https://gitcode.com/TimeRainStarSky/miao-plugin.git plugins/miao-plugin
pnpm install -P

After the files are placed in the `plugins` directory, restart Yunzai-Bot. In the chat interface, send `#喵喵帮助` to view commands and `#面板帮助` to learn how to use the character-panel feature. The README does not publish expected startup output or a sample generated panel, so acceptance should be based on those documented commands being available after the restart.

The installation uses `pnpm`, although `package.json` does not declare a `packageManager` field. Its only two runtime dependencies are `cheerio` and `image-size`, while `request` is listed under `devDependencies`. There are no package scripts in `package.json`, so installation should not be presented as requiring an undocumented build or test command.

Remote sources, bot-managed updates, and upgrade cost

The clone command with `--depth=1` reduces the initial Git history, but it retains the configured `origin` remote that the update workflow needs. Once installed through Git, an administrator can send `#喵喵更新` in chat. The README does not show the implementation of that command, its conflict policy, or whether it handles local modifications. The repository has no GitHub releases, so Git history and `CHANGELOG.md` are the documented update references rather than a versioned release artifact.

The README says the Gitee source cannot currently be used and supplies commands for changing `origin` to GitCode or GitHub. Apply the command matching the remote already used by the installation:

git -C plugins/miao-plugin remote set-url origin https://github.com/yoimiya-kokomi/miao-plugin

git -C plugins/miao-plugin remote set-url origin https://gitcode.com/TimeRainStarSky/miao-plugin.git

Manual installation is possible, but the README rejects it for update purposes. It requires downloading and extracting the archive, renaming `miao-plugin-master` to `miao-plugin`, and placing it in the Yunzai plugins directory. Without a usable Git checkout, `#喵喵更新` cannot provide the documented automatic update path. That makes manual deployment cheaper initially and more expensive for later maintenance.

The last push was on 2026-10-17, but the repository has no GitHub releases. The README does not define a release cadence, support policy, migration process, or version compatibility matrix. `CHANGELOG.md` is the first place named by the project for detailed change information, so upgrade review cannot be reduced to checking whether the latest Git commit installed successfully.

Yunzai fork and QQ adapter constraints

miao-plugin declares support for Yunzai-Bot V2 and V3, but that broad statement does not make every Yunzai distribution interchangeable. The README lists Miao-Yunzai, a Miao-maintained Yunzai V3 using `icqq`, and another Yunzai V3 using `oicq`. It characterizes the latter as the Le-niao original and warns that login problems may occur. Users therefore need to check both the Yunzai branch and its QQ protocol adapter before adding this plugin.

Miao-Yunzai takes a different deployment approach from installing miao-plugin into an existing Yunzai root. The README says that Miao-Yunzai does not include check-in functionality, has more frequent iteration, and integrates with miao-plugin. It is recommended only for new deployments or migrations. This bundled distribution may reduce decisions for a new Miao-based setup, while the standalone plugin remains applicable to administrators who already operate one of the listed Yunzai variants.

The choice is not simply "modified versus original." Miao-Yunzai couples the bot and plugin within a particular distribution, while `miao-plugin` is copied into an existing `plugins` directory and inherits the runtime behavior of that installation. The README does not document a compatibility test matrix, automatic dependency checks between Yunzai versions, or recovery steps when a Yunzai update breaks plugin imports. Those checks belong in pre-deployment verification.

License scope and documentation gaps in miao-plugin

The repository declares the MIT license. The README also says that miao-plugin's own UI and code are open and may be used with attribution encouraged but not required. That README statement should not be treated as a blanket permission covering Yunzai-Bot, other plugins, network images, or game-related assets. Its disclaimer explicitly separates miao-plugin from Yunzai and other plugin authors, and says that images and other materials come from the internet for discussion and learning.

This creates two layers to review before redistribution. Code use is associated with the stated MIT license, while bundled resources may have separate provenance. The README does not provide a file-by-file inventory of image licenses, nor does it identify whether every generated asset ships in the repository. An engineer planning to modify and redistribute rendered output would need to inspect `resources/`, the applicable asset notices, and the terms of the services that provide data or imagery.

Documentation is also uneven by design. The README names `#喵喵帮助`, `#喵喵设置`, `#面板帮助`, `#更新面板`, `#雷神伤害`, and `#喵喵更新`, but it delegates most command syntax to chat help. It refers readers to `CHANGELOG.md` for more information and uses a playful phrase for the remaining documentation instead of publishing it. This is acceptable for a bot plugin whose help menu is part of its interface, but it makes repository documentation insufficient for previewing every command, setting, permission, or error condition.

Practical limits of panel data and local calculations

The clearest failure boundary is external panel availability. `#更新面板` depends on a panel query API, and the default documented source is Enka. The optional `MiniGG-Api` setting changes the upstream for the China and Bilibili servers, but the README provides no health check, cache behavior, retry policy, or guarantee that both paths cover identical fields. A deployment that requires deterministic, offline panel refresh does not match the documented design.

Local damage calculation avoids that dependency for the calculation itself, but it does not eliminate input or formula concerns. The README treats discrepancies as feedback cases and asks for a damage recording and UID. It does not state the supported characters, game version, parameter sources, or precision rules. For that reason, a value shown by `#雷神伤害` should not be treated as independently verified game output based only on this repository documentation.

Artifact scoring is similarly bounded by the implementation. The README confirms that `#雷神圣遗物` uses a Miao scoring rule, but it does not reproduce the weights or version history. Users who need an official scoring methodology have to inspect the implementation or request clarification from the project. The plugin is best suited to chat-driven exploration of character data, not compliance workflows that require a documented, version-pinned scoring specification.

Editorial conclusion

Adopt miao-plugin if you operate Yunzai-Bot V2 or V3 and want character panels, local damage calculation, and plugin-managed Git updates through commands such as #喵喵更新. Do not choose it if you need a standalone application or cannot accept dependence on Yunzai, external panel APIs, image services, and community-maintained sources. Before deployment, verify compatibility with the exact Yunzai fork and QQ adapter, confirm access to the intended panel service, and inspect CHANGELOG.md because the README leaves much of the detailed behavior outside its documentation.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. yoimiya-kokomi/miao-plugin on GitHub