magic-agent 2.4.3 → 2.6.3

package/internal/agent/fallback_test.go

@@ -0,0 +1,340 @@
+package agent
+
+// fallback_test.go - 主备降级（2026-10-24；2026-10-26 按真机报障补口径）。
+//
+// 钉子：同引擎换模型也降级 / 换引擎不把主引擎的模型带过去 / 只有正文算产出 /
+// 降级要发 fallback 帧且不带主引擎残留的终帧 / 降级清会话锚点且只降一级 /
+// 没降级要给得出原因（原因进 FallbackInfo）。
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+type fallbackFakeEngine struct {
+	name   string
+	text   string
+	events []string
+	err    error
+	// 记录最后一次收到的请求（验降级时清掉了会话锚点 / 模型怎么传的）。
+	lastReq Request
+}
+
+func (f *fallbackFakeEngine) Name() string           { return f.name }
+func (f *fallbackFakeEngine) Detect() (bool, string) { return true, "fake://" + f.name }
+func (f *fallbackFakeEngine) Complete(_ context.Context, req Request) (Response, error) {
+	f.lastReq = req
+	return Response{Engine: f.name, Model: req.Model, Text: f.text}, f.err
+}
+
+// Stream 默认可用 —— 与内置引擎一致（它们都是 Streamer）。
+func (f *fallbackFakeEngine) Stream(_ context.Context, req Request, onEvent func(StreamEvent)) (StreamResult, error) {
+	f.lastReq = req
+	// 先以「思考」形态吐一遍（纯过程不拦降级），再把 events 当正文吐。
+	if len(f.events) > 0 {
+		onEvent(StreamEvent{Kind: KindThinking, Text: "让我想想"})
+	}
+	for _, s := range f.events {
+		onEvent(StreamEvent{Kind: KindText, Text: s})
+	}
+	return StreamResult{Response: Response{Engine: f.name, Model: req.Model, Text: f.text}}, f.err
+}
+
+// fallbackFakeNonStream 不支持流式的引擎（只有 Engine 接口，没有 Stream）。
+type fallbackFakeNonStream struct {
+	name string
+	text string
+	req  Request
+}
+
+func (f *fallbackFakeNonStream) Name() string           { return f.name }
+func (f *fallbackFakeNonStream) Detect() (bool, string) { return true, "fake://" + f.name }
+func (f *fallbackFakeNonStream) Complete(_ context.Context, req Request) (Response, error) {
+	f.req = req
+	return Response{Engine: f.name, Text: f.text}, nil
+}
+
+// withFallbackEngines 临时替换注册表：Lookup 只认这里登记的假引擎，测完还原
+// （别让内置引擎的惰性注册被这个用例打断，见 engine.go 的 registry 注释）。
+func withFallbackEngines(t *testing.T, engines ...Engine) {
+	t.Helper()
+	old := registry
+	registry = append([]Engine(nil), engines...)
+	t.Cleanup(func() { registry = old })
+}
+
+// collectFallback 收事件的助手：按 kind 分类存下来。
+type fallbackRecorder struct {
+	notices  []string
+	fallback []FallbackEvent
+	texts    []string
+	turnEnds int
+}
+
+func (r *fallbackRecorder) on(ev StreamEvent) {
+	switch ev.Kind {
+	case KindNotice:
+		r.notices = append(r.notices, ev.Text)
+	case KindFallback:
+		if ev.Fallback != nil {
+			r.fallback = append(r.fallback, *ev.Fallback)
+		}
+	case KindText:
+		r.texts = append(r.texts, ev.Text)
+	case KindTurnEnd:
+		r.turnEnds++
+	}
+}
+
+func TestStreamWithFallbackOnZeroOutput(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-primary", err: errors.New("402 insufficient_balance_error")}
+	backup := &fallbackFakeEngine{name: "fb-backup", text: "备用答案"}
+	withFallbackEngines(t, primary, backup)
+
+	rec := &fallbackRecorder{}
+	res, info, err := StreamWithFallback(context.Background(), primary, Request{
+		Model:          "m1",
+		FallbackEngine: "fb-backup",
+		FallbackModel:  "m2",
+	}, rec.on)
+	if err != nil {
+		t.Fatalf("主引擎失败、备用成功时不该报错：%v", err)
+	}
+	if res.Text != "备用答案" {
+		t.Errorf("应返回备用引擎的正文，得到 %q", res.Text)
+	}
+	if len(rec.fallback) != 1 {
+		t.Fatalf("应发一条 fallback 帧，得到 %#v", rec.fallback)
+	}
+	fe := rec.fallback[0]
+	if fe.FromEngine != "fb-primary" || fe.ToEngine != "fb-backup" || !fe.Switched || fe.FromModel != "m1" {
+		t.Errorf("fallback 帧两端不对：%#v", fe)
+	}
+	if !strings.Contains(fe.Reason, "402") {
+		t.Errorf("fallback 帧应带主引擎失败原因：%q", fe.Reason)
+	}
+	/* 换引擎：备用模型属于主引擎的清单，不能带过去（z 以前把 codebuddy 的 hy3 喂给 dsh）。 */
+	if backup.lastReq.Model != "" || !backup.lastReq.FallbackDown {
+		t.Errorf("换引擎时模型应清空并标记 FallbackDown：model=%q down=%v",
+			backup.lastReq.Model, backup.lastReq.FallbackDown)
+	}
+	if backup.lastReq.FallbackEngine != "" {
+		t.Error("降级请求里不该再留着备用字段（只降一级）")
+	}
+	if !info.Used || info.Engine != "fb-backup" || info.SwitchedEngine != true {
+		t.Errorf("FallbackInfo 应记录降级已生效：%#v", info)
+	}
+}
+
+// 同引擎换模型（手机上最常见的配法：dsh 主 modelverse、备 volcengine）——
+// 2026-10-26 真机作业记录里这一路以前被直接判成「没配备用」。
+func TestStreamWithFallbackSameEngineOtherModel(t *testing.T) {
+	var calls []string
+	primary := &fallbackFakeEngine{name: "fb-same", err: errors.New("402 Token Plan 用量上限")}
+	backup := &fallbackFakeEngine{name: "fb-same", text: "备用模型给的答案"}
+	withFallbackEngines(t, backup)
+
+	rec := &fallbackRecorder{}
+	res, info, err := StreamWithFallback(context.Background(), primary, Request{
+		Model:          "modelverse/x",
+		FallbackEngine: "fb-same",
+		FallbackModel:  "volcengine/x",
+	}, func(ev StreamEvent) {
+		if ev.Kind == KindFallback {
+			calls = append(calls, "fallback")
+		}
+		rec.on(ev)
+	})
+	if err != nil {
+		t.Fatalf("同引擎换模型应能降级：%v", err)
+	}
+	if res.Text != "备用模型给的答案" {
+		t.Errorf("应返回备用模型的正文，得到 %q", res.Text)
+	}
+	if backup.lastReq.Model != "volcengine/x" {
+		t.Errorf("同引擎换模型时必须带上备用模型，得到 %q", backup.lastReq.Model)
+	}
+	if len(rec.fallback) != 1 || rec.fallback[0].Switched || rec.fallback[0].ToModel != "volcengine/x" {
+		t.Fatalf("fallback 帧应说明是同引擎换模型：%#v", rec.fallback)
+	}
+	if !info.Used || info.SwitchedEngine {
+		t.Errorf("FallbackInfo：%#v", info)
+	}
+	// 人话里要能看到模型名 —— 用户配的正是模型。
+	if !strings.Contains(FallbackNoticeText(rec.fallback[0]), "volcengine/x") {
+		t.Errorf("提示里应带备用模型名：%q", FallbackNoticeText(rec.fallback[0]))
+	}
+}
+
+// 只有过程没有正文（思考 / 空 delta）也降级：已流出的思考是过程，不是答案。
+func TestStreamWithFallbackIgnoresThinkingOnly(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-think", err: errors.New("余额不足")}
+	// 主引擎只吐了思考与空白正文，没给答案。
+	primary.events = []string{"", "   "}
+	backup := &fallbackFakeEngine{name: "fb-think-backup", text: "答案"}
+	withFallbackEngines(t, primary, backup)
+
+	rec := &fallbackRecorder{}
+	_, info, err := StreamWithFallback(context.Background(), primary, Request{
+		FallbackEngine: "fb-think-backup",
+	}, rec.on)
+	if err != nil {
+		t.Fatalf("只吐过思考时仍应降级：%v", err)
+	}
+	if !info.Used {
+		t.Errorf("只吐过思考时仍应降级：%#v", info)
+	}
+}
+
+// 已经吐过正文：不降级，保留原始错误，并给出原因。
+func TestStreamWithFallbackKeepsPartialOutput(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-partial", events: []string{"已经写了一"}, err: errors.New("boom")}
+	backup := &fallbackFakeEngine{name: "fb-backup2", text: "不该出现"}
+	withFallbackEngines(t, primary, backup)
+
+	rec := &fallbackRecorder{}
+	_, info, err := StreamWithFallback(context.Background(), primary, Request{
+		FallbackEngine: "fb-backup2",
+	}, rec.on)
+	if err == nil {
+		t.Fatal("已经产出正文时应当保留原始错误")
+	}
+	if len(rec.fallback) != 0 {
+		t.Error("已经产出正文时不该降级（会出现两段互相矛盾的答案）")
+	}
+	if !strings.Contains(info.Reason, "正文") {
+		t.Errorf("没降级要给原因：%q", info.Reason)
+	}
+}
+
+func TestStreamWithFallbackClearsSession(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-sess", err: errors.New("expired")}
+	backup := &fallbackFakeEngine{name: "fb-sess2", text: "ok"}
+	withFallbackEngines(t, primary, backup)
+
+	_, _, err := StreamWithFallback(context.Background(), primary, Request{
+		SessionID:      "sess-of-primary",
+		Continue:       true,
+		FallbackEngine: "fb-sess2",
+	}, func(StreamEvent) {})
+	if err != nil {
+		t.Fatalf("降级应成功：%v", err)
+	}
+	if backup.lastReq.SessionID != "" || backup.lastReq.Continue {
+		t.Errorf("降级必须清掉会话锚点：session=%q continue=%v", backup.lastReq.SessionID, backup.lastReq.Continue)
+	}
+}
+
+// 主引擎残留的终帧不能漏给调用方：否则这一轮在备用开口前就被画成「已结束」。
+func TestStreamWithFallbackDropsPrimaryTerminalFrames(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-term", err: errors.New("boom")}
+	backup := &fallbackFakeEngine{name: "fb-term2", text: "ok"}
+	withFallbackEngines(t, primary, backup)
+
+	rec := &fallbackRecorder{}
+	_, _, err := StreamWithFallback(context.Background(), primary, Request{
+		FallbackEngine: "fb-term2",
+	}, rec.on)
+	if err != nil {
+		t.Fatalf("应降级成功：%v", err)
+	}
+	// 假引擎的 Stream 不走 accumulator、不会自己发终帧；这里直接验过滤口径。
+	if _, keep := stripNonResetKinds(StreamEvent{Kind: KindTurnEnd}); keep {
+		t.Error("turn_end 应被吞掉")
+	}
+	if _, keep := stripNonResetKinds(StreamEvent{Kind: KindTurnFailed}); keep {
+		t.Error("turn_failed 应被吞掉")
+	}
+	if _, keep := stripNonResetKinds(StreamEvent{Kind: KindThinking, Text: "思考"}); !keep {
+		t.Error("思考等过程事件应照常转发")
+	}
+}
+
+func TestRunWithFallback(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-c1", err: errors.New("quota")}
+	backup := &fallbackFakeEngine{name: "fb-c2", text: "完成"}
+	withFallbackEngines(t, primary, backup)
+
+	var note string
+	resp, info, err := RunWithFallback(context.Background(), primary, Request{FallbackEngine: "fb-c2"},
+		RunOptions{}, func(fe FallbackEvent) { note = FallbackNoticeText(fe) })
+	if err != nil {
+		t.Fatalf("应降级成功：%v", err)
+	}
+	if resp.Text != "完成" || !strings.Contains(note, "降级") || !strings.Contains(note, "fb-c2") {
+		t.Errorf("resp=%q note=%q", resp.Text, note)
+	}
+	if !info.Used || info.Engine != "fb-c2" {
+		t.Errorf("FallbackInfo：%#v", info)
+	}
+}
+
+// 同引擎换模型（非流式路径同样要生效）。
+func TestRunWithFallbackSameEngineOtherModel(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-rm", err: errors.New("402")}
+	backup := &fallbackFakeEngine{name: "fb-rm", text: "备用"}
+	withFallbackEngines(t, backup)
+
+	_, info, err := RunWithFallback(context.Background(), primary, Request{
+		Model: "a", FallbackEngine: "fb-rm", FallbackModel: "b",
+	}, RunOptions{}, nil)
+	if err != nil {
+		t.Fatalf("应降级成功：%v", err)
+	}
+	if backup.lastReq.Model != "b" {
+		t.Errorf("同引擎换模型应带上备用模型：%q", backup.lastReq.Model)
+	}
+	if !info.Used || info.Model != "b" {
+		t.Errorf("FallbackInfo.Model 应是备用模型：%#v", info)
+	}
+}
+
+// 引擎与模型都相同 = 没有可降级的目标：不白跑一次，原因说出来。
+func TestFallbackNoopWhenIdentical(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-id", err: errors.New("boom")}
+	withFallbackEngines(t, primary)
+
+	_, info, err := RunWithFallback(context.Background(), primary, Request{
+		FallbackEngine: "fb-id", FallbackModel: "",
+	}, RunOptions{}, nil)
+	if err == nil {
+		t.Fatal("引擎与模型都相同时应返回原始错误")
+	}
+	if !strings.Contains(info.Reason, "没有可降级") {
+		t.Errorf("应说明没有降级目标：%q", info.Reason)
+	}
+}
+
+func TestFallbackIgnoresUnknownEngine(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-only", err: errors.New("boom")}
+	withFallbackEngines(t, primary)
+
+	_, info, err := StreamWithFallback(context.Background(), primary, Request{
+		FallbackEngine: "不存在的引擎",
+	}, func(StreamEvent) {})
+	if err == nil {
+		t.Fatal("备用引擎不存在时应返回原始错误")
+	}
+	if !strings.Contains(info.Reason, "不存在") {
+		t.Errorf("应说明备用引擎不存在：%q", info.Reason)
+	}
+}
+
+// 备用没有流式能力：流式路径不降级（原因说出来）。
+func TestFallbackStreamNeedsStreamer(t *testing.T) {
+	primary := &fallbackFakeEngine{name: "fb-ns-p", err: errors.New("boom")}
+	backup := &fallbackFakeNonStream{name: "fb-ns", text: "非流式答案"}
+	withFallbackEngines(t, primary, backup)
+
+	_, info, err := StreamWithFallback(context.Background(), primary, Request{
+		FallbackEngine: "fb-ns",
+	}, func(StreamEvent) {})
+	if err == nil {
+		t.Fatal("备用不支持流式时应返回原始错误")
+	}
+	if !strings.Contains(info.Reason, "流式") {
+		t.Errorf("应说明备用不支持流式：%q", info.Reason)
+	}
+}

package/internal/agent/launch.go

@@ -8,7 +8,7 @@ package agent
 //
 //	npm 全局装的 shim：Windows 上是 claude.cmd / codebuddy.cmd（批处理），
 //	                  macOS/Linux 上是 claude / codebuddy（无扩展名的脚本）
-//	独立安装的原生二进制：trae-cli.exe / dsh 等
+//	独立安装的原生二进制：traex.exe / dsh 等
 //
 // **批处理不能被直接 exec**。Windows 的 exec.Command 遇到 `.cmd` 会走
 // cmd.exe 解析层，参数里的非 ASCII 字符会被代码页转换吃掉（中文 → 乱码），
@@ -112,6 +112,48 @@ func launchWrap(bin string, args []string) launchSpec {
 	}
 }
 
+/* WrapLaunch 把「可执行文件 + 参数」变成**可直接 exec** 的形式，供本仓之外的
+ * 调用方使用（目前是 internal/client 的脚本管理，见 scripts.go）。
+ *
+ * 与 launchWrap 的区别（三条，都重要）：
+ *
+ *  1. **不做 emptyStringFlags 改写**。那张表登记的是**引擎 prompt flag**
+ *     （--tools），是引擎语义的一部分；脚本的参数是用户自己填的定长参数，
+ *     套上引擎的白名单只会莫名其妙地改写用户的参数。
+ *  2. **返回两个值而不是 launchSpec**。launchSpec 是引擎内部的启动决策，
+ *     带上 wrapped 诊断位；对外只需要「拿这俩去 exec」。
+ *  3. **会传播退出码**（launchWrap 不会）。见下面那段说明。
+ *
+ * 为什么需要它：Windows 上 `.cmd/.bat/.ps1` **不能直接 exec** ——
+ * cmd.exe 解析层会把参数里的中文、& | ^ % 拆坏（见本文件头）。
+ * 脚本管理要跑用户登记的脚本文件，Windows 上多半就是 `.cmd` / `.ps1`，
+ * 不走这层包装就会静默失败。
+ *
+ * ── 为什么要传播退出码 ──
+ *
+ * 实测（2026-10-24）：PowerShell 用 `& 'script.cmd'` 调一个 `exit /b 3` 的
+ * 批处理时，**PowerShell 自己的退出码是 1，不是 3** —— 脚本的退出码被
+ * PowerShell 吞掉了。后果是「脚本失败」在界面上显示成退出码 1，
+ * 具体的 3 看不到（用户排查时少一条关键信息）。
+ *
+ * 补一句 `exit $LASTEXITCODE` 就能把它带出来（实测退出码变回 3）。
+ * 引擎路径不需要这个 —— 引擎的成败看的是输出与 `result` 事件，不是退出码。
+ */
+func WrapLaunch(bin string, args []string) (string, []string) {
+	if !platformIsWindows() {
+		return bin, args
+	}
+	if !needsPowerShellWrap(bin) {
+		return bin, args
+	}
+	script := powershellInvokeScript(bin, args)
+	// 退出码透传：$LASTEXITCODE 是「最近一次原生命令」的退出码。
+	// 对 .ps1 它是 $null（PowerShell 脚本没有原生退出码）—— 那时
+	// `exit $null` 等于 exit 0，也合理（PowerShell 脚本正常跑完就是成功）。
+	script += "; exit $LASTEXITCODE"
+	return powershellBin(), []string{"-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script}
+}
+
 // emptyStringFlags 全局登记：本项目里哪些 flag 会以**空串**作为值。
 //
 // 为什么要全局而不是按引擎传：改写发生在 launchWrap 这一层，

package/internal/agent/limitnotice.go

@@ -44,12 +44,17 @@ package agent
 import (
 	"regexp"
 	"strings"
+	"time"
 	"unicode/utf8"
 )
 
 // limitNoticeMaxRunes 通告那一段的长度上限（一句话；长回答不该被整段吞掉）。
 const limitNoticeMaxRunes = 400
 
+// limitNoticeWholeMaxRunes 「整段就是通告、但没给恢复时刻」那一档的长度上限。
+// 它没有「时刻」当分水岭，所以更靠长度挡误伤：真通告都短，正经回答很少整段这么短。
+const limitNoticeWholeMaxRunes = 160
+
 var (
 	// 起点：句子边界（正文开头 / 换行 / 句末标点 / 冒号）+ 已知状态码 + 一个空格。
 	// ⚠️ 刻意**不认「普通空格之后」**：模型正经回答里写「HTTP 429 是限流，额度会在 … 重置」
@@ -64,12 +69,41 @@ var (
 	// 排障用的请求 id 尾巴（形如 `(0l1a124d…/0l1a123c3-…)`）—— 它属于通告，
 	// 判「整段一句话」时要先剥掉。
 	limitNoticeIDTailRe = regexp.MustCompile(`\s*\([^()\n]{4,200}\)\s*$`)
+	// 请求 id 的另一种写法（实测 2026-10-25 英文额度通告：`Request id: 0217929113…`）——
+	// 它既不是给人看的，也不该进卡片的原文行；剥掉括号尾巴之后再剥它一次。
+	limitNoticeReqIDRe = regexp.MustCompile(`(?i)\s*request[\s_-]?id\s*[:：]\s*[0-9a-z][0-9a-z-]{6,}\s*$`)
 	// 末尾那个句号（可有可无，剥掉后再判「段内还有没有句末标点」）。
 	limitNoticeEndRe = regexp.MustCompile(`[。.!！?？]\s*$`)
 	// 段内的句末标点（出现即说明这段不止一句话 → 不是通告）。
 	limitNoticeSeptRe = regexp.MustCompile(`[。！？!?]`)
+
+	/* 「整段就是通告、但没给恢复时刻」那一档（见 wholeNoticeCore）。它的判据不带时刻，
+	   所以每一条都独立收紧：状态码必须顶在最前面、措辞必须是「用量真的没了」（不是
+	   「429 表示限流」这种释义句）、并且必须给出「接下来怎么办」。 */
+	limitNoticeCodeHeadRe = regexp.MustCompile(`^(?:429|402|401|403|5\d{2})\s`)
+	/* 释义句的形状：「429 是限流」「429 表示…」—— 这是模型在**回答**用户的问题，
+	   不是供应商在报错。只认状态码开头那一种（别的位置出现「表示」不影响）。 */
+	limitNoticeExplainRe = regexp.MustCompile(`(?i)^(?:429|402|401|403|5\d{2})\s*(?:是|就是|表示|指|means|refers)`)
+	noticeExhaustRe      = regexp.MustCompile(`(?i)用量上限|用量已|额度|余额|欠费|用尽|用完|quota|insufficient|exceeded|balance`)
+	noticeExhaustHintRe  = regexp.MustCompile(`(?i)升级|购买|充值|续费|补充|开通|重置|切换|稍后|再试|upgrade|purchase|top ?up|recharge|reset|retry|switch`)
 )
 
+// stripNoticeTails 剥掉通告末尾的排障尾巴（括号里的请求 id、以及 `Request id: …` 那种写法）
+// 与末尾标点。三条路径（末尾夹通告 / 整段就是通告）都要剥同一套，所以收在一处。
+func stripNoticeTails(s string) string {
+	out := strings.TrimSpace(s)
+	// 可能连着几条尾巴（实测 402：「…消耗。 (2067) (01a1…/01a1…)」），循环剥干净。
+	for i := 0; i < 3; i++ {
+		next := strings.TrimSpace(limitNoticeIDTailRe.ReplaceAllString(out, ""))
+		next = strings.TrimSpace(limitNoticeReqIDRe.ReplaceAllString(next, ""))
+		if next == out {
+			break
+		}
+		out = next
+	}
+	return strings.TrimSpace(limitNoticeEndRe.ReplaceAllString(out, ""))
+}
+
 // splitLimitNotice 判 text 的**末尾**是不是夹着一句供应商的限流/额度通告。
 //
 // 命中返回 (通告原文, 通告之前真正的正文, true)；不命中返回 ("", "", false)。
@@ -88,7 +122,7 @@ func splitLimitNotice(text string) (notice, body string, ok bool) {
 		if seg == "" || utf8.RuneCountInString(seg) > limitNoticeMaxRunes {
 			continue
 		}
-		core := strings.TrimSpace(limitNoticeEndRe.ReplaceAllString(limitNoticeIDTailRe.ReplaceAllString(seg, ""), ""))
+		core := stripNoticeTails(seg)
 		if limitNoticeSeptRe.MatchString(core) {
 			continue
 		}
@@ -99,5 +133,177 @@ func splitLimitNotice(text string) (notice, body string, ok bool) {
 		}
 		return strings.Join(strings.Fields(core), " "), strings.TrimRight(s[:at], " \t\r\n\u3000"), true
 	}
+	// 整段就是通告、但**没给恢复时刻**那一档（2026-10-25，实测 402 原文）：
+	//   402 当前已达到 Token Plan 用量上限。为避免调用中断，请升级 Token Plan 套餐，或购买积分…
+	// 上面那条判据把「有恢复时刻」当分水岭，这类通告因此漏了；而它整轮只有这一段正文，
+	// 落到画面上就是「一大段供应商原文 + 已完成」。这里补一条**更严**的窄路（四条同时成立）：
+	//   ① 整段就是它（body 必须为空）—— 不是「末尾夹着」，那就没有「哪句是通告」的歧义；
+	//   ② 开头就是状态码（前面连正文都没有）；
+	//   ③ 有「用量真的没了」的措辞（noticeExhaustRe）—— 不是「429 是什么意思」那种释义句；
+	//   ④ 短（≤160 字）。
+	if core, hit := wholeNoticeCore(s); hit {
+		return core, "", true
+	}
 	return "", "", false
 }
+
+// wholeNoticeCore 上面那条窄路的本体（整段就是一个不带时刻的额度通告）。
+//
+// ⚠️ 这条路**不要求「一句话」**：实测那条 402 原文本身就有两个句号（「…用量上限。为避免
+// 调用中断，请升级…」）。换成四条更硬的约束来挡误伤 —— 它们任何一条都比「句数」更难蒙对：
+// 整段只有它（没有「哪句是通告」的歧义）、开头就是状态码、措辞是「用量真的没了」而不是
+// 「429 表示…」这种释义句、并且短。
+func wholeNoticeCore(s string) (string, bool) {
+	core := stripNoticeTails(s)
+	if core == "" || utf8.RuneCountInString(core) > limitNoticeWholeMaxRunes {
+		return "", false
+	}
+	if strings.ContainsAny(core, "\n\r") { // 通告只有一段；换行 = 这是个正经回答
+		return "", false
+	}
+	if !limitNoticeCodeHeadRe.MatchString(core) { // 状态码必须在最前面
+		return "", false
+	}
+	if limitNoticeExplainRe.MatchString(core) { // 「429 是限流…」= 在回答，不是通告
+		return "", false
+	}
+	if !noticeExhaustRe.MatchString(core) || !noticeExhaustHintRe.MatchString(core) {
+		return "", false
+	}
+	return strings.Join(strings.Fields(core), " "), true
+}
+
+/* ── 通告的结构化字段（2026-10-25）────────────────────────────────
+ *
+ * 由来：用户报障「没额度了，设计一个提示卡」。界面要画一张**额度卡**
+ * （什么时候恢复 / 该怎么办），可事件上原来只有 Error / Reason 两段人话原文，
+ * 客户端只能靠正则从原文里反推 —— 反推逻辑一旦写错就是错卡，且三端会各写一套。
+ * 所以分类与时刻解析收在这里（core 一处），事件带上 error_kind / error_code /
+ * reset_at，客户端只做展示。
+ *
+ * 两档（客户端据此决定标题与建议，不能只有一个「出了错」）：
+ *
+ *	quota      额度用尽 / 余额不足 / 套餐用量上限 —— 等恢复或换模型，与代码无关；
+ *	rate_limit 频率限制（短时窗口）—— 隔一会儿再试即可。
+ *
+ * 判据刻意保守：认不出来就返回空 kind（客户端退回普通「调用失败」卡），
+ * 不硬套标签 —— 把「工具报错」画成「额度不足」比不画更糟。
+ */
+const (
+	// ErrorKindQuota 额度用尽（余额 / 套餐用量上限 / quota exhausted）。
+	ErrorKindQuota = "quota"
+	// ErrorKindRateLimit 频率限制（短时窗口，等一会儿就能再试）。
+	ErrorKindRateLimit = "rate_limit"
+)
+
+var (
+	// 额度类措辞（比 limitNoticeNounRe 更宽：通告已经被认出来了，这里只分档）。
+	noticeQuotaRe = regexp.MustCompile(`(?i)额度|余额|欠费|quota|insufficient|balance|credit|用量上限|token plan|plan limit|套餐`)
+	noticeRateRe  = regexp.MustCompile(`(?i)频率限制|限流|rate[\s_-]?limit|frequency limit|too many requests|用量过多`)
+	// 状态码（通告开头那几个，与 splitLimitNotice 的起点判据同一套）。
+	noticeCodeRe = regexp.MustCompile(`^\s*(\d{3})\b`)
+	// 恢复时刻：`2026-10-25 15:07:27` 主体（两种实测格式共用）。
+	noticeStampRe = regexp.MustCompile(`(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?`)
+	// 时区偏移：`+0800` / `+08:00` / `UTC+8` 三种拼法（实测都出现过）。
+	noticeZoneRe = regexp.MustCompile(`(?i)(?:UTC)?\s*([+-])(\d{1,2}):?(\d{2})?`)
+	// ISO 的 Z（= UTC）。必须单独判：`noticeZoneRe` 认的是带符号的偏移，Z 没有符号。
+	noticeZuluRe = regexp.MustCompile(`(?i)^\s*Z\b`)
+)
+
+// classifyNotice 把一条已认定的额度/限流通告分成两档，并取出状态码。
+//
+// kind 为空 = 是限流类通告但分不清是哪一档（客户端按普通失败卡处理）。
+// code 为空 = 通告里没有状态码。
+func classifyNotice(text string) (kind, code string) {
+	s := strings.TrimSpace(text)
+	if s == "" {
+		return "", ""
+	}
+	if m := noticeCodeRe.FindStringSubmatch(s); m != nil {
+		code = m[1]
+	}
+	switch {
+	case noticeQuotaRe.MatchString(s):
+		kind = ErrorKindQuota
+	case noticeRateRe.MatchString(s):
+		kind = ErrorKindRateLimit
+	}
+	/* 402 是「需要付费」的语义码，原文措辞可能只有一句「Payment Required」——
+	   这种也要算额度，否则用户看到的是一张普通错误卡。 */
+	if kind == "" && code == "402" {
+		kind = ErrorKindQuota
+	}
+	return kind, code
+}
+
+// parseNoticeReset 从通告里取「什么时候恢复」，取不到返回零值时间。
+//
+// ⚠️ 三种拼法都要认（都是本仓库日志里的**实测原文**）：
+//
+//	2026-10-25 15:07:27 +0800 CST   ← 英文版；偏移无冒号，尾部还有一个**无意义**的 CST
+//	2026-10-25 23:45:51 UTC+8       ← 中文版
+//	2026-10-25T15:07:27Z            ← 少数供应商给 ISO 形状
+//
+// ⚠️ **绝不用 Date.parse 那套宽松解析**：V8 会把 `CST` 当美国中部时间，
+// 实测偏 14 小时 —— 界面上就成了「半夜三点恢复」。这里只认显式偏移，
+// 没有偏移就按**本地时区**理解（通告是给本机用户看的，供应商给的钟点也是本地的）。
+func parseNoticeReset(text string) time.Time {
+	s := strings.TrimSpace(text)
+	m := noticeStampRe.FindStringSubmatch(s)
+	if m == nil {
+		return time.Time{}
+	}
+	atoi := func(v string) int {
+		n := 0
+		for _, c := range v {
+			if c < '0' || c > '9' {
+				return n
+			}
+			n = n*10 + int(c-'0')
+		}
+		return n
+	}
+	sec := 0
+	if m[6] != "" {
+		sec = atoi(m[6])
+	}
+	t := time.Date(atoi(m[1]), time.Month(atoi(m[2])), atoi(m[3]),
+		atoi(m[4]), atoi(m[5]), sec, 0, time.Local)
+	/* 时区：只在时间戳**紧跟其后**的那一小段里找偏移 —— 全串搜会把
+	   「Request id: +86…」这类内容当成时区。 */
+	rest := strings.TrimSpace(s[strings.Index(s, m[0])+len(m[0]):])
+	if rest != "" {
+		zonePart := rest
+		if i := strings.IndexAny(zonePart, "\n"); i >= 0 {
+			zonePart = zonePart[:i]
+		}
+		if len(zonePart) > 16 {
+			zonePart = zonePart[:16]
+		}
+		if z := noticeZoneRe.FindStringSubmatch(zonePart); z != nil {
+			h, min := atoi(z[2]), atoi(z[3])
+			offset := h*3600 + min*60
+			if z[1] == "-" {
+				offset = -offset
+			}
+			loc := time.FixedZone("", offset)
+			t = time.Date(atoi(m[1]), time.Month(atoi(m[2])), atoi(m[3]),
+				atoi(m[4]), atoi(m[5]), sec, 0, loc)
+		} else if noticeZuluRe.MatchString(zonePart) {
+			/* `…T15:07:27Z`（ISO 的 Z = UTC）。别漏了这一支：漏了就会按**本地时区**理解，
+			   本机在 +08 时整体偏 8 小时（测试就是在这里抓到它的）。 */
+			t = time.Date(atoi(m[1]), time.Month(atoi(m[2])), atoi(m[3]),
+				atoi(m[4]), atoi(m[5]), sec, 0, time.UTC)
+		}
+	}
+	return t
+}
+
+// noticeResetRFC3339 通告里的恢复时刻（RFC3339）；取不到回空串（wire 上是 omitempty）。
+func noticeResetRFC3339(text string) string {
+	t := parseNoticeReset(text)
+	if t.IsZero() {
+		return ""
+	}
+	return t.Format(time.RFC3339)
+}