pixi-vn-ink-migration

用途

本技能用于两类场景：一是将现有 @drincs/pixi-vn-ink 项目从某个版本升级到更新版本；二是开发者反馈在依赖升级后，原本可用的 ink 井号命令（例如 # show、# play sound 等）静默停止触发。技能提供按版本分段组织的迁移说明，帮助只处理项目实际跨越的版本边界，避免无关变更带来的干扰。

主要能力

技能覆盖的核心迁移内容是 v1.0.x → v1.1.0：

在 v1.1.0 之前，导入 @drincs/pixi-vn-ink 会以副作用方式自动注册所有内置井号命令（# show、# play sound、# load、# request input 等）。
自 v1.1.0 起，在显式调用前不会有任何命令被注册，需要在应用启动初期、解析任何 ink 内容之前调用一次：

import { addBaseHashtagCommands } from "@drincs/pixi-vn-ink";

addBaseHashtagCommands();

同一代版本中，addBaseHashtagCommands 新增了可选配置：bundleIds/assetAliasIds 用于对 # load/# lazyload 做严格校验，sections 用于选择退出某一整组内置命令；不传任何选项即保持 v1.1.0 之前注册全部内置命令的行为。

使用方式

先确认当前安装的版本：可查看 package.json 中的依赖版本，或在运行时通过 Vite 开发服务器的 GET /__pixi-vn-ink/info 端点返回的 version 字段获取。
仅按顺序阅读位于“已安装版本”与“目标版本”之间各版本段落，逐项处理对应的迁移事项。多数变更仅在项目跨过该特定版本边界时才适用。
升级后若内置 # 命令在运行时静默无反应，检查 Vite 开发服务器日志：它会将每个未识别的命令记录为未知井号命令，这是确认缺失 addBaseHashtagCommands 调用最快的方式。

适用场景

升级 @drincs/pixi-vn-ink 依赖版本。
依赖升级后原有 ink 命令失效的排查。
需要了解 addBaseHashtagCommands 新增可选配置（严格校验、分组开关）的迁移影响。

限制与说明

官方迁移文档位于 pixi-vn.com/faq/migration，同时涵盖独立的 @drincs/pixi-vn 与 nqtr 包；本技能仅覆盖其中 pixi-vn-ink 部分。
资料未提供除 v1.0.x → v1.1.0 之外其他版本段的具体迁移内容；实际升级时需以已安装版本与目标版本之间官方文档为准。
资料未说明该技能是否提供除迁移指导外的自动化工具或脚本。

技能介绍

用途

主要能力

使用方式

适用场景

限制与说明

相关技能