By name: plugin-quality description: "审查和改进 Zhin.js 插件质量。Use when asked to review plugin code, check code quality, audit plugin structure, refactor plugin, or improve plugin before publishing. 引导检查插件的结构规范性、代码健壮性、性能和安全性。" keywords: - 代码审查 - 质量检查 - review - 审计 - 重构 - refactor - 代码规范 - lint - quality tags: - development - quality - review
Zhin 插件质量审查
对 Zhin.js 插件进行全面质量审查，检查结构规范性、代码风格、性能问题和安全隐患，确保达到发布标准。
适用场景
- 用户说"检查一下插件质量"、"审查代码"、"发布前看看有没有问题"
- 插件开发完成，准备发布前的质量把关
- 重构现有插件使其更规范
审查维度
1. 结构规范性
检查项：
| 项目 | 要求 | 严重程度 |
|---|---|---|
| usePlugin() 位置 | 模块顶层调用 | 🔴 严重 |
| 导入路径 | TS 文件间使用 .js 扩展名 |
🔴 严重 |
| 框架导入 | 统一从 zhin.js 导入 |
🟡 中等 |
| 入口职责 | index.ts 只做装配，不堆业务 | 🟡 中等 |
| 目录布局 | 命令/中间件/服务分目录（多功能时） | 🟢 建议 |
| package.json | type:module、exports、files | 🔴 严重 |
常见错误：
// ❌ usePlugin 在 async 内调用
async function setup() {
const plugin = usePlugin() // 上下文可能丢失
}
// ✅ 模块顶层
const plugin = usePlugin()
// ❌ 缺少 .js 扩展名
import { foo } from './bar'
// ✅ 正确
import { foo } from './bar.js'
// ❌ 从内部包导入
import { Plugin } from '@zhin.js/core'
// ✅ 统一导入
import { Plugin } from 'zhin.js'
2. 生命周期管理
检查项：
| 项目 | 要求 | 严重程度 |
|---|---|---|
| useContext 清理 | 回调返回清理函数 | 🔴 严重 |
| 定时器清理 | setInterval/setTimeout 有 clearInterval | 🔴 严重 |
| 事件监听清理 | 外部 EventEmitter 监听有移除 | 🟡 中等 |
| 连接清理 | WebSocket/HTTP 连接有断开逻辑 | 🔴 严重 |
常见泄漏模式：
// ❌ 没有清理
useContext('database', (db) => {
const timer = setInterval(() => { /* ... */ }, 1000)
// 插件卸载后 timer 仍在运行！
})
// ✅ 返回清理函数
useContext('database', (db) => {
const timer = setInterval(() => { /* ... */ }, 1000)
return () => clearInterval(timer)
})
3. 类型安全
检查项：
| 项目 | 要求 | 严重程度 |
|---|---|---|
无 any 滥用 |
除必要的类型断言外不使用 any | 🟡 中等 |
| 类型声明完整 | Context 扩展、命令参数有类型 | 🟡 中等 |
| 严格模式 | tsconfig.json 开启 strict | 🟢 建议 |
4. 安全性
检查项：
| 项目 | 要求 | 严重程度 |
|---|---|---|
| 无硬编码凭据 | token/password/secret 不在源码中 | 🔴 严重 |
| 用户输入校验 | 命令参数、API 入参有校验 | 🟡 中等 |
| SQL 注入防护 | 使用参数化查询 | 🔴 严重 |
| 路径遍历防护 | 文件操作验证路径 | 🔴 严重 |
| eval/Function | 不使用 eval 或 new Function | 🔴 严重 |
5. 性能
检查项：
| 项目 | 要求 | 严重程度 |
|---|---|---|
| 无阻塞操作 | 不在中间件中执行同步重操作 | 🟡 中等 |
| 合理缓存 | 高频查询结果有缓存策略 | 🟢 建议 |
| 内存泄漏 | WeakMap/WeakRef 用于大量对象引用 | 🟡 中等 |
| 批量操作 | 数据库操作避免 N+1 查询 | 🟢 建议 |
6. 文档与测试
检查项：
| 项目 | 要求 | 严重程度 |
|---|---|---|
| README 完整 | 安装、配置、使用、命令列表 | 🔴 严重 |
| CHANGELOG | 版本变更记录 | 🟡 中等 |
| 测试存在 | 核心功能有测试 | 🔴 严重 |
| 覆盖率 | ≥ 60% statements | 🟡 中等 |
审查流程
第 1 步：快速扫描
# 检查结构
ls -la src/ tests/ client/ skills/
# 检查类型
pnpm build 2>&1 | grep error
# 检查测试
pnpm test
# 检查安全关键词
grep -rn "eval\|Function(\|exec(\|execSync\|password\|secret\|token" src/
第 2 步：逐文件审查
对每个源文件检查：
- 导入路径是否正确
- usePlugin/useContext 使用是否正确
- 资源是否有清理路径
- 用户输入是否有校验
第 3 步：输出审查报告
格式：
## 插件质量审查报告
### 概要
- 插件名：xxx
- 审查文件数：N
- 问题总数：X（严重 A / 中等 B / 建议 C）
### 🔴 严重问题
1. [文件:行号] 问题描述 → 建议修复方式
### 🟡 中等问题
1. [文件:行号] 问题描述 → 建议修复方式
### 🟢 改进建议
1. [文件:行号] 建议内容
### 发布就绪度
- ✅/❌ 结构规范
- ✅/❌ 生命周期安全
- ✅/❌ 类型完整
- ✅/❌ 安全无风险
- ✅/❌ 测试通过
- ✅/❌ 文档完整
失败与兜底
| 触发条件 | 一线处理 | 仍失败 |
|---|---|---|
| 审查范围不清 | 问用户：全插件 / 指定目录 / 发布前 | 默认只审 src/ + client/ |
grep 误报过多 |
人工读上下文，区分测试/mock | 只报告可复现路径 + 行号 |
| 无法跑测试 | 报告标注「静态审查 only」 | 建议用户 pnpm test 后补测 |
🔴 CHECKPOINT · 严重问题
发现 🔴 严重项（泄漏、注入、绕过发送链）时，先向用户汇报，再建议是否继续发布。
不要做什么
- 不要把风格偏好标成严重安全问题
- 不要在报告里粘贴 token、
.env、用户 ID - 不要建议绕过 IM 发送链或架构分层
- 不要仅凭
grep命中就定级「严重」 - 不要用本 skill 替代
zhin-audit做全仓 monorepo 审计
检查清单（总结）
- usePlugin() 在模块顶层
- 导入路径使用 .js 扩展名
- 所有 useContext 回调返回清理函数
- 无硬编码凭据
- 无 eval/Function 使用
- 用户输入有校验
- tsc 编译无错误
- 测试全部通过
- 覆盖率 ≥ 60%
- README 完整
- CHANGELOG 更新