Repository navigation
UserGuide zh CN.md
本指南对应 0.1.4，依据当前插件实现编写。NikoTools 将常用脚本保存为列表，执行前生成参数表单，并在 IDE 原生 Run 控制台显示结果。脚本库与环境路径属于 IDE 用户级配置，跨项目共享；执行时的工作目录、参数文件选择和 Android 设备来自当前项目窗口。
最低平台版本为 242（IntelliJ IDEA 2024.2 系列），字节码要求 Java 21；使用符合要求的 IDE 自带运行时即可，不需要为了使用插件单独配置开发 JDK。项目以 IDEA 2024.2.6 为构建基线，面向 Android Studio、IntelliJ IDEA、PyCharm 等 IntelliJ Platform IDE。不同产品的版本号不完全相同，应以平台构建号和实际兼容性为准。
- 获取项目构建的
NikoTools-0.1.4.zip；本地构建方法见项目 README。 - 打开 IDE 的 Settings / Preferences → Plugins → 齿轮 → Install Plugin from Disk，选择 ZIP。
- 按 IDE 提示重启，打开项目，通过 Tools → NikoTools 或侧边 NikoTools 图标打开工具窗口。
- 插件发布到 Marketplace 后，也可通过对应 Marketplace 页面安装。项目中的发布配置并不表示已经上架。
插件不附带 Python、PowerShell、Bash、cmd、adb 或 scrcpy。只需准备脚本实际使用的工具：Python 脚本需要 Python，Bash 脚本需要 Bash，普通脚本不需要 Android 设备或 adb。
打开 Settings → NikoTools，或工具窗口顶部的“环境路径”，可填写以下可执行文件的绝对路径：
| 设置项 | 用途 |
|---|---|
python |
Python 解释器；虚拟环境可选择其 Python 可执行文件 |
powershell |
PowerShell，通常是 pwsh 或 Windows 的 powershell.exe
|
bash |
Bash；Windows 默认使用已安装的 Git Bash |
cmd |
Windows 批处理解释器 cmd.exe
|
adb |
Android 调试工具 |
scrcpy |
Android 屏幕镜像工具 |
留空时显示自动解析到的默认路径（灰色提示及下方完整路径）；未检测到时明确提示。显示默认路径不会保存为手动配置。默认使用 IDE 进程继承的 PATH；Windows 的 Bash 优先使用 PATH 对应的 Git 安装，并检测常见的系统与用户 Git 安装目录。其他系统的 Bash 使用 PATH。脚本级解释器路径优先于全局设置，全局设置优先于默认环境解析。显式配置的路径无效时会报错，不自动回退。修改系统 PATH 后通常需要重启 IDE；终端临时激活的虚拟环境不会自动传递给插件。
以 Python 为例，先确保 IDE 能找到 Python，或在“环境路径”中指定它。
-
打开 NikoTools，点击顶部“新建脚本”图标。
-
名称填写
问候，执行类型选择python。 -
正文填写：
import sys print("Hello, " + sys.argv[1])
-
展开“执行配置”，在“参数数组 JSON”中填写：
["${姓名:World}"] -
其余配置保持默认并点击“保存”。
-
双击列表中的脚本，在“运行参数”弹窗输入姓名，点击“执行”。“执行后保留弹窗”默认不勾选，执行后关闭；勾选后保留弹窗，可修改参数再次执行。点击“关闭”结束填写。弹窗不阻塞 IDE 操作，同一项目中重复打开同一脚本会聚焦已有弹窗，运行期间不会重复启动脚本。
-
在 IDE 的 Run 窗口查看
Hello, World（或你输入的姓名）以及退出码。
这个示例把用户输入作为独立进程参数传递，正文无需拼接输入。没有占位符的脚本直接启动，不显示参数表单。
顶部工具栏包含七个入口，悬停图标可查看名称：
| 入口 | 操作 |
|---|---|
| 新建脚本 | 创建名称、说明、执行类型及正文 |
| 批量操作 | 导入目录或导出整个脚本库 |
| 导入 | 从剪贴板读取脚本 JSON |
| 排序 | 按使用频率、添加顺序或名称排序 |
| 环境路径 | 配置全局解释器和工具路径 |
| 帮助 | 直接打开“脚本模板与参数语法”弹窗 |
| 复制 SKILL | 将完整的脚本参数转换技能复制到剪贴板，供 AI 编写插件脚本使用 |
列表展示名称、类型、说明。双击脚本执行；右键脚本行可“执行脚本”“编辑脚本”“分享脚本”“删除脚本”。选中后也可按 Shift+F10 或菜单键打开菜单。选中单个脚本后按 Delete 也可弹出删除确认（macOS 支持 Backspace）。顶部“排序”提供使用频率（高到低）、添加顺序（先添加在前）、名称（忽略大小写升序）三种方式，并持久化选择。使用频率按实际启动次数累计，再次运行计入，取消或启动失败不计入；同频率或同名时保留添加顺序。删除需要确认；右键或双击空白处不会操作脚本。
点击顶部“帮助”或编辑器中的“脚本模板与参数语法”可打开帮助弹窗，采用左右布局，左侧列表选择模板，右侧自动切换语法说明与参考代码，代码下方内嵌参数输入与实时替换结果预览，可分别复制原始代码和预览结果。预览仅查看替换结果，不运行命令。复制后粘贴到脚本正文，调整执行类型及配置再保存。当前没有独立模板库或“保存为模板”入口。内置完整脚本示例为“全部参数类型演示 Bash”，覆盖十种类型、默认值和重复引用；路径 1、2 与令牌 1009 是演示值，示例最后会输出令牌内容。
点击工具栏“复制 SKILL”，可将完整的脚本参数转换技能复制到剪贴板，与业务需求或原脚本一起交给 AI。该技能指导 AI 将运行前的用户输入转换成参数控件和 var 声明，保留脚本语言与业务逻辑；按钮不会自动安装技能。
安装并启用 IDE Terminal 插件后，可在支持的本地终端选中文本，右键选择“新建 NikoTools 自定义脚本”。选区进入编辑器，保存前不会执行。新建脚本默认类型为 powershell；从 Bash/Python 等终端复制内容后应改为对应类型。Terminal 为可选依赖，缺少它不影响脚本列表和执行。
| 类型 | 正文含义 | 适合场景 |
|---|---|---|
powershell |
交给 PowerShell 执行的命令或脚本正文 | PowerShell 自动化、Windows 管理命令 |
python |
Python 代码，或可识别的现有 Python 脚本文件路径 | 数据处理、文件工具、多行逻辑 |
bash |
交给 bash -c 执行的命令正文 |
macOS/Linux 命令、管道与重定向 |
batch |
Windows 批处理正文，或现有批处理文件路径 |
.bat / .cmd 脚本 |
process |
一个可执行文件路径或名称，参数另填 JSON 数组 | 直接启动 git、adb、scrcpy 等工具 |
process 在列表中显示为“外部进程”。正文应为 git，参数数组为 ["status", "--short"]；不要把 git status --short 全部写进正文。它不经过 Shell，不解析管道、重定向或 Shell 变量，也不需要单独的脚本解释器。只执行一个程序时很合适；需要多条命令或 Shell 语法时选择相应语言。
Python 正文若为一行，且首个解析项指向工作目录下存在的文件，会按脚本文件启动；否则作为 Python 代码写入临时文件。路径含空格时可在正文中加双引号；建议把参数写到参数数组。Bash 和 PowerShell 的文件调用使用各自语言语法，例如 Bash 的 bash "./scripts/task.sh"、PowerShell 的 & './scripts/task.ps1'。批处理文件的参数使用参数数组，不依赖正文路径后的参数。
类型决定运行方式，不代表自动跨平台转换。batch 需要 Windows cmd；Bash、PowerShell、Python 是否可用取决于本机安装。
插件从正文、参数数组、环境变量值、工作目录识别占位符，保存时生成参数表单。解释器路径不参与模板解析。
| 写法 | 含义 |
|---|---|
${名称} |
文本输入，无内联默认值 |
${名称:默认值} |
文本输入及默认值 |
${名称=默认值} |
兼容旧格式的默认值 |
${模式:开启=1|关闭=0} |
下拉项；显示中文标签，替换为 1 或 0，默认第一项 |
${名称@text:示例} |
显式单行文本，不根据内容推断下拉选项 |
${说明@multiline} |
多行文本输入，保留换行 |
${重试次数@integer:3} |
整数输入，执行前校验 |
${比例@number:0.5} |
数字输入，支持整数和小数，执行前校验 |
${启用缓存@boolean:true} |
复选框；true/1 默认勾选，false/0 或无默认值时不勾选；输出 True/False
|
${模式@choice:开启=1|关闭=0} |
显式下拉单选；默认第一项，输出实际值 |
${环境@radio:开发=dev|生产=prod} |
单选按钮组；默认第一项，输出实际值 |
${访问令牌@secret} |
密码输入；支持设为默认值及显示/隐藏密码，帮助预览显示星号 |
${输入文件@file} |
文件选择器 |
${输出目录@dir} |
目录选择器；元数据类型名为 directory
|
${输入文件@file:./data.txt} |
文件输入及内联默认路径 |
参数名称支持中文、字母、数字和下划线，不包含空格。重复使用同一个参数名称会共用输入；重复定义的类型、默认值或选项冲突会报错。表格中的 \| 仅为 Markdown 转义，实际脚本写 |。
统一格式为 ${名称@类型:默认值或选项}；类型省略时保留旧解析规则。@choice 和 @radio 必须提供选项，支持仅一个选项，选项标签不能为空或重复、实际值不能为空。@text 和 @multiline 等显式输入类型将 A=1|B=2 当作普通内容。重复的裸引用 ${名称} 共用已定义的参数类型；显式类型冲突会报错。分享脚本会移除输入默认值并保留类型和选项定义。密码输入支持通过“设为默认值”保存内容，并通过眼睛图标切换显示或隐藏。参数标题不显示必填星号，必填校验仍然有效；单选按钮组横向排列。
可用声明将内部变量名与显示标签分开：
var file = ${输入文件路径@file}
var mode = ${模式:开启=1|关闭=0}
var output = ${输出目录@dir}
在后续正文、参数数组等处用 ${file}、${mode}、${output}。声明中的标识符是元数据 id，大括号中的名称是表单标签。推荐使用小写 var，兼容旧写法 Var 和 pVal，声明需单独占一行；声明行执行前会被移除，不是交给 Shell/Python 的变量定义。
点击文件或目录输入框的浏览按钮，优先打开输入框中的目录或文件所在目录（相对路径基于当前项目根目录）；文件或目录不存在时，逐级向上查找最近可打开的父目录，例如 A/B/C.txt 中 C 不存在时打开 B，B 也不存在时打开 A。路径为空、格式无效或没有可用父目录时，从当前 IDE 窗口打开的项目根目录开始，也可选择项目外路径；无项目根目录时使用 IDE 的默认行为。@file 用于选择文件，@dir 用于选择目录。浏览文件时可进入文件夹是正常导航；手工输入路径目前只检查必填，不检查路径是否存在或确为文件/目录。
模板使用字面替换，不自动转义引号、反斜线、换行或 Shell 特殊字符。把任意文本嵌入脚本正文时，需由脚本作者处理目标语言语法。传递路径或任意文本时优先使用参数数组，每个数组元素是一项参数。
运行弹窗中部分输入提供“设为默认值”，保存到脚本库后供后续使用；布尔、下拉、单选按钮组和设备控件没有此按钮，密码控件支持保存默认值。修改模板内容并保存时，会按模板重新同步默认值、文件/目录类型及下拉选项；未修改模板时保留已保存的自定义默认值。
参数数组支持条件项，例如 "?verbose:--verbose"：verbose 值为真时添加 --verbose，否则省略。布尔按 true（不区分大小写）或 1 判断，数字按非零判断，其他类型按非空判断。用于控制条件的参数也需通过模板声明；完整例子见后文。
日常创建脚本只需名称、类型、正文；以下设置按需要展开填写。
| 字段 | 默认行为 | 何时设置 |
|---|---|---|
| 工作目录 | 当前项目根目录 | 工具需在子目录运行；相对路径以项目根目录解析，目录必须存在 |
| 解释器路径 | 全局设置，然后 IDE 的 PATH | 为某脚本指定虚拟环境 Python 或不同解释器；process 时覆盖实际可执行程序 |
| 依赖工具 | 空 | 运行前检查额外工具，如 adb, scrcpy；当前类型的解释器本身会自动解析 |
| 输出编码 | utf-8 |
外部工具实际输出其他编码时，如 GBK；此项控制控制台解码 |
| 超时秒数 | 空，不限 | 正整数；超时后停止本次进程及可追踪子进程 |
| 参数数组 JSON | [] |
向程序传递独立参数，支持模板和条件项 |
| 环境变量 JSON | {} |
仅对本次子进程覆盖环境变量，支持值中的模板 |
参数数组示例：
["--input", "${输入文件@file}", "--output", "${输出目录@dir}"]环境变量示例：
{"APP_MODE": "${运行模式:dev}", "LOG_LEVEL": "info"}环境变量 JSON 是可选高级功能，普通脚本保持 {} 即可。插件继承 IDE 环境，并注入运行所需工具路径、设备序列号（如有）和输出目录。声明工具依赖后，对应工具目录加入本次 PATH，并提供 POPTOOLS_ADB、POPTOOLS_SCRCPY 等 POPTOOLS_<工具名大写> 路径变量。
插件设置 PYTHONUTF8=1、PYTHONIOENCODING=utf-8、PYTHONUNBUFFERED=1；这些 Python 环境值在自定义环境之后写入。POPTOOLS_OUTPUT_DIR 也由运行器生成。相关变量名称保留 POPTOOLS 前缀以兼容已有脚本。
Bash 参数数组对应 $1、$2 等（$0 固定为 poptool-script）；Python 对应 sys.argv；批处理对应 %1、%2 等。PowerShell 会将参数附加到 -Command 调用，应按 PowerShell 的调用语义编写正文。
元数据是参数表单的高级配置，默认从模板自动生成，不是创建普通脚本的必填项。十种普通控件可直接使用显式模板类型；需要可选参数、自定义标签或 Android 设备输入时再编辑 JSON 数组。
类型 kind
|
表单及规则 |
|---|---|
text |
单行文本 |
multiline |
多行文本 |
integer |
整数，提交时校验 |
number |
十进制数，提交时校验 |
boolean |
复选框，替换为 True / False
|
choice |
下拉选择，使用选项的 value；选项建议写在模板中 |
radio |
横向单选按钮组，使用选项的 value
|
file |
文件浏览输入 |
directory |
目录浏览输入 |
secret |
密码输入，遮蔽显示；模板替换仍使用真实文本 |
android_device |
当前 IDE 所选设备序列号，只读 |
字段说明：id 对应模板内部名称，label 为显示名称，required 控制非空校验，default 是默认值，options 是下拉或单选项的标签和值。兼容字段 placeholder 可保存在 JSON 中，但当前表单未显示该提示。
例如正文有 ${count:3}，元数据可写：
[
{
"id": "count",
"label": "重复次数",
"kind": "integer",
"required": true,
"default": "3",
"options": []
}
]先保存包含占位符的脚本，再编辑自动生成的元数据，最容易保持 id 一致。编辑器保存时只保留模板中使用的参数，未被引用的元数据会移除；显式类型、默认值及选项会随模板同步。兼容已有脚本中通过元数据设置 integer、boolean、secret 等类型的普通文本占位符；新脚本推荐直接使用显式 @类型。
secret 控件只负责遮蔽输入，不是加密存储。将其“设为默认值”会持久化真实内容，脚本输出或直接嵌入正文也可能展示它。
不需要指定脚本“是否为 adb 命令”，编辑器没有 auto / use / none 选择。运行时自动尝试读取当前项目 IDE 运行工具栏中唯一、在线、可用的 Android 设备，取得序列号后设置本次进程的 ANDROID_SERIAL。
普通脚本不依赖 Android 设备。未安装/启用 Android 插件、设备选择 API 不兼容、未选择设备、设备离线或选择多个设备时，不注入自动序列号，普通脚本仍可启动。仅选择设备也不会给普通脚本额外添加 adb 依赖。
- 在 Android Studio 或具有兼容 Android 插件的 IDE 中连接并授权设备。
- 在当前项目运行工具栏选择一个设备。
- 确保 adb 或 scrcpy 已安装，必要时配置其路径。
- 执行脚本。控制台显示取得的默认设备序列号。
若业务确实要求已选设备，可在依赖工具中填写 adb, android_device，或将一个被模板引用的参数设为 kind: "android_device"、required: true。此时无有效设备会阻止运行；非必填设备参数无设备时为空。
设备选择在运行开始时读取，执行中切换设备不会更新已启动进程。脚本环境中的显式 ANDROID_SERIAL 可覆盖自动值，adb -s SERIAL 按工具自身规则指定设备。没有自动值时，外部工具使用继承的环境和自身选设备规则，可能正常运行，也可能提示设备缺失或多设备；插件不扫描/连接设备，不重启 adb 服务。
旧 JSON 中的 android_device_mode 仍保留用于兼容存储与导入，不再控制执行。
- 输出进入当前项目的 IDE Run 标签，显示标准输出、错误、退出码及本次输出目录；不自动打印包含脚本正文的启动命令行。
- 同一脚本按 ID 复用标签，即使改名也复用；再次执行后旧输出清空。
- 启动中或运行中重复点击同一脚本，会切回已有控制台，不创建重复进程；不同脚本可并发。
- 绿色三角形“再次运行”按钮使用 IDE 标准运行图标，读取最新保存的脚本，并用上次输入初始化参数表单。
- “停止”或超时会终止本次进程及可追踪子进程，不停止共享 adb 服务。脚本主动脱离父进程的程序不保证可追踪。
- 运行进程的标准输入关闭，不支持需要实时输入的交互菜单、密码提示等；改用运行前参数表单或程序的非交互选项。
每次执行创建一个临时输出目录，通过 POPTOOLS_OUTPUT_DIR 提供给脚本并在控制台打印路径。普通 echo、print 只显示到控制台，不会自动写入文件；脚本可以主动将报告、截图等生成文件写入此目录。退出后临时 Python/批处理源文件会删除，空输出目录会清理，非空目录保留生成结果。目录位于系统临时目录，仍可能被系统清理；需要长期保存的结果应复制到项目或自选目录。
右键“分享脚本”复制 JSON，接收方复制整段 JSON 后点击顶部“导入”。支持：
-
poptools.custom-script的 v1 分享封装； - 原始 v1 自定义工具 JSON；
- 工具 JSON 数组；
- 包含
scripts数组的对象（剪贴板入口）。
分享会移除解释器路径、参数默认值和模板内联默认值，保留显式类型和下拉、单选按钮组选项。正文、环境变量中的普通字面内容与非默认路径仍保留；分享前应按实际内容检查，移除不希望分享的值。分享不复制外部脚本文件。
ID 或名称冲突时，可选“覆盖”（保留已有 ID）、“另存”（生成新 ID 和不重复名称）或“跳过”。批量导入逐条报告成功、跳过、失败，不因某一项失败回滚已成功项。未知字段、类型或版本会拒绝导入；internal、url 执行方式不支持，PopTool 托管环境或内部资源路径需要手动调整。
最小可导入示例（Python）：
{
"schema_version": 1,
"id": "custom.hello",
"title": "Hello Python",
"description": "输出一条问候",
"executor": {
"kind": "python",
"command": "print('Hello from NikoTools')"
}
}“批量操作 → 导出目录”选择目标目录后，会新建 poptool-scripts-时间戳：
poptool-scripts-时间戳/
├── tools/ # 脚本 JSON，保留默认值
└── scripts/ # 可迁移的外部脚本文件（如有）
“批量操作 → 导入目录”选择导出根目录，优先读取其中 tools 子目录，递归查找 JSON。目录文件使用单个工具/分享对象或工具数组；scripts 包装对象用剪贴板入口导入。导入前会备份当前库到 IDE 配置目录下的 poptool-backups/时间戳，来源文件不修改。
直接引用绝对路径 .py/.ps1/.sh/.bat/.cmd 文件的脚本导出时，插件会复制其所在目录的文件并改为相对入口；导入可迁移的相对入口时，将文件复制到 IDE 配置目录的 poptool-assets 并更新路径。符号链接不参与复制。动态引用、项目其他位置的资源、额外工具和解释器路径需另行迁移；目录导出不能视为完整项目打包。
批量导出与自动备份保留默认值，适合备份和换机；剪贴板分享会移除默认值，适合分享脚本定义。换机后重新配置外部工具路径。
执行类型 python，正文：
import pathlib
import sys
path = pathlib.Path(sys.argv[1])
print(path)
print(path.stat().st_size)参数数组 JSON：
["${输入文件@file}"]执行类型 bash，正文：
printf 'Directory: %s\n' "$1"
ls -la -- "$1"参数数组 JSON：["${目录@dir}"]。目录含空格时仍作为一项参数传递。
执行类型 powershell，正文：
var message = ${消息:你好}
var mode = ${模式:开启=1|关闭=0}
Write-Output '${message}'
Write-Output '${mode}'此例演示字面替换；消息中含单引号时须调整正文的字符串处理。
执行类型 process，正文 adb，参数数组 ["devices", "-l"]。它用于列出设备，无需 IDE 已选设备。如需读取所选设备属性，参数数组改为 ["shell", "getprop", "ro.product.model"]；取得的 ANDROID_SERIAL 为 adb 提供默认目标。希望强制有 IDE 所选设备时设置依赖 android_device。
执行类型 bash，正文：
var verbose = ${详细输出:False}
printf 'Argument: %s\n' "$@"参数数组 JSON：["?verbose:--verbose"]。保存后编辑 verbose 元数据，将 kind 改为 boolean。选中复选框时添加 --verbose，未选中时省略该参数；这个演示脚本只打印收到的参数。用于实际工具时将正文的打印替换为工具调用，例如 mytool "$@"。
| 问题 | 处理方法 |
|---|---|
| 找不到解释器/工具 | 检查是否安装、IDE 的 PATH 或 NikoTools 全局路径；显式无效路径必须修正或清空 |
| 终端能运行，插件不能运行 | 检查 IDE 启动时继承的环境、虚拟环境、工作目录和执行类型 |
process 提示找不到 git status
|
正文只写 git，其余移到参数数组 |
| 工作目录不存在 | 默认使用当前项目根目录；相对路径基于该根目录，创建目录或填写已有绝对目录 |
| 没有 Android 设备 | 普通脚本可继续；强制设备脚本需选择唯一在线且已授权设备，并启用兼容 Android 插件 |
| 文件输入能进入文件夹 | 属于浏览导航；选择目录参数用 @dir，文件参数用 @file
|
| 输出乱码 | 根据工具实际输出调整“输出编码”；Python 运行器默认请求 UTF-8 |
| 参数报错或 JSON 不能保存 | 使用标准 JSON 双引号，参数数组为数组、环境为对象、元数据为数组；检查重复定义和整数/数字格式 |
| 输入含引号后语法错误 | 占位符不自动转义，改用参数数组或按目标语言处理引号 |
| 脚本一直等待输入 | 插件不提供运行中 stdin，改用运行前参数或非交互方式 |
| 终端没有新建脚本菜单 | 确认 Terminal 插件启用并已有选区；不同终端实现需具备兼容选区 API |
| 项目 B 也看到了项目 A 的脚本 | 脚本库是 IDE 用户级共享；执行上下文仍来自当前窗口 |
持久化文件为 IDE 配置目录下的 options/poptool-scripts.xml，包含脚本库和工具路径；不是项目目录内的文件。目录备份在 poptool-backups，导入资源在 poptool-assets。不同 IDE 安装或配置目录之间不会自动共享，可使用批量迁移。
项目实现使用 Kotlin 和官方 Kotlin UI DSL，UI 文本当前为中文。完整构建、测试、兼容性验证及 Marketplace 发布步骤见项目 README。中英文 Overview 在 plugin.xml 的 description 中维护；重新构建并安装后可查看本地插件介绍，Marketplace 的更新需发布新版安装包。
插件源码及模板资源采用 MIT License；外部工具和 IDE 使用各自许可。