add-action
新增 IDEA Action(菜单项 / 工具栏按钮),含后台扫描套路
- License 许可
- MIT
- 最近更新
- 2026-08-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- add-action
- description
- 新增 IDEA Action(菜单项 / 工具栏按钮),含后台扫描套路
03 SKILL.md 正文
/add-action — 新增 Action
新增一个 IDEA AnAction:菜单项、工具栏按钮、右键菜单或快捷键。默认配套写一个后台扫描套路,避免阻塞 EDT。
Usage
/add-action [ActionName]
ActionName— PascalCase Java 类名,例如RebuildSkillsIndexAction、ExportSkillReportAction。
Information Needed
- Action 标题 / 描述 — i18n key
action.{xxx}.title/.description。 - 挂载位置 —
EditorPopupMenu(编辑器右键)、MainMenu(主菜单)、ProjectViewPopupMenu(项目树右键)、ToolsMenu等。 - 是否需要图标 — 没有则只走文字;需要先走
/add-icon。 - 执行体是否耗时 — > 100ms 必须走后台
Task.Backgroundable。 - 可见 / 可用条件 — 例如"仅当有 project 时启用"、"仅在 SKILL.md 上启用"。
Files to Create/Modify
1. Action 类:src/main/java/dev/dong4j/idea/skill/inspector/action/{ActionName}.java
同步 / 轻量场景(< 100ms)
public class {ActionName} extends AnAction {
public {ActionName}() {
super(
SkillInspectorBundle.message("action.{xxx}.title"),
SkillInspectorBundle.message("action.{xxx}.description"),
SkillInspectorIcons.SKILL_INSPECTOR_16 // 没图标就传 null
);
}
@Override
public void actionPerformed(@NotNull AnActionEvent e) {
Project project = e.getProject();
if (project == null) {
NotificationUtil.showError(null, SkillInspectorBundle.message("error.no.project"));
return;
}
// TODO: 业务
}
@Override
public void update(@NotNull AnActionEvent e) {
e.getPresentation().setEnabledAndVisible(e.getProject() != null);
}
@Override
@NotNull
public ActionUpdateThread getActionUpdateThread() {
return ActionUpdateThread.BGT;
}
}
后台扫描场景(推荐范式)
参考 SkillInspectorAction:把 actionPerformed 拆成"后台扫描 → EDT 发布结果"两段。
@Override
public void actionPerformed(@NotNull AnActionEvent e) {
Project project = e.getProject();
if (project == null) {
NotificationUtil.showError(null, SkillInspectorBundle.message("error.no.project"));
return;
}
ProgressManager.getInstance().run(new Task.Backgroundable(
project,
SkillInspectorBundle.message("action.{xxx}.title"),
true // canBeCancelled
) {
@Override
public void run(@NotNull ProgressIndicator indicator) {
// 1. 在后台 + read action 内做重活(PSI / VFS 访问必须在 read action)
Result result = ApplicationManager.getApplication()
.runReadAction((Computable<Result>) () -> doScan(project, indicator));
// 2. 切回 EDT 写 UI(通知、激活 ToolWindow、打开文件等)
ApplicationManager.getApplication().invokeLater(() -> publish(project, result));
}
});
}
关键约束:
actionPerformed在 EDT 上执行:不要直接做 PSI 遍历或文件 IO,否则会卡 UI。- PSI / VFS 访问必须在 read action 内:
ApplicationManager.getApplication().runReadAction(...),否则会触发Read access is allowed from inside read-action only。 - 写 UI(通知、ToolWindow、打开文件)必须在 EDT:用
invokeLater。 getActionUpdateThread()必须实现:2024.2+ 强制要求,绝大多数情况返回BGT(Background Thread),让 IDE 在后台线程做update()计算。update()里禁止做耗时操作:只读e.getProject()/ 当前文件等廉价数据。
2. 扫描结果模型(小工程不用 record)
private static final class ScanSummary {
final int totalFiles;
final int totalErrors;
@Nullable final VirtualFile firstHit;
ScanSummary(int totalFiles, int totalErrors, @Nullable VirtualFile firstHit) { ... }
@NotNull
static ScanSummary empty() { return new ScanSummary(0, 0, null); }
}
用普通类而不是 record 是项目惯例:方便在 read action 与 EDT 之间传递并保留可读字段名。
3. 注册:src/main/resources/META-INF/plugin.xml
<actions>
<action id="dev.dong4j.idea.skill.inspector.action.{ActionName}"
class="dev.dong4j.idea.skill.inspector.action.{ActionName}">
<add-to-group group-id="EditorPopupMenu" anchor="last"/>
</action>
</actions>
参考:
<!-- 插件定义的动作 -->
<actions>
<!-- 编辑器右键菜单 -->
<action id="dev.dong4j.idea.skill.inspector.action.SkillInspectorAction"
class="dev.dong4j.idea.skill.inspector.action.SkillInspectorAction">
<add-to-group group-id="EditorPopupMenu" anchor="last"/>
</action>
</actions>
关键约束:
id必须是全限定类名:保持与 GitLens 等成熟插件一致的可追溯性,便于在Help → Find Action里搜到。<add-to-group>的group-id:常用值EditorPopupMenu、ProjectViewPopupMenu、ToolsMenu、MainToolbarLeft、EditorTabPopupMenu。- 如果要支持快捷键:用
<keyboard-shortcut keymap="$default" first-keystroke="..."/>,但要先到 keymap 注册表 检查是否冲突。
4. 国际化
action.{xxx}.title=My Action
action.{xxx}.description=Detailed description shown in tooltip
详见 /add-i18n-key。
5. 完成反馈
操作完成后用 NotificationUtil 通知用户,详见 /add-notification。
ToolWindow / Problems View 激活
如果你的 Action 跑完要把 IDE 视图切到某面板:
ToolWindow problems = ToolWindowManager.getInstance(project).getToolWindow("Problems View");
if (problems != null) {
problems.show();
}
常见 ToolWindow ID:Problems View、Project、TODO、Run、Debug、Version Control、Terminal。
Build & Verify
./gradlew compileJava
./gradlew runIde
# 在 IDE 实例中:右键编辑器 / 打开 Help → Find Action → 搜你的 Action 名 → 触发并观察通知
Troubleshooting
Action class not found in classpath:plugin.xml 里的class写错了全限定名。Read access is allowed from inside read-action only:在后台线程访问了 PSI,套一层runReadAction。Cannot access disposed project:长任务完成时 project 已经关闭。在 EDT 段开头加if (project.isDisposed()) return;,参考SkillInspectorAction.publishResult()。update()在 2024.2+ 报Cannot determine action update thread:必须实现getActionUpdateThread()返回BGT或EDT。ProgressIndicator不更新进度条:必须在循环内调indicator.checkCanceled()+setFraction(...)+setText2(...),参考SkillInspectorAction.scanProject()。
参考代码
- 完整范式(后台扫描):
src/main/java/dev/dong4j/idea/skill/inspector/action/SkillInspectorAction.java - plugin.xml 注册:
src/main/resources/META-INF/plugin.xml
04 同仓库更多 Skills
unused-reference-resource
Use this skill when `references/` contains files that are never linked from the body.
short-description
too short
security-sensitive-path
Use this skill when verifying detection of sensitive paths like `.env` or `~/.ssh` in the body.
security-secret
Use this skill when verifying detection of leaked secret patterns in the body.
security-prompt-injection
Use this skill when verifying detection of prompt-injection phrases such as "ignore previous instructions".
security-dangerous-command
Use this skill when verifying detection of dangerous shell commands in the body.