mirror of
https://github.com/SECTL/SecScore.git
synced 2026-07-19 19:04:23 +08:00
NanGua-QWQ
127 lines
3.1 KiB
Markdown
127 lines
3.1 KiB
Markdown
# 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`
|