脚本包路径迁移指南

通过 /auto 接口下发远端 Go 脚本的开发者，以及维护本地 scripts/*.majsoul 样本的人，都需要按本指南更新脚本里的 import 路径。

一句话总结

• 绝大多数包：只改 import 路径，包名.Inst().方法() 的调用写法完全不变。
• utils 拆成 4 个包（去掉 .Inst()，改用包级函数，见 B1）。（原先合并出的 countdown / playerinfo 等 UI 状态查询包已随 Unity 迁移移除，见上方提示。）
• 通知改用 notify.Inst().SendText（见 C 节）：pusher / discord / telegram / wechat 包已删除；/auto 远端脚本不得 import internal/notify 下的任何包。
• A 表里的包方法名一律不变。config 路径不变。引擎包 github.com/moxcomic/lq、github.com/moxcomic/engine/tenhou_client 不受影响。

为什么会变

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

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

调用写法不变，举例：

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

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

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

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

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

C. 通知接口（2026-10 起，pusher 已删除）

本节适用于包含本次改动的新版 Archer；仍在使用旧版客户端的，本地脚本里的 pusher 照旧可用；/auto 远端脚本的规则不分版本，需要在新版发布之前完成。

Archer 的推送改用 nikoksr/notify，设置页的“通知”里可以勾选 30 多个渠道。客户端本地脚本里发通知只用一个接口 （/auto 远端脚本的改法不同，见表下说明）：

• SendText 发给设置页里勾选、并且勾了“脚本消息”的渠道；调用立即返回，后台发送。
• 手机指令只在 Telegram、Discord 上可用：先给机器人发 ping 绑定会话，之后只有已绑定的会话发来的文字才会交给 onTelegramMessage / onDiscordMessage。screenshot 指令已移除。
• 升级到新版后需要重新给机器人发一次 ping：旧版的绑定从未保存到磁盘。
• 只有接收人列表为空时，ping 才会自动绑定；列表非空时，陌生会话发来的 ping 会被忽略，需要在设置页手动添加会话 ID。
• Discord 需要在开发者后台为机器人打开 Message Content Intent，否则机器人连不上网关（会被以 4014 关闭），收不到任何指令；发送通知不受影响。
• discord、telegram、wechat 包已删除，脚本不能再直接调用它们。
• /auto 下发的远端脚本不分客户端版本，不得 import internal/notify 下的任何包：新旧客户端没有一个同时都有的通知包（旧版提供的是 internal/notify/pusher，新版提供的是 internal/notify），哪一边缺符号都会让整份脚本加载失败。正确改法：删除 pusher 的 import 和全部调用，不要换成 notify；服务端脚本不再发送指令回执，需要发通知的逻辑放到客户端本地脚本里。

// 仅限客户端本地脚本（如 scripts/auto.go）；/auto 远端脚本不要这样写
import "github.com/moxcomic/Archer/internal/notify"

notify.Inst().SendText("start match.")

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

迁移前（旧路径 + 旧 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. 本地脚本（scripts/auto.go 等客户端本地加载的脚本；scripts/*.majsoul 样本的内容也按这种写法）：把 pusher.Inst().SendMasterText(...) 改成 notify.Inst().SendText(...)（见 C 节），删除 SendMasterImages 调用；新版不再调用 onWeChatMessage / onDingtalkMessage，可一并删除。
3. /auto 远端脚本：删除 pusher 的 import 和全部调用，不要换成 notify（服务端脚本不再发送指令回执，需要发通知的逻辑放到本地脚本）。 onWeChatMessage / onDingtalkMessage 可保留：新版客户端不再调用，旧版客户端仍靠它们响应微信/钉钉指令。 scripts/*.majsoul 样本是给 /auto 开发者参考的，但内容按本地脚本写法使用 notify，照着它写 /auto 脚本时必须删掉通知相关的 import 与调用。
4. utils.Inst().X() → 按 B1 改成 engineswitch / botdispatch / pagecontrol / extension 对应的包级函数（去掉 Inst().）。
5. winmgr / huleshowmgr / scorechangemgr / playerinfomgr / otherplayerinfomgr 等 UI 状态查询包 → 已随 Unity 迁移移除，请删除相关调用，改为基于对局事件流判断状态。
6. config、github.com/moxcomic/lq、github.com/moxcomic/engine/tenhou_client 保持不变。
7. 若用过 userinfo.Inst().IsVaild()，改为 IsValid()。
8. 确认 /auto 脚本里没有 import internal/notify 下的任何包后，重新部署到 /auto 下发端。scripts/*.majsoul 样本按本地脚本写法使用 notify，参考它写 /auto 脚本时必须删掉通知相关的 import 与调用。