用途 该技能解决 ink 文本无法直接展示 JS/TS 计算结果的问题。原生 ink 用 {name} 只能注入 ink 变量，而 [key] 语法允许把任意函数的返回值或查表结果内联到文本中。官方文档地址为 pixi-vn.com/ink/replacement。
主要能力
- 使用方括号 [key] 作为替换占位符，例如：What do you want, [alice]?
- 使用反斜杠转义字面方括号，如 [bob]，避免被当作替换键；在选项文本中与原生 ink 的 [/] 选择语法并存时同样需要转义。
- 通过 TextReplaces.add(handler, options) 注册处理器。handler 接收方括号内的文本（不含括号），返回替换字符串；返回 undefined 则保留该处原文。
- validation 决定处理器对哪些键生效："all" 对所有 [key] 生效；"characterId" 仅当键是 RegisteredCharacters 中已注册的角色 id 时生效；RegExp 在键匹配时生效；ZodType<string> 在 schema.safeParse(key) 成功时生效。
- type 选项："before-translation" 在 onInkTranslate 之前运行，可先把键改写为 i18next 风格的 {{key}} 令牌；"after-translation"（默认）在翻译之后运行，适合依赖已翻译文本的替换。
- i18nInterpolation 为 true 时，匹配键的第二次及之后出现直接替换，首次出现改写为 {{key}}，以便翻译字符串中存在 i18next 插值槽位；需配合 i18n 配置中的 missingInterpolationHandler，让无翻译条目的键返回原始值而非空字符串。默认 false，每次出现都直接替换。
- 处理器按注册顺序执行，每个处理器作用于当前（可能已被修改的）文本，后注册者可看到前者的替换结果。
使用方式 示例代码： import { TextReplaces } from "@drincs/pixi-vn-ink";
TextReplaces.add(() => "Alice", { name: "Replace Alice", validation: /alice/, type: "after-translation", i18nInterpolation: true, description: "Replaces 'alice' with the character's name.", });
文本示例：Everyone just calls her Steph, but her full name is [steph_fullname].
调试时可通过 Vite 开发服务器 API（GET /__pixi-vn-ink/text-replaces）查看当前注册的所有 TextReplaces 处理器。
相关技能 pixi-vn-ink-characters 是该机制的常见具体用法（[characterId] 显示角色名，带验证）；pixi-vn-ink 说明翻译接线（onInkTranslate）。
适用场景与限制 适用于需要在 ink 对话中显示函数返回值、查表结果、翻译感知替换或角色名的场景。限制：原生 ink 的 {variable} 不能注入函数结果；字面方括号必须转义；替换逻辑需在 JS/TS 侧注册处理器。资料未提供收费、平台支持范围等其它信息。