# 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`