feat: 插件系统 V1

plugin-wiki/插件开发指南.md

@@ -0,0 +1,126 @@
+# SecScore 插件开发指南（V1）
+
+## 1. 当前插件能力
+
+当前版本支持：
+
+- 在“插件管理”中安装、卸载、启用、禁用插件
+- 启动时自动加载已启用插件
+- 插件变更后自动热重载（安装/卸载/启用状态变化）
+- 插件通过 `setup(ctx)` 运行，并可订阅应用事件
+
+当前限制：
+
+- `main` 入口建议使用单文件 ESM（不建议写相对 `import`）
+- `permissions` 字段目前用于声明，不做强制拦截
+- 插件运行在前端渲染层，属于“本机受信任代码”模型
+
+## 2. 插件目录结构
+
+```text
+my-plugin/
+  manifest.json
+  main.js
+```
+
+`manifest.json` 最小示例：
+
+```json
+{
+  "id": "demo.hello",
+  "name": "Hello Plugin",
+  "version": "0.1.0",
+  "description": "我的第一个 SecScore 插件",
+  "author": "YourName",
+  "main": "main.js",
+  "permissions": ["events.read"],
+  "enabled": true
+}
+```
+
+字段说明：
+
+- `id`：插件唯一标识，仅允许字母/数字/`.`/`_`/`-`
+- `name`：插件名称
+- `version`：版本号
+- `main`：入口脚本（相对路径）
+- `enabled`：是否启用
+- `permissions`：声明型权限数组（V1 不强制）
+
+## 3. 入口脚本写法
+
+`main.js` 示例：
+
+```js
+export default {
+  setup(ctx) {
+    ctx.log("插件已加载")
+
+    const offRoute = ctx.on("route-changed", (detail) => {
+      ctx.log("路由变化", detail)
+    })
+
+    const offData = ctx.on("data-updated", (detail) => {
+      ctx.log("数据变化", detail)
+    })
+
+    // 示例：调用内置 API（仍受后端权限控制）
+    ctx.api
+      ?.queryStudents?.()
+      .then((res) => ctx.log("学生数量", res?.data?.length ?? 0))
+      .catch((err) => ctx.log("查询失败", String(err)))
+
+    // 返回清理函数（可选）
+    return () => {
+      offRoute()
+      offData()
+      ctx.log("插件已卸载")
+    }
+  },
+}
+```
+
+也支持：
+
+```js
+export default function setup(ctx) {
+  ctx.log("以函数形式加载")
+}
+```
+
+## 4. `ctx` 上下文
+
+`setup(ctx)` 可用能力：
+
+- `ctx.id` / `ctx.name` / `ctx.version`
+- `ctx.permissions`：manifest 中的权限声明
+- `ctx.api`：应用 `window.api`（可调用现有 IPC API）
+- `ctx.log(message, meta?)`：插件日志输出
+- `ctx.on(event, handler)`：订阅事件并返回取消订阅函数
+
+可订阅事件：
+
+- `data-updated`：对应 `ss:data-updated`
+- `route-changed`：对应 `ss:route-changed`
+- `plugins-updated`：对应 `ss:plugins-updated`
+
+## 5. 安装与调试
+
+1. 准备好插件目录（包含 `manifest.json` 与入口文件）
+2. 打开 SecScore -> `插件管理` -> `安装插件`
+3. 选择插件目录并确认安装
+4. 查看日志：
+   - 开发环境浏览器控制台
+   - 或应用日志（设置页日志模块）
+
+卸载行为说明：
+
+- 卸载会删除安装到应用插件目录中的插件副本
+- 源插件目录（你自己本地开发目录）不会被改动
+
+## 6. 推荐开发流程
+
+1. 先写最小插件（仅 `ctx.log`）
+2. 再接入事件监听（`route-changed` / `data-updated`）
+3. 最后增加 API 调用和容错处理（`try/catch`）
+4. 升级版本时同步更新 `manifest.json` 的 `version`