add-notification
在 IDEA 插件中通过统一通知组发送气泡通知(信息 / 警告 / 错误)
- License 许可
- MIT
- 最近更新
- 2026-08-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- add-notification
- description
- 在 IDEA 插件中通过统一通知组发送气泡通知(信息 / 警告 / 错误)
03 SKILL.md 正文
/add-notification — 发送通知
通过项目统一的 NotificationUtil 工具类发送一条气泡通知。项目惯例:所有通知共用一个通知组 Skill Inspector Notifications,避免在
Settings → Notifications 里散落多个开关。
Usage
/add-notification [type] [message-key]
type—info/warning/errormessage-key— i18n key(不要直接写死字符串)
Information Needed
- 触发场景 — Action 完成、Quick Fix 失败、扫描结果汇总……
- 严重度 — INFORMATION(绿)/ WARNING(黄)/ ERROR(红)。
- 是否需要操作链接 — 例如"点击查看详情"。
- 是否在没有 project 时也要发 — 如插件加载失败提示,传
project=null。
Files to Create/Modify
不需要新建文件,直接调用 NotificationUtil
import dev.dong4j.idea.skill.inspector.util.NotificationUtil;
import dev.dong4j.idea.skill.inspector.util.SkillInspectorBundle;
NotificationUtil.showInfo(project, SkillInspectorBundle.message("xxx.completed"));
NotificationUtil.showWarning(project, SkillInspectorBundle.message("xxx.has.errors"));
NotificationUtil.showError(project, SkillInspectorBundle.message("xxx.failed"));
参考:
public static void showInfo(@Nullable Project project, @NotNull String message) {
notify(project, message, NotificationType.INFORMATION);
}
/**
* 显示警告通知
* <p> 调用 IntelliJ Platform 的通知系统显示警告信息
*
* @param project 项目对象, 可以为空
* @param message 要显示的警告内容, 不能为空
*/
public static void showWarning(@Nullable Project project, @NotNull String message) {
notify(project, message, NotificationType.WARNING);
}
/**
* 显示错误通知
* <p> 在指定的项目中显示错误级别的通知信息
*
* @param project 项目对象, 可以为空
* @param message 错误通知的内容, 不能为空
*/
public static void showError(@Nullable Project project, @NotNull String message) {
notify(project, message, NotificationType.ERROR);
}
严重度选择指南
| 场景 | 选哪个 |
|---|---|
| 任务成功完成、纯信息提示 | showInfo |
| 任务完成但发现需要用户关注的问题(如扫到 N 个 warning) | showWarning |
| 任务失败、操作被拦截 | showError |
| 重大异常 / 需要用户立刻处理 | 用 showError 并附操作链接(见下方扩展) |
参考用法:
String message = SkillInspectorBundle.message(
"action.validate.skill.completed",
summary.totalFiles,
summary.totalErrors,
summary.totalWarnings
);
if (summary.totalErrors > 0 && summary.firstErrorFile != null) {
NotificationUtil.showWarning(project, message);
// 自动把第一个有错的 SKILL.md 打到编辑器前台, 方便用户立刻处理.
FileEditorManager.getInstance(project).openFile(summary.firstErrorFile, true);
} else if (summary.totalErrors > 0) {
NotificationUtil.showWarning(project, message);
} else if (summary.totalWarnings > 0) {
NotificationUtil.showInfo(project, message);
} else {
NotificationUtil.showInfo(project, message);
}
通知组(已注册,不要新建)
通知组 ID 在 plugin.xml 中注册:
<!-- 通知组 -->
<!--suppress PluginXmlI18n -->
<notificationGroup id="Skill Inspector Notifications"
displayType="BALLOON"
isLogByDefault="true"/>
关键约束:
displayType选BALLOON(项目惯例):右下角气泡,不阻塞、可被用户在 Settings 里调成 STICKY_BALLOON / TOOL_WINDOW / NONE。isLogByDefault="true":确保通知历史可在Event Log里回看,方便用户查证。- 不要为新功能建新通知组:除非语义完全不同(例如"自动同步"vs"规则检查"分得很开),否则一律复用
Skill Inspector Notifications。
扩展:附操作链接
如果通知需要用户点击执行某个 Action(例如"查看详情"),用 Notification.addAction():
Notification notification = NotificationGroupManager.getInstance()
.getNotificationGroup("Skill Inspector Notifications")
.createNotification(PluginContents.PLUGIN_NAME, message, NotificationType.WARNING);
notification.addAction(NotificationAction.createSimple(
SkillInspectorBundle.message("notification.action.open.problems"),
() -> {
ToolWindow tw = ToolWindowManager.getInstance(project).getToolWindow("Problems View");
if (tw != null) tw.show();
}
));
notification.notify(project);
当前
NotificationUtil只暴露三个无操作链接的便捷方法。如果某个 skill 一定要带操作链接,要么在调用处直接用上面的原生 API,要么扩展NotificationUtil加一个showWithAction(...)方法(注意保持 i18n + bundle key 同步)。
i18n 文案
xxx.completed=Operation completed: {0} files processed
xxx.failed=Operation failed: {0}
notification.action.open.problems=Open Problems View
详见 /add-i18n-key。
Build & Verify
./gradlew compileJava
./gradlew runIde
# 在 IDE 实例触发动作 → 右下角应弹出气泡,且 Event Log 中可见同条记录
Troubleshooting
Notification group not registered: ...:通知组 ID 与plugin.xml不一致。NotificationUtil.NOTIFICATION_GROUP_ID常量与<notificationGroup id="...">必须 byte-for-byte 相同。- 气泡不出现:用户可能在
Settings → Notifications把对应组关成了 NONE;可在 Event Log 中确认通知是否真的发出。 PluginXmlI18n警告:通知组的id是英文常量,IntelliJ 静态检查会要求加 i18n,本项目已用<!--suppress PluginXmlI18n -->抑制。新增通知组沿用相同抑制即可。- 通知里换行不生效:
message用<br/>而不是\n(IntelliJ 通知支持简单 HTML)。 - 没有 project 时通知 NPE:用
NotificationUtil.showError(null, ...),工具类已经处理 nullable。
参考代码
- 工具类:
src/main/java/dev/dong4j/idea/skill/inspector/util/NotificationUtil.java - 通知组注册:
src/main/resources/META-INF/plugin.xml - 调用范式:
src/main/java/dev/dong4j/idea/skill/inspector/action/SkillInspectorAction.java - IntelliJ 官方文档:https://plugins.jetbrains.com/docs/intellij/notifications.html
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.