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 和权限列表。用户确认后才执行插件代码。

官方插件

官方源提供记牌器、可逆屏蔽、模式入口自动化、当前角色信息读取、每日任务奖励领取和月卡奖励领取。插件仍按普通插件安装、启用、禁用、更新和删除；禁用或卸载后不得继续保留 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 节点：必要时从 ModeScene 打开活动场，在 ActivityModeView 中按真实页码查找模式入口，再调用对应 NCt.onEnterMode()。角色信息函数只读当前 Stage 中标记为自己的角色数据。每日任务和月卡奖励函数都使用调用时的服务器状态，不假定任务或累计档位数量固定，也不要求目标界面已经显示。

const rogue = await SgsFramework.plugins.invokeAction(
  "sgs.automation", "openRogueMap"
);
const trial = await SgsFramework.plugins.invokeAction(
  "sgs.automation", "openGeneralTrial"
);
const character = await SgsFramework.plugins.invokeAction(
  "sgs.automation", "getCharacterInfo"
);
const dailyRewards = await SgsFramework.plugins.invokeAction(
  "sgs.automation", "claimDailyTaskRewards"
);
const monthCardRewards = await SgsFramework.plugins.invokeAction(
  "sgs.automation", "claimMonthCardRewards"
);

模式入口返回值包含 ok、action、status、modeId 和目标摘要。角色信息成功时返回 status=ok、数据来源摘要和 character 白名单；当前 Stage 没有自己的角色数据时返回 character-unavailable，不会为了读取而跳转界面。每日任务奖励返回本次实际每日任务数、每个任务的领取状态、累计完成数、每档银两奖励状态，以及执行前后 Stage 中的任务界面摘要。月卡奖励返回同步前后的卡片天数、当日奖励状态、每个累计档位的天数/物品/数量/领取状态，以及执行前后 Stage 中的月卡界面摘要。没有可领取奖励时返回 nothing-claimable；月卡未激活时返回 card-inactive；部分请求超时或失败时返回 partial。插件未启用时返回 inactive；Laya、任务数据或所需长名称接口不可用时返回结构化失败。函数不会代替用户返回主页、选择武将、开始挑战、确认弹窗、购买、续费或继续战斗。

权限与边界

插件权限用于安装前披露，不是能力沙箱，也不会按权限名拒绝执行。插件与普通页面脚本处于同一页面环境，可以读取对象、调用公开方法、发起网络请求或创建 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()，不会购买或续费；未激活月卡返回 card-inactive。离屏月卡对象不加入 Laya.stage，结束时解除监听并销毁；monthCardUi.opened 用于确认本次调用没有新增福利界面。

禁用、更新、删除插件或热替换 Core 时，插件必须释放 Hook、监听器、定时器、离屏对象、DOM 和内部可调用服务。Automation 的 action 只在插件启用期间工作；停用后的直接调用返回 inactive，等待中的领取流程会在当前短轮询结束后停止继续请求。

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