magic-agent 2.6.0 → 2.6.3

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)
+}

package/internal/agent/limitnotice_test.go

@@ -19,6 +19,7 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 )
 
 const (
@@ -30,6 +31,18 @@ const (
 	limitNoticeZH = "429 您的使用量已超出频率限制，将在 2026-09-19 17:49:56 UTC+8 重置，" +
 		"您也可以切换其他模型继续使用。"
 	limitNoticeNarration = "Let me read the file's end."
+	/* 实测英文额度通告（2026-10-25 用户报障截图里的那一轮原文，会话日志 01a16fea：
+	 **整段只有它**、前面没有正文、带两个尾巴）。与上面那条 429 的差别是措辞：
+	 这条说的是「5 小时额度用尽」，上面那条是「频率限制」。 */
+	limitNoticeQuotaEN = "429 You have exceeded the 5-hour usage quota. It will reset at " +
+		"2026-10-25 15:07:27 +0800 CST. We recommend upgrading your plan for more quota, " +
+		"or waiting for the reset. Request id: 021792911321900fd0de7354b348b065f00b895e07126b865f18b" +
+		" (01a171d5e11f7519bcf4077dffd2ebad/01a16fea-4a01-789d-b694-3d99c11b3c8b)"
+	/* 实测 402 原文（同一批日志里连出七条）：**没有恢复时刻**，却整段就是通告。
+	   它落在画面上就是「一大段供应商原文 + 已完成」—— 上面那条「有恢复时刻」的判据
+	   因此认不出它（2026-10-25 补的窄路就是为它）。 */
+	limitNoticeQuota402 = "402 当前已达到 Token Plan 用量上限。为避免调用中断，请升级 Token Plan 套餐，" +
+		"或购买积分补充用量并开启积分自动消耗。 (2067) (01a16c13a2e67c05b09eb8b1311f97d8/01a16c05-cabd-7fd0-9fdc-abca97cb92ae)"
 )
 
 func TestSplitLimitNoticeRealSamples(t *testing.T) {
@@ -81,6 +94,43 @@ func TestSplitLimitNoticeRealSamples(t *testing.T) {
 	}
 }
 
+// 2026-10-25 加的两条实测原文：英文 5 小时额度、中文 402（都没在前面挂正文）。
+func TestSplitLimitNoticeQuotaSamples(t *testing.T) {
+	notice, body, ok := splitLimitNotice(limitNoticeQuotaEN)
+	if !ok {
+		t.Fatalf("英文额度通告（截图里的那一轮）没认出来 —— 它会原样铺在气泡里")
+	}
+	if !strings.HasPrefix(notice, "429 You have exceeded") {
+		t.Errorf("notice = %q", notice)
+	}
+	if strings.Contains(notice, "01a171d5") || strings.Contains(notice, "Request id:") {
+		t.Errorf("notice = %q，尾巴应被剥掉（它会直接进卡片的原文行）", notice)
+	}
+	if body != "" {
+		t.Errorf("body = %q，want 空串（这一轮只回了通告）", body)
+	}
+
+	// 402 没有恢复时刻 → 走「整段就是通告」那条窄路。
+	notice, body, ok = splitLimitNotice(limitNoticeQuota402)
+	if !ok {
+		t.Fatalf("中文 402 原文没认出来（没有恢复时刻，靠窄路认）")
+	}
+	if !strings.HasPrefix(notice, "402 当前已达到") {
+		t.Errorf("notice = %q", notice)
+	}
+	if strings.Contains(notice, "2067") && !strings.Contains(notice, "积分") {
+		t.Errorf("notice = %q，尾巴 (2067) 应被剥掉", notice)
+	}
+	if body != "" {
+		t.Errorf("body = %q，want 空串", body)
+	}
+
+	// 402 前面挂着正文 → 不是「整段就是它」，不该整段吞掉（那条窄路只认 body 为空）。
+	if _, b, ok := splitLimitNotice("先跑了一遍测试。\n" + limitNoticeQuota402); ok && b != "先跑了一遍测试。" {
+		t.Errorf("正文被吞了：body = %q", b)
+	}
+}
+
 func TestSplitLimitNoticeNoFalsePositive(t *testing.T) {
 	cases := map[string]string{
 		"科普句（无限流措辞）":         "HTTP 429 是「请求过多」，服务端让你慢一点。",
@@ -89,6 +139,13 @@ func TestSplitLimitNoticeNoFalsePositive(t *testing.T) {
 		"正文里出现过 429、后面还有别的话": "日志里出现了 429。先看限流配置，额度在 2026-10-11 重置。建议改用另一个模型。",
 		"端口号不是状态码":           "端口 8080 与 usage 有关。",
 		"普通回答":               "已按你的要求改完 3 个文件。",
+		/* 窄路（整段就是通告、无时刻）要挡住的几类（2026-10-25）：
+		   「429 是限流，把额度用完就等它重置」= 模型在**回答**，措辞全中但没有一个字说
+		   「你此刻被拒了」。 */
+		"释义句（状态码在句首 + 表示）": "429 表示请求过多，额度用完时会自动重置，稍后再试即可。",
+		"释义句（中文「是」）":       "402 是「需要付费」的意思，余额不足时你先升级套餐。",
+		/* 长一点的正常回答里提了额度：整段不短于 160 字 → 不是那条窄路。 */
+		"长回答里提额度": strings.Repeat("这一版把额度用完时的提示改成了卡片。", 12),
 	}
 	for name, in := range cases {
 		if _, _, ok := splitLimitNotice(in); ok {
@@ -97,6 +154,89 @@ func TestSplitLimitNoticeNoFalsePositive(t *testing.T) {
 	}
 }
 
+// ── 分类与恢复时刻（2026-10-25，界面额度卡要的三项）────────────────────────
+
+func TestClassifyNotice(t *testing.T) {
+	cases := []struct{ in, kind, code string }{
+		{limitNoticeQuotaEN, ErrorKindQuota, "429"},
+		{limitNoticeQuota402, ErrorKindQuota, "402"},
+		{limitNoticeZH, ErrorKindRateLimit, "429"}, // 「超出频率限制」→ 短时窗口
+		{limitNoticeEN, ErrorKindRateLimit, "429"},
+		{"", "", ""},
+		{"codebuddy CLI stream ended without result line", "", ""},
+		/* 402 即使没有一句措辞也要算额度：它是「需要付费」的语义码（原文可能只有
+		   「Payment Required」），归到普通错误卡会让人去查配置。 */
+		{"402 Payment Required", ErrorKindQuota, "402"},
+	}
+	for _, c := range cases {
+		kind, code := classifyNotice(c.in)
+		if kind != c.kind || code != c.code {
+			t.Errorf("classifyNotice(%q) = (%q,%q)，want (%q,%q)", c.in, kind, code, c.kind, c.code)
+		}
+	}
+}
+
+func TestParseNoticeReset(t *testing.T) {
+	/* 三种拼法都是本仓库日志里的实测原文。**期望值是绝对时刻**，不看本机时区 ——
+	   带偏移的必须解成同一个瞬间（这就是不用宽松解析的理由：V8 会把 CST 当美国中部时间）。 */
+	cases := []struct{ in, want string }{
+		{limitNoticeQuotaEN, "2026-10-25T15:07:27+08:00"},                   // +0800 无冒号，尾部还有 CST
+		{limitNoticeZH, "2026-09-19T17:49:56+08:00"},                        // UTC+8 那种拼法
+		{limitNoticeEN, "2026-10-11T10:32:59+08:00"},                        // UTC+8
+		{"will reset at 2026-10-25T07:07:27Z", "2026-10-25T15:07:27+08:00"}, // ISO 形状（Z = UTC）
+		{limitNoticeQuota402, ""},                                           // 没有时刻 → 空（客户端不编「稍后」）
+		{"已按你的要求改完 3 个文件。", ""},
+	}
+	for _, c := range cases {
+		got := noticeResetRFC3339(c.in)
+		if c.want == "" {
+			if got != "" {
+				t.Errorf("noticeResetRFC3339(%q) = %q，want 空", c.in, got)
+			}
+			continue
+		}
+		wt, err := time.Parse(time.RFC3339, c.want)
+		if err != nil {
+			t.Fatalf("测试自身的期望值写错了：%v", err)
+		}
+		gt, err := time.Parse(time.RFC3339, got)
+		if err != nil {
+			t.Errorf("noticeResetRFC3339(%q) = %q（不是 RFC3339）", c.in, got)
+			continue
+		}
+		if !gt.Equal(wt) {
+			t.Errorf("noticeResetRFC3339(%q) = %s，want 同一瞬间 %s", c.in, got, c.want)
+		}
+	}
+}
+
+// 收尾事件要带上三项结构化字段（界面靠它们决定画额度卡还是普通失败卡）。
+func TestLimitNoticeEventCarriesFields(t *testing.T) {
+	var got *StreamEvent
+	a := &streamAccumulator{}
+	a.OnEvent = func(ev StreamEvent) { e := ev; got = &e }
+	a.emitLimitNoticeFailed("sid", strings.Join(strings.Fields(stripNoticeTails(limitNoticeQuotaEN)), " "), limitNoticeNarration)
+	if got == nil {
+		t.Fatal("没发事件")
+	}
+	if got.ErrorKind != ErrorKindQuota || got.ErrorCode != "429" {
+		t.Errorf("kind/code = %q/%q，want quota/429", got.ErrorKind, got.ErrorCode)
+	}
+	if got.ResetAt != "2026-10-25T15:07:27+08:00" {
+		t.Errorf("ResetAt = %q，want 2026-10-25T15:07:27+08:00", got.ResetAt)
+	}
+	if got.Text != limitNoticeNarration {
+		t.Errorf("Text = %q，want 剥掉通告的正文", got.Text)
+	}
+
+	// 402 那条：有 kind/code、**没有** reset（客户端据此不写「将于…恢复」）。
+	got = nil
+	a.emitLimitNoticeFailed("sid", strings.Join(strings.Fields(stripNoticeTails(limitNoticeQuota402)), " "), "")
+	if got == nil || got.ErrorKind != ErrorKindQuota || got.ErrorCode != "402" || got.ResetAt != "" {
+		t.Errorf("402 那条的 kind/code/reset = %+v", got)
+	}
+}
+
 // codebuddyStreamWithResult 造一个假 codebuddy CLI：只吐一条给定正文的 result 行。
 // 正文里带单引号（英文通告的 don't）时没法直接写进 shell 脚本，所以落成文件再 cat。
 func codebuddyStreamWithResult(t *testing.T, text string) string {

package/internal/agent/stream.go

@@ -258,6 +258,25 @@ type StreamEvent struct {
 	//（同走 agent.ReasonOf），同一次失败在事件流与 stderr 两处的说法必然一致。
 	Reason string
 
+	/* ── 失败分类（2026-10-25）──
+	 *
+	 * 为什么要有这三个字段：客户端要画一张**额度卡**（什么时候恢复、该怎么办），
+	 * 而 Error / Reason 只有一段人话原文。让每个客户端各自从原文里正则反推，
+	 * 就是三端三套判据、各错各的；分类口径收在 core（见 limitnotice.go），
+	 * 客户端只做展示。
+	 *
+	 * 空串 = 与以前完全一致（非 turn_failed 的事件、以及认不出类别的失败）。
+	 * 按 CLIENT-CONTRACT 的「只增字段不升 contractVersion」规则添加，
+	 * 老消费方忽略它们即可。 */
+
+	// ErrorKind 失败类别：quota（额度用尽）/ rate_limit（频率限制）/ ""（未分类）。
+	ErrorKind string
+	// ErrorCode 通告里的状态码（429 / 402 / 401 / 403 / 5xx），空 = 原文里没有。
+	ErrorCode string
+	// ResetAt 供应商给的恢复时刻（RFC3339）。空 = 通告里没说什么时候恢复 ——
+	// 客户端此时**不要**编「稍后」，把这一行整条省掉。
+	ResetAt string
+
 	/* Parent 父委派 id（2026-10-21，团队模式）。
 	 *
 	 * 语义与 claude 系原生的 `parent_tool_use_id` 完全一致：非空表示「这条事件发生在
@@ -1729,6 +1748,10 @@ func (a *streamAccumulator) emitTurnFailed(sessionID string, err error) {
 		Reason:    ReasonOf(err),
 		Status:    StatusFailed,
 	}
+	/* 「协议没跑完」的错误串里也可能夹着供应商的 429 原文（runner 的重试判据就是
+	   靠这种子串认出来的），所以这里同样分一次类 —— 认出来客户端才画得出额度卡。 */
+	ev.ErrorKind, ev.ErrorCode = classifyNotice(ev.Reason + "\n" + ev.Error)
+	ev.ResetAt = noticeResetRFC3339(ev.Reason + "\n" + ev.Error)
 	// 已建立 item 时把失败也挂到同一个 item 上：partial 的内容仍然存在，
 	// 只是这条 item 不会再更新了（Status=failed 明确终止增长）。
 	if attrs, ok := a.trackers().failText(a.joinBlocks(a.textBlocks)); ok {
@@ -1762,6 +1785,13 @@ func (a *streamAccumulator) emitLimitNoticeFailed(sessionID, notice, body string
 		Reason:    notice,
 		Status:    StatusFailed,
 	}
+	/* 分类与恢复时刻就在这里定（客户端只展示，不自己解析原文）——
+	   这条路径**已经认定**是限流/额度通告，所以 kind 至少是 rate_limit。 */
+	ev.ErrorKind, ev.ErrorCode = classifyNotice(notice)
+	if ev.ErrorKind == "" {
+		ev.ErrorKind = ErrorKindRateLimit
+	}
+	ev.ResetAt = noticeResetRFC3339(notice)
 	/* 快照 = 剥掉通告的正文；正文为空（这一轮引擎只回了通告）时退回**累积正文** ——
 	   引擎把通告混在最后一条 assistant 消息里时，那里面也夹着它，再判一次剥掉。
 	   （累积正文里判不出来就原样留着：宁可多留一句话，也不把用户真看过的正文抹成空。） */

package/internal/agent/streamjson.go

@@ -65,7 +65,17 @@ func runStreamJSONIn(
 			   ⚠️ 抛错会让 lineHandler 中止读循环，那里会顺手 kill 掉引擎进程组
 			   （见 runStreamCLIStdinReaderIn），所以这里不能改成「先把事件转发出去、
 			   等收尾再抛」—— 那样 turn_failed 会晚到，消费方早就按 turn_end 收尾了。 */
-			if notice, body, hit := splitLimitNotice(fin.Result); hit {
+			/* ⚠️ **判的是「屏幕上真正显示的那段」，不是 result 字段**（2026-10-25）：
+			   AggregateOnly 引擎（codebuddy 实测）不发 content_block_delta，正文只随
+			   assistant 聚合行以 text 增量下来，而收尾 result 行的 result **是空串** ——
+			   只判 fin.Result 的话，额度通告永远认不出来，界面上就是「一整段 429 英文 +
+			   已完成」（用户 2026-10-25 截图报障：「没额度了」）。
+			   口径与 emitTurnEnd 的落笔一致：result 非空以它为准，空则退回累积正文。 */
+			shown := fin.Result
+			if strings.TrimSpace(shown) == "" {
+				shown = acc.joinBlocks(acc.textBlocks)
+			}
+			if notice, body, hit := splitLimitNotice(shown); hit {
 				acc.emitLimitNoticeFailed(fin.SessionID, notice, body)
 				return errors.New(notice)
 			}

package/internal/cli/ask.go

@@ -147,6 +147,10 @@ type askOptions struct {
 	suggestFallbackEngine string // --suggest-fallback-engine
 	suggestFallbackModel  string // --suggest-fallback-model
 
+	// 自动任务模式的冲突判定（2026-10-26）：一次性旁路调用，不续接会话。
+	// 值 = 请求 JSON 的文件路径（"-" = stdin）。
+	judgeInput string // --judge-conflict <file|->：{"prompt":"…","candidates":[…]}
+
 	// 四档权限模型（见 internal/agent/permission.go）。仅 claude / codebuddy 接线。
 	permission     string   // 档位：manual | accept-edits | auto | full
 	sandboxExclude []string // 始终在沙箱外执行的命令（sandbox.excludedCommands）
@@ -244,6 +248,7 @@ func bindAskFlags(cmd *cobra.Command, opts *askOptions) {
 	f.StringVar(&opts.suggestInput, "suggest-followups", "", "生成下一轮快捷回复：传请求 JSON 的文件路径（\"-\" = stdin）：{\"user\":\"…\",\"reply\":\"…\"}。旁路调用，不续接当前会话；引擎走 -e（默认 llm）")
 	f.StringVar(&opts.suggestFallbackEngine, "suggest-fallback-engine", "", "配合 --suggest-followups：建议引擎的备用（主建议引擎失败时先试它，再落到内置 llm 兜底）")
 	f.StringVar(&opts.suggestFallbackModel, "suggest-fallback-model", "", "配合 --suggest-followups：建议备用引擎的模型（空 = 该引擎默认）")
+	f.StringVar(&opts.judgeInput, "judge-conflict", "", "判断本轮任务与同工作空间运行中任务是否冲突（自动任务模式用）：传请求 JSON 的文件路径（\"-\" = stdin）：{\"prompt\":\"…\",\"candidates\":[{title,recent,files}]}。旁路调用，不续接会话；引擎走 -e（默认 llm）")
 	f.Uint64Var(&opts.logAfter, "after", 0, "配合 --session-log：增量续读，只回 seq > N 的事件（另附 count/after/lastSeq/snapshotRequired）")
 	f.Uint64Var(&opts.logBefore, "before", 0, "配合 --session-log：向上翻更早的历史，从文件尾跳过 N 条已画事件再取一页（0 = 最新一页；下一页把返回的 nextBefore 传回来。另附 count/before/nextBefore/firstSeq/more；与 --after 互斥）")
 	f.IntVar(&opts.logLimit, "limit", 200, "配合 --before：每页最多返回多少条事件（默认 200）")
@@ -798,6 +803,9 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 			Status: string(ev.Status), Parent: ev.Parent,
 			SubSessionID: ev.SubSessionID,
 			Error:        ev.Error, Reason: ev.Reason,
+			/* 失败分类（2026-10-25）：落盘它，历史回放才画得出**同一张**额度卡 ——
+			   只在实时流里带，用户翻历史时那一轮会退回普通失败卡（两张脸）。 */
+			ErrorKind: ev.ErrorKind, ErrorCode: ev.ErrorCode, ResetAt: ev.ResetAt,
 		})
 	}
 	if format == agent.FormatJSON {

package/internal/cli/engines_test.go

@@ -30,6 +30,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"strings"
 	"testing"
 
@@ -203,3 +204,105 @@ func TestEnginesInstallKeyOmittedWhenNoCommand(t *testing.T) {
 	}
 	t.Fatal("--engines 输出里没找到 install-fake-ok-2")
 }
+
+// TestEnginesModelsSourceDistinguishesNoSourceFromFailure 钉住 2026-10 报障的根因：
+// 「引擎没有模型源」（arkclaw 按 claw_id 绑模型 / codebuddy-gateway 用网关进程的模型）
+// 与「模型探测失败」（openclaw 因 Node 版本门禁 exit 1）是两种语义，客户端不能都隐藏。
+//
+// 约定：
+//
+//	models_source = none   → 引擎本身不提供模型选择，**保留**在可选清单里；
+//	              = failed → 有来源但探测失败，可以隐藏 / 置灰；
+//	              = dynamic→ models 可用。
+func TestEnginesModelsSourceDistinguishesNoSourceFromFailure(t *testing.T) {
+	clearModelListCache()
+	t.Cleanup(clearModelListCache)
+
+	registerFake(&modelListEngine{
+		stringEngine: stringEngine{name: "__no_source__", text: "x"},
+		err:          fmt.Errorf("%w: bound by claw_id", agent.ErrNoModelSource),
+	})
+	registerFake(&modelListEngine{
+		stringEngine: stringEngine{name: "__probe_failed__", text: "x"},
+		err:          errors.New("exit status 1"),
+	})
+	registerFake(&modelListEngine{
+		stringEngine: stringEngine{name: "__dynamic__", text: "x"},
+		models:       []string{"m1", "m2"},
+	})
+
+	stdout, _, err := runAskCmd(t, "", "--engines")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+	var rows []struct {
+		Engine       string   `json:"engine"`
+		Models       []string `json:"models"`
+		ModelsNote   string   `json:"models_note"`
+		ModelsSource string   `json:"models_source"`
+	}
+	if err := json.Unmarshal([]byte(strings.TrimSpace(stdout)), &rows); err != nil {
+		t.Fatalf("--engines 输出不是 JSON 数组: %v\n%s", err, stdout)
+	}
+	byName := map[string]int{}
+	for i, r := range rows {
+		byName[r.Engine] = i
+	}
+	get := func(name string) (int, struct {
+		Engine       string   `json:"engine"`
+		Models       []string `json:"models"`
+		ModelsNote   string   `json:"models_note"`
+		ModelsSource string   `json:"models_source"`
+	}) {
+		t.Helper()
+		i, ok := byName[name]
+		if !ok {
+			t.Fatalf("--engines 输出里没找到 %s", name)
+		}
+		return i, rows[i]
+	}
+	_, noSource := get("__no_source__")
+	if noSource.ModelsSource != "none" {
+		t.Errorf("无模型源引擎 models_source = %q want none", noSource.ModelsSource)
+	}
+	if len(noSource.Models) != 0 {
+		t.Errorf("无模型源引擎不该有 models: %v", noSource.Models)
+	}
+	if !strings.Contains(noSource.ModelsNote, "no dynamic model source") {
+		t.Errorf("无模型源引擎仍应保留人读原因，got %q", noSource.ModelsNote)
+	}
+	_, failed := get("__probe_failed__")
+	if failed.ModelsSource != "failed" {
+		t.Errorf("探测失败引擎 models_source = %q want failed", failed.ModelsSource)
+	}
+	_, dynamic := get("__dynamic__")
+	if dynamic.ModelsSource != "dynamic" {
+		t.Errorf("正常引擎 models_source = %q want dynamic", dynamic.ModelsSource)
+	}
+	if len(dynamic.Models) != 2 {
+		t.Errorf("正常引擎 models = %v want 2 条", dynamic.Models)
+	}
+}
+
+// TestEnginesModelsSourceOmittedWithoutLister 钉住「没有 ModelLister 的引擎」也标 none：
+// 它们连探测入口都没有，属于「本身不提供」，不能报成 failed。
+func TestEnginesModelsSourceOmittedWithoutLister(t *testing.T) {
+	registerFake(&stringEngine{name: "no-lister-fake", text: "x"})
+	stdout, _, err := runAskCmd(t, "", "--engines")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+	var rows []map[string]any
+	if err := json.Unmarshal([]byte(strings.TrimSpace(stdout)), &rows); err != nil {
+		t.Fatalf("解析失败: %v\n%s", err, stdout)
+	}
+	for _, r := range rows {
+		if r["engine"] == "no-lister-fake" {
+			if got := r["models_source"]; got != "none" {
+				t.Errorf("无 ModelLister 引擎 models_source = %v want none", got)
+			}
+			return
+		}
+	}
+	t.Fatal("--engines 输出里没找到 no-lister-fake")
+}

package/internal/cli/events.go

@@ -222,6 +222,14 @@ func streamEventPayload(ev agent.StreamEvent) any {
 		   与 -o json 的失败 envelope 同源（都走 agent.ReasonOf）。 */
 		Error  string `json:"error,omitempty"`
 		Reason string `json:"reason,omitempty"`
+		/* 失败分类（2026-10-25，仅 turn_failed）：客户端据此决定画哪种卡 ——
+		   error_kind=quota 画「额度用尽」卡（等恢复 / 换模型），rate_limit 画
+		   「请求太频繁」卡，其它或空就退回普通「调用失败」卡。
+		   error_code 是通告里的状态码（429 / 402 …），reset_at 是供应商给的恢复
+		   时刻（RFC3339）。全都 omitempty：分不出来时字段不出现，老消费者字段集不变。 */
+		ErrorKind string `json:"error_kind,omitempty"`
+		ErrorCode string `json:"error_code,omitempty"`
+		ResetAt   string `json:"reset_at,omitempty"`
 	}{
 		Type:         string(ev.Kind),
 		Text:         ev.Text,
@@ -239,6 +247,9 @@ func streamEventPayload(ev agent.StreamEvent) any {
 		Parent:       ev.Parent,
 		Error:        ev.Error,
 		Reason:       ev.Reason,
+		ErrorKind:    ev.ErrorKind,
+		ErrorCode:    ev.ErrorCode,
+		ResetAt:      ev.ResetAt,
 	}
 }