SGS Framework

概览与界面

SGS Framework 由下载器在 Laya 初始化前注入。Core 统一管理生命周期、运行时事件、可逆 Hook、插件安装与配置、LocalStorage 前缀、版本检测和 Laya 底层访问。

屏幕边缘的 SGS 悬浮窗自动吸附左侧或右侧。自动隐藏开启时，只保留边缘感应区，鼠标进入当前侧边缘才显示；拖动后在边缘松开也会按该设置隐藏。点击悬浮窗可选择“选项”、切换自动隐藏，并查看不可点击的 Core 版本号。

选项窗口默认占视口宽高各 50%，可拖动和从右下角缩放。最小宽高为视口的 20%，同时保留 260×180 像素的可用下限；移动、缩放、视口变化和浏览器缩放后，窗口都会被约束在屏幕内。

安装与入口

1. 在油猴脚本管理器中打开 download.mjs 并安装。
2. 下载器在 document-start 安装 Laya 初始化屏障，优先请求本站 core.mjs，失败后请求 GitHub；两个来源各自最多等待 5 秒。
3. 远程请求都失败时，下载器先尝试页面 LocalStorage 缓存；仍不可用时显示“继续游戏 / 刷新重试”。选择继续时使用可用缓存，没有缓存则不加载 Framework。
4. Core 注入完成后释放 Laya 屏障，恢复已启用插件并执行静默版本检测。

用户手册：https://sgs.senrax.com/
安装脚本：https://sgs.senrax.com/script/download.mjs
公开目录：https://sgs.senrax.com/script/

在 https://web.sanguosha.com/login/index.html 登录页，Core 会显示只读版本标记，便于确认注入是否成功。

Core API

window.SgsFramework 与 window.__SgsFramework 指向同一个实例。插件优先使用传入的 context；只有框架调试或插件接口不足时才直接使用顶层服务。

const framework = window.SgsFramework;
const remove = framework.events.on("battle:start", ({ scene, manager }) => {
  framework.logger.info("battle started", scene, manager);
});

// 插件卸载时调用 remove，或交给 context.addDisposer(remove)。

插件定义

插件是可直接下载、无需构建的经典 JavaScript 文件。Core 在执行代码前解析 Header，用于安装确认和版本检测；正文必须调用 SgsFramework.plugins.define()。

// ==SgsPlugin==
// @id           example.plugin
// @name         Example Plugin
// @version      1.0.0
// @description  Example description.
// @permissions  core.events,browser.dom-overlay
// @updateMode   default
// ==/SgsPlugin==

(() => {
  SgsFramework.plugins.define({
    id: "example.plugin",
    manifest: {
      name: "Example Plugin",
      version: "1.0.0",
      description: "Example description.",
      permissions: ["core.events", "browser.dom-overlay"]
    },
    defaults: {},
    settings: [],
    install(context) {
      const remove = context.events.on("battle:end", () => {});
      context.addDisposer(remove, "battle-end");
      return () => {};
    }
  });
})();

context 提供 framework、id、manifest、sourceUrl、events、logger、storage、config、timers、hooks、dom、browser、laya、runtime 和 addDisposer。install 返回的函数也会在禁用、更新、删除或 Core 热替换时调用。

插件配置

插件只声明配置、默认值和动作，Core 负责 Group、行列、控件、错误提示与重置按钮。每个插件独立显示并可收起；没有配置项的插件仍显示“无可配置项”，且不显示重置按钮。

defaults: { enabled: true, name: "demo", mode: "safe" },
settings: [{
  id: "general",
  name: "General",
  items: [
    { key: "enabled", name: "Enabled", type: "toggle", onChange: "apply" },
    { key: "name", name: "Name", type: "text",
      minLength: 1, maxLength: 20,
      patterns: ["^[A-Za-z]", "^[A-Za-z0-9_-]+$"] },
    { key: "mode", name: "Mode", type: "select", options: [
      { value: "safe", label: "Safe" },
      { value: "full", label: "Full" }
    ], onChange: "apply" },
    { name: "Open list", type: "button", action: "openList" },
    { name: "Complex", type: "custom", render: "renderComplex" }
  ]
}],
actions: {
  apply(context, value, key) {},
  openList(context) {},
  renderComplex(context, host) {},
  onReset(context, values) {}
}

context.config.get/set/reset/defaults 与配置页共享同一状态。值先通过全部约束，再序列化到 LocalStorage，随后触发动作；动作读取 context.config 时得到的就是本次新值。首次安装且没有配置、或用户按下重置时，使用插件的 defaults。

更新检测

Core 恢复插件后自动检测插件版本，同时检测自身版本。插件管理页提供手动检测按钮；远程版本更高时，插件行显示更新按钮。Core 页显示当前/远程版本，并在有更新时显示热重载按钮。

插件更新会保存新源码、停止旧实例、执行新定义并恢复原启用状态。Core 热重载会释放旧 Core 的插件、Hook、定时器、监听器和 DOM，再由新 Core 从缓存源码恢复已启用插件。

跨域来源必须允许当前游戏页面读取响应。Header 模式若使用自定义响应头，还要通过 Access-Control-Expose-Headers 暴露该名称。

运行时事件

有效可见性会检查节点及父链的 visible、alpha、scaleX/scaleY 和 destroyed。Core 不通过 console.log 判断战斗，也不把可能残留的窗口注册表当作事实。

高层事件不足时，可从 framework.laya.getLaya()、getStage() 或事件 Payload 取得原始 Laya 对象并调用底层公开接口。

存储

sgs.framework.ui.dock
sgs.framework.ui.window
sgs.framework.plugins.registry
sgs.framework.plugins.sources
sgs.framework.plugins.catalog-cache
sgs.framework.plugins.<pluginId>.code
sgs.framework.plugins.<pluginId>.config
sgs.framework.plugins.<pluginId>.data.*

context.config 保存 Core 排版配置；context.storage 保存插件内部配置或数据。插件只传相对键，Core 自动添加 plugins.<pluginId> 前缀并负责序列化。

Core 启动时把历史双分隔符键（例如 ui..dock、data..runtime-source）迁移为单点键；如果单点键已经存在，以单点键为准。

删除插件会删除注册记录和源码缓存，但保留 .config 与 .data.*。Core 页的“检查已删除插件配置”按插件 ID 汇总这些孤儿键、数量和字符数；用户确认删除时只移除该插件的配置/数据，不影响已安装或被禁用插件。

插件源

插件管理页按来源分组，每个官方/第三方/手动来源都可收起。官方源固定为 /script/plugin/index.json。第三方源可添加名称与 Catalog URL，并支持禁用、重命名和删除；删除来源不会删除已经安装的插件。

{
  "name": "Source name",
  "plugins": [
    { "id": "example.plugin", "url": "https://example/plugin.js" }
  ]
}

从 URL 安装插件时，Core 先下载并解析 Header，再显示名称、版本、简介、来源 URL 和权限列表。用户确认后才执行插件代码。

官方插件

官方源提供 SGS Card Tracker、SGS Blocker 和 SGS Automation。它们与普通插件使用同一套安装、启用、禁用、更新和删除流程；插件停止后，所属 Hook、DOM、定时器、离屏对象、等待任务和可调用服务都会释放。

SGS Card Tracker

无配置项。插件加载与 Scripts/dist/sgs-runtime.js 相同的运行时构建，只在有效可见的 TableGameScene 或 RogueLikeGameScene 中显示 UI。离开战斗后立即停止描画并清理临时状态。已知牌只来自自己的手牌、公开日志或窗口、公开区和明确揭示牌的协议记录；隐藏对手 handCards 不作为已知事实。

SGS Blocker

提供“屏蔽广告 / 屏蔽特效 / 屏蔽道具弹窗”三个独立开关。每项都使用当前 Laya 类与已经核对的具体路径，不按宽泛英文类名隐藏节点，也不全局关闭 Tween、Timer、Animation 或渲染。

禁用、更新、删除 Blocker 或热替换 Core 时，每个 Hook 都恢复包装前的方法。

SGS Automation

无配置项。插件通过 plugins.invokeAction() 暴露九个供 Agent 或控制台调用的函数。模式入口使用当前有效可见的 Laya 节点；角色信息按固定白名单读取自己的角色对象；领奖、免费抽取与免费擂鼓使用当前运行时管理器的资格状态，不要求目标窗口已经显示。相同 Action 的并发调用会复用同一个进行中的 Promise，不会重复发送请求。

const invoke = (action) => SgsFramework.plugins.invokeAction(
  "sgs.automation", action
);

const rogue = await invoke("openRogueMap");
const trial = await invoke("openGeneralTrial");
const character = await invoke("getCharacterInfo");
const dailyRewards = await invoke("claimDailyTaskRewards");
const monthCardRewards = await invoke("claimMonthCardRewards");
const generalDraw = await invoke("claimFreeGeneralDrawRewards");
const blessDraw = await invoke("claimFreeBlessDrawRewards");
const guildDrums = await invoke("useFreeGuildDrums");
const officerSalary = await invoke("claimOfficerSalaryRewards");

每个函数都返回 ok、action 和 status，并附带适合该操作的调用前后状态。没有可执行项时返回 nothing-claimable；月卡未激活返回 card-inactive；未加入公会返回 not-in-guild；请求占用、刷新超时、回包未确认或部分完成会返回相应结构化状态。插件未启用时返回 inactive。模式入口不会选择武将、开始挑战、确认弹窗或继续战斗；奖励、免费抽取和免费擂鼓函数不会购买、续费、消耗元宝或使用付费擂鼓道具。

权限与边界

插件权限用于安装前披露，不是能力沙箱，也不会按权限名拒绝执行。插件与普通页面脚本处于同一页面环境，可以读取对象、调用公开方法、发起网络请求或创建 DOM。只安装可信来源，并审查声明了网络、Hook、Laya、游戏请求或 DOM 能力的代码。

Framework 不替插件绕过付费、购买确认或服务器权限。Card Tracker 不得把隐藏对手手牌当作已知事实。Blocker 只能使用具体、可恢复且经过当前运行时核对的路径。Automation 的模式入口会改变当前游戏界面，但只调用活动场分页与模式入口方法；不选择武将、不开始挑战、不确认弹窗，也不调用购买路径。入口条件不成立时返回结构化失败。

getCharacterInfo 只读取当前 Stage 中 IsSelf=true 的角色对象，并按固定白名单构造新对象。它不返回原始运行时引用，也不返回 Session、重连 Token、二级密码、账号散列或登录 IP。当前 Scene 没有自己的角色对象时返回 character-unavailable，不打开个人资料窗口，也不发出资料查询请求。

claimDailyTaskRewards 会发出真实任务领奖请求。它只处理运行时标记为每日且状态为 CanAward 的任务，再循环点击运行时提供的累计银两档位，由游戏自身方法过滤未达标和已领取项目。任务数量不参与正确性判断，跨日增减只是本次循环输入不同。离屏任务对象不加入 Laya.stage，结束时销毁；taskUi.opened 用于确认调用没有新增任务界面。

claimMonthCardRewards 会发出真实特权卡同步与领奖请求。它先调用 SendClientPrivilegeDataReq() 同步服务器状态；仅当类型 3 月卡激活且 bReward=true 时调用 sendAwardReq()。累计奖励只对 AddAwardsCanAwardList() 为真的索引调用 addItemClick(index)，并通过 AddAwardsHasAwardList() 确认。实现不调用含购买分支的 getBtnClick()，不会购买或续费。离屏月卡对象不加入 Stage，结束时解除监听并销毁。

claimFreeGeneralDrawRewards 会发出一次真实武将抽取请求。请求前必须同时确认免费掉落 ID 存在、客户端免费标记可见、免费按钮可用、FreeOpenGeneralPackTime/CanFreeOpenGeneral() 判定免费、请求池未占用，并使用运行时枚举 Free_MianFei_Draw。它不调用单抽、五连抽、购买道具或元宝补足路径；任一免费证据缺失时不发送请求。

claimFreeBlessDrawRewards 会先调用 SendAllListReq() 同步祈福数据。每个轮次都必须同时满足 freeOpen、活动时间、抽取时间和 CanFreeBless(roundId)，才会发送 sendQifuDrawReq(roundId, 1)。函数不调用 blessBtnClick()、confirmBuy() 或商店方法，因此不会落入灯数不足后的购买分支；同步失败或免费状态无法确认时不抽取。

useFreeGuildDrums 会发出真实公会擂鼓请求。它只在已加入公会、CanDrum=true 且 LeftFreeDrumTimes>0 时调用 SendGuildDonate()，并在每次免费次数减少后继续。它不调用亮银槌、鎏金锤、背包道具使用、SendGuildDrumUse() 或元宝确认路径。免费次数为零、加入公会时间不足或不在公会时不请求。

claimOfficerSalaryRewards 会发出真实官阶领奖请求。每日俸禄只在 CanGetOfficerDayReward() 为真时调用 sendGetDayReward()，并以资格状态变为 false 确认；随后每周俸禄只在 CanGetOfficerWeekReward() 为真时调用 sendGetWeekReward()，使用同一方式确认。函数不升级官阶、不领取其他官阶活动奖励，也不打开官阶窗口。

禁用、更新、删除插件或热替换 Core 时，插件释放 Hook、监听器、定时器、离屏对象、DOM、等待任务和内部可调用服务。Automation Action 只在插件启用期间工作；停用后的调用返回 inactive。相同 Action 的并发调用复用同一 Promise，停用时取消事件等待，循环在当前短轮询结束后停止继续请求。

浏览器 Fetch 受 CORS 约束。第三方插件与 Catalog 来源需要允许游戏页面跨域访问；Header 更新模式还需要显式暴露版本响应头。