magic-agent 2.4.3 → 2.6.3

package/internal/cli/control.go

@@ -25,12 +25,17 @@ import (
  *   {"op":"answer","text":"..."}        → 把答案作为后续 user 消息追进常驻会话
  *                                         → {"type":"answered"}；通道不可用 →
  *                                           {"type":"control_error","error":"..."}
+ *   {"op":"ask_answer","request_id":"perm_…","allowed":true|false,"message":"…","tool_name":"…"}
+ *                                       → **原地**回应引擎的 control_request（计划审批 /
+ *                                         工具授权），走子进程 stdin 写一行 control_response
+ *                                         → {"type":"ask_answered",…}；无落点（引擎不支持 /
+ *                                           本轮已结束 / stdin 已关）→ control_error
  *   其它                                 → {"type":"control_error","op":"..."}
  *
- * ⚠️ answer 为什么走「后续 user 消息」而不是原地作答：headless 下 claude 在模型提问后
- * 会**立刻自行拒绝**（见 agent.KindAsk 的注释），唯一能把答案真正喂给模型的通道就是
- * 下一轮 user 消息 —— 也就是常驻会话的追加通道，与 `--append` 是同一条路。
- * 因此 answer 只在常驻会话生效时可用；不可用时明确回一条 control_error，不静默丢弃。
+ * ⚠️ answer 与 ask_answer 是**两件事**，别合并：
+ *   · answer 是「下一轮用户消息」（headless 下模型提问后 CLI 会自行拒绝，答案只能这样补）；
+ *   · ask_answer 是「这一轮正阻塞等着的裁决」（ExitPlanMode 计划审批、manual 档的工具授权），
+ *     必须写回 CLI 的 control_response —— 当 user 消息发进去它不会读，整轮继续挂着。
  */
 
 // controlCommand 一条控制命令。
@@ -38,6 +43,14 @@ type controlCommand struct {
 	Op     string `json:"op"`
 	Reason string `json:"reason,omitempty"`
 	Text   string `json:"text,omitempty"`
+	// RequestID 引擎 control_request 的 id（ask_answer 必填；原样带回 control_response）。
+	RequestID string `json:"request_id,omitempty"`
+	// Allowed 裁决结果（ask_answer 必填；nil = 没给 → 明确报错，不猜）。
+	Allowed *bool `json:"allowed,omitempty"`
+	// Message 拒绝理由 / 想回给引擎的话。
+	Message string `json:"message,omitempty"`
+	// ToolName 待裁决的工具名（只用于回执与排障，编码时不参与）。
+	ToolName string `json:"tool_name,omitempty"`
 }
 
 // controlHooks 控制命令的落地动作。
@@ -48,6 +61,9 @@ type controlHooks struct {
 	stop func()
 	// answer 把答案追进常驻会话；返回 false 表示通道此刻不可用。
 	answer func(text string) bool
+	// answerAsk 原地回应一条 control_request；返回 false 表示写不回去
+	//（引擎不支持 / stdin 已关 / 这一轮已结束），调用方据此回 control_error。
+	answerAsk func(requestID string, allowed bool, message, toolName string) bool
 }
 
 // controlSession 一次控制通道的生命周期。
@@ -129,10 +145,35 @@ func (s *controlSession) dispatch(c controlCommand) {
 		}
 		_ = s.sink.notice("answered", nil)
 
+	case "ask_answer":
+		if strings.TrimSpace(c.RequestID) == "" {
+			_ = s.sink.notice("control_error", map[string]any{
+				"op": "ask_answer", "error": "ask_answer 需要 request_id（引擎 control_request 的 id）",
+			})
+			return
+		}
+		if c.Allowed == nil {
+			_ = s.sink.notice("control_error", map[string]any{
+				"op": "ask_answer", "error": "ask_answer 需要 allowed（true = 允许，false = 拒绝）",
+			})
+			return
+		}
+		if s.hooks.answerAsk == nil || !s.hooks.answerAsk(c.RequestID, *c.Allowed, c.Message, c.ToolName) {
+			_ = s.sink.notice("control_error", map[string]any{
+				"op": "ask_answer",
+				"error": "这一轮没法原地回审批：引擎不支持控制应答，或 stdin 已关（本轮已结束）。" +
+					"请改用 answer（会把答复作为下一轮用户消息发进会话）",
+			})
+			return
+		}
+		_ = s.sink.notice("ask_answered", map[string]any{
+			"request_id": c.RequestID, "allowed": *c.Allowed, "tool_name": c.ToolName,
+		})
+
 	default:
 		_ = s.sink.notice("control_error", map[string]any{
 			"op":    c.Op,
-			"error": "未知 op：支持 ping / interrupt / stop / answer",
+			"error": "未知 op：支持 ping / interrupt / stop / answer / ask_answer",
 		})
 	}
 }

package/internal/cli/control_test.go

@@ -129,6 +129,71 @@ func TestControlAnswer(t *testing.T) {
 	})
 }
 
+// TestControlAskAnswer 原地回审批（ask_answer）：参数校验、成败回执，以及
+// 它和 answer（下一轮用户消息）是两条不同的路 —— 别把审批偷偷降级成追加。
+func TestControlAskAnswer(t *testing.T) {
+	t.Run("缺 request_id", func(t *testing.T) {
+		w := newLineWriter()
+		ctl := startControlReader(strings.NewReader(`{"op":"ask_answer","allowed":true}`+"\n"),
+			newEventSink(w, "codebuddy", true), controlHooks{})
+		defer ctl.Close()
+		if ln := w.wait(t, 1)[0]; !strings.Contains(ln, "control_error") || !strings.Contains(ln, "request_id") {
+			t.Errorf("应回带 request_id 的 control_error，实际 %s", ln)
+		}
+	})
+
+	t.Run("缺 allowed", func(t *testing.T) {
+		w := newLineWriter()
+		ctl := startControlReader(strings.NewReader(`{"op":"ask_answer","request_id":"perm_1"}`+"\n"),
+			newEventSink(w, "codebuddy", true), controlHooks{})
+		defer ctl.Close()
+		if ln := w.wait(t, 1)[0]; !strings.Contains(ln, "control_error") || !strings.Contains(ln, "allowed") {
+			t.Errorf("应回带 allowed 的 control_error，实际 %s", ln)
+		}
+	})
+
+	t.Run("写不回去", func(t *testing.T) {
+		w := newLineWriter()
+		ctl := startControlReader(strings.NewReader(`{"op":"ask_answer","request_id":"perm_1","allowed":true}`+"\n"),
+			newEventSink(w, "codebuddy", true), controlHooks{})
+		defer ctl.Close()
+		if ln := w.wait(t, 1)[0]; !strings.Contains(ln, "control_error") {
+			t.Errorf("没有 answerAsk 时应回 control_error，实际 %s", ln)
+		}
+	})
+
+	t.Run("可用", func(t *testing.T) {
+		w := newLineWriter()
+		var gotReq atomic.Value
+		var gotAllowed atomic.Bool
+		var gotMsg atomic.Value
+		ctl := startControlReader(strings.NewReader(
+			`{"op":"ask_answer","request_id":"perm_9","allowed":false,"message":"先改改","tool_name":"ExitPlanMode"}`+"\n"),
+			newEventSink(w, "codebuddy", true), controlHooks{
+				answerAsk: func(requestID string, allowed bool, message, toolName string) bool {
+					gotReq.Store(requestID + "|" + toolName)
+					gotAllowed.Store(allowed)
+					gotMsg.Store(message)
+					return true
+				},
+			})
+		defer ctl.Close()
+		ln := w.wait(t, 1)[0]
+		if !strings.Contains(ln, `"type":"ask_answered"`) || !strings.Contains(ln, `"request_id":"perm_9"`) {
+			t.Errorf("应回 ask_answered 并带回 request_id，实际 %s", ln)
+		}
+		if v, _ := gotReq.Load().(string); v != "perm_9|ExitPlanMode" {
+			t.Errorf("hook 收到的 request_id/tool_name = %q", v)
+		}
+		if gotAllowed.Load() {
+			t.Error("allowed 应为 false")
+		}
+		if v, _ := gotMsg.Load().(string); v != "先改改" {
+			t.Errorf("message = %q want 先改改", v)
+		}
+	})
+}
+
 // TestControlInterruptAndStop interrupt 不立即回应答（应答在本轮真的结束时发），
 // stop 立即回；两个标志位都要落。
 func TestControlInterruptAndStop(t *testing.T) {

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

@@ -202,6 +202,9 @@ func streamEventPayload(ev agent.StreamEvent) any {
 		   session_id）。omitempty：非团队事件不带它，老消费者字段集不变。 */
 		SubSessionID string            `json:"sub_session_id,omitempty"`
 		Ask          *agent.AskRequest `json:"ask,omitempty"`
+		/* 主备降级（2026-10-26，仅 type=fallback）：from/to 两端 + 是否换了引擎 + 原因。
+		   omitempty：其它事件不带它，老消费者字段集不变。 */
+		Fallback *agent.FallbackEvent `json:"fallback,omitempty"`
 		/* 状态收敛四元组（2026-10-02，对齐 agents-anywhere 的 timeline item）。
 		   消费方按 (item_id, item_revision) 覆盖式 upsert 即可：
 		   同一 item 的多个 partial 帧 + 最后一个 final 帧，
@@ -219,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,
@@ -228,6 +239,7 @@ func streamEventPayload(ev agent.StreamEvent) any {
 		SessionID:    ev.SessionID,
 		SubSessionID: ev.SubSessionID,
 		Ask:          ev.Ask,
+		Fallback:     ev.Fallback,
 		ItemID:       ev.ItemID,
 		ItemRevision: ev.ItemRevision,
 		Status:       string(ev.Status),
@@ -235,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,
 	}
 }
 

package/internal/cli/events_test.go

@@ -31,6 +31,15 @@ func sinkSamples() []agent.StreamEvent {
 			Reason: "without result line",
 			Status: agent.StatusFailed, ItemID: "claude_msg_1", ItemRevision: 4,
 		},
+		/* 额度卡三项（2026-10-25）：非空时才出现在 wire 上 —— 放进样本是为了让上面
+		   那条「两条路径字段集只差 v/seq」的断言也覆盖到它们（否则新字段漏了 marshal
+		   到老形状里也测不出来）。 */
+		{
+			Kind: agent.KindTurnFailed, Text: "", SessionID: "sess_quota",
+			Error: "429 You have exceeded the 5-hour usage quota.", Reason: "429 You have exceeded the 5-hour usage quota.",
+			ErrorKind: agent.ErrorKindQuota, ErrorCode: "429", ResetAt: "2026-10-25T15:07:27+08:00",
+			Status: agent.StatusFailed,
+		},
 	}
 }
 
@@ -250,6 +259,47 @@ func TestTurnFailedPayloadFields(t *testing.T) {
 	}
 }
 
+// 额度卡三项必须原样过 wire（客户端靠它决定画额度卡还是普通失败卡）：
+// 名字与 CLAUDE-CONTRACT / CLIENT-CONTRACT.md 1.1.1 那张表逐字一致，改一个字母
+// 客户端就再也认不出来 —— 所以这里按**字符串字段名**断言，而不是读结构体。
+func TestTurnFailedQuotaFields(t *testing.T) {
+	var buf bytes.Buffer
+	s := newEventSink(&buf, "codebuddy", true)
+	if err := s.stream(agent.StreamEvent{
+		Kind: agent.KindTurnFailed, SessionID: "s2",
+		Error: "429 You have exceeded the 5-hour usage quota.", Reason: "429 You have exceeded the 5-hour usage quota.",
+		ErrorKind: agent.ErrorKindQuota, ErrorCode: "429", ResetAt: "2026-10-25T15:07:27+08:00",
+		Status: agent.StatusFailed,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	m := decodeEventLine(t, buf.String())
+	if m["error_kind"] != "quota" {
+		t.Errorf("error_kind = %v，want quota", m["error_kind"])
+	}
+	if m["error_code"] != "429" {
+		t.Errorf("error_code = %v，want 429", m["error_code"])
+	}
+	if m["reset_at"] != "2026-10-25T15:07:27+08:00" {
+		t.Errorf("reset_at = %v", m["reset_at"])
+	}
+
+	/* 分不出来时三项都不出现（omitempty）—— 老消费者的字段集因此不变。 */
+	buf.Reset()
+	if err := s.stream(agent.StreamEvent{
+		Kind: agent.KindTurnFailed, SessionID: "s3",
+		Error: "工具执行失败", Reason: "工具执行失败", Status: agent.StatusFailed,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	m = decodeEventLine(t, buf.String())
+	for _, k := range []string{"error_kind", "error_code", "reset_at"} {
+		if _, ok := m[k]; ok {
+			t.Errorf("分不出来时不该出现 %s：%v", k, m)
+		}
+	}
+}
+
 // ── 黄金样本：钉住 Claude / CodeBuddy 在 wire 上的真实字节形状 ──
 //
 // 为什么不复用上面的 TestStreamEventPayloadConvergenceFields：

package/internal/cli/judge.go

@@ -0,0 +1,104 @@
+package cli
+
+// judge.go - `--judge-conflict <file|->`：判断本轮任务与同空间运行中任务是否冲突。
+//
+// 为什么要单独一条 CLI（2026-10-26）：「自动」任务模式要在**开跑前**决定这一轮是并行还是
+// 排队，判断依据是两边「在干什么」—— 这是语义问题，只能由模型答；而提示词与解析口径必须
+// 只有一份（移动端 / PC / 服务端都不能各写一套）。口径收进 core（internal/judge）之后，
+// magic-client 的作业队列 exec 这一条即可。
+//
+// 与 `--suggest-followups` 同一套旁路调用：独立进程、新会话、ToolsOff、不写历史。
+//
+// 退出码：
+//
+//	0  判定完成（conflict=true / false 都是成功；调用方按结论排队或放行）
+//	1  引擎失败（不可用 / 超时 / 输出不是 JSON）—— 调用方按「默认并行」放行
+//	2  参数错（请求 JSON 读不到 / 不合法 / 缺 prompt）
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/darren/magic-agent/internal/judge"
+)
+
+// runJudgeConflict 读请求 JSON → 调 judge.Judge → 打印 JSON 结论。
+func runJudgeConflict(cmd *cobra.Command, opts *askOptions) error {
+	body, err := readJudgeInput(cmd, opts.judgeInput)
+	if err != nil {
+		return &usageError{err}
+	}
+	/* 引擎：没显式传 -e 时用 llm（启动最快，2.5s 预算内能答完）；传了就以调用方的为准
+	   （调用方传的是用户配的「建议引擎」）。 */
+	engine := judge.DefaultEngine
+	if flagChanged(cmd, "engine") {
+		engine = opts.engine
+	}
+	model := ""
+	if flagChanged(cmd, "model") {
+		model = opts.model
+	}
+	res, err := judge.Judge(cmd.Context(), judge.Request{
+		Prompt:     body.Prompt,
+		Candidates: body.Candidates,
+		Engine:     engine,
+		Model:      model,
+		Timeout:    judge.DefaultTimeout,
+	})
+	if err != nil {
+		return fmt.Errorf("--judge-conflict: 判定失败: %w", err)
+	}
+	if res.Overlaps == nil {
+		res.Overlaps = []string{}
+	}
+	return printJSON(cmd.OutOrStdout(), res)
+}
+
+// readJudgeInput 读请求 JSON：`-` = stdin，其余按文件路径（支持 `@file`）。
+// 上限 256KB：判定只该带「本轮提示词 + 几个候选的摘要」，超了说明调用方塞了整条历史。
+func readJudgeInput(cmd *cobra.Command, spec string) (judge.RequestBody, error) {
+	var body judge.RequestBody
+	src := strings.TrimSpace(spec)
+	read := func(r io.Reader, from string) error {
+		b, err := io.ReadAll(io.LimitReader(r, 256<<10))
+		if err != nil {
+			return fmt.Errorf("读%s失败：%w", from, err)
+		}
+		if err := json.Unmarshal(b, &body); err != nil {
+			return fmt.Errorf("%s不是合法 JSON：%w", from, err)
+		}
+		return nil
+	}
+	switch src {
+	case "":
+		return body, fmt.Errorf("--judge-conflict 需要请求 JSON：传文件路径或 \"-\"（stdin）")
+	case "-":
+		if err := read(cmd.InOrStdin(), "stdin "); err != nil {
+			return body, err
+		}
+	default:
+		path := strings.TrimPrefix(src, "@")
+		if strings.HasPrefix(path, "~/") {
+			if home, herr := os.UserHomeDir(); herr == nil {
+				path = home + path[1:]
+			}
+		}
+		f, err := os.Open(path)
+		if err != nil {
+			return body, fmt.Errorf("读请求文件失败：%w", err)
+		}
+		defer f.Close()
+		if err := read(f, "请求文件 "); err != nil {
+			return body, err
+		}
+	}
+	if strings.TrimSpace(body.Prompt) == "" {
+		return body, fmt.Errorf(`缺少 prompt（本轮任务）：形如 {"prompt":"…","candidates":[…]}（candidates 为空表示没有冲突对象）`)
+	}
+	return body, nil
+}

package/internal/cli/quotas.go

@@ -0,0 +1,125 @@
+package cli
+
+// quotas.go - `--quotas`：只查「账号额度 / 模型套餐额度 / 每日签到」的轻量命令。
+//
+// 为什么单独一条：`--engines` 为了拿模型清单要真的启动各引擎的 CLI（秒级），客户端
+// 因此把它整份缓存起来；但额度是会变的（用一次就掉、换个 key 就是另一个账号）。
+// 缓存整份清单会让额度跟着一起冻住 —— 用户看到「额度不刷新」。
+//
+// 这条命令**不探测引擎、不启动任何 CLI**：只读本机票据 / models.json，再发一两条
+// 只读 HTTP 请求（codebuddy 系 2 条、llm 的 MiniMax 各 key 1 条），秒级返回。
+// 客户端把它合并进缓存清单，就能做到「模型清单用缓存、额度每次现查」。
+//
+// 输出：`[{engine, credit_left?, credit_suffix?, model_quota?, checkin_today?, checkin_credit?}]`
+// （字段与 --engines 同名同义；查不到的字段省略，调用方据此保留旧值）。
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+	"github.com/spf13/cobra"
+)
+
+// quotaRow `--quotas` 的一行；字段语义与 --engines 对应字段完全一致。
+type quotaRow struct {
+	Engine        string                        `json:"engine"`
+	CreditLeft    string                        `json:"credit_left,omitempty"`
+	CreditSuffix  string                        `json:"credit_suffix,omitempty"`
+	ModelQuota    map[string]agent.QuotaWindows `json:"model_quota,omitempty"`
+	CheckinToday  *bool                         `json:"checkin_today,omitempty"`
+	CheckinCredit string                        `json:"checkin_credit,omitempty"`
+	// LoggedIn 该账号槽位是否已登录（只读票据文件，无网络）。登录 / 登出后
+	// 下一次打开选择器就能看到行数变化，不用等引擎清单缓存过期。
+	LoggedIn *bool `json:"logged_in,omitempty"`
+	// Account 登录的账号昵称（票据里的 account.nickname；未登录 / 无昵称时省略）。
+	Account string `json:"account,omitempty"`
+}
+
+// quotaProbeTimeout 整条命令的上限：额度查询本身各自有 8s 超时，这里再兜一层，
+// 保证客户端不会因为一个挂住的账单接口把选择器拖到几十秒。
+const quotaProbeTimeout = 6 * time.Second
+
+// runQuotas 处理 `--quotas`。
+func runQuotas(cmd *cobra.Command) error {
+	ctx, cancel := context.WithTimeout(cmd.Context(), quotaProbeTimeout)
+	defer cancel()
+
+	engines := agent.Engines()
+	rows := make([]quotaRow, 0, len(engines))
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+	for _, e := range engines {
+		cl, hasCredit := e.(agent.CreditLister)
+		mq, hasQuota := e.(agent.ModelQuotaLister)
+		ck, hasCheckin := e.(agent.Checkiner)
+		if !hasCredit && !hasQuota && !hasCheckin {
+			continue
+		}
+		unit := ""
+		if u, ok := e.(agent.CreditUnitLister); ok {
+			unit = u.CreditUnit()
+		}
+		i := len(rows)
+		rows = append(rows, quotaRow{Engine: e.Name()})
+		// 登录态只读票据文件，同步拿（不发网络）；未登录的槽位客户端据此隐藏。
+		if lc, okl := e.(agent.LoginChecker); okl {
+			loggedIn := lc.LoggedIn()
+			rows[i].LoggedIn = &loggedIn
+		}
+		if al, okl := e.(agent.AccountLister); okl {
+			rows[i].Account = al.AccountName()
+		}
+
+		if hasCredit {
+			wg.Add(1)
+			go func(i int, l agent.CreditLister) {
+				defer wg.Done()
+				left := l.CreditLeft(ctx)
+				if left == "" {
+					return
+				}
+				mu.Lock()
+				rows[i].CreditLeft = left
+				if unit != "" {
+					rows[i].CreditSuffix = unit
+				}
+				mu.Unlock()
+			}(i, cl)
+		}
+		if hasQuota {
+			wg.Add(1)
+			go func(i int, l agent.ModelQuotaLister) {
+				defer wg.Done()
+				q := l.ModelQuota(ctx)
+				if len(q) == 0 {
+					return
+				}
+				mu.Lock()
+				rows[i].ModelQuota = q
+				if unit != "" {
+					rows[i].CreditSuffix = unit
+				}
+				mu.Unlock()
+			}(i, mq)
+		}
+		if hasCheckin {
+			wg.Add(1)
+			go func(i int, c agent.Checkiner) {
+				defer wg.Done()
+				info, known := c.CheckinStatus(ctx)
+				if !known {
+					return
+				}
+				checked := info.CheckedToday
+				mu.Lock()
+				rows[i].CheckinToday = &checked
+				rows[i].CheckinCredit = info.DailyCredit
+				mu.Unlock()
+			}(i, ck)
+		}
+	}
+	wg.Wait()
+	return printJSON(cmd.OutOrStdout(), rows)
+}