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

SecScore 插件开发指南（V1）

1. 当前插件能力

当前版本支持：

• 在“插件管理”中安装、卸载、启用、禁用插件
• 启动时自动加载已启用插件
• 插件变更后自动热重载（安装/卸载/启用状态变化）
• 插件通过 setup(ctx) 运行，并可订阅应用事件

当前限制：

• main 入口建议使用单文件 ESM（不建议写相对 import）
• permissions 字段目前用于声明，不做强制拦截
• 插件运行在前端渲染层，属于“本机受信任代码”模型

2. 插件目录结构

my-plugin/
  manifest.json
  main.js

manifest.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 示例：

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("插件已卸载")
    }
  },
}

也支持：

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