diff --git a/.vscodeignore b/.vscodeignore index bfc8888..03f4411 100644 --- a/.vscodeignore +++ b/.vscodeignore @@ -16,7 +16,7 @@ tsconfig.json scripts/** jetbrains/** .gitmodules -RELEASING.md +RELEASING*.md DEVELOPMENT.md DEVELOPMENT.en.md # 仓库自身的忽略规则对运行时毫无用处，打进 VSIX 只是噪音 @@ -33,7 +33,6 @@ logs/**/*.log .vscode/tasks.json .vscode/launch.json .vscode/ok-lang-hints-*.json -AGENT.md AGENTS.md **/agent.md **/agents.md @@ -47,7 +46,7 @@ python/test_*.py **/*.bak **/*.ok-script-toolkit.tmp # 审查/修复计划类的一次性工作目录（verification-<日期> at <时间>/ 等）。 -# 这些是开发过程产物，按 AGENT.md 的打包红线不得进产物。用通配而不是逐个列名 —— +# 这些是开发过程产物，按 AGENTS.md 的打包红线不得进产物。用通配而不是逐个列名 —— # 每次审查都会新建一个带时间戳的目录，逐个列名必然漏（2026-09-20 实测漏了 107 KB）。 verification-*/ verification */* diff --git a/AGENT.md b/AGENT.md deleted file mode 100644 index 95c956b..0000000 --- a/AGENT.md +++ /dev/null @@ -1,67 +0,0 @@ -# 开发规范：资源外置与插件打包 / Development Standards: External Resources & Plugin Packaging - -## 中文 - -### 资源外置 - -* **i18n 文案必须外置**，禁止在业务代码中硬编码可翻译文本。 -* **任何代码内使用的 HTML 资源必须外置**，禁止将 HTML 模板、HTML 片段直接嵌入 Python/JS/TS 等代码中。 -* 外置资源应放在项目约定的资源目录中，并通过统一的资源加载机制读取。 -* 新增功能时，如果涉及 i18n 或 HTML，必须同步新增对应的外部资源文件，不得为了方便直接写入代码。 -* 修改现有功能时，如发现已有代码内嵌 i18n 或 HTML，应优先一并迁移到外部资源。 - -### 插件打包 - -以下属于**仅开发使用的文件**，不得进入插件最终打包产物： - -* `AGENTS.md` -* `AGENT.md` -* 其他 `agent.md` / `agents.md` 文件 -* 项目开发说明、AI Agent 指令及相关开发辅助文件 -* 测试文件及其他明确标记为开发用途的资源 - -插件打包配置必须显式忽略上述文件，避免将开发文件随插件发布。 - -### 检查要求 - -提交代码前应检查： - -1. 是否存在新增的代码内嵌 i18n 文案。 -2. 是否存在新增的代码内嵌 HTML。 -3. 新增的 HTML/i18n 是否已经外置到规定目录。 -4. 插件打包产物中不得包含 `AGENT.md`、`AGENTS.md` 等 Agent 开发文件。 -5. 修改打包忽略规则后，应验证最终插件压缩包/产物中确实不存在这些文件。 - ---- - -## English - -### External Resources - -* **i18n strings must be externalized** — hardcoding translatable text in business code is prohibited. -* **Any HTML resources used in code must be externalized** — embedding HTML templates or HTML fragments directly into Python/JS/TS code is prohibited. -* Externalized resources should be placed in the project's designated resource directories and loaded through a unified resource loading mechanism. -* When adding new features that involve i18n or HTML, corresponding external resource files must be added simultaneously — do not embed them directly in code for convenience. -* When modifying existing features, if inline i18n or HTML is found, it should be migrated to external resources as a priority. - -### Plugin Packaging - -The following are **development-only files** and must not be included in the final plugin package: - -* `AGENTS.md` -* `AGENT.md` -* Other `agent.md` / `agents.md` files -* Project development documentation, AI Agent instructions, and related development auxiliary files -* Test files and other resources explicitly marked as development-purpose - -The plugin packaging configuration must explicitly ignore the above files to prevent development files from being shipped with the plugin. - -### Checklist - -Before committing code, verify: - -1. No new inline i18n strings have been added to code. -2. No new inline HTML has been added to code. -3. New HTML/i18n has been externalized to the designated directories. -4. The plugin package does not contain `AGENT.md`, `AGENTS.md`, or other Agent development files. -5. After modifying packaging ignore rules, verify the final plugin archive/products do not contain these files. diff --git a/AGENTS.md b/AGENTS.md index 7271c6b..79aed98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,66 @@ -# 仓库协作指引 +# 仓库协作指引与开发规范 -- 开发与打包约束见 [AGENT.md](AGENT.md)。 -- 处理主仓或 `jetbrains/` 子仓的 PR review 时，先读 - [.agents/skills/ok-script-pr-review/SKILL.md](.agents/skills/ok-script-pr-review/SKILL.md)。 - 两边是独立 Git 仓库，调用 GitHub API 时须明确仓库。 +## PR review + +处理主仓或 `jetbrains/` 子仓的 PR review 时，先读 +[.agents/skills/ok-script-pr-review/SKILL.md](.agents/skills/ok-script-pr-review/SKILL.md)。 +两边是独立 Git 仓库，调用 GitHub API 时须明确仓库。 + +等待 PR review 时使用技能提供的长时间等待脚本，复用已有终端进程，并让用户能在 Codex 侧边查看输出。不要默认改成隐藏进程，也不要为等待另外创建定时任务、heartbeat 或轮询 automation，除非用户明确要求。 + +## 仓库定位与功能边界 + +本仓库是面向 **ok-script 项目开发者的 IDE 插件**，用于开发、调试和资源制作。功能取舍以缩短开发步骤、准确操作当前本地代码、方便定位问题为目标。 + +**需要承担：** + +* 准确识别本地工作区当前的项目、解释器、任务注册、参数声明和资源入口；核对功能时以本地代码为准，历史版本与远程提交仅作参考。 +* 支持任务运行、触发任务启用、暂停、停止和当前参数试验，尽量沿用项目与框架的真实启动方式。 +* 隔离调试配置与项目实际配置，明确覆盖范围；用户主动编辑模板、框、角色等项目资源时，按该操作的既有保存语义写入。 +* 提供真实的保存结果、可确认的运行状态、日志与错误入口。项目路径、执行器、任务标识、配置来源等技术信息应清楚可达。 +* 支持截图、标注、模板与区域制作、代码引用、补全、预览和来源跳转；两端保持操作含义一致，界面紧凑、清晰、易操作。 +* 插件依赖的框架 API、任务元数据、配置定位或资源格式变化，导致当前功能读错、写错或不能运行时，修正插件的检测与调用入口。 + +**不需要承担：** + +* 业务项目的参数迁移、历史值恢复、跨任务配置搬运、账号覆盖迁移或旧业务版本兼容。这些由业务项目负责；项目启动链内已有逻辑可正常执行，插件不另建一套业务迁移机制。 +* 恢复业务项目已经移除、不再需要的参数。参数删除、任务拆分、参数归属调整和内部检测点更换属于正常内容改造；能正确读取当前声明时，不据此安排额外适配。 +* 把旧调试快照中的键当作当前任务仍支持的参数，或凭字段同名、旧任务关系自动推断并搬运历史值。 +* 默认扩展普通业务软件的账号生命周期、迁移恢复向导、完整健康看板等流程；也不为凑齐 UI 状态要求每个业务项目新增应用回执或观测协议。 + +插件仍负责**自己的**持久化格式、协议和缓存兼容。无法确认运行应用或等待原因时，如实说明并提供日志入口。优先保证当前调试链可靠，再改善开发效率与视觉体验。详细依据见 [开发者插件功能范围](docs/developer-tool-scope.md)。 + +## 协作说明文档 + +* 面向大模型的指令、技能和配套说明（包括 `AGENTS.md`、`SKILL.md`）每份文档只维护单文件、单语言版本，本仓库使用中文；不混写中英文正文，也不另建 `.en.md` 等翻译副本。 +* 除 Agent 指令、技能及技能配套说明外，所有文档必须同时维护中文与英文版本，分别放在 `名称.md` 与 `名称.en.md` 中；每个文件只保留对应语言的正文，更新时同步两份内容与相应链接。 +* 文件名、代码、API 名称和必要的原始界面文字保留原文，不视为双语正文。 + +## 资源外置 + +* **i18n 文案必须外置**，禁止在业务代码中硬编码可翻译文本。 +* **任何代码内使用的 HTML 资源必须外置**，禁止将 HTML 模板、HTML 片段直接嵌入 Python/JS/TS 等代码中。 +* 外置资源应放在项目约定的资源目录中，并通过统一的资源加载机制读取。 +* 新增功能时，如果涉及 i18n 或 HTML，必须同步新增对应的外部资源文件，不得为了方便直接写入代码。 +* 修改现有功能时，如发现已有代码内嵌 i18n 或 HTML，应优先一并迁移到外部资源。 + +## 插件打包 + +以下属于**仅开发使用的文件**，不得进入插件最终打包产物： + +* `AGENTS.md` +* 其他 `agent.md` / `agents.md` 文件 +* 项目开发说明、AI Agent 指令及相关开发辅助文件 +* 测试文件及其他明确标记为开发用途的资源 + +插件打包配置必须显式忽略上述文件，避免将开发文件随插件发布。 + +## 检查要求 + +提交代码前应检查： + +1. 是否存在新增的代码内嵌 i18n 文案。 +2. 是否存在新增的代码内嵌 HTML。 +3. 新增的 HTML/i18n 是否已经外置到规定目录。 +4. 插件打包产物中不得包含 `AGENTS.md` 等 Agent 开发文件。 +5. 修改打包忽略规则后，应验证最终插件压缩包/产物中确实不存在这些文件。 diff --git a/DEVELOPMENT.en.md b/DEVELOPMENT.en.md index 0f796d4..0fb0578 100644 --- a/DEVELOPMENT.en.md +++ b/DEVELOPMENT.en.md @@ -1,4 +1,4 @@ -# 开发指南 / Development Guide +# Development Guide
@@ -6,18 +6,16 @@
-本文档面向扩展开发者，包含项目结构、本地构建安装和发布流程。 - This document is for extension developers and covers the project structure, local build/installation, and release workflow. -The shared runtime scripts, protocol, and host boundaries are documented in [Shared core](docs/shared-core.md). +The shared runtime scripts, protocol, and host boundaries are documented in [Shared core](docs/shared-core.en.md); see [feature parity](docs/feature-parity.en.md) for current capabilities and limits. --- ## Project Structure ```text -src/ VS Code extension host TypeScript source (33 modules; entry points and major ones listed) +src/ VS Code extension host TypeScript source (entry points and major modules listed, not a complete inventory) projectConfig.ts Read side of the project convention file ok-script-toolkit.json (locate + cache + personal preference) projectConfigPure.ts Pure precedence-chain logic (no vscode dependency, unit-testable): parse + precedence + winning layer conventionSources.ts Data source for the "Project Convention vs My Settings" tracing panel @@ -62,7 +60,7 @@ media/ Per-Webview HTML/CSS/JS (loaded by the host via CS python/ Helper scripts shipped with the extension: task discovery, probing & execution (parse_config_tasks.py, probe_task_schemas.py, run_executor.py), plus game window capture & config probing for the template asset panel (capture_game_window.py, probe_window_config.py) python/tests/ Development-time Python regression tests (test_probe_*.py ×5 and test_run_executor_*.py ×4, 9 in total, all wired into npm test; plus _test_tmp.py, the shared per-suite temp-dir infrastructure); - excluded from VSIX / JetBrains JAR per AGENT.md packaging rules + excluded from VSIX / JetBrains JAR per AGENTS.md packaging rules jetbrains/ The JetBrains plugin's **separate public repository** (git submodule), with its own README / CI / release flow schemas/ JSON Schema for ok-script-toolkit.json (editor completion and validation) docs/ Design documents (config-reads overview, convention-file design, global UI design system, copy-pasteable example config) @@ -118,7 +116,7 @@ The `jetbrains/` directory contains a standalone Kotlin + IntelliJ Platform plug Drag **works here** — the two tool windows share the same JVM and use a custom `DataFlavor` to pass paths; note that `JPanel` has no built-in auto-drag-out, requiring manual `exportAsDrag` in `mouseDragged`. - Follow-up parity work from main-repo v1.9.0 → v1.13.0 (Swing-side spec at - [`jetbrains/docs/design-parity.md`](https://github.com/AliceJump/ok-script-toolkit-jetbrains/blob/main/docs/design-parity.md)): + [`jetbrains/docs/design-parity.md`](https://github.com/AliceJump/ok-script-toolkit-jetbrains/blob/main/docs/design-parity.en.md)): **global config takeover** (probe parses global config groups → parameter snapshots persisted → full snapshot injected via `OK_TOOLKIT_GCONFIG` at executor launch → live push via `gparams` while running), the health bar and the idle-state **run center** (current task / execution queue / trigger polling), @@ -131,7 +129,7 @@ cd jetbrains ./gradlew test buildPlugin verifyPluginStructure verifyPluginConfiguration ``` -Use `gradlew.bat` on Windows. The generated ZIP is at `jetbrains/build/distributions/` and can be installed via **Settings / Plugins / Install Plugin from Disk...** in a JetBrains IDE. For per-feature alignment status and remaining gaps, see [`jetbrains/docs/parity-review.md`](https://github.com/AliceJump/ok-script-toolkit-jetbrains/blob/main/docs/parity-review.md) (re-verified line by line against the code on 2026-09-21, baseline v1.8.0). +Use `gradlew.bat` on Windows. The generated ZIP is at `jetbrains/build/distributions/` and can be installed via **Settings / Plugins / Install Plugin from Disk...** in a JetBrains IDE. For per-feature alignment status and remaining gaps, see [`jetbrains/docs/parity-review.md`](https://github.com/AliceJump/ok-script-toolkit-jetbrains/blob/main/docs/parity-review.en.md) (historical baseline; see [current feature parity](docs/feature-parity.en.md)). ## Installation @@ -284,4 +282,4 @@ Add each one in the GitHub repo under **Settings → Secrets and variables → A When using VS Marketplace OIDC, also add `VSCE_USE_OIDC=true` under **Actions → Variables → New repository variable**; only enable after completing Marketplace Trusted Publishing policy. -See [RELEASING.md](RELEASING.md) for full token setup, signing key generation, and step-by-step release instructions. +See [RELEASING.md](RELEASING.en.md) for full token setup, signing key generation, and step-by-step release instructions. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 18483e3..727f183 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,4 +1,4 @@ -# 开发指南 / Development Guide +# 开发指南
@@ -8,16 +8,14 @@ 本文档面向扩展开发者，包含项目结构、本地构建安装和发布流程。 -两端共同维护的运行脚本、协议和宿主边界见 [共用核心](docs/shared-core.md)。 - -This document is for extension developers and covers the project structure, local build/installation, and release workflow. +两端共同维护的运行脚本、协议和宿主边界见 [共用核心](docs/shared-core.md)，当前功能和限制见 [功能对齐表](docs/feature-parity.md)。 --- ## 项目结构 ```text -src/ VS Code 扩展宿主 TypeScript 源码（33 个模块，下列为入口与主要模块） +src/ VS Code 扩展宿主 TypeScript 源码（下列为入口与主要模块，非完整清单） projectConfig.ts 项目约定文件 ok-script-toolkit.json 的读盘侧（定位 + 缓存 + 个人偏好） projectConfigPure.ts 取值链纯逻辑（不依赖 vscode，可单测）：解析 + 优先级 + 来源层 conventionSources.ts 「项目约定 vs 我的设置」溯源面板的数据源 @@ -62,7 +60,7 @@ media/ 每个外置 Webview 的 HTML/CSS/JS（宿主经 C python/ 随扩展发布的辅助脚本：任务发现、探测与执行（parse_config_tasks.py、probe_task_schemas.py、run_executor.py），以及模板素材面板的游戏窗口截图与配置探测（capture_game_window.py、probe_window_config.py） python/tests/ 开发期 Python 回归测试（test_probe_*.py ×5、test_run_executor_*.py ×4， 共 9 个，npm test 全部接入；另有三端共用的测试临时目录基建 _test_tmp.py）； - 按 AGENT.md 打包规范不进 VSIX / JetBrains JAR + 按 AGENTS.md 打包规范不进 VSIX / JetBrains JAR jetbrains/ JetBrains 插件的**独立公开仓库**（git submodule），有自己的 README / CI / 发版流程 schemas/ ok-script-toolkit.json 的 JSON Schema（编辑器补全与校验） docs/ 设计文档（配置读取全景、项目约定文件设计、全局 UI 设计规范、可直接复制的示例配置） @@ -130,7 +128,7 @@ cd jetbrains ./gradlew test buildPlugin verifyPluginStructure verifyPluginConfiguration ``` -Windows 使用 `gradlew.bat`。生成的 ZIP 位于 `jetbrains/build/distributions/`，可在 JetBrains IDE 的 **Settings / Plugins / Install Plugin from Disk...** 中安装。逐功能的对齐状态与剩余差异见 [`jetbrains/docs/parity-review.md`](https://github.com/AliceJump/ok-script-toolkit-jetbrains/blob/main/docs/parity-review.md)（2026-09-21 已按代码逐条重核，基线 v1.8.0）。 +Windows 使用 `gradlew.bat`。生成的 ZIP 位于 `jetbrains/build/distributions/`，可在 JetBrains IDE 的 **Settings / Plugins / Install Plugin from Disk...** 中安装。逐功能的对齐状态与剩余差异见 [`jetbrains/docs/parity-review.md`](https://github.com/AliceJump/ok-script-toolkit-jetbrains/blob/main/docs/parity-review.md)（保留历史基线；当前实现见 [功能对齐表](docs/feature-parity.md)）。 ## 安装 diff --git a/README.en.md b/README.en.md index b6d2981..d8536fe 100644 --- a/README.en.md +++ b/README.en.md @@ -6,11 +6,8 @@ # ok-script Toolkit -**把 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 Marketplace](https://img.shields.io/badge/VS%20Code%20Marketplace-ok--script%20Toolkit-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=AliceJump.ok-script-toolkit) @@ -26,8 +23,6 @@ Language key completion · OCR fix hints · Template browsing · Task launching --- -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] @@ -51,6 +46,8 @@ For PyCharm / IntelliJ IDEA users, install the JetBrains version: [ok-script Too ## Features +See [feature and documentation parity](docs/feature-parity.en.md) for current host implementations and remaining differences. + | Module | Description | |---|---| | [Code development assistance](#code-development-assistance) | Complete and explain `self.lang`, OCR regex, and skill effect IDs in the editor | @@ -84,7 +81,7 @@ When editing Python code, the extension automatically detects ok-script-specific

- **Template panel**: Open via the sidebar icon or `Ctrl+Alt+T` shortcut (requires focus on a Python editor). Displays all workspace templates in a thumbnail grid with real-time name search and filtering. -- **Quick insert**: Click a card to insert `fL.` at the editor cursor, double-click to copy to clipboard, click the thumbnail to open the source image. +- **Quick insert**: Click a card to insert `fL.` at the editor cursor, double-click to copy to clipboard, or use **View Original** to open the source. VS Code template and box galleries use a shared 500 ms card double-click window; clicks beyond that window are independent single clicks. The insert, copy and source buttons act immediately. - **Template code hints**: Type `fL.` or `FeatureList.` to complete template names with size info. Hover shows thumbnail preview, dimensions, and source info. - You can also open a larger grid view in the editor area via the command **ok-script Toolkit: Open Template Panel in Editor**. - Supports both sidebar (template panel and template asset views) and large editor window browsing modes. @@ -96,6 +93,10 @@ self.wait_click_feature(feature=fL.give_gift, time_out=10) Hover over `fL.give_gift` to see the cropped template image; type `fL.` to select from the template name list. +### Box Resources + +Box resource management reuses source annotation images and the COCO editor. Edit boxes, generate enclosing boxes from templates, and explicitly publish normalized position tables. The box gallery provides cropped previews, source navigation, and insertion/copy/completion/Hover for `self.pos` references. Working and runtime files are separate; business projects own game loading. See [Box Resource Design](docs/box-resources.en.md). + ### Temp Screenshots

@@ -239,10 +240,10 @@ Settings that take part in the precedence chain ↔ the field they map to: > The **`okScriptToolkit.showConventionSources`** command ("Project Convention vs My Settings") > lists which layer each effective value comes from and lets you revert to the project convention. -See [`docs/project-config.md`](docs/project-config.md) for the full field list and design notes, +See [`docs/project-config.md`](docs/project-config.en.md) for the full field list and design notes, and [`docs/ok-script-toolkit.example.json`](docs/ok-script-toolkit.example.json) for a copy-paste example. For **what the plugin actually reads at runtime, what each setting does, and the precedence rules**, -see [`docs/config-reads.md`](docs/config-reads.md) (six read-path types, per-item purpose, the invariants, and a troubleshooting list). +see [`docs/config-reads.md`](docs/config-reads.en.md) (six read-path types, per-item purpose, the invariants, and a troubleshooting list). ### Configuration Example @@ -307,6 +308,6 @@ If you just modified the extension's `package.json` configuration declarations, **Related** -[ok-script Toolkit for JetBrains](https://github.com/AliceJump/ok-script-toolkit-jetbrains) · [Development Guide](DEVELOPMENT.en.md) · [Release Process](RELEASING.md) +[ok-script Toolkit for JetBrains](https://github.com/AliceJump/ok-script-toolkit-jetbrains) · [Development Guide](DEVELOPMENT.en.md) · [Release Process](RELEASING.en.md)

diff --git a/README.md b/README.md index 78c1bd3..fd7e4ee 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,7 @@ **把 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 Marketplace](https://img.shields.io/badge/VS%20Code%20Marketplace-ok--script%20Toolkit-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=AliceJump.ok-script-toolkit) [![JetBrains Marketplace](https://img.shields.io/badge/JetBrains%20Marketplace-ok--script%20Toolkit-000000?logo=jetbrains&logoColor=white)](https://plugins.jetbrains.com/plugin/34091-ok-script-toolkit) @@ -28,8 +25,6 @@ Language key completion · OCR fix hints · Template browsing · Task launching 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] > 下面每个功能章节开头的演示图都是可点的——如果动图没加载出来，直接点开链接看。 @@ -51,6 +46,8 @@ PyCharm / IntelliJ IDEA 用户请装 JetBrains 版：[ok-script Toolkit for JetB ## 功能 +当前两端实现及保留差异见 [功能与文档对齐表](docs/feature-parity.md)。 + | 模块 | 一句话说明 | |---|---| | [代码开发辅助](#代码开发辅助) | 在编辑器内补全和解释 `self.lang`、OCR 正则与技能效果 ID | @@ -84,7 +81,7 @@ PyCharm / IntelliJ IDEA 用户请装 JetBrains 版：[ok-script Toolkit for JetB

- **模板面板**：通过侧边栏图标或 `Ctrl+Alt+T` 快捷键（需聚焦 Python 编辑器时生效）打开，网格展示工作区全部模板的缩略图，支持按名称实时搜索和过滤。 -- **快速插入**：单击卡片将 `fL.<模板名>` 插入编辑器光标处，双击复制到剪贴板，点击缩略图打开来源原图。 +- **快速插入**：单击卡片将 `fL.<模板名>` 插入编辑器光标处，双击复制到剪贴板，使用「查看原图」按钮打开来源。VS Code 模板与框图库统一使用 500 ms 的卡片双击窗口；超过窗口的点击分别按单击处理。插入、复制和查看原图按钮立即执行。 - **模板代码提示**：输入 `fL.` 或 `FeatureList.` 补全模板名称并显示尺寸，悬停显示缩略图预览、尺寸和来源信息。 - 也可通过命令 **ok-script 工具箱: 在编辑器中打开模板面板** 在编辑器区打开更大的网格视图。 - 支持侧边栏（模板面板和模板素材两个视图）和编辑器大窗口两种浏览方式。 @@ -96,6 +93,10 @@ self.wait_click_feature(feature=fL.give_gift, time_out=10) 悬停 `fL.give_gift` 可查看对应模板裁剪图；输入 `fL.` 可从模板名称列表中选择。 +### 框资源 + +框资源管理复用标注原图与 COCO 编辑器，支持编辑框、从模板生成包围框，并显式发布归一化位置表。框画廊提供裁剪预览、来源定位及 `self.pos` 引用的插入、复制、补全和 Hover。工作文件与运行时文件分开，游戏中的加载由业务项目负责。详见 [框资源设计](docs/box-resources.md)。 + ### 临时截图

diff --git a/RELEASING.en.md b/RELEASING.en.md new file mode 100644 index 0000000..cc5c1a1 --- /dev/null +++ b/RELEASING.en.md @@ -0,0 +1,153 @@ +# Dual-Platform Tag Release + +[简体中文](RELEASING.md) | [English](RELEASING.en.md) + +Releases are coordinated by the parent repository `AliceJump/ok-script-toolkit`. Regular commits and manual runs do not publish; only the first push of a matching version tag triggers a Release: + +```text +vMAJOR.MINOR.PATCH +``` + +## One-time Configuration + +All Secrets are added to the parent repo: + +**Settings → Secrets and variables → Actions → New repository secret** + +### Visual Studio Marketplace + +It is recommended to configure **Trusted Publishing/OIDC** for Visual Studio Marketplace, avoiding long-lived Secrets: + +1. Go to the Visual Studio Marketplace Publisher/extension management page. +2. Add a Trusted Publishing policy for `AliceJump.ok-script-toolkit`. +3. Fill in GitHub repo as `AliceJump/ok-script-toolkit`, workflow as `release.yml`, and environment as required by the Marketplace page (or leave empty). +4. Add `VSCE_USE_OIDC=true` in the parent repo under **Settings → Secrets and variables → Actions → Variables**. +5. The tag workflow already has `id-token: write` granted; when `VSCE_PAT` is not configured and this variable is `true`, it will execute `vsce publish --oidc`. + +If continuing with PAT for now, add Secret: `VSCE_PAT` + +1. Open the Azure DevOps Personal Access Tokens page. +2. Create a new Token, selecting **All accessible organizations** for Organization. +3. Select **Custom defined**, expand all permissions, and check only **Marketplace → Manage**. +4. Copy the Token immediately after creation and save as `VSCE_PAT`. +5. Ensure the account that created the Token is a member of Visual Studio Marketplace Publisher `AliceJump`. + +The repo already has this Secret configured as a fallback before OIDC setup is complete. Microsoft has announced global PATs will retire on 2026-12-01; migration to Trusted Publishing/OIDC should be done as soon as possible. + +### JetBrains Marketplace First Listing + +The first time requires manual plugin creation: + +1. Log in to https://plugins.jetbrains.com/author/me. +2. Select **Add new plugin**. +3. Build the ZIP locally: `cd jetbrains && ./gradlew buildPlugin`. +4. Upload `build/distributions/ok-script-toolkit-jetbrains-.zip`. +5. Confirm the Plugin XML ID is `com.alicejump.okscripttoolkit`, complete license, source code, issue tracker info, and submit for review. + +After the first successful creation, the tag workflow can upload subsequent versions via API. + +### JetBrains Release Token + +Secret: `JETBRAINS_TOKEN` + +1. Open https://plugins.jetbrains.com/author/me/tokens. +2. Select **Generate Token** and enter a name. +3. Copy the permanent Token immediately (shown only once). +4. Save as parent repo Secret `JETBRAINS_TOKEN`. + +### JetBrains Signing Keys + +Secrets: + +- `JETBRAINS_PRIVATE_KEY` +- `JETBRAINS_PRIVATE_KEY_PASSWORD` +- `JETBRAINS_CERTIFICATE_CHAIN` + +Generate using OpenSSL: + +```bash +openssl genpkey -aes-256-cbc -algorithm RSA \ + -out private_encrypted.pem -pkeyopt rsa_keygen_bits:4096 +openssl rsa -in private_encrypted.pem -out private.pem +openssl req -key private.pem -new -x509 -days 365 -out chain.crt +``` + +- `JETBRAINS_PRIVATE_KEY`: Full text of `private.pem`. +- `JETBRAINS_PRIVATE_KEY_PASSWORD`: Password set in the first command and used in the second. +- `JETBRAINS_CERTIFICATE_CHAIN`: Full text of `chain.crt`. + +GitHub Secrets support multi-line text; you can paste PEM/CRT full text directly, or Base64-encode to a single line first. Never commit private keys, certificates, or passwords. Generate new certificates and update corresponding Secrets before expiration. + +## Each Release + +> **Prefer the one-shot script**: `npm run release -- --minor` (or `sh scripts/release.sh --minor`; +> Windows can use `scripts/release.ps1`). It performs every step below automatically — syncing the +> seven version locations, verifying, committing/pushing sub-repo then parent, and finally tagging. +> Add `--dry-run` to preview first. The script only runs on the `main` branch +> (required for both the parent repo and the jetbrains submodule) and refuses +> otherwise — the release commit lands on whatever branch it runs from (hit on v1.12.0). +> If releasing manually, follow the order below exactly and +> **do not skip any step**. + +On Windows, `scripts/release.ps1` first stashes uncommitted changes separately in the +parent and JetBrains repositories, including untracked files but excluding ignored files. +The release uses committed code; automatic version increments use the version in `HEAD`. +It attempts to restore this run's stashes and the original staging state afterward, +without touching existing stashes. Conflicting stashes are retained and their commit IDs +are printed. Uncommitted version changes left by a failed release are stashed separately; +successful commits or pushes are not rolled back. PowerShell uses `-DryRun` to preview +without stashing or releasing. The Shell script still requires clean workspaces. + +Run `node scripts/test_release.js` to verify the PowerShell release flow. It requires +`git`, `node`, and `pwsh`, and uses temporary repositories and local remotes only. + +For example, releasing `0.6.0`: + +```bash +# 1. Sync all seven version locations: package.json, package-lock.json, jetbrains/gradle.properties +# and all four README version badges (missing any one causes Release validation failure) +npm run version:sync -- 0.6.0 + +# 2. Verify +npm test +cd jetbrains +./gradlew test buildPlugin verifyPluginStructure verifyPluginConfiguration +cd .. + +# 3. Commit sub-repo version changes first +cd jetbrains +git add . +git commit -m "chore(release): prepare v0.6.0" +git push origin main +cd .. + +# 4. Then commit parent repo version, README badge, and new submodule pointer +# Note: README.md must be committed together — version:sync modifies its badge, +# and verify-version.js checks it in the tag pipeline (a missing commit in 2026-09 +# caused v1.6.0 validation failure) +npm run verify:version +git add package.json package-lock.json README.md jetbrains +git commit -m "chore(release): prepare v0.6.0" +git push origin main + +# 5. The only release action: create and push a new tag +git tag -a v0.6.0 -m "Release v0.6.0" +git push origin v0.6.0 +``` + +Tag release proceeds as: + +1. Check out the parent repo and pinned JetBrains submodule commit. +2. Validate all seven version locations (`package.json`, `package-lock.json`, `jetbrains/gradle.properties`, and all four README badges) match the tag exactly. +3. Test and build VSIX. +4. Test, validate, build, and sign the JetBrains ZIP using the Secrets. +5. Create a GitHub Release with both installers attached. +6. Publish to Visual Studio Marketplace if `VSCE_PAT` is present. +7. Publish to JetBrains Marketplace if complete JetBrains Token and signing Secrets are present. + +## Failure Handling + +- Do not move or force-push a tag that has already been pushed. +- When a tag build fails, fix the code, bump the patch version (e.g., `0.6.0` → `0.6.1`), and push a new tag. +- Tags and GitHub Releases are not reusable; both Marketplaces also reject duplicate versions. +- If only Marketplace Secrets are missing, the GitHub Release is still created with both offline installers available. diff --git a/RELEASING.md b/RELEASING.md index 32de944..557b520 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,8 +1,8 @@ -# 双端标签发布 / Dual-Platform Tag Release +# 双端标签发布 -发布由父仓库 `AliceJump/ok-script-toolkit` 统一协调。普通提交和手动运行不会发布；只有首次推送匹配版本的标签会运行 Release： +[简体中文](RELEASING.md) | [English](RELEASING.en.md) -Releases are coordinated by the parent repo `AliceJump/ok-script-toolkit`. Regular commits and manual runs do not publish; only a first-time push of a matching version tag triggers a Release: +发布由父仓库 `AliceJump/ok-script-toolkit` 统一协调。普通提交和手动运行不会发布；只有首次推送匹配版本的标签会运行 Release： ```text vMAJOR.MINOR.PATCH @@ -10,15 +10,13 @@ vMAJOR.MINOR.PATCH --- -## 中文 - -### 一次性配置 +## 一次性配置 所有 Secret 都添加到父仓库： **Settings → Secrets and variables → Actions → New repository secret** -#### Visual Studio Marketplace +### Visual Studio Marketplace 推荐配置 Visual Studio Marketplace 的 **Trusted Publishing/OIDC**，无需保存长期 Secret： @@ -38,7 +36,7 @@ vMAJOR.MINOR.PATCH 目前仓库已经配置该 Secret，可作为 OIDC 配置完成前的回退。Microsoft 已宣布全局 PAT 将于 2026-12-01 退役，应尽快迁移到 Trusted Publishing/OIDC。 -#### JetBrains Marketplace 首次上架 +### JetBrains Marketplace 首次上架 第一次必须手动创建插件： @@ -50,7 +48,7 @@ vMAJOR.MINOR.PATCH 第一次创建成功之后，标签工作流才能通过 API 上传后续版本。 -#### JetBrains 发布 Token +### JetBrains 发布 Token Secret：`JETBRAINS_TOKEN` @@ -59,7 +57,7 @@ Secret：`JETBRAINS_TOKEN` 3. 立即复制只显示一次的永久 Token。 4. 保存为父仓库 Secret `JETBRAINS_TOKEN`。 -#### JetBrains 签名密钥 +### JetBrains 签名密钥 Secrets： @@ -82,7 +80,7 @@ openssl req -key private.pem -new -x509 -days 365 -out chain.crt GitHub Secret 支持多行文本，可直接粘贴 PEM/CRT 全文；也可先 Base64 编码为单行。不要提交私钥、证书或密码。证书到期前需生成新证书并更新对应 Secrets。 -### 每次发布 +## 每次发布 > **推荐用一键脚本**：`npm run release -- --minor`（或 `sh scripts/release.sh --minor`， > Windows 可用 `scripts/release.ps1`）。它会自动完成下面全部步骤——同步七处版本、 @@ -144,157 +142,9 @@ git push origin v0.6.0 6. 有 `VSCE_PAT` 时发布 Visual Studio Marketplace。 7. 有完整 JetBrains Token 和签名 Secrets 时发布 JetBrains Marketplace。 -### 失败处理 +## 失败处理 - 不要移动或强制覆盖已经推送的标签。 - 标签构建失败时，修复后提升补丁版本，例如从 `0.6.0` 改为 `0.6.1`，再推送新标签。 - 标签和 GitHub Release 都不可复用；两个 Marketplace 也拒绝重复版本。 - 如果只缺 Marketplace Secret，GitHub Release 仍会创建并提供两个离线安装包。 - ---- - -## English - -### One-time Configuration - -All Secrets are added to the parent repo: - -**Settings → Secrets and variables → Actions → New repository secret** - -#### Visual Studio Marketplace - -It is recommended to configure **Trusted Publishing/OIDC** for Visual Studio Marketplace, avoiding long-lived Secrets: - -1. Go to the Visual Studio Marketplace Publisher/extension management page. -2. Add a Trusted Publishing policy for `AliceJump.ok-script-toolkit`. -3. Fill in GitHub repo as `AliceJump/ok-script-toolkit`, workflow as `release.yml`, and environment as required by the Marketplace page (or leave empty). -4. Add `VSCE_USE_OIDC=true` in the parent repo under **Settings → Secrets and variables → Actions → Variables**. -5. The tag workflow already has `id-token: write` granted; when `VSCE_PAT` is not configured and this variable is `true`, it will execute `vsce publish --oidc`. - -If continuing with PAT for now, add Secret: `VSCE_PAT` - -1. Open the Azure DevOps Personal Access Tokens page. -2. Create a new Token, selecting **All accessible organizations** for Organization. -3. Select **Custom defined**, expand all permissions, and check only **Marketplace → Manage**. -4. Copy the Token immediately after creation and save as `VSCE_PAT`. -5. Ensure the account that created the Token is a member of Visual Studio Marketplace Publisher `AliceJump`. - -The repo already has this Secret configured as a fallback before OIDC setup is complete. Microsoft has announced global PATs will retire on 2026-12-01; migration to Trusted Publishing/OIDC should be done as soon as possible. - -#### JetBrains Marketplace First Listing - -The first time requires manual plugin creation: - -1. Log in to https://plugins.jetbrains.com/author/me. -2. Select **Add new plugin**. -3. Build the ZIP locally: `cd jetbrains && ./gradlew buildPlugin`. -4. Upload `build/distributions/ok-script-toolkit-jetbrains-.zip`. -5. Confirm the Plugin XML ID is `com.alicejump.okscripttoolkit`, complete license, source code, issue tracker info, and submit for review. - -After the first successful creation, the tag workflow can upload subsequent versions via API. - -#### JetBrains Release Token - -Secret: `JETBRAINS_TOKEN` - -1. Open https://plugins.jetbrains.com/author/me/tokens. -2. Select **Generate Token** and enter a name. -3. Copy the permanent Token immediately (shown only once). -4. Save as parent repo Secret `JETBRAINS_TOKEN`. - -#### JetBrains Signing Keys - -Secrets: - -- `JETBRAINS_PRIVATE_KEY` -- `JETBRAINS_PRIVATE_KEY_PASSWORD` -- `JETBRAINS_CERTIFICATE_CHAIN` - -Generate using OpenSSL: - -```bash -openssl genpkey -aes-256-cbc -algorithm RSA \ - -out private_encrypted.pem -pkeyopt rsa_keygen_bits:4096 -openssl rsa -in private_encrypted.pem -out private.pem -openssl req -key private.pem -new -x509 -days 365 -out chain.crt -``` - -- `JETBRAINS_PRIVATE_KEY`: Full text of `private.pem`. -- `JETBRAINS_PRIVATE_KEY_PASSWORD`: Password set in the first command and used in the second. -- `JETBRAINS_CERTIFICATE_CHAIN`: Full text of `chain.crt`. - -GitHub Secrets support multi-line text; you can paste PEM/CRT full text directly, or Base64-encode to a single line first. Never commit private keys, certificates, or passwords. Generate new certificates and update corresponding Secrets before expiration. - -### Each Release - -> **Prefer the one-shot script**: `npm run release -- --minor` (or `sh scripts/release.sh --minor`; -> Windows can use `scripts/release.ps1`). It performs every step below automatically — syncing the -> seven version locations, verifying, committing/pushing sub-repo then parent, and finally tagging. -> Add `--dry-run` to preview first. The script only runs on the `main` branch -> (required for both the parent repo and the jetbrains submodule) and refuses -> otherwise — the release commit lands on whatever branch it runs from (hit on v1.12.0). -> If releasing manually, follow the order below exactly and -> **do not skip any step**. - -On Windows, `scripts/release.ps1` first stashes uncommitted changes separately in the -parent and JetBrains repositories, including untracked files but excluding ignored files. -The release uses committed code; automatic version increments use the version in `HEAD`. -It attempts to restore this run's stashes and the original staging state afterward, -without touching existing stashes. Conflicting stashes are retained and their commit IDs -are printed. Uncommitted version changes left by a failed release are stashed separately; -successful commits or pushes are not rolled back. PowerShell uses `-DryRun` to preview -without stashing or releasing. The Shell script still requires clean workspaces. - -Run `node scripts/test_release.js` to verify the PowerShell release flow. It requires -`git`, `node`, and `pwsh`, and uses temporary repositories and local remotes only. - -For example, releasing `0.6.0`: - -```bash -# 1. Sync all seven version locations: package.json, package-lock.json, jetbrains/gradle.properties -# and all four README version badges (missing any one causes Release validation failure) -npm run version:sync -- 0.6.0 - -# 2. Verify -npm test -cd jetbrains -./gradlew test buildPlugin verifyPluginStructure verifyPluginConfiguration -cd .. - -# 3. Commit sub-repo version changes first -cd jetbrains -git add . -git commit -m "chore(release): prepare v0.6.0" -git push origin main -cd .. - -# 4. Then commit parent repo version, README badge, and new submodule pointer -# Note: README.md must be committed together — version:sync modifies its badge, -# and verify-version.js checks it in the tag pipeline (a missing commit in 2026-09 -# caused v1.6.0 validation failure) -npm run verify:version -git add package.json package-lock.json README.md jetbrains -git commit -m "chore(release): prepare v0.6.0" -git push origin main - -# 5. The only release action: create and push a new tag -git tag -a v0.6.0 -m "Release v0.6.0" -git push origin v0.6.0 -``` - -Tag release proceeds as: - -1. Check out the parent repo and pinned JetBrains submodule commit. -2. Validate all seven version locations (`package.json`, `package-lock.json`, `jetbrains/gradle.properties`, and all four README badges) match the tag exactly. -3. Test and build VSIX. -4. Test, validate, build, and sign the JetBrains ZIP using the Secrets. -5. Create a GitHub Release with both installers attached. -6. Publish to Visual Studio Marketplace if `VSCE_PAT` is present. -7. Publish to JetBrains Marketplace if complete JetBrains Token and signing Secrets are present. - -### Failure Handling - -- Do not move or force-push a tag that has already been pushed. -- When a tag build fails, fix the code, bump the patch version (e.g., `0.6.0` → `0.6.1`), and push a new tag. -- Tags and GitHub Releases are not reusable; both Marketplaces also reject duplicate versions. -- If only Marketplace Secrets are missing, the GitHub Release is still created with both offline installers available. diff --git a/docs/box-resources.en.md b/docs/box-resources.en.md new file mode 100644 index 0000000..7f61e2f --- /dev/null +++ b/docs/box-resources.en.md @@ -0,0 +1,198 @@ +# Box Resource Design + +[简体中文](box-resources.md) | [English](box-resources.en.md) + +Local status, 2026-10-01: both hosts have box editing, publication, runtime galleries, completion, and source preview entry points; see [feature parity](feature-parity.en.md). This document retains data contracts and implementation order. Section 1 describes the pre-change foundation; section 10 is not a current TODO list. Actual project `ScreenPosition` loading is outside this repository's acceptance. + +Box management follows template management, with two resources. The annotation working copy is edited by the plugin only. The runtime copy is a published position table read by box management and `self.pos` completion. The game uses it only after the business project's `ScreenPosition` loads it; current ok-framework template matching still reads only `template_matching.coco_feature_json`. Reuse existing images, canvas, and visibility handling. + +This document is an implementation reference. The real call in ok-neverness-to-everness (ok-nte) is `self.pos.screen.main_viewport.to_box()`, not `self.pos.main_viewport`; there is no `screen_pos`. + +## 1. Existing Capabilities + +The toolkit already separates two template paths. + +| | Annotation resource | Runtime resource | +|---|---|---| +| File | `/coco_annotations.json`; default directory `ok_templates` | `config.py`'s `template_matching.coco_feature_json`; otherwise probe `assets/coco_annotations.json` and `ok_tasks/assets/coco_annotations.json` | +| Readers/writers | Annotation management (asset panel) | Template gallery, completion, Hover; ok-framework template matching | +| Transfer | Explicit Export to assets; editing does not automatically write runtime files | | + +The annotation editor (`AnnotationDialog` / `media/annotationPanel`) already supports selection, dragging, eight-direction resizing, add/delete, zoom, pan, undo, copy/paste, and image navigation. Memory uses pixel `xywh`; disk uses COCO `bbox`. `NormalizedBox` only serves coordinate copying: it is neither persisted nor ok-script's `Box`. + +Previously, the editor had no annotation list or visibility controls. Hiding and deletion were the same operation. + +The template gallery reads runtime COCO only. A click inserts `fL.`. Region previews dynamically crop the source image with pixel bbox; cache keys combine image-content hash and bbox. Quick Documentation and Hover share that crop. JetBrains lookup entries show dimensions on the right; VS Code adds the image to documentation when resolving a completion entry. + +This repository has no business Point resource or position table. + +## 2. ok-nte pos / Box + +The handwritten Python position table lives in `src/scene/`. + +- `self.pos` is a `PositionMap`, created in `BaseNTETask`. +- `self.pos.screen` contains rectangles: currently `center`, `dialog_icon`, and `main_viewport`, using four screen-relative `(left, top, right, bottom)` values. +- `self.pos.panels.*` contains two-value click points, unpacked with `*self.pos.panels.esc.mail`. Calling `to_box()` on a point raises an error. +- `ScreenRatio.to_box()` calls `box_of_screen(..., hcenter=True)` to create a pixel `ok.Box` for the current captured frame. `hcenter` applies at call time and must not enter resources. +- A descriptor sets `Box.name` to `ScreenPosition.` for debugging only. Search regions are not matched by that name. +- Approximately 73 task-private `box_of_screen(...)` calls explicitly remain outside the position table; box resources do not absorb them. +- Runtime does not depend on the IDE plugin. + +## 3. Two Box Resources + +| | Templates | Boxes | +|---|---|---| +| Annotation resource | `