SGS Framework

概览与界面

SGS Framework 由下载器在 Laya 初始化前注入。工程源码按 Downloader、Core 与各插件项目分别维护，发布时统一合并、压缩和变量混淆；浏览器取得的 Downloader、Core 与每个插件各自都是一个完整 JavaScript 文件。Core 统一管理生命周期、运行时事件、可逆 Hook、插件安装与配置、LocalStorage 前缀、版本检测和 Laya 底层访问。

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

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

窗口包含“插件管理”“插件配置”“Core”三个 Tab。“插件管理”显示插件名称、版本、ID、简介和更新/启停/删除操作，不重复显示安装时已经确认的能力列表，也不附加独立的运行中/已禁用状态文字；启停开关本身仍负责控制插件。Core Tab 的“Core 版本”区域同时显示版本检测与“开发者模式”开关。开关成功保存后，公共字段会立即更新；已经运行的插件可以监听对应事件，后续启动的插件可以直接读取当前值。

安装与入口

1. 在油猴脚本管理器中打开 download.mjs 并安装；该地址是构建后的单文件油猴脚本，不是工程源码目录。
2. 下载器在 document-start 安装 Laya 初始化屏障，优先请求本站 core.mjs，失败后请求 GitHub 当前存在的 main/framework/core.mjs；两个来源各自最多等待 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 会显示只读版本标记，便于确认注入是否成功。

开发工作区位于 E:\ds-sgs\src。npm run build 生成与公开目录同构的 dist，npm run publish:check 只比较 Oracle 文件，npm run deploy 才会构建并发布。

Core API

window.SgsFramework 与 window.__SgsFramework 指向同一个实例。插件通过 context.framework 获得该实例；页面控制台也可以直接读取全局入口。

install(context) {
  function applyDeveloperMode() {
    if (context.framework.developerMode) {
      // 创建或启用仅用于开发的行为。
    } else {
      // 关闭并清理仅用于开发的行为。
    }
  }

  applyDeveloperMode();
  context.addDisposer(
    context.events.on("core:developer-mode-changed", applyDeveloperMode),
    "developer-mode"
  );
}

插件安装时先读取 context.framework.developerMode，可以获得 Core 启动时恢复的值。运行期间切换开关时，字段先更新，再触发事件；只在动作执行时判断的代码也可以直接读取字段，不需要缓存副本。

插件定义

插件工程源码按项目放在 E:\ds-sgs\src，可以拆分为多个模块、数据文件和构建辅助代码。统一流水线用 esbuild 合并模块，再用 Terser 压缩与变量混淆。Core 面向的发布产物仍是一个可直接下载的经典 JavaScript 文件：文件开头保留 Header，正文调用 SgsFramework.plugins.define()，且不能依赖同项目的第二个 JavaScript 下载。

// ==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 热替换时调用。

Header 在混淆前从入口文件提取并原样置于产物顶部，因此 Catalog 检查、首次安装确认和版本比较不需要理解混淆后的正文。公开文件使用既有 .mjs URL 保持更新兼容，但按经典脚本执行。

插件配置

插件声明配置分组、默认值和可选动作，Core 负责控件排版、保存、校验、错误提示与重置。每个插件可独立收起；没有配置项的插件显示“无可配置项”，也不显示重置按钮。

defaults: { enabled: true, mode: "safe" },
settings: [{
  id: "general",
  name: "General",
  items: [
    { key: "enabled", name: "Enabled", type: "toggle", onChange: "apply" },
    { key: "mode", name: "Mode", type: "select", options: [
      { value: "safe", label: "Safe" },
      { value: "full", label: "Full" }
    ], onChange: "apply" }
  ]
}],
actions: { apply(context, value, key) {} }

context.config.get/set/reset/defaults 与配置页共享同一状态。Core 先校验并序列化新值，再触发配置动作，因此动作读取 context.config 时已经是新值。首次安装没有历史配置或用户重置时，使用插件声明的 defaults。

AutoRewards 显示“领取周卡月卡、自动免费将池、自动免费祈福、自动官阶俸禄、自动签到、自动砍树”六个 Toggle。六项默认开启；免费常山战鼓没有独立开关，会在每次自动检查中处理。

AutoRewards 的“签到策略”下拉列表提供“不自动签到、自动签到-跳过试用、自动签到-跳过使用-月底领”。“自动签到”Toggle 是签到子系统总开关；下拉选择“不自动签到”也会停用整个签到子系统。“月底领”只在 +8 服务器日历的当月最后一天允许领取试用武将奖励，其他日期仍跳过。

Core Tab 的“开发者模式”是 Core 自身设置，不属于插件配置。切换它不修改任何插件的 defaults/settings；插件通过公共字段和 Core 事件决定开发专用行为。

更新检测

Core 恢复插件后自动检测插件版本，同时检测自身版本。检测对象始终是 dist 发布的单文件产物，而不是工程目录中的模块。Core 版本来自混淆后仍保留的 SgsCore @version Header，不解析压缩正文中的变量声明；首个 Header 版本同时保留注释形式的兼容标记，使已安装的旧 Downloader/Core 也能识别并升级。插件管理页提供手动检测按钮；远程版本更高时，插件行显示更新按钮。Core 页显示当前/远程版本，并在有更新时显示热重载按钮。

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

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

运行时事件

Core 启动时从存储恢复开发者模式，并在恢复插件前公开该字段；启动恢复本身不触发变更事件。插件应在安装时读取一次字段，并在需要持续响应时注册 core:developer-mode-changed，同时把取消函数交给插件清理流程。

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

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

存储

sgs.framework.core.developer-mode
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.*

sgs.framework.core.developer-mode 保存 Core 开发者模式，缺失时按 false 处理。Core 启动时先读取该键，再创建插件上下文；切换时先写入该键，保存成功后才更新公共字段与发送变更事件。写入失败时字段保持原值，Toggle 恢复原状态并显示错误提示。

context.config 保存插件声明的配置对象；context.storage 保存插件自己的内部数据。插件只传相对键，Core 自动添加 plugins.<pluginId> 前缀并负责字符串或 JSON 序列化。Core 的停靠位置与窗口几何信息由 sgs.framework.ui.* 独立保存。

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

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

插件源

插件管理页按来源分组，每个官方、第三方或手动来源都可收起。固定官方源 /script/plugin/index.json 只引用构建后的单文件产物，发布 SGS Game Model、SGS Blocker、SGS DebugTools 与 SGS AutoRewards。Game Model 为使旧记牌器原位升级，继续使用稳定 ID sgs.card-tracker；DebugTools 继续使用 sgs.automation，AutoRewards 使用 sgs.auto-rewards。

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

第三方源可添加名称与 Catalog URL，并支持禁用、重命名和删除；删除来源不删除已经安装的插件。从 URL 安装时，Core 先下载并解析 Header，显示名称、版本、简介、来源 URL 和完整能力列表，用户确认后才执行代码。安装后的管理列表不重复能力标签或独立运行状态，只保留启停操作和需要处理的错误。Catalog 的 ID 与插件 Header/定义不一致时，安装校验失败。

官方插件

官方源提供 SGS Game Model、SGS Blocker、SGS DebugTools 与 SGS AutoRewards。它们使用普通插件相同的安装、启用、禁用、更新和删除流程；停止时释放所属 Hook、定时器、离屏对象、等待任务和可调用服务。

SGS Game Model

无配置项。插件 ID 仍为 sgs.card-tracker，发布文件 card-tracker.mjs 内嵌 gzip 压缩的完整 Game Model runtime，启用时才通过 Chrome 原生 DecompressionStream 解压并执行，不再下载或缓存第二个 card-tracker-runtime.js。它是无 UI、只读的牌局事实与推理核心：不创建 Overlay、旧侧栏、DOM 面板、Laya 节点、按钮或牌面描画。它只在有效可见的 TableGameScene 中同步服务器协议、牌堆数量、所有座位、公开区与可证明的运行时事实；离开牌局、更换 manager 或收到新开局协议时会建立全新 session，上一局的牌、顺序、弃牌和约束不会泄漏。

const runtime = window.__SgsScripts;
runtime.manager.update();
const model = runtime.tracker.gameModel;
const state = model.snapshot();
const next = model.nextCardProbability({ endpoint: "top" });
model.recast({ eventId: "recast:<protocol-id>", actorSeat: 0, from: "hand:0", cardIds: [72], drawnCardIds: [91] });
model.orderedMatchSearch({ endpoint: "top", predicate: { color: "red" }, foundCount: 1, foundCardIds: [72], to: "hand:0" });
model.takeFromDeckAtRank({ cardId: 72, rank: 3, to: "hand:0" });
const discard = model.discardForTurn(4, 2);
const checkpoint = model.observeGameEvent({ type: "game:turn", turn: 4, round: 2 });
model.cardResidence(72);
model.cardLocationAt({ cardId: 72, eventIndex: movement.eventIndex, moment: "before" });
model.cardsContinuouslyInZone({ zoneKey: "hand:0", sinceEventIndex: checkpoint.eventIndex });
model.handTransitions({ seatIndex: 1, turn: 4, lostLastHand: true });
model.handKnowledgeChanges({ seatIndex: 1, knowledgeOnly: true });
model.exchangeZones({ leftZone: "hand:0", rightZone: "hand:1", atomicOperationId: "whole-hand:1" });
model.zoneExchanges({ atomicOperationId: "whole-hand:1" });
model.cardEvents({ cardId: 72, turn: 4, movementReason: "discard", moveType: 17, tags: ["discard-phase"] });
model.observeCausalEvent({ eventId: "response:<protocol-id>", eventType: "card:respond", parentEventId: "target-effect:<protocol-id>", roles: { responderSeat: 1 }, cardId: 72 });
model.queryCausalEvents({ rootEventId: "use:<protocol-id>" });
model.causalLineage("response:<protocol-id>");
model.observeCardAction({ eventId: "use:<protocol-id>", action: "use", identityKind: "virtual-with-subcards", subcards: [{ cardId: 72, fromZone: "hand:1", role: "material" }], effectiveIdentity: { name: "杀" }, providerSeat: 1, effectiveUserSeat: 0 });
model.queryCardActions({ identityKind: "virtual-with-subcards", effectiveName: "杀" });
model.cardActionMaterials("use:<protocol-id>", { zone: "discard" });
model.moveCardActionMaterials({ eventId: "use:<protocol-id>", from: "discard", to: "hand:0" });
model.observeComparison({ comparisonId: "pindian:<protocol-id>", kind: "pindian", initiator: { seat: 0, cardId: 72 }, opponents: [{ seat: 1, cardId: 91 }], status: "chosen" });
model.swapComparisonAssignments({ comparisonId: "pindian:<protocol-id>", opponentSeat: 1 });
model.queryComparisons({ kind: "pindian", seat: 1 });
model.queryCurrentDiscard({ eventAny: [{ turn: 4, tag: "used" }, { turn: 4, tag: "offset" }], movementReasons: ["card-use", "card-response"] });
model.queryCardSources({ zones: ["deck", "discard"], predicate: { name: "无中生有" } });
model.resolveCardSourceResult({ zones: ["deck", "discard"], predicate: { name: "无中生有" }, foundCount: 1, foundCardIds: [72], to: "hand:0" });
model.observeEntityPile({ key: "character-deck:mode:<id>", entityType: "general", count: 3, entityIds: [1001, 1002, 1003], complete: true });
model.moveEntityPile({ entityType: "general", from: "character-deck:mode:<id>", to: "general-zone:seat:0", count: 1, entityIds: [1001] });
model.observeLocationGroup({ cardIds: [72, 91, 98], zoneKeys: ["hand:0", "hand:1"], zoneCounts: { "hand:0": 2, "hand:1": 1 } });
model.activeLocationGroups({ cardId: 72 });
model.updateRuleState({ key: "rule:<identity>:used-names", kind: "ordered-list", operation: "append", value: "杀", lifecycle: "turn" });
model.registerRuleModifier({ key: "rule:<identity>:weapon:<cardId>:sha-limit", kind: "modify-limit", subject: "sha-use-count", effect: { delta: 3 }, lifecycle: "while-zone", whileCardId: 72, whileZone: "equip:0" });
model.observeChoiceSet({ key: "rule:<identity>:prompt:<id>", domain: "effective-card-identity", candidates: [101, 102, 103], exactSelections: 1, visibility: "holder-only" });
model.observeApparentCardAttributes({ cardId: 72, scope: "guessing-disguise", attributes: { name: "闪" }, observerSeats: [0, 2], whileChoiceSetKey: "rule:<identity>:prompt:<id>" });
model.apparentCard(72, { scope: "guessing-disguise", observerSeat: 0 }); // 不改变 effectiveCard
model.resolveChoiceSet({ key: "rule:<identity>:prompt:<id>", selectedIndex: 1 }); // 只记录选择，不移动实体牌
model.observeSkillBinding({ skillId: 21134, ownerSeat: 0, derivedFromSkillId: 21132, ruleIdentityKey: "sgs-web-h5:21134:owner:0" });
model.activeSkillBindings({ skillId: 21134, ownerSeat: 0 });
model.activeRuleModifiers({ subject: "sha-use-count", ownerSeat: 0 });
model.observeDeckRanks({ rank: 3, cardId: 72 });
model.insertAtRank({ cardId: 72, rank: 6, fallback: "bottom" });
model.tagCard({ cardId: 72, tag: "example" });
runtime.tracker.skillResearchCoverage();
runtime.tracker.skillKnowledgeFor(816);
runtime.tracker.applyResolvedSkillOperation(816, resolvedOperation);

当前仍缺少把所有技能触发、选择、零结果反馈、稀疏位置、时序标签和规则 IR 自动绑定到对应协议，以及重连既有牌局时对弃牌堆与处理区的完整重建。现有入口只能接收已验证事实，不能把技能文本直接当成服务器事件。3031 条技能完成逐条语义审阅和运行时冲突复核前，不会宣称全部技能已经建模。

SGS Blocker

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

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

SGS DebugTools

无配置项。插件显示名为 DebugTools，但为使已安装的旧插件原位更新，ID 仍是 sgs.automation。它通过 plugins.invokeAction() 暴露四个调试函数；相同函数的并发调用复用同一 Promise。

const invokeDebug = (action) => SgsFramework.plugins.invokeAction(
  "sgs.automation", action
);
const rogue = await invokeDebug("openRogueMap");
const trial = await invokeDebug("openGeneralTrial");
const character = await invokeDebug("getCharacterInfo");
const dailyTasks = await invokeDebug("claimDailyTaskRewards");

函数返回 ok、action、status 与对应的前后状态。插件未启用时返回 inactive。模式入口不选择武将、不开始挑战、不确认弹窗，也不继续战斗。

SGS AutoRewards

插件启用后每秒读取一次运行时管理器公开的 ServerTime/ServerDate。首次取得 +8 服务器时钟时执行一次启动检查；服务器日期变化时执行一次跨日检查。检查按“卡类、免费将池、免费祈福、免费常山战鼓、官阶俸禄、签到、发财树”顺序串行，正在执行时不会并发重复，期间检测到的跨日会排队补跑。

插件提供六个 Toggle 与一个签到策略下拉列表，默认开启全部 Toggle，并默认“自动签到-跳过试用”；第三项按界面显示为“自动签到-跳过使用-月底领”。AutoRewards 不暴露手动领奖 Action；配置变更影响下一次启动/跨日自动检查。禁用插件会停止服务器时钟监听并取消后续等待。

权限与边界

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

开发者模式只是插件可读取的布尔信号，不授予权限、不隔离 Debug 代码，也不改变生命周期。使用该信号的插件必须自己在关闭时清理开发专用 Hook、监听器、定时器和 DOM，并把最终清理交给 Disposer。

Game Model 是无 UI 只读推理插件，不发送出牌、选牌或技能操作。它记录页面运行时实际包含的具体 CardID，并为敌方手牌区分公开/授权与原始服务器暴露来源；服务器未下发的牌仍是未知数量。概率结论会标注牌堆定义、物理数量、已知区域和交换性假设，未确认规则保留为开放问题。

Game Model 不把技能 Taxonomy 的 complete=true 当作机制完成。配置文本、语义研究、可执行规则与运行时证据独立统计；冲突不会被静默覆盖。插件不声明 browser.fetch、browser.local-storage 或 browser.dom-overlay，不为加载自身 runtime 发出网络请求，也不创建牌局 UI。

Blocker 只使用具体、可恢复且经过运行时核对的路径。DebugTools 的模式入口会改变当前界面，但只调用活动场分页和模式入口；不选择武将、不开始挑战、不确认弹窗，也不调用购买路径。入口条件不成立时返回结构化失败。

DebugTools 的 getCharacterInfo 只读取当前 Stage 中 IsSelf=true 的角色对象，并构造白名单结果。它不返回原始对象、Session、重连 Token、二级密码、账号散列或登录 IP；对象不可用时不打开资料窗口或发出资料查询。claimDailyTaskRewards 会发出真实领奖请求，但只处理每日且 CanAward 的任务和运行时累计奖励数组，不以固定任务数量判断正确性，也不把任务 View 加入 Stage。

AutoRewards 启用后会在首次取得服务器时间和每次 +8 服务器日期变化时发出真实请求。跨日卡类流程有意忽略客户端每日/银两按钮的本地可领标记：只要卡仍有效，就对月卡和周卡各发送一次对应请求；服务器仍负责最终资格校验。启动检查会先同步状态并避免对已领取卡奖励重复请求。月卡累计奖励始终按运行时的可领/已领数组逐项判断。

AutoRewards 不调用月卡/周卡购买或续费方法。武将抽取必须同时满足免费掉落 ID、免费 UI、管理器免费状态和请求空闲，并只使用 Free_MianFei_Draw；祈福必须通过免费配置与时间检查，只发送 count=1。两者均不调用付费抽取、灯购买、道具购买或元宝补足路径。

免费擂鼓只调用常山战鼓的 SendGuildDonate()，不调用亮银槌、鎏金锤、背包道具、SendGuildDrumUse() 或元宝确认。官阶只调用资格为真的每日/每周俸禄接口，不升级官阶，也不领取其他官阶活动奖励。

签到只在普通免费状态执行，补签状态不会点击，因此不会发起补签消耗。试用武将由 IsTryGeneralSkin 判定；跳过策略不会污染将池，“月底领”会在服务器当月最后一天放行该奖励。累计签到奖励仍会独立处理。

发财树只在免费奖励物品就绪时领奖，不购买物品。存在 HasTriggerEvent 时返回 event-required，不会自动打开、跳过或伪造事件窗口；该次可能需要用户手动处理后等待下一次自动检查。跨日的强制砍树请求只用于绕过客户端缓存的昨日状态，服务器仍负责资格校验。

AutoRewards 使用串行队列避免并发重复；禁用、更新、删除插件或热替换 Core 时停止时钟监听、取消等待并销毁离屏对象。已送达服务器的请求无法撤回，但清理后不会继续下一轮请求。DebugTools 停止后 Action 返回 inactive。

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

官方发布器只上传本地 dist，并在同步后从公开 URL 下载每个 JavaScript 核对 SHA-256。发布使用显式命令，不运行常驻文件监视器；读写 Oracle 的权限不进入浏览器产物。