pixi-vn-ink-hashtag-commands

用途

该技能面向 Pixi'VN 与 ink 结合的项目：当 ink 脚本需要执行原生 ink 无法表达的、与项目自身应用代码绑定的自定义行为（如页面导航、成就或标志检查等）时，应将其编写为 HashtagCommands 处理器，而不是 ink 函数。

在 Pixi'VN 中，ink 函数（=== function name(...) === / ~ return ...）虽然能被 ink 编译器正常编译，但会被 Pixi'VN 静默忽略：调用它不会做任何事，也不会返回任何值，并且没有警告提示。

与普通 ink 标签的区别

原生 ink 的 # 是通用标签系统，ink 本身不赋予其含义，游戏可以自行读取解释或完全忽略。Pixi'VN 的 ink 并非如此：它运行的是真正的命令到操作的派发系统。每条 # 行会被分词为字符串数组（如 ["show", "image", "bg", ...]），并与所有已注册处理器的校验规则匹配；若无匹配，Vite 开发服务器会将其记录为未知井号命令。也就是说，一条 # 行要么是经过识别且带类型检查的具体命令，要么是应被报告的错误。

为何不用 ink 函数

从 ink 中调用的函数不能有可选参数，每次调用都必须传入所有参数；而井号命令的校验 schema 可以直接表达可选或变体参数形态。
井号命令可内省：HashtagCommands.info()（以及 Vite 开发服务器的 GET /__pixi-vn-ink/hashtag-commands 端点）会列出每个已注册命令的名称、描述与校验规则。
与开发期检查集成：未识别的 # 行，或对象形参数（如 edit 的 properties）不符合其 schema 时，会在保存时以 file:line 形式警告；普通 JS 函数没有此类检查。

HashtagCommands.add：通用拦截

通过 add(handler, options) 注册一个在步骤执行前运行的中间件。处理器接收分词后的命令（script: string[]）、当前步骤的 StepLabelProps，以及用于解析键值尾部参数的 convertListStringToObj 辅助函数。返回值语义：

返回 true：命令被完全处理，该行不再执行后续逻辑；
返回字符串：该字符串会被重新解释为新的井号命令（链式调用）；
返回假值：交由下一个已注册处理器（或内置命令表）尝试。

自定义处理器在内置命令之前运行，按注册的逆序检查（最后添加的先检查）。validation 决定处理器能看到哪些命令：可为针对拼接 token 测试的 RegExp，或校验解析后 token 数组的 Zod schema（zod.tuple([...])，zod.literal 锁定精确 token，通常为命令名，zod.string/zod.enum 接受参数）。需自行安装 zod（对等依赖，不随包捆绑）。

HashtagCommands.addMapper：声明式写法

当命令的职责是“把 token 转换为 PixiVNJsonOperation（或直接修改当前步骤）”而非执行任意副作用代码时，addMapper(handler, options) 是更清晰的选择——所有内置命令（# show、# play sound、# load 等）均以它实现。Mapper 按注册顺序在内置 switch 表之前运行，因此项目可通过注册校验规则重叠的 mapper 来覆盖或扩展内置命令行为。默认优先使用 addMapper；仅当命令需要拦截/短路流水线、链接到另一命令，或执行无法归约为单个操作对象的、依赖 StepLabelProps 的任意副作用时，才使用 add。

addBaseHashtagCommands：内置命令库

pixi-vn-ink-canvas、-sound、-assets、-pause-continue（以及 -input 的 # request input）中记录的每条命令本身都通过 addMapper 注册，分为四个可开关的分组：canvas、sound、narration（含 # call/jump（已弃用）、# pause、# continue、# request input）、assets，默认均开启。传入 bundleIds 与 assetAliasIds 可为 # load bundle <alias> 和 # load assets <alias> 启用严格校验。应在应用启动早期、解析任何 ink 内容之前调用一次；导入包本身不会产生副作用。仅当项目为整组命令注册了自己的替代实现（否则会与内置命令冲突），或确实不需要该组并希望拼写错误被报告为完全未知命令时，才将对应分节设为 false。# call/# jump 已弃用，应改用原生 ink 的 -> 与 -> ->。

检查已注册命令

HashtagCommands.info() 返回每个已注册处理器的 { name, description, validation, ... }，与 Vite 开发服务器 GET /__pixi-vn-ink/hashtag-commands 端点提供的内容一致，可用于查询命令是否存在及其期望的参数形态。

技能介绍

用途