脚本包路径迁移指南

适用对象：通过 /auto 接口下发远端 yaegi 脚本的开发者，以及维护本地 scripts/*.majsoul 样本的人。

本次重构把脚本可见的 Go 包搬进了 internal/ 分层目录。你脚本里的 import 路径需要更新，否则 yaegi 在加载/运行时会报 unable to find source / undefined symbol。

⚠️ 2026 更新（雀魂 Unity 迁移）：雀魂网页版改用 Unity + WASM 后，所有查询 LayaBox UI 状态的“管理器”包已被整体移除：lobbymgr、desktopmgr、infomgr、gameendmgr、activitymgr、activitysignmgr、monthlymgr、countdown、playerinfo。它们依赖的 LayaBox 引擎 JS 全局对象在 Unity 下不存在。下文 A 表中的这些 widget 行、以及 B2 / B3 小节均已失效，请勿再使用；游戏状态判断请改为基于对局 protobuf 事件流推导。其余包（gamestate / userinfo / variable / actions / pusher 等）与 utils 拆分（B1）不受影响。

一句话总结

• 绝大多数包：只改 import 路径，包名.Inst().方法() 的调用写法完全不变。
• utils 拆成 4 个包（去掉 .Inst()，改用包级函数，见 B1）。（原先合并出的 countdown / playerinfo 等 UI 状态查询包已随 Unity 迁移移除，见上方提示。）
• 方法名一律不变。config 路径不变。引擎包 github.com/moxcomic/lq、github.com/moxcomic/engine/tenhou_client 不受影响。

为什么会变

yaegi 解释器靠一张 symbols 符号表把脚本里的 import 路径映射到真实的 Go 包。重构后这些包的物理位置（import 路径）变了，symbols 表已随之同步更新；但你脚本里写死的 import 路径需要你手动改——路径对不上，yaegi 找不到对应符号，就会在加载或运行时报错。

A. 只改 import 路径（调用写法不变）

github.com/moxcomic/Archer/config 保持不变（仍是顶层公开包）。

⚠️ userinfo 的方法 IsVaild 已更名为 IsValid（修正拼写）。如果你的脚本调用过 .IsVaild()，请改为 .IsValid()；其余方法名一律不变。

调用写法不变，举例：

// 只改了上面 import 的那一行，下面的调用一字不动
gamestate.Inst().GetHandTile()
variable.Inst().GetInt("ju")
actions.NewMajsoulActions()
pusher.Inst().SendMasterText("...")

B. 调用写法也变了（拆包 / 合并）

B1. utils 拆成 4 个包（去掉 .Inst()）

原来的 utils.Inst().X(...) 现在改成对应包的包级函数 pkg.X(...)：

B2 / B3. 倒计时（countdown）与玩家信息（playerinfo）—— 已移除

⚠️ 这两套 UI 状态查询包随雀魂 Unity 迁移已被移除（见顶部说明），不再提供。原先的 winmgr / huleshowmgr / scorechangemgr / playerinfomgr / otherplayerinfomgr 一并失效。请改为从对局 protobuf 事件流推导相应状态。

完整示例：天凤个室脚本迁移前后

迁移前（旧路径 + 旧 utils 调用）：

import (
	"github.com/moxcomic/Archer/utils"
	"github.com/moxcomic/Archer/gamestate"
	"github.com/moxcomic/Archer/userinfo"
	"github.com/moxcomic/Archer/variable"
	tenhouclient "github.com/moxcomic/engine/tenhou_client"
	"github.com/moxcomic/lq"
)

func dispatch() error {
	return utils.Inst().DispatchBot(1000, 20, strconv.Itoa(ROOM_ID), "high", "4.1b", "4.1b", "4.1b")
}

迁移后：

import (
	"github.com/moxcomic/Archer/internal/platformutil/botdispatch"
	"github.com/moxcomic/Archer/internal/domain/gamestate"
	"github.com/moxcomic/Archer/internal/infra/userinfo"
	"github.com/moxcomic/Archer/internal/infra/variable"
	tenhouclient "github.com/moxcomic/engine/tenhou_client"
	"github.com/moxcomic/lq"
)

func dispatch() error {
	return botdispatch.DispatchBot(1000, 20, strconv.Itoa(ROOM_ID), "high", "4.1b", "4.1b", "4.1b")
}

gamestate.Inst() / userinfo.Inst() / variable.Inst() / tenhouclient.Inst() 等调用一字未动——只有 import 行和 utils.Inst().DispatchBot 这一处调用变了。

迁移检查清单

1. 把脚本里所有 github.com/moxcomic/Archer/<X> 的 import 按 A 表替换为 internal/... 路径。
2. utils.Inst().X() → 按 B1 改成 engineswitch / botdispatch / pagecontrol / extension 对应的包级函数（去掉 Inst().）。
3. winmgr / huleshowmgr / scorechangemgr / playerinfomgr / otherplayerinfomgr 等 UI 状态查询包 → 已随 Unity 迁移移除，请删除相关调用，改为基于对局事件流判断状态。
4. config、github.com/moxcomic/lq、github.com/moxcomic/engine/tenhou_client 保持不变。
5. 若用过 userinfo.Inst().IsVaild()，改为 IsValid()。
6. 重新部署到 /auto 下发端。本地样本 scripts/auto.majsoul 已同步更新，可作参考。

本地实际加载的脚本 scripts/auto.go 已随重构同步更新并通过 yaegi 测试。远端 /auto 下发的脚本需要你按本指南更新。