magic-agent 2.4.3 → 2.6.0

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/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 帧，
@@ -228,6 +231,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),

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

package/internal/cli/requirements.go

@@ -22,6 +22,7 @@ package cli
 
 import (
 	"fmt"
+	"io"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -69,6 +70,23 @@ func runRequirements(cmd *cobra.Command, opts *askOptions) error {
 	return printJSON(cmd.OutOrStdout(), out)
 }
 
+// runRequirementsGraph 会话↔需求关系图谱：`--requirements-graph all|<ws_id|目录>`。
+//
+// 只读（与 --requirements 同族，客户端每刷一次都调，绝不能触发 LLM）。
+// 聚合 relations.jsonl + 文档目录 → {ok,root,workspaces:[{id,name,dir,nodes,edges}]}。
+func runRequirementsGraph(cmd *cobra.Command, opts *askOptions) error {
+	where := strings.TrimSpace(opts.reqGraph)
+	if where == "*" {
+		where = "all"
+	}
+	b, err := requirements.BuildGraph(where)
+	if err != nil {
+		return fmt.Errorf("--requirements-graph %s: %w", where, err)
+	}
+	_, err = cmd.OutOrStdout().Write(append(b, '\n'))
+	return err
+}
+
 // runConsolidateRequirements 立即归纳一轮：`--consolidate-requirements <ws_id|目录|.>`。
 //
 // `.` = 当前目录（与 `-w` 的默认语义一致：用户站在哪个项目里，整理的就是哪个项目）。
@@ -103,6 +121,35 @@ func runConsolidateRequirements(cmd *cobra.Command, opts *askOptions) error {
 	return printJSON(cmd.OutOrStdout(), res)
 }
 
+// runRequirementShot 给一个功能点追加一张「页面完成情况」截图：
+// `--requirement-shot [<ws|dir>]` + `--requirement-name` / `--requirement-caption`。
+//
+// PNG 内容走 **stdin**（不走命令行参数）：图片动辄几百 KB，放进 argv 会撞 Windows
+// 命令行长度上限，也会把二进制搅进进程列表。stdin 的好处是调用方可以管线接。
+func runRequirementShot(cmd *cobra.Command, opts *askOptions) error {
+	where := strings.TrimSpace(opts.reqShot)
+	if where == "." {
+		where = ""
+	}
+	name := strings.TrimSpace(opts.reqShotName)
+	if name == "" {
+		return &usageError{fmt.Errorf("--requirement-shot 需要 --requirement-name <功能点名>")}
+	}
+	png, err := io.ReadAll(io.LimitReader(cmd.InOrStdin(), requirements.MaxShotBytes+1))
+	if err != nil {
+		return fmt.Errorf("--requirement-shot: 读取 stdin 失败: %w", err)
+	}
+	res, err := requirements.AttachShot(where, opts.reqModule, name, opts.reqShotCap, png)
+	if err != nil && !requirements.IsBusy(err) {
+		if res.Error == "" {
+			res.Error = err.Error()
+		}
+		_ = printJSON(cmd.OutOrStdout(), res)
+		return fmt.Errorf("--requirement-shot %s: %s", where, err)
+	}
+	return printJSON(cmd.OutOrStdout(), res)
+}
+
 // bindRequirementFlags 注册需求聚合的 flags。
 //
 // --requirements / --consolidate-requirements 的值都可以留空（空串是合法输入：
@@ -110,6 +157,7 @@ func runConsolidateRequirements(cmd *cobra.Command, opts *askOptions) error {
 func bindRequirementFlags(cmd *cobra.Command, opts *askOptions) {
 	f := cmd.PersistentFlags()
 	f.StringVar(&opts.requirements, "requirements", "", "列出需求清单（工作区 → 模块 → 功能点，JSON：{ok,root,workspaces}）。值留空 = 列全部；给 ws id 或目录 = 只列那一个。只读，不调模型")
+	f.StringVar(&opts.reqGraph, "requirements-graph", "", "会话↔需求关系图谱（JSON：{ok,root,workspaces:[{nodes,edges}]}，nodes 带 type=session|feature）。值留空 = 全部；只读，不调模型")
 	f.StringVar(&opts.consolidateReqs, "consolidate-requirements", "", "立即把会话记忆归纳成需求文档（会调模型）。值留空 = 当前目录；给 ws id 或目录 = 归纳那一个")
 	f.BoolVar(&opts.reqForce, "requirement-force", false, "配合 --consolidate-requirements：没有未归纳的记忆也跑一轮（手动「立即整理」）")
 	f.BoolVar(&opts.reqAll, "requirement-all", false, "配合 --consolidate-requirements：全量重放历史记忆（回填 / 滚动校正）。仍走增量合并，只增不减，不会推翻已有内容")
@@ -118,4 +166,7 @@ func bindRequirementFlags(cmd *cobra.Command, opts *askOptions) {
 	f.StringVar(&opts.reqModule, "requirement-module", "", "配合 --consolidate-requirements：只整理这个模块（空 = 整个空间）。不推进空间游标，不触发首次目录初始化")
 	f.DurationVar(&opts.reqTimeout, "requirement-timeout", requirements.DefaultTimeout, "配合 --consolidate-requirements：单次模型调用超时（默认归纳 4m / 首次目录初始化 9m）")
 	f.BoolVar(&opts.reqAuto, "requirement-auto", false, "配合 --consolidate-requirements：自动归纳（不触发首次按目录初始化；插件轮末 / 每日兜底用）")
+	f.StringVar(&opts.reqShot, "requirement-shot", "", "给功能点追加一张「页面完成情况」截图（PNG 走 stdin）。值留空 = 当前目录；给 ws id 或目录 = 那个空间")
+	f.StringVar(&opts.reqShotName, "requirement-name", "", "配合 --requirement-shot：功能点名（= 文档名）")
+	f.StringVar(&opts.reqShotCap, "requirement-caption", "", "配合 --requirement-shot：截图的标注说明")
 }

package/internal/cli/root.go

@@ -33,6 +33,7 @@ package cli
 //	    --temperature <t>    采样温度（仅 llm 引擎透传 -o temperature，其余忽略）
 //	--engines            列出引擎、可用性与支持的模型（JSON 数组；--json 兼容保留）
 //	--no-models          配合 --engines：跳过模型探测（只列引擎，快）
+//	--quotas             只查各引擎账号的额度与每日签到（不探测引擎/不启动 CLI，秒级）
 //	--stop <id>          停止指定会话/运行（session_id 或 run_id），杀掉它的引擎进程组
 //	--delete-session <id> 删除一条会话：登记记录 + 事件历史 + 标题覆盖一起删，**全机生效**
 //	                     （各端读同一份登记表，一端删了处处都看不到）。幂等
@@ -185,7 +186,7 @@ llm 引擎（包装 simonw/LLM CLI，模型/密钥由它自管）：
   每个可用引擎的模型清单都从它自己的权威入口现取现算，CLI 升级/新注册模型后自动跟随：
     claude    ~/.claude/settings.json（顶层 model + env 里 ANTHROPIC_*MODEL[*_NAME]）
     codebuddy codebuddy --help 里 --model 自带的 "Currently supported: (...)" 清单
-    trae      trae-cli models --json
+    trae      traex models --json
     llm       llm models
     codex     codex debug models
     openclaw  openclaw models list --json
@@ -202,7 +203,7 @@ llm 引擎（包装 simonw/LLM CLI，模型/密钥由它自管）：
   codex     npm install -g @openai/codex
   openclaw  npm install -g openclaw@latest
   dsh       npm i -g @deepseek-ai/dsh
-  trae      sh -c "$(curl -L https://trae.cn/trae-cli/install.sh)"
+  trae      sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"   # Windows: irm https://trae.cn/trae-cli/install_v2.ps1 | iex
   llm       python3 -m venv ~/.llm-venv && ~/.llm-venv/bin/pip install llm
   命令一律取自各 CLI 的官方安装方式；**没有可执行安装路径的引擎不给该字段**
   （codebuddy / codebuddy-ai 是桌面端 GUI 应用，arkclaw 靠配置文件），
@@ -468,6 +469,9 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 			case flagChanged(cmd, "repair-models"):
 				// 同上：`--repair-models ""` 要走参数校验，而不是掉进「提问」分支报 empty prompt。
 				return runRepairModels(cmd, opts)
+			case flagChanged(cmd, "checkin"):
+				// 同上：`--checkin ""` 要走参数校验。
+				return runCheckin(cmd, opts)
 			case opts.listSessions:
 				return runSessions(cmd, opts)
 			case flagChanged(cmd, "session-log"):
@@ -500,9 +504,15 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 			case flagChanged(cmd, "requirements"):
 				// 读清单：值留空 = 列全部工作区（`--requirements ""` 也是合法调用）。
 				return runRequirements(cmd, opts)
+			case flagChanged(cmd, "requirements-graph"):
+				// 读图谱：值留空 = 全部工作区。只读，不调模型。
+				return runRequirementsGraph(cmd, opts)
 			case flagChanged(cmd, "consolidate-requirements"):
 				// 写：跑一轮归纳。值留空 = 当前目录。
 				return runConsolidateRequirements(cmd, opts)
+			case flagChanged(cmd, "requirement-shot"):
+				// 写：给功能点追加一张完成情况截图（PNG 走 stdin）。
+				return runRequirementShot(cmd, opts)
 			case flagChanged(cmd, "requirement-force"), flagChanged(cmd, "requirement-all"),
 				flagChanged(cmd, "requirement-engine"), flagChanged(cmd, "requirement-model"),
 				flagChanged(cmd, "requirement-timeout"), flagChanged(cmd, "requirement-auto"):
@@ -510,6 +520,10 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 				// 静默忽略就等于「传了参数什么都没发生」。
 				return &usageError{fmt.Errorf("--requirement-force / -all / -engine / -model / -timeout / -auto " +
 					"只在 --consolidate-requirements 下成立：请配合它使用")}
+			case flagChanged(cmd, "requirement-name"), flagChanged(cmd, "requirement-caption"):
+				// 这两个是 --requirement-shot 的修饰项（截图落在哪个功能点、标注写什么）。
+				return &usageError{fmt.Errorf("--requirement-name / --requirement-caption " +
+					"只在 --requirement-shot 下成立：请配合它使用")}
 			case flagChanged(cmd, "stop"):
 				// 用「传过没有」而不是「值非空」判断：`--stop ""` 也要走参数校验
 				//（exit 2 提示要 id），而不是掉进「提问」分支报 empty prompt。
@@ -523,6 +537,8 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 				return runContract(cmd, opts)
 			case opts.engines:
 				return runEngines(cmd, opts)
+			case opts.quotas:
+				return runQuotas(cmd)
 			case opts.team:
 				// 团队模式必须排在 --stream 之前：它自己就是流式路径的一种运行模式
 				//（同一套 ready / seq / result 收尾），但内部编排完全不同。
@@ -767,7 +783,7 @@ func flagChanged(cmd *cobra.Command, name string) bool {
 //	                  实测只有「受理帧 + 整段正文」，见 internal/agent/arkclaw_stream.go
 //
 // 模型**一律现取现算、不硬编码**：各引擎用自己 CLI/配置文件里的权威入口
-// （trae-cli models / llm models / codex debug models / openclaw models list /
+// （traex models / llm models / codex debug models / openclaw models list /
 // codebuddy --help / claude settings.json）。探测要真的启动 CLI（只读子命令），
 // 故并发执行并套 agent.DefaultModelProbeTimeout；--no-models 可整段跳过（只列引擎，快）。
 // --json 为兼容旧调用保留（本函数不再区分，恒为 JSON）。
@@ -823,6 +839,40 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 		// 仅实现了 agent.ModelCreditLister 的引擎给出 —— 目前 codebuddy / codebuddy-ai）。
 		// 客户端不给倍率的模型（custom-local）不出现在 map 里。
 		ModelCredits map[string]string `json:"model_credits,omitempty"`
+		// ModelVendors 各模型的供应商展示名（model → 供应商，如 "Volcengine"）；
+		// 与 models 同形同链，键已剥 `custom-local:` 前缀。只用于**选择器的第二行**，
+		// 不参与 -m / 落库。仅实现 agent.ModelVendorLister 的引擎给出（目前 codebuddy 系），
+		// 其余引擎省略该字段（新增字段，不升 contractVersion）。
+		ModelVendors map[string]string `json:"model_vendors,omitempty"`
+		// CreditLeft 账号当前**剩余积分**（decimal 字符串，如 "5939.2"；单位 credits）。
+		// 仅实现了 agent.CreditLister 的引擎给出（codebuddy / codebuddy-ai），
+		// 各自读自己票据（codebuddy-ai 读隔离目录），查不到就省略该字段。
+		// 新增（2026-10-24，只增字段不升 contractVersion）。
+		CreditLeft string `json:"credit_left,omitempty"`
+		// CreditSuffix CreditLeft / ModelQuota 的单位后缀（缺省「积分」）。llm 的
+		// MiniMax 套餐额度是百分比，给 "%" —— 客户端据此显示「5h 98% · 周 53%」。
+		// 新增（2026-10-25，只增字段不升 contractVersion）。
+		CreditSuffix string `json:"credit_suffix,omitempty"`
+		// ModelQuota 按**模型**给出的套餐额度快照（model id → {interval_left, weekly_left}，
+		// 两个窗口的剩余百分比，单位见 credit_suffix）。仅实现了 agent.ModelQuotaLister
+		// 的引擎给出 —— 目前是 llm（MiniMax 套餐；只挂在走 MiniMax 端点的模型上）。
+		// 新增（2026-10-25，只增字段不升 contractVersion）。
+		ModelQuota map[string]agent.QuotaWindows `json:"model_quota,omitempty"`
+		// CheckinToday 今天是否已领每日积分（true / false）；拿不到状态时**省略**该字段
+		// （nil 指针），客户端据此决定要不要画「领取」按钮。
+		// 新增（2026-10-24，只增字段不升 contractVersion）。
+		CheckinToday *bool `json:"checkin_today,omitempty"`
+		// CheckinCredit 今日可领积分（字符串，如 "100"；活动没开 / 拿不到时省略）。
+		CheckinCredit string `json:"checkin_credit,omitempty"`
+		// LoggedIn 该账号槽位是否已登录（仅实现 agent.LoginChecker 的多账号引擎给出：
+		// codebuddy / codebuddy-ai）。客户端据此**只显示已登录的账号** ——
+		// 「登录了几个账号就显示几个」，而不是固定两行。
+		// 新增（2026-10-25，只增字段不升 contractVersion）；老 core 没有该字段时客户端按「显示」处理。
+		LoggedIn *bool `json:"logged_in,omitempty"`
+		// Account 该账号槽位登录的**账号昵称**（如 "Darren" / "玲"；仅 codebuddy 系给出，
+		// 来自票据里的 account.nickname）。选择器把它画在引擎名下面，一眼看出这行是哪个号。
+		// 新增（2026-10-25，只增字段不升 contractVersion）。
+		Account string `json:"account,omitempty"`
 		// Workspace 该引擎「指定工作目录」的落地方式（machine-readable，供调用方决定是否下发）：
 		//   flag:-C 原生 flag（codex）；cwd 子进程 cwd（claude/codebuddy/trae）；
 		//   none    无落地通道（llm/arkclaw/openclaw/codebuddy-gateway，参数会被忽略）
@@ -896,6 +946,16 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 		if ok {
 			r.Bin, r.Note = note, ""
 		}
+		/* 多账号引擎（codebuddy 系）：这个槽位有没有登录。没登录的槽位客户端不显示，
+		   所以「登录了几个账号就显示几个」；探测本身不依赖它（模型清单照旧给）。 */
+		if lc, okl := e.(agent.LoginChecker); okl {
+			loggedIn := lc.LoggedIn()
+			r.LoggedIn = &loggedIn
+		}
+		/* 账号昵称：选择器里两个 codebuddy 槽位只差引擎名，标上「这行是哪个号」。 */
+		if al, okl := e.(agent.AccountLister); okl {
+			r.Account = al.AccountName()
+		}
 		/* 安装 / 升级命令：**可用时也给**（同一条命令重跑一遍 = 升级到最新版）。
 		   没有可执行安装路径的引擎留空 —— 见 InstallCommandOf 的说明，不编命令。 */
 		r.Install = agent.InstallCommandOf(e.Name())
@@ -914,6 +974,51 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 				rows[i].Version = agent.EngineVersionOf(cmd.Context(), bin)
 			}(i, r.Bin)
 		}
+		/* 账号剩余额度（codebuddy 系积分 / llm 的 MiniMax 套餐百分比）：只读本机票据
+		   或 models.json + 一次只读请求。与模型探测并发跑；查不到就不给该字段。 */
+		if cl, okc := e.(agent.CreditLister); okc {
+			eng := e
+			wg.Add(1)
+			go func(i int, l agent.CreditLister) {
+				defer wg.Done()
+				left := l.CreditLeft(cmd.Context())
+				rows[i].CreditLeft = left
+				if left != "" {
+					if u, oku := eng.(agent.CreditUnitLister); oku {
+						rows[i].CreditSuffix = u.CreditUnit()
+					}
+				}
+			}(i, cl)
+		}
+		/* 模型级套餐额度（llm 的 MiniMax 模型）：同一账号一份快照，挂到每个走该端点的模型。 */
+		if mq, okm := e.(agent.ModelQuotaLister); okm {
+			eng := e
+			wg.Add(1)
+			go func(i int, l agent.ModelQuotaLister) {
+				defer wg.Done()
+				q := l.ModelQuota(cmd.Context())
+				if len(q) == 0 {
+					return
+				}
+				rows[i].ModelQuota = q
+				if u, oku := eng.(agent.CreditUnitLister); oku {
+					rows[i].CreditSuffix = u.CreditUnit()
+				}
+			}(i, mq)
+		}
+		/* 每日签到状态（同上，仅 codebuddy 系）：今天是否已领 + 可领多少，
+		   客户端据此画「领取」按钮；拿不到就省略两个字段。 */
+		if ck, okc := e.(agent.Checkiner); okc {
+			wg.Add(1)
+			go func(i int, c agent.Checkiner) {
+				defer wg.Done()
+				if info, known := c.CheckinStatus(cmd.Context()); known {
+					claimed := info.CheckedToday
+					rows[i].CheckinToday = &claimed
+					rows[i].CheckinCredit = info.DailyCredit
+				}
+			}(i, ck)
+		}
 		if !ok {
 			continue
 		}
@@ -923,7 +1028,7 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 			continue
 		}
 		wg.Add(1)
-		go func(i int, name string, l agent.ModelLister) {
+		go func(i int, name string, l agent.ModelLister, eng agent.Engine) {
 			defer wg.Done()
 			ctx, cancel := context.WithTimeout(cmd.Context(), agent.DefaultModelProbeTimeout)
 			defer cancel()
@@ -946,7 +1051,19 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 					rows[i].ModelCredits = credits
 				}
 			}
-		}(i, e.Name(), lister)
+			/* 供应商展示名（选择器第二行）：与 models 同形，键同样剥前缀。
+			   拿不到就整个省略 —— 界面据此决定画不画第二行（dsh 的第二行是路由，
+			   走的是另一条「id 里自带 route/」的路径，与此无关）。 */
+			if vl := agent.ModelVendorListOf(eng); vl != nil {
+				vendors := vl.ModelVendors(ctx)
+				if name == "codebuddy" || name == "codebuddy-ai" {
+					vendors = agent.StripCustomLocalPrefixCredits(vendors)
+				}
+				if len(vendors) > 0 {
+					rows[i].ModelVendors = vendors
+				}
+			}
+		}(i, e.Name(), lister, e)
 	}
 	wg.Wait()
 	if !envelope {

package/internal/cli/session.go

@@ -397,6 +397,12 @@ func runSessions(cmd *cobra.Command, opts *askOptions) error {
 		if title == "" {
 			title = r.PromptHead
 		}
+		/* 排队占位（服务端作业队列预登记，state=queued）还没有会话日志，归纳必然失败。
+		   这里直接报「已定稿」，客户端就不会每轮列表刷新都去打一次 --summarize-title。
+		   真开跑后 core 那条记录照常走归纳。 */
+		if r.State == session.StateQueued {
+			summarized = true
+		}
 		/* 统一状态：一条会话一个值（各轮的行给出同一个），决定客户端画「进行中 / 已完成」。
 		   没有条目（改造前的老记录）才回落这一轮的 state。alive 也**按它算** ——
 		   否则一行里 status=idle、alive=true 自相矛盾，客户端又会分叉。 */

package/internal/cli/suggest.go

@@ -45,11 +45,13 @@ func runSuggestFollowups(cmd *cobra.Command, opts *askOptions) error {
 		model = opts.model
 	}
 	res, err := suggest.Generate(cmd.Context(), suggest.Request{
-		User:    body.User,
-		Reply:   body.Reply,
-		Engine:  engine,
-		Model:   model,
-		Timeout: suggest.DefaultTimeout,
+		User:           body.User,
+		Reply:          body.Reply,
+		Engine:         engine,
+		Model:          model,
+		FallbackEngine: strings.TrimSpace(opts.suggestFallbackEngine),
+		FallbackModel:  strings.TrimSpace(opts.suggestFallbackModel),
+		Timeout:        suggest.DefaultTimeout,
 	})
 	if err != nil {
 		return fmt.Errorf("--suggest-followups: 生成失败: %w", err)