plugin-quality

Zhin 插件质量审查（Plugin Runtime）

对照 Plugin Runtime 审查插件：结构、约定目录、依赖方向、发送链与安全。发现仍用 usePlugin / MessageCommand 的新代码应标为缺陷并迁移。

适用场景

• 「检查插件质量」「审查代码」「发布前看看有没有问题」
• 重构现有插件使其符合 Runtime

审查维度

1. 结构规范性

项目	要求	严重程度
入口	plugin.ts default-export definePlugin()	🔴 严重
manifest	package.json#zhin（protocol、entry、features）	🔴 严重
能力放置	约定目录 + default export；非业务堆在 plugin.ts	🔴 严重
旧 API	新代码无 usePlugin / getPlugin / MessageCommand	🔴 严重
导入路径	相对导入带 .js	🔴 严重
Feature 依赖	用到的能力已在 zhin.features 声明	🟡 中等
配置	自有字段在 schema.json，经 context.config 读取	🟡 中等

常见错误：

// ❌ 经典插件 API（Runtime 下不工作）
import { usePlugin, MessageCommand } from 'zhin.js'
const plugin = usePlugin()
plugin.addCommand(new MessageCommand('hi').action(() => 'hi'))

// ✅ Runtime
import { definePlugin } from 'zhin.js'
export default definePlugin({ name: 'my-plugin', setup() {} })
// + commands/hi.ts → defineCommand(...)

2. 生命周期与资源

• 清理走 context.lifecycle.add 或 setup 返回 disposer
• 共享连接/DB 用 context.resources.provide，禁止裸模块级单例或 createGenerationStore
• Host token 先 has 再 use（精简安装下可选）

3. 发送与安全

• 出站不绕过 Message.$reply / Adapter.sendMessage → before.sendMessage
• 密钥只走环境变量 / ${VAR} 配置引用
• AI 工具副作用边界清晰；危险操作有策略/确认

4. 测试与文档

• 至少覆盖核心 execute 路径
• README 写明命令触发方式与 Feature 依赖
• 带 agent/ 的包检查 files / prepublishOnly（pnpm check:plugin-agent-publish）

审查流程

1. 读 package.json#zhin + plugin.ts
2. 扫 commands/ / tools/ / middlewares/ 是否 default export 正确 API
3. ripgrep：usePlugin|MessageCommand|getPlugin|bootstrapNode
4. 跑 pnpm --filter <pkg> test（及需要的 harness）
5. 输出问题清单（严重度 + 建议修复）

输出格式

## 结论
- 是否可发布：是 / 否

## 问题
| 严重度 | 位置 | 问题 | 建议 |
|--------|------|------|------|
| 🔴 | ... | ... | ... |

## 已通过
- definePlugin 入口 / 约定目录 / 发送链 …

迁移

旧插件迁 Runtime：.github/skills/migrate-zhin-plugin-runtime。