magic-agent 1.0.2 → 1.0.46

package/internal/agent/launch.go

@@ -0,0 +1,192 @@
+package agent
+
+// launch.go - 跨平台的「怎么把引擎进程拉起来」包装层（平台无关部分）。
+//
+// ## 为什么需要这一层
+//
+// 引擎 CLI 有两种落地形态：
+//
+//	npm 全局装的 shim：Windows 上是 claude.cmd / codebuddy.cmd（批处理），
+//	                  macOS/Linux 上是 claude / codebuddy（无扩展名的脚本）
+//	独立安装的原生二进制：trae-cli.exe / dsh 等
+//
+// **批处理不能被直接 exec**。Windows 的 exec.Command 遇到 `.cmd` 会走
+// cmd.exe 解析层，参数里的非 ASCII 字符会被代码页转换吃掉（中文 → 乱码），
+// `&` `|` `^` `%` 会被当命令语法解析，子进程拿不到原始输入。
+//
+// 实测的真凶（2026-10-01，对照矩阵，提示词含换行+中文+%&^+引号）：
+//
+//	裸 claude.exe 直连        → 位置参数、stdin 两条路都完好无损
+//	claude.cmd 直连 + 位置参数 → 中文乱码、`&` 触发「'香蕉' 不是内部或外部命令」
+//	claude.cmd 直连 + stdin    → 完好（stdin 走字节流，不过参数解析层）
+//
+// ⚠️ 换行**不是**元凶（.cmd 下 LF/CRLF 都正常）。换行只是最容易被肉眼
+// 发现的触发点，真正破坏内容的是编码转换与元字符解析。
+//
+// agents-anywhere 对同一问题的处理见
+// `anywhere-labs/Agents-Anywhere` 的 `connector/connector/launch.py:48-56`：
+// `.cmd`/`.bat` 一律不直接 exec，改包成
+// `powershell -NoProfile -ExecutionPolicy Bypass -Command "& 'path' 'arg1' …"`，
+// 参数用**单引号**转义（单引号写两个）。本文件是它的 Go 等价物。
+//
+// ## 本层解决什么、不解决什么
+//
+// 解决：**引号层面的**参数传递（launchWrap 只在 Windows 上生效，
+// unix 直连，行为零变化）。
+//
+// 不解决：**长度/结构层面**的提示词传递 —— 提示词不该当位置参数传。
+// 那是引擎各自的选择，见 claude.go / codebuddy.go 的「提示词走 stdin」。
+// 两层是互补的：stdin 解决内容，launchWrap 解决剩下的 flag 传递。
+
+import (
+	"path/filepath"
+	"strings"
+)
+
+// launchSpec 描述一次「最终怎么 exec」的决策结果。
+type launchSpec struct {
+	// bin 真正要交给 exec.Command 的可执行文件。
+	bin string
+	// args 真正要交给 exec.Command 的参数（已按 launcher 变形）。
+	args []string
+	// wrapped 标记是否经过了 PowerShell 包装（诊断用；false = 原样直连）。
+	wrapped bool
+}
+
+// windowsBatchExt 是 Windows 上**不能直接 exec** 的脚本后缀。
+//
+// `.ps1` 需要 ExecutionPolicy Bypass 才能跑，`.cmd`/`.bat` 需要 cmd.exe
+// 解析层 —— 两者都要包一层 PowerShell 才安全。
+var windowsBatchExt = map[string]bool{
+	".cmd": true,
+	".bat": true,
+	".ps1": true,
+}
+
+// needsPowerShellWrap 报告这个可执行文件在当前平台是否需要 PowerShell 包装。
+//
+// 判定依据是**后缀**而非「能不能执行」：npm 装的 shim 在 Windows 上
+// 一定是 .cmd，即便 PATH 里 shim 指向的可能是别的东西。
+func needsPowerShellWrap(bin string) bool {
+	if !platformIsWindows() {
+		return false
+	}
+	return windowsBatchExt[strings.ToLower(filepath.Ext(bin))]
+}
+
+// launchWrap 按平台把「引擎可执行文件 + 它的参数」变成可直接 exec 的形式。
+//
+// unix：原样返回（零行为变化）。
+// Windows + 原生 exe：原样返回。
+// Windows + .cmd/.bat/.ps1：包成
+//
+//	powershell -NoProfile -ExecutionPolicy Bypass -Command
+//	  "& 'C:\path\claude.cmd' 'arg1' 'arg2'"
+//
+// 空串 flag 由调用方通过 emptyStringFlags 声明（见 emptyArgAsFlagValue 的说明）。
+//
+// ⚠️ 为什么不用 cmd /c 包一层（更"原生"的做法）：cmd 的引号规则在参数里
+// 出现时无法可靠转义 —— % 是变量展开、^ 是转义符、& 是命令分隔符，
+// 提示词里任何一个都可能踩到。PowerShell 的单引号字符串是字面量，
+// 唯一的转义就是把单引号写成两个，语义上没有二义性。这与 agents-anywhere 的
+// launch.py 选 powershell 而非 cmd 是同一个理由。
+func launchWrap(bin string, args []string) launchSpec {
+	if !platformIsWindows() {
+		return launchSpec{bin: bin, args: args}
+	}
+	// 先把「flag + 空串」改写成 flag=，再进包装 —— 顺序不能反：
+	// 包装后参数已成 PowerShell 脚本文本，空串已无处安放。
+	if len(emptyStringFlags) > 0 {
+		for _, f := range emptyStringFlags {
+			args = emptyArgAsFlagValue(args, f)
+		}
+	}
+	if !needsPowerShellWrap(bin) {
+		return launchSpec{bin: bin, args: args}
+	}
+	script := powershellInvokeScript(bin, args)
+	return launchSpec{
+		bin:     powershellBin(),
+		args:    []string{"-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script},
+		wrapped: true,
+	}
+}
+
+// emptyStringFlags 全局登记：本项目里哪些 flag 会以**空串**作为值。
+//
+// 为什么要全局而不是按引擎传：改写发生在 launchWrap 这一层，
+// 而引擎各自的 buildArgs 只知道「我要传 --tools 空串」，
+// 不该知道「Windows 上这么传会丢」。分层就在这里 —— 引擎管语义，
+// launch 管平台怎么落地。
+//
+// ⚠️ 这是一张**白名单**，不是「所有空串」的通用规则：
+// 未来新增「用空串表达含义」的 flag 时必须登记进来，否则在 Windows 上
+// 会静默丢参数（症状：该 flag 被 CLI 忽略，行为退回默认）。
+var emptyStringFlags = []string{"--tools"}
+
+// powershellInvokeScript 拼出 PowerShell 的调用脚本：
+// `& '脚本路径' '参数1' '参数2' …`
+//
+// & 是 PowerShell 的调用运算符（"执行这个"），必须保留；
+// 路径与每个参数都用单引号包起来，单引号自身写成两个。
+func powershellInvokeScript(bin string, args []string) string {
+	parts := make([]string, 0, len(args)+1)
+	parts = append(parts, "&", powershellQuote(bin))
+	for _, a := range args {
+		parts = append(parts, powershellQuote(a))
+	}
+	return strings.Join(parts, " ")
+}
+
+// powershellQuote PowerShell 单引号字符串字面量。
+//
+// 单引号字符串内**只有两种转义**：” 表示一个字面单引号，
+// 其余（含 $ ` " ）全部按字面量处理 —— 这正是我们要的：提示词里的
+// 美元符号、反引号、双引号都不用操心。
+func powershellQuote(v string) string {
+	return "'" + strings.ReplaceAll(v, "'", "''") + "'"
+}
+
+// emptyArgAsFlagValue 把「flag + 空串值」这一对参数改写成 `flag=` 形式。
+//
+// ## 为什么必须改写（2026-10-01 实测，本文件存在的第二个理由）
+//
+// 引擎 CLI 里有一批「用空串表达含义」的 flag，claude 的 `--tools ""` 就是
+// 典型（空串 = 禁用全部内置工具，见 claude.go buildArgsBase 的 toolsIsOff 分支）。
+//
+// 传法有两种，**只有一种在 Windows 上活着**：
+//
+//	--tools ""     ❌ 0 行输出、~320ms 挂
+//	--tools=       ✅ 正常输出
+//
+// ⚠️ 机制不是「cmd.exe 吞空串」—— 2026-10-01 的对照实测（裸 claude.exe
+// 直连，绕开一切 shim）里 `--tools ""` 一样挂，所以**这跟 .cmd/cmd.exe
+// 无关**。真实机制是：**Windows 命令行本身无法可靠传递空串参数**。
+// Go 的 `syscall.EscapeArg` 把空串编成 `""`，可命令行解析层不保证把它
+// 当成一个实参传下去（本机实测就是被丢弃），于是 CLI 收到的 argv 表
+// 少了一个元素 → 后续位置参数**整体错位** → 表现为「认不出 prompt」：
+//
+//	Input must be provided either through stdin or as a prompt argument
+//
+// 2×2 交叉实测（单行 / 多行 / 单换行 × split / merged）结论一致：
+// 只要是独立空串 argv 就 ~320ms 挂，**与换行、与中文都无关**。
+// `-p ""`（flag 自己吃空串）同样挂；而 `--model ""` + `--tools=` 正常 ——
+// 说明触发条件是「flag 与空串相邻」这一形状，不是某个具体 flag。
+//
+// `--tools=` 只有一个 argv 元素、不含空串，绕开了这个坑，且对 CLI 等价
+// （所有这些 CLI 都同时接受 `--flag value` 与 `--flag=value` 两种写法）。
+//
+// unix 上不做改写：argv 原样传，空串本来就是合法的空参数。
+func emptyArgAsFlagValue(args []string, flag string) []string {
+	out := make([]string, 0, len(args))
+	for i := 0; i < len(args); i++ {
+		// 命中 `flag` + 空串值这一对 → 合并成 `flag=`
+		if args[i] == flag && i+1 < len(args) && args[i+1] == "" {
+			out = append(out, flag+"=")
+			i++ // 跳过被合并的空串
+			continue
+		}
+		out = append(out, args[i])
+	}
+	return out
+}

package/internal/agent/launch_test.go

@@ -0,0 +1,206 @@
+package agent
+
+// launch_test.go - 平台包装层的回归测试（2026-10-01）。
+//
+// 这组断言守的是两个**静默**退化：参数被 cmd.exe 吞掉、思维链混进正文。
+// 两者都不报错、退出码都是 0，只能靠断言挡住。
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestEmptyArgAsFlagValue 「flag + 空串」必须改写成 flag=。
+//
+// 这是 Windows 上必需的一步：--tools "" 的空串是独立 argv 元素，
+// 经 .cmd 传参时被丢弃，CLI 收到残缺参数表后表现是「认不出 prompt」。
+func TestEmptyArgAsFlagValue(t *testing.T) {
+	cases := []struct {
+		name string
+		in   []string
+		want []string
+	}{
+		{"独立空串改写", []string{"-p", "--tools", "", "--model", "m"},
+			[]string{"-p", "--tools=", "--model", "m"}},
+		{"末尾空串", []string{"--tools", ""}, []string{"--tools="}},
+		{"无空串不动", []string{"--tools", "Read,Bash"}, []string{"--tools", "Read,Bash"}},
+		{"flag 不误伤其他值", []string{"--model", "", "--tools", "x"},
+			[]string{"--model", "", "--tools", "x"}},
+		{"空 flag 不匹配", []string{"--tool", ""}, []string{"--tool", ""}},
+		{"空数组", []string{}, []string{}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := emptyArgAsFlagValue(c.in, "--tools")
+			if len(got) != len(c.want) {
+				t.Fatalf("长度 = %d(%q)，want %d(%q)", len(got), got, len(c.want), c.want)
+			}
+			for i := range got {
+				if got[i] != c.want[i] {
+					t.Fatalf("第 %d 个 = %q，want %q", i, got[i], c.want[i])
+				}
+			}
+		})
+	}
+}
+
+// TestPowershellQuoteLiteral 提示词里的元字符必须原样保留。
+//
+// PowerShell 单引号字符串里只有一种转义（”），所以 $ ` " 都自动安全。
+// 这条断言是「不要偷懒改成双引号字符串」的护栏 —— 换成双引号后
+// $var 会被 PowerShell 展开，提示词内容就变了。
+func TestPowershellQuoteLiteral(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"abc", "'abc'"},
+		{"", "''"},
+		{"$env:PATH", "'$env:PATH'"},
+		{"say \"hi\"", `'say "hi"'`},
+		{"back`tick", "'back`tick'"},
+		{"it's", "'it''s'"},
+		{"a\nb", "'a\nb'"}, // 换行在单引号内是字面量，不需转义
+	}
+	for _, c := range cases {
+		if got := powershellQuote(c.in); got != c.want {
+			t.Errorf("powershellQuote(%q) = %s，want %s", c.in, got, c.want)
+		}
+	}
+}
+
+// TestPowerShellScriptShape 生成的调用脚本形状正确（& 调用运算符 + 逐参数单引号）。
+func TestPowerShellScriptShape(t *testing.T) {
+	got := powershellInvokeScript(`C:\a b\claude.cmd`, []string{"-p", "it's", "x\ny"})
+	want := `& 'C:\a b\claude.cmd' '-p' 'it''s' 'x` + "\n" + `y'`
+	if got != want {
+		t.Fatalf("got  = %q\nwant = %q", got, want)
+	}
+	// 换行绝不能把脚本截断（PowerShell -Command 按行解析）。
+	if strings.Count(got, "\n") != 1 || !strings.Contains(got, "'x\ny'") {
+		t.Fatalf("换行未被安全包住：%q", got)
+	}
+}
+
+// TestNeedsPowerShellWrap 后缀判定。
+//
+// 期望值按**运行平台**取值：unix 上 needsPowerShellWrap 一律 false
+// （launchWrap 直接原样返回），Windows 上才看后缀。
+// 写死 Windows 的期望会让本文件在 macOS/CI(linux) 上必然红。
+func TestNeedsPowerShellWrap(t *testing.T) {
+	wrap := platformIsWindows() // 平台总开关
+	cases := []struct {
+		bin      string
+		wantWrap bool // 仅当 wrap == true 时才参与断言
+	}{
+		{`C:\npm\claude.cmd`, true},
+		{`C:\npm\foo.BAT`, true},
+		{`C:\npm\script.ps1`, true},
+		{`C:\trae\trae-cli.exe`, false},
+		{`/opt/homebrew/bin/claude`, false},
+		{"claude", false},
+		{"", false},
+		{"weird.cmd.txt", false}, // 只看最后一个后缀
+	}
+	for _, c := range cases {
+		want := c.wantWrap && wrap
+		if got := needsPowerShellWrap(c.bin); got != want {
+			t.Errorf("needsPowerShellWrap(%q) = %v，want %v（platformIsWindows=%v）",
+				c.bin, got, want, wrap)
+		}
+	}
+}
+
+// TestLaunchWrapKeepsOriginalWhenNoWrap 明确「不该包装时绝不包装」。
+//
+// unix 上 launchWrap 必须原样返回：任何改写都会静默改变既有行为
+// （尤其不能改写空串 flag —— 那是 Windows 专属改写）。
+func TestLaunchWrapKeepsOriginalWhenNoWrap(t *testing.T) {
+	if platformIsWindows() {
+		t.Skip("Windows 上 .cmd 会被包装，本断言只对 unix 成立")
+	}
+	in := []string{"-p", "--tools", "", "prompt\nwith\nnewlines"}
+	spec := launchWrap("/opt/homebrew/bin/claude", in)
+	if spec.wrapped {
+		t.Fatal("unix 上不应包装")
+	}
+	if spec.bin != "/opt/homebrew/bin/claude" {
+		t.Fatalf("bin = %q，应原样保留", spec.bin)
+	}
+	if len(spec.args) != len(in) {
+		t.Fatalf("args = %q，应原样保留（含空串）", spec.args)
+	}
+	// 逐项比对：空串必须还在原位（launchWrap 不许碰 unix 的 argv）。
+	for i := range in {
+		if spec.args[i] != in[i] {
+			t.Fatalf("第 %d 个 = %q，want %q", i, spec.args[i], in[i])
+		}
+	}
+}
+
+// TestLaunchWrapNativeExeUntouched Windows 上：原生 .exe 不包装、但空串仍改写。
+//
+// 这条挡的是「把所有 Windows bin 都包一层 PowerShell」的偷懒改法 ——
+// 那样会多出一个常驻 powershell 进程，进程组杀、超时、信号转发全部多一跳，
+// 回归面极大。原生 exe 必须直连。
+func TestLaunchWrapNativeExeUntouched(t *testing.T) {
+	if !platformIsWindows() {
+		t.Skip("本断言只对 Windows 成立")
+	}
+	spec := launchWrap(`C:\trae\trae-cli.exe`, []string{"-p", "--tools", "", "x"})
+	if spec.wrapped {
+		t.Fatal(".exe 不该被包装成 PowerShell")
+	}
+	if spec.bin != `C:\trae\trae-cli.exe` {
+		t.Fatalf("bin = %q", spec.bin)
+	}
+	// 空串改写仍生效（它不依赖包装，是 argv 层面的修补）。
+	joined := strings.Join(spec.args, "\x00")
+	if strings.Contains(joined, "--tools\x00\x00") {
+		t.Fatalf("空串未被改写：%q", spec.args)
+	}
+	if !strings.Contains(joined, "--tools=") {
+		t.Fatalf("缺少 --tools=：%q", spec.args)
+	}
+}
+
+// TestLaunchWrapWindowsScriptShape Windows 上：包装后的参数形状必须可 exec。
+//
+// 精确断言整个 argv（不是 contains 弱匹配）—— 参数顺序/个数错了
+// PowerShell 会静默执行错的命令，而这正是本层要防的那类失败。
+func TestLaunchWrapWindowsScriptShape(t *testing.T) {
+	if !platformIsWindows() {
+		t.Skip("本断言只对 Windows 成立")
+	}
+	spec := launchWrap(`C:\npm\claude.cmd`, []string{"-p", "--tools", "", "multi\nline"})
+	if !spec.wrapped {
+		t.Fatal(".cmd 应被包装成 PowerShell")
+	}
+	if spec.bin != powershellBin() {
+		t.Fatalf("bin = %q，want %q", spec.bin, powershellBin())
+	}
+	wantArgs := []string{
+		"-NoProfile",
+		"-ExecutionPolicy",
+		"Bypass",
+		"-Command",
+		`& 'C:\npm\claude.cmd' '-p' '--tools=' 'multi` + "\n" + `line'`,
+	}
+	if len(spec.args) != len(wantArgs) {
+		t.Fatalf("args = %q\nwant = %q", spec.args, wantArgs)
+	}
+	for i := range wantArgs {
+		if spec.args[i] != wantArgs[i] {
+			t.Fatalf("第 %d 个 = %q，want %q", i, spec.args[i], wantArgs[i])
+		}
+	}
+	// 独立空参数绝不能出现在脚本里（cmd.exe 会把它吞掉）。
+	script := spec.args[len(spec.args)-1]
+	if strings.Contains(script, "''") {
+		t.Fatalf("脚本里出现独立空参数：%q", script)
+	}
+	// 多行提示词必须仍是**一个**引号包裹的参数，不能把 -Command 脚本截断。
+	if !strings.Contains(script, "'multi\nline'") {
+		t.Fatalf("多行提示词未完整保留：%q", script)
+	}
+	if strings.Count(script, "\n") != 1 {
+		t.Fatalf("脚本被换行截断：%q", script)
+	}
+}

package/internal/agent/launch_unix.go

@@ -0,0 +1,15 @@
+//go:build !windows
+
+package agent
+
+// launch_unix.go - Unix (darwin/linux) 侧的 launcher 解析。
+//
+// unix 上没有这一层：npm 装的 shim 是无扩展名的脚本（带 shebang），
+// exec 可以直接执行；launchWrap 在 launch.go 里对非 Windows 直接原样返回。
+// 本文件只提供两个平台分派用的最小实现。
+
+func platformIsWindows() bool { return false }
+
+// powershellBin 在 unix 上不会被调用（launchWrap 不走包装分支）。
+// 保留实现只为让 launch.go 保持可编译，不返回真路径。
+func powershellBin() string { return "" }

package/internal/agent/launch_windows.go

@@ -0,0 +1,24 @@
+//go:build windows
+
+package agent
+
+// launch_windows.go - Windows 侧的 launcher 解析。
+//
+// PowerShell 可执行名按 powershell.exe → powershell → 固定名 顺序找。
+// 优先找实际存在的那个，避免在只有 pwsh 的精简环境里退化成无效命令。
+
+import "os/exec"
+
+func platformIsWindows() bool { return true }
+
+// powershellBin 找可用的 PowerShell。找不到时返回 "powershell.exe"
+// 作为最后的兜底（让 exec 报「找不到文件」这种能看懂的错，
+// 而不是静默失败）。
+func powershellBin() string {
+	for _, name := range []string{"powershell.exe", "powershell", "pwsh.exe", "pwsh"} {
+		if p, err := exec.LookPath(name); err == nil && p != "" {
+			return p
+		}
+	}
+	return "powershell.exe"
+}

package/internal/agent/limitnotice.go

@@ -0,0 +1,103 @@
+package agent
+
+// limitnotice.go - 「限流 / 额度」通告被当成助手正文发回来时的判据（2026-10-10）。
+//
+// 由来（用户报障原话）：「codebuddy ai 没有额度了 没有输出一个独立的错误消息用于提示吗
+// 现在混在回复里了」—— 引擎（供应商）在额度用尽时把通告**当正文**发了回来，而且往往
+// **粘在这一轮正文的末尾**（实测原文两版，中英各一）：
+//
+//	英文（实测这版前面没有换行，直接粘在上一句句号后面，请求 id 尾巴跟在最后）：
+//	  …file's end.429 usage exceeds frequency limit, but don't worry, your usage will reset
+//	  at 2026-10-11 10:32:59 UTC+8, alternatively, you can switch to the other models to
+//	  continue using it. (0l1a124d…/0l1a123c3-…)
+//	中文（2026-09-19 实测）：
+//	  429 您的使用量已超出频率限制，将在 2026-09-19 17:49:56 UTC+8 重置，您也可以切换其他模型继续使用。
+//
+// 这不是回答，是**失败**：原样转发出去，消费方看到的是「一段正经正文 + 一句额度通告 +
+// 已完成」—— 用户既看不出这一轮其实没干完，也不知道该换模型（最坏的那类假成功）。
+//
+// 与本包既有判据的分工（三条都不同，别互相替代）：
+//   - runner.go 的 isRetryable 认的是「**错误**消息里有没有 429 / rate limit」；
+//   - 会话文件那条（cli 侧捞 providerData.error.message）认的是「正文**为空**、原因只在
+//     引擎自己的会话文件里」；
+//   - 本条认的是「**正文末尾夹着**通告」（状态码在中间）—— 上面两条都认不出来。
+//
+// 判据（五条同时成立，宁可漏判也不误伤正常回答）：
+//  ① 状态码是已知的那几个（429/402/401/403/5xx）—— 不认「任意三位数」：否则正文里
+//     一句「端口 8080 与 usage 有关」都会被当成通告；
+//  ② 它落在句子边界上（正文开头 / 换行 / 句末标点或冒号之后，**普通空格不算**）且后面
+//     紧跟空格 —— 实测那个英文版前面是「.」，所以边界里必须有句末标点（不能只认行首）；
+//  ③ 从它到正文结尾这一段里有「限流 / 额度」措辞；
+//  ④ 这一段里还有「重置 / 切换」类提示；
+//  ⑤ 这一段里有完整的日期时间戳（`2026-10-11` 这种）—— 这条是判据的**分水岭**：用户真在
+//     问「429 是什么意思」时，模型答「429 表示限流，等额度重置即可」（措辞全中，但没有
+//     「什么时候恢复」的时刻）不会被误判；而真通告一定带着恢复时刻。
+//
+// 另加两条形状约束：整段是**一句话**（段内无句末标点，末尾那个可有可无）且不超过 400 字
+// —— 通告就是一句话，几百字的长回答不该被整段吞掉。
+//
+// ⚠️ 起点从后往前找（见实现）：拿到的是最短的那一段 —— 前面正文里万一也出现过状态码，
+// 取到的是紧贴结尾的真通告，而不是「从那个状态码开始的一大段」。
+//
+// ⚠️ 纯函数（不碰进程 / 磁盘 / 全局状态）：单测直接钉（见 limitnotice_test.go）。
+
+import (
+	"regexp"
+	"strings"
+	"unicode/utf8"
+)
+
+// limitNoticeMaxRunes 通告那一段的长度上限（一句话；长回答不该被整段吞掉）。
+const limitNoticeMaxRunes = 400
+
+var (
+	// 起点：句子边界（正文开头 / 换行 / 句末标点 / 冒号）+ 已知状态码 + 一个空格。
+	// ⚠️ 刻意**不认「普通空格之后」**：模型正经回答里写「HTTP 429 是限流，额度会在 … 重置」
+	// 这种科普句时，状态码前面就是一个空格 —— 认了它就会把正常回答当通告（实测过的误伤）。
+	limitNoticeStartRe = regexp.MustCompile(`(?:^|[\n。！？!?.;；：:])((?:429|402|401|403|5\d{2})[ \t])`)
+	// 限流 / 额度措辞（中英两套）。
+	limitNoticeNounRe = regexp.MustCompile(`(?i)超出频率限制|频率限制|限流|rate[\s_-]?limit|frequency limit|quota|额度|余额|欠费|usage exceeds|usage will reset`)
+	// 重置 / 切换类提示（通告一定会告诉用户「等多久」或「换个模型」）。
+	limitNoticeHintRe = regexp.MustCompile(`(?i)重置|切换|重试|稍后|再试|reset|retry|switch`)
+	// 恢复时刻的时间戳（判据的分水岭，见上）。
+	limitNoticeStampRe = regexp.MustCompile(`\d{4}-\d{2}-\d{2}`)
+	// 排障用的请求 id 尾巴（形如 `(0l1a124d…/0l1a123c3-…)`）—— 它属于通告，
+	// 判「整段一句话」时要先剥掉。
+	limitNoticeIDTailRe = regexp.MustCompile(`\s*\([^()\n]{4,200}\)\s*$`)
+	// 末尾那个句号（可有可无，剥掉后再判「段内还有没有句末标点」）。
+	limitNoticeEndRe = regexp.MustCompile(`[。.!！?？]\s*$`)
+	// 段内的句末标点（出现即说明这段不止一句话 → 不是通告）。
+	limitNoticeSeptRe = regexp.MustCompile(`[。！？!?]`)
+)
+
+// splitLimitNotice 判 text 的**末尾**是不是夹着一句供应商的限流/额度通告。
+//
+// 命中返回 (通告原文, 通告之前真正的正文, true)；不命中返回 ("", "", false)。
+// 通告原文已剥掉请求 id 尾巴与末尾标点、内部空白压成单空格 —— 它要直接进界面的错因行；
+// 正文可能为空串（这一轮引擎只回了通告）。
+func splitLimitNotice(text string) (notice, body string, ok bool) {
+	s := strings.ReplaceAll(strings.ReplaceAll(text, "\r\n", "\n"), "\r", "\n")
+	if strings.TrimSpace(s) == "" {
+		return "", "", false
+	}
+	locs := limitNoticeStartRe.FindAllStringSubmatchIndex(s, -1)
+	// 从后往前：先试最短的那一段（它才是紧贴结尾的通告）。
+	for i := len(locs) - 1; i >= 0; i-- {
+		at := locs[i][2] // 子匹配 1（状态码本身）的起点：跳过前面那个边界字符
+		seg := strings.TrimSpace(s[at:])
+		if seg == "" || utf8.RuneCountInString(seg) > limitNoticeMaxRunes {
+			continue
+		}
+		core := strings.TrimSpace(limitNoticeEndRe.ReplaceAllString(limitNoticeIDTailRe.ReplaceAllString(seg, ""), ""))
+		if limitNoticeSeptRe.MatchString(core) {
+			continue
+		}
+		if !limitNoticeNounRe.MatchString(core) ||
+			!limitNoticeHintRe.MatchString(core) ||
+			!limitNoticeStampRe.MatchString(core) {
+			continue
+		}
+		return strings.Join(strings.Fields(core), " "), strings.TrimRight(s[:at], " \t\r\n\u3000"), true
+	}
+	return "", "", false
+}