把 ok-script 的语言、OCR、模板、技能和任务数据，直接搬进 VS Code 的开发流程。
Bring ok-script's language keys, OCR fixes, templates, skills and task data straight into your VS Code workflow.
语言键补全 · OCR 修正提示 · 模板浏览 · 任务启动 · 角色技能管理 Language key completion · OCR fix hints · Template browsing · Task launching · Character skill management
VS Code 扩展，为 ok-script 项目的 Python 开发提供语言键、OCR 修正、模板和技能效果的数据提示，同时内置模板浏览、任务启动和角色技能管理面板，让 ok-script 的语言、OCR、模板、技能和任务数据直接进入开发流程。
A VS Code extension that brings ok-script language keys, OCR fixes, templates, skill effects, and task data directly into your Python development workflow. It also includes built-in template browsing, task launching, and character skill management panels.
Tip
下面每个功能章节开头的演示图都是可点的——如果动图没加载出来，直接点开链接看。
| 方式 | 操作 |
|---|---|
| VS Code 内 | Ctrl+Shift+X 打开扩展视图，搜索 ok-script Toolkit，点 Install |
| 网页 | 打开 VS Code Marketplace 页面，点 Install |
| 命令行 | code --install-extension AliceJump.ok-script-toolkit |
需要 VS Code 1.85.0 或更高版本。安装后若提示不生效，见 更新后不生效。
PyCharm / IntelliJ IDEA 用户请装 JetBrains 版：ok-script Toolkit for JetBrains（Marketplace 页面）。
| 模块 | 一句话说明 |
|---|---|
| 代码开发辅助 | 在编辑器内补全和解释 self.lang、OCR 正则与技能效果 ID |
| 模板管理 | 网格浏览模板，单击插入 fL.<名称>，支持缩略图预览 |
| 临时截图 | 活动栏里的 10 张暂存区，框选即可复制归一化坐标 |
| 任务启动 | 从 config.py 自动生成参数表单并运行任务，全程不写目标项目配置 |
| 角色技能管理 | 角色 / 技能 / 效果 / 强化组的可视化管理与诊断 |
| 多语言支持 | 界面支持 6 种语言，数据提示跟随目标项目 |
在编辑 Python 代码时，扩展自动识别 ok-script 特有的 API 上下文，提供精准的数据提示和补全：
-
self.lang语言键 输入self.lang.补全语言模块和语言键，补全详情和行内幽灵注释显示当前语言的值（string类型用「值」、pattern类型用~值~标记），悬停可查看zh_CN、zh_TW、en_US、ja_JP、ko_KR、es_ES全部语言的值。 -
OCR 修正 在
ocr、wait_ocr、wait_click_ocr、find_boxes等函数的match参数处，悬停可查看正则 pattern 在ocr.po中的全部语言修正映射，行内显示修正后的值（如→ 体力[0-9]+），引号内输入可补全ocr.po中的 key。 -
技能效果 ID 悬停
EffectType.XXX或"effect_id": "XXX"显示效果 ID、分类和中文描述，行内幽灵注释显示中文说明（如「敌人被施加寒冷元素」），在effect_id: "的引号内输入可补全全部效果 ID，按分类展示。数据从src/data/effects.py自动解析，无需手动维护。
- 模板面板：通过侧边栏图标或
Ctrl+Alt+T快捷键（需聚焦 Python 编辑器时生效）打开，网格展示工作区全部模板的缩略图，支持按名称实时搜索和过滤。 - 快速插入：单击卡片将
fL.<模板名>插入编辑器光标处，双击复制到剪贴板，点击缩略图打开来源原图。 - 模板代码提示：输入
fL.或FeatureList.补全模板名称并显示尺寸，悬停显示缩略图预览、尺寸和来源信息。 - 也可通过命令 ok-script 工具箱: 在编辑器中打开模板面板 在编辑器区打开更大的网格视图。
- 支持侧边栏（模板面板和模板素材两个视图）和编辑器大窗口两种浏览方式。
self.wait_click_feature(feature=fL.give_gift, time_out=10)悬停 fL.give_gift 可查看对应模板裁剪图；输入 fL. 可从模板名称列表中选择。
ok-script 临时截图 是活动栏上的独立容器（有自己的图标），里面是一个最多 10 张的暂存区（超出自动淘汰最早一张），用于快速取素材：
| 能力 | 说明 |
|---|---|
| 入列 | Ctrl+V 粘贴剪贴板图片、点「截屏」截取游戏窗口，或直接把图片文件拖进来 |
| 0.1s 轮播 | 按 100ms 间隔循环播放全部截图，方便观察有移动界限的按钮等目标 |
| 框选复制 | 在「框选坐标」模式下框选，把 x,y,tox,toy 归一化坐标复制到剪贴板 |
| 导入标注 | 缩略图卡片右上角的 → 按钮把该张导入「标注管理」（即复制进 ok_templates 并登记 COCO） |
细节说明：
- 轮播与框选相互独立——框选期间轮播不停，选框松手后保留在原位，便于反复比对微调。
- 归一化坐标按图片宽高归一化到 0..1，保留 4 位小数，同样支持滚轮缩放、中键/空白拖拽平移。
- 框选完成后框会保留并可继续调整（带 8 向手柄、可整体拖动，交互与模板标注框一致）：创建时与每次调整结束都会重新复制一次当前框的坐标；框本身不写入标注数据、不落盘。点击图片的非交互部分（框体与手柄之外）即清除。
- 注：VS Code 的跨 Webview 拖拽不可用（各 webview 是不同 origin 的 iframe，
dataTransfer被屏蔽），所以 → 按钮是导入的可靠入口。 - 标注编辑器同样支持该模式：工具栏「坐标 (C)」或按
C键后框选，直接复制同样的x,y,tox,toy归一化坐标，不会创建标注框、不改动 COCO。得到的框同样带手柄可继续微调，每次调整结束重新复制；点击图片非交互部分清除。快捷键可用okScriptToolkit.annotationKeybindings的copyCoords覆盖。
- 从目标项目的
src/config.py/config.py自动解析所有一次性任务和触发任务，生成完整的参数配置表单。 - 支持布尔、数字、文本、多行文本、下拉、多选、列表、项目级联下拉和结构化条件序列等多种参数类型。
- 任务名、说明、参数名和选项标签自动读取目标项目 i18n 翻译显示；支持递归可折叠的子任务配置树。
- 单一常驻执行器：整个项目只维持一个进程——连接一次游戏后，由 ok-script 框架原生的
TaskExecutor循环轮询全部已启用的触发任务，实现多触发任务串连轮询（旧版逐个启动会让框架把触发任务列表收窄成单个）。 - 执行器显式启动：勾选触发任务只是「记录我要跑哪些」，不会自动拉起执行器；点工具栏的「启动执行器」按钮才开始运行，运行中勾选依然即时生效。执行器未运行时，已勾选的任务显示「已启用」而非「已入列」，避免误以为正在轮询。
- 触发任务勾选启用：卡片上的「启用」勾选框即入列 / 出列，勾选状态按项目持久化，重开面板或重启 IDE 后仍是勾选状态，下次启动执行器时按此集合入列。
- 一次性任务入队：点「启动」把任务送进同一个执行器的队列，执行一次后自动出队，不会另起进程争抢游戏窗口。
- 每个项目、每个任务独立保存参数覆盖，参数修改后自动保存并即时推送给运行中的执行器；覆盖只作用于执行器进程的内存，不写回目标项目配置文件。
- 不污染目标项目配置：执行器运行时，ok 框架对
configs/与截图的读写全部改道到工作区的沙箱目录.vscode/ok-script-toolkit/，目标项目的配置文件与截图全程保持原样（devices.json做桥接拷贝以复用游戏连接）。调试时可以放心地改参数试跑，不会弄脏项目。 - 执行器可随时暂停/恢复（全局挂起轮询与任务），也可以「停止当前任务」而不关闭执行器；运行日志输出到专属输出频道。
执行命令 ok-script 工具箱: 打开角色技能管理面板，在编辑器区打开角色数据库总览：
- 筛选与查看：按星级、元素、职业、技能类型、强化组和诊断状态筛选角色，查看角色基础信息、多语言名称、技能说明、倍率、失衡、冷却和技力等数据。
- 技能与强化组管理：添加、修改、删除自定义技能；为任意技能配置强化组的基础效果、触发条件和产出效果，均从效果定义中按类别多选。
- 效果索引：按效果分类汇总，并反向列出每个效果被哪些角色、技能和强化组引用；支持添加新的效果类别和效果定义。
- 名称本地化矩阵：横向比较全部 locale 的角色名称，突出显示缺失翻译。
- 数据诊断：检查角色主表与技能文件覆盖、重复技能 ID、未知效果 ID、强化声明不一致和缺失语言等问题，诊断结果可一键跳转到对应文件。
- 写入前自动生成备份，通过临时文件校验后原子替换源文件；源文件保存后面板自动刷新。
- 扩展界面（通知、输出频道、hover、模板面板、任务启动器、工具箱和角色技能管理面板）支持简体中文、繁体中文、英文、日文、韩文和西班牙文，默认跟随 VS Code 显示语言。
- 侧边栏分为 ok-script 工具（工具箱 + 任务启动）、ok-script 模板（模板面板 + 模板素材）和 ok-script 临时截图 三个独立活动栏容器。
- 代码提示中的语言数据始终使用目标项目自身的 locale 和原始协议值，不受插件界面语言影响。
Note
语言与模板提示只针对 python 文件生效；效果 ID 提示（hover、补全、幽灵注释）额外覆盖 json 和 jsonc 文件。扩展不修改源代码，也不生成存根文件。
默认从当前工作区读取：
| 路径 | 用途 |
|---|---|
assets/lang/*.json |
语言数据，节点格式为 { "string": "..." } 或 { "pattern": "..." } |
i18n/<locale>/LC_MESSAGES/*.po |
gettext PO 数据（okScriptToolkit.enablePoData 控制，默认开启） |
assets/coco_annotations.json |
模板名称、原图和 bbox |
assets/images/*.png |
模板预览使用的原图 |
ok_tasks/assets/coco_annotations.json |
可选，存在时一并读取 |
ok_tasks/assets/images/*.png |
可选，存在时一并读取 |
src/data/effects.py |
技能效果 ID 数据源（EffectType 枚举 + EFFECT_DESCRIPTIONS 中文描述） |
assets/lang/effect_names.json |
角色技能管理面板中的效果本地化名称；缺失时回退到效果描述和原始 ID |
关于 PO 数据：仅加载 okScriptToolkit.poDomains 白名单内的 domain（默认 ocr，排除 ok.po 等 UI 通用文案）。msgid（如 借 款 金 额、体力.*）作为 key，msgstr 作为对应语言的 string 值；含空格的 msgid 会自动生成去空格副本（借款金额）。该数据用于 OCR 函数 match 参数的提示，不作为 self.lang 模块。
保存 JSON（包括效果名称）、COCO 标注、PNG 或 effects.py 后，扩展会自动刷新，无需重启项目。
项目结构、JetBrains 版本、本地安装和 CI/CD 发布流程详见 DEVELOPMENT.md。
| 配置项 | 默认值 | 说明 |
|---|---|---|
okScriptToolkit.langDirectory |
assets/lang |
lang JSON 目录（相对工作区根） |
okScriptToolkit.poDirectory |
i18n |
gettext PO 目录（相对工作区根），按 <locale>/LC_MESSAGES/*.po 扫描 |
okScriptToolkit.enablePoData |
true |
是否启用 gettext PO 数据源，与 lang JSON 合并 |
okScriptToolkit.poDomains |
["ocr"] |
要加载的 PO domain 白名单（默认只加载 ocr，排除 ok 等 UI 文案） |
okScriptToolkit.displayLocale |
auto |
幽灵注释显示的语言；auto 跟随 VS Code UI 语言 |
okScriptToolkit.enableInlayHints |
true |
是否启用幽灵注释 |
okScriptToolkit.featureAliases |
["fL", "FeatureList"] |
模板别名列表；别名会用于模板补全和 hover 识别 |
okScriptToolkit.labelEnumPath |
空 | 生成 LabelEnum.py 的路径（相对工作区根，带不带 .py 都可以）；留空则跟随项目约定。对应项目文件的 labelEnum.path |
okScriptToolkit.labelEnumName |
空 | 生成枚举的类名；留空则由文件名推导。对应项目文件的 labelEnum.name。 |
okScriptToolkit.effectsFile |
src/data/effects.py |
技能效果 ID 定义文件（EffectType 枚举与 EFFECT_DESCRIPTIONS），相对工作区根目录 |
okScriptToolkit.okScriptProjectPath |
空 | 任务启动器使用的 ok-script 项目根目录；为空时尝试使用当前工作区 |
okScriptToolkit.okScriptPython |
空 | 任务启动器使用的 Python；为空时优先使用目标项目 .venv/Scripts/python.exe |
okScriptToolkit.captureMethod |
auto |
游戏窗口截图方式：auto / wgc / bitblt / foreground |
okScriptToolkit.characterProjectPath |
空 | 角色技能管理面板的数据项目；为空时使用 okScriptProjectPath 或当前工作区 |
okScriptToolkit.characterMasterFile |
assets/data/characters.json |
角色主表 JSON |
okScriptToolkit.characterSkillsDirectory |
assets/data/character_skills |
角色技能 JSON 目录 |
okScriptToolkit.characterLocaleFile |
assets/lang/characters.json |
角色名称多语言 JSON |
okScriptToolkit.characterAvatarTemplateRegex |
^battle[_-]?icon[_-]? |
角色头像模板名正则；有捕获组时使用第一组，否则使用匹配前缀后的剩余名称，与角色主表英文 slug 匹配；默认兼容 battleicon、battle_icon 和 battle-icon 前缀 |
okScriptToolkit.okTemplatesDirectory |
ok_templates |
ok_templates 文件夹名（相对工作区根），供模板素材管理器使用 |
okScriptToolkit.annotationKeybindings |
见默认值 | 标注编辑器的键盘快捷键；值为按键名，支持 ctrl+z 等修饰符前缀 |
把随项目走的约定写在被调试项目的根目录：枚举文件路径与类名、模板目录、 执行器启动钩子、i18n（语言 / PO 目录与开关）、角色数据位置、效果定义文件等。 提交进仓库后，团队成员、以及另一个 IDE（JetBrains 插件读同一份） 都能直接用，不必各自在 IDE 设置里重配一遍。
取值优先级（高 → 低）：
个人偏好（IDE 设置）> 项目约定文件 > 项目 config.py 已声明的事实 > 内置默认。
- 文件缺席时行为与不引入它时完全一致（纯增量）
- 插件只读本文件，绝不写入
- 编辑器里对它提供悬浮说明与补全（来自
schemas/ok-script-toolkit.schema.json）
已经接入取值链的设置项 ↔ 文件里的字段：
| IDE 设置 | 项目文件字段 |
|---|---|
okTemplatesDirectory |
templates.directory |
featureAliases |
labelEnum.aliases |
labelEnumPath / labelEnumName |
labelEnum.path / labelEnum.name（同名：两边语义相同，分名反而要用户多记一个词） |
langDirectory / poDirectory / poDomains |
i18n.langDirectory / i18n.poDirectory / i18n.poDomains |
enablePoData |
i18n.enabled（名字不同是刻意的：前者是"我这台机器要不要读它"，后者是"这个项目的 i18n 长什么样"） |
characterProjectPath / characterMasterFile / characterSkillsDirectory / characterLocaleFile / characterAvatarTemplateRegex |
characters.projectPath / characters.masterFile / characters.skillsDirectory / characters.localeFile / characters.avatarTemplateRegex |
effectsFile |
effects.file |
templates.cocoAnnotations没有对应的 IDE 设置（所以没有"个人偏好"层）：它声明的是 运行时模板库（ok 框架加载的那份 COCO）的路径，取值链为templates.cocoAnnotations→ 项目config.py的template_matching.coco_feature_json→ 依次探测assets/coco_annotations.json、ok_tasks/assets/coco_annotations.json（即旧行为）。 实测 6 个 ok 系项目全都在config.py里声明了它，其中一个的文件名是coco_detection.json—— 没有这条链时插件在那类项目上找不到模板库。
⚠️ 素材面板自己的<模板目录>/coco_annotations.json是另一个文件，路径由templates.directory决定，不受cocoAnnotations影响。
⚠️ 个人偏好排最高有个副作用：一旦你手动改过某一项，项目声明的那一项就对你 永久失效，界面上毫无提示。命令okScriptToolkit.showConventionSources（「项目约定 vs 我的设置」）会把每一项的生效值来自哪一层列出来，并支持一键恢复为项目约定。
完整字段清单与设计说明见 docs/project-config.md，
可直接复制的示例见 docs/ok-script-toolkit.example.json。
「运行时到底读了哪些配置、每一项是干什么的、按什么规则取值」见
docs/config-reads.md（六型分类的全景 + 逐项用途 + 不变量清单 + 排查步骤）。
在工作区的 .vscode/settings.json 中：
{
"okScriptToolkit.langDirectory": "assets/lang",
"okScriptToolkit.poDirectory": "i18n",
"okScriptToolkit.poDomains": ["ocr"],
"okScriptToolkit.displayLocale": "zh_CN",
"okScriptToolkit.enableInlayHints": true,
"okScriptToolkit.featureAliases": ["fL", "FeatureList"]
}displayLocale 支持 auto、zh_CN、zh_TW、en_US、ja_JP、ko_KR 和 es_ES。hover 仍会显示完整语言表格；该设置只影响行内提示和语言补全详情。
如果项目使用了其他变量名，例如 featureList，可以配置：
{
"okScriptToolkit.featureAliases": ["fL", "FeatureList", "featureList"]
}示例效果——在代码中：
self.wait_click_ocr(match=self.lang.zip_line_mixin.k_2f4f4a2f, ...)幽灵注释会在 k_2f4f4a2f 后面显示 「向目标移动」；hover 会弹出包含 zh_CN / zh_TW / en_US / ja_JP / ko_KR / es_ES 全部值的表格。
命令分类随界面语言显示为「ok-script 工具箱」/「ok-script Toolkit」。
| 命令 | 快捷键 | 说明 |
|---|---|---|
ok-script 工具箱: 打开模板面板 |
Ctrl+Alt+T（macOS Cmd+Alt+T，需聚焦 Python 编辑器） |
聚焦活动栏中的模板侧边栏视图 |
ok-script 工具箱: 在编辑器中打开模板面板 |
— | 在编辑器区打开大窗口网格视图 |
ok-script 工具箱: 打开任务启动 |
— | 聚焦活动栏中的任务启动器视图 |
ok-script 工具箱: 打开角色技能管理面板 |
— | 打开角色、技能、效果、强化组和名称本地化管理页 |
ok-script 工具箱: 打开模板素材 |
— | 在编辑器区打开模板素材管理大窗口面板 |
ok-script 工具箱: 打开标注编辑器 |
— | 提示在模板素材面板中点击图片以进入 COCO 标注编辑器（命令本身不直接打开编辑器） |
ok-script 工具箱: 打开临时截图 |
— | 聚焦活动栏中的临时截图视图 |
ok-script 工具箱: 截图并打开模板素材 |
Ctrl+Alt+S（macOS Cmd+Alt+S） |
打开模板素材管理面板并立即截图。复用面板自己的截图动作，截图会登记进 COCO。键位可在「键盘快捷方式」里改 |
ok-script 工具箱: 项目约定 vs 我的设置 |
— | 列出参与取值链的设置项，显示每一项的生效值来自哪一层（我的设置 / 项目约定 / 内置默认）。被个人设置覆盖过的项带一个「恢复」按钮，一键回到项目约定。用于解决"我改过一次就再也看不到团队改了什么" |
安装或直接覆盖扩展文件后执行：
Ctrl+Shift+P → Developer: Reload Window
相关项目