magic-agent 2.4.3 → 2.6.3

package/internal/agent/wraplaunch_test.go

@@ -0,0 +1,113 @@
+package agent
+
+/* wraplaunch_test.go - 钉住两个对外导出的行为。
+ *
+ * 这两个导出是「发现 → 脚本」功能的地基：
+ *   · WrapLaunch        —— Windows 上 .cmd/.bat/.ps1 必须包 PowerShell，否则参数被拆坏；
+ *                          且**退出码要透传**（否则「脚本失败」只显示退出码 1）。
+ *   · ConfigureProcGroup —— 停止脚本要能整组杀，不留孤儿 worker。
+ *
+ * 放在这里而不是 internal/client：这两个是 agent 层的能力，
+ * 行为边界属于 agent 层（平台差异 + 退出码语义）。
+ */
+
+import (
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestWrapLaunchKeepsArgsOnUnix unix 上：原样返回，不包装、不改写。
+//
+// 脚本参数是用户自己填的定长参数 —— 套上引擎的 emptyStringFlags 白名单
+// 会莫名其妙地改写用户的参数。
+func TestWrapLaunchKeepsArgsOnUnix(t *testing.T) {
+	if platformIsWindows() {
+		t.Skip("Windows 上 .cmd 会被包装，本断言只对 unix 成立")
+	}
+	bin, args := WrapLaunch("/opt/bin/run.sh", []string{"--port", "8080", "a b"})
+	if bin != "/opt/bin/run.sh" {
+		t.Fatalf("bin = %q，应原样保留", bin)
+	}
+	if len(args) != 3 || args[0] != "--port" || args[1] != "8080" || args[2] != "a b" {
+		t.Fatalf("args = %q，应原样保留", args)
+	}
+}
+
+// TestWrapLaunchNativeExeUntouched Windows 上：原生 .exe 不包装。
+//
+// 包一层 PowerShell 会多一个常驻进程，进程组杀 / 超时 / 信号转发都多一跳。
+func TestWrapLaunchNativeExeUntouched(t *testing.T) {
+	if !platformIsWindows() {
+		t.Skip("本断言只对 Windows 成立")
+	}
+	bin, args := WrapLaunch(`C:\tools\run.exe`, []string{"--x"})
+	if bin != `C:\tools\run.exe` {
+		t.Fatalf("bin = %q，.exe 不该被包装", bin)
+	}
+	if len(args) != 1 || args[0] != "--x" {
+		t.Fatalf("args = %q，应原样保留", args)
+	}
+}
+
+// TestWrapLaunchWindowsScriptShape Windows 上：脚本被包成 PowerShell，且参数是单引号字面量。
+//
+// 精确断言整个 argv —— 参数顺序/个数错了 PowerShell 会静默执行错的命令。
+func TestWrapLaunchWindowsScriptShape(t *testing.T) {
+	if !platformIsWindows() {
+		t.Skip("本断言只对 Windows 成立")
+	}
+	bin, args := WrapLaunch(`D:\tools\build.cmd`, []string{"--port", "8080"})
+	if bin != powershellBin() {
+		t.Fatalf("bin = %q，want %q", bin, powershellBin())
+	}
+	// argv 形状：-NoProfile / -ExecutionPolicy / Bypass / -Command / <脚本>
+	want := []string{"-NoProfile", "-ExecutionPolicy", "Bypass", "-Command"}
+	if len(args) != len(want)+1 {
+		t.Fatalf("args = %q\nwant 前缀 %q + 一个脚本", args, want)
+	}
+	for i := range want {
+		if args[i] != want[i] {
+			t.Fatalf("第 %d 个 = %q，want %q", i, args[i], want[i])
+		}
+	}
+	script := args[len(args)-1]
+	// 路径与参数都必须是**单引号字面量**（不是双引号 —— 双引号里的 $ 会被展开）。
+	if !strings.Contains(script, `& 'D:\tools\build.cmd'`) {
+		t.Fatalf("脚本里没有单引号字面量调用：%q", script)
+	}
+	if !strings.Contains(script, `'--port' '8080'`) {
+		t.Fatalf("参数没有逐个单引号包裹：%q", script)
+	}
+}
+
+// TestWrapLaunchPropagatesExitCode Windows 上：包装后必须带 `exit $LASTEXITCODE`。
+//
+// 实测：PowerShell 用 `& 'script.cmd'` 调 `exit /b 3` 的批处理时，
+// **PowerShell 自己的退出码是 1，不是 3** —— 退出码被吞了。
+// 少这句，界面上「脚本失败」只显示退出码 1，用户少一条关键排查信息。
+func TestWrapLaunchPropagatesExitCode(t *testing.T) {
+	if !platformIsWindows() {
+		t.Skip("本断言只对 Windows 成立")
+	}
+	_, args := WrapLaunch(`D:\tools\build.cmd`, nil)
+	script := args[len(args)-1]
+	if !strings.Contains(script, "exit $LASTEXITCODE") {
+		t.Fatalf("包装后没有透传退出码：%q", script)
+	}
+}
+
+// TestConfigureProcGroupSetsAttr 配置后进程组要真的建起来。
+//
+// 这条钉的是「停止脚本能整组杀」的前提 —— 没建进程组，
+// unix 上 kill(-pid) 会杀掉调用方自己那一组（灾难性），Windows 上 taskkill /T 无树可杀。
+func TestConfigureProcGroupSetsAttr(t *testing.T) {
+	cmd := exec.Command("cmd", "/c", "exit", "0")
+	before := cmd.SysProcAttr
+	ConfigureProcGroup(cmd)
+	if cmd.SysProcAttr == before {
+		t.Fatal("配置后 SysProcAttr 没变（进程组没建起来）")
+	}
+	// nil 不能 panic（调用方可能拿到空 cmd）。
+	ConfigureProcGroup(nil)
+}

package/internal/cli/ask.go

@@ -44,25 +44,32 @@ import (
 
 // askOptions 根命令的全部参数。
 type askOptions struct {
-	engine   string
-	model    string
-	system   string
-	prompt   string
-	file     string
-	attach   []string // 附件（截图/图片）路径；与提示词一起发给引擎
-	tools    string
-	timeout  time.Duration
-	retries  int
-	backoff  time.Duration
-	output   string
-	verbose  bool
-	engines  bool
-	contract bool // 输出带版本的契约 envelope（--contract；客户端启动校验用）
-	noModels bool
-	login    string // 拉起某引擎自己的交互式登录会话（--login <engine>）
+	engine string
+	model  string
+	// 备用引擎（2026-10-24）：主引擎失败且零产出时自动降级（见 agent/fallback.go）。
+	// 空 = 不降级，行为与以前一致。
+	fallbackEngine string
+	fallbackModel  string
+	system         string
+	prompt         string
+	file           string
+	attach         []string // 附件（截图/图片）路径；与提示词一起发给引擎
+	tools          string
+	timeout        time.Duration
+	retries        int
+	backoff        time.Duration
+	output         string
+	verbose        bool
+	engines        bool
+	contract       bool // 输出带版本的契约 envelope（--contract；客户端启动校验用）
+	noModels       bool
+	quotas         bool   // 只查额度 / 签到（--quotas；不探测引擎、不启动 CLI）
+	login          string // 拉起某引擎自己的交互式登录会话（--login <engine>）
 	// repairModels 还原被反向同步写坏的桌面端 models.json（--repair-models <engine>）：
 	// 2026-09-30 Windows 事故的收尾手段，见 internal/agent/custom_models.go 的事故还原一节。
-	repairModels    string
+	repairModels string
+	// checkin 领取指定引擎账号的每日积分（--checkin <engine>）：只读本机票据调账单接口。
+	checkin         string
 	events          bool // --stream 的事件流带契约版本与行号（--events；客户端消费用）
 	control         bool // 从 stdin 读 NDJSON 控制命令（--control；打断 / 收工 / 回审批）
 	jsonOut         bool
@@ -136,6 +143,13 @@ type askOptions struct {
 	// 一轮结束后生成 0-3 条「用户下一句」的快捷回复；一次性旁路调用，不续接会话。
 	// 值 = 请求 JSON 的文件路径（"-" = stdin）。
 	suggestInput string // --suggest-followups <file|->：{"user":"…","reply":"…"}
+	// 建议引擎的主备（2026-10-24）：主建议引擎失败时先试这个，再落到内置 llm 兜底。
+	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
@@ -157,8 +171,9 @@ type askOptions struct {
 	teamParallel  int           // --team-parallel：并发度（默认 4）
 	teamTaskTO    time.Duration // --team-task-timeout：单子任务超时（0 = 按总超时推算）
 	teamRoutes    []string      // --team-route <kind>=<engine>[/<model>]，可重复
+	teamFallbacks []string      // --team-fallback <kind>=<engine>[/<model>]，可重复（主备里的「备」）
 	teamRunDir    string        // --team-run-dir：覆盖运行目录父级
-	teamPerm      string        // --team-permission：子任务权限上限（默认 accept-edits）
+	teamPerm      string        // --team-permission：子任务权限上限（空 = 继承主会话 --permission）
 	teamAdaptive  bool          // --team-adaptive：执行后按失败 / open 项再规划一轮
 	teamSplit     string        // --team-split：拆解粒度 coarse | standard | fine
 	teamSplitCode bool          // --team-split-code：简单代码也拆成独立子任务
@@ -173,6 +188,7 @@ type askOptions struct {
 	 * 所以派发一律用 flagChanged 判断（看「传过没有」而不是「值非空」）。 */
 	requirements    string        // --requirements [<ws|dir>]：读清单
 	consolidateReqs string        // --consolidate-requirements [<ws|dir>]：跑一轮归纳
+	reqGraph        string        // --requirements-graph [<ws|dir>]：会话↔需求关系图谱（只读）
 	reqForce        bool          // --requirement-force
 	reqAll          bool          // --requirement-all：全量重放
 	reqEngine       string        // --requirement-engine（默认 llm）
@@ -180,6 +196,10 @@ type askOptions struct {
 	reqModule       string        // --requirement-module：只整理这个模块
 	reqTimeout      time.Duration // --requirement-timeout
 	reqAuto         bool          // --requirement-auto：自动归纳，不触发首次初始化
+	// 截图相关（--requirement-shot）：PNG 走 stdin，不走命令行参数。
+	reqShot     string // --requirement-shot [<ws|dir>]：给功能点追加一张完成情况截图
+	reqShotName string // --requirement-shot-name：功能点名
+	reqShotCap  string // --requirement-shot-caption：截图标注说明
 }
 
 // newAskOptions 返回带默认值的选项集。
@@ -203,6 +223,10 @@ func bindAskFlags(cmd *cobra.Command, opts *askOptions) {
 	f := cmd.PersistentFlags()
 	f.StringVarP(&opts.engine, "engine", "e", "codebuddy", "引擎: codebuddy | codebuddy-ai | claude | trae | llm | codex | openclaw | dsh | arkclaw（默认 codebuddy）")
 	f.StringVarP(&opts.model, "model", "m", "", "模型（空 = 引擎默认：codebuddy=hy3；codebuddy-ai=CLI 自选默认；llm 引擎传 llm CLI 注册名，如 minimax-m3；dsh/arkclaw 不透传）")
+	/* 主备（2026-10-24）：主引擎失败且**零产出**时自动换备用重跑（额度用尽 / 单模型故障）。
+	   只降一级；已经流出正文则不降级（避免两段互相矛盾的答案）。 */
+	f.StringVar(&opts.fallbackEngine, "fallback-engine", "", "备用引擎：主引擎失败且零产出时自动降级（缺省 = 不降级；可用值同 --engine）")
+	f.StringVar(&opts.fallbackModel, "fallback-model", "", "备用引擎的模型（空 = 该引擎默认；只在 --fallback-engine 非空时生效）")
 	f.StringVarP(&opts.system, "system", "s", "", "系统提示词（空 = 用配置文件 ~/.config/magic-agent/config.json 的 systemPrompt；两者都为空则不注入）。值若是文件路径或 @文件 → 读该文件内容")
 	f.StringVarP(&opts.prompt, "prompt", "p", "", "提示词（值若是文件路径或 @文件 → 读该文件内容作为提示词）")
 	f.StringVarP(&opts.workspace, "workspace", "w", "", "工作目录（workspace）：在该目录里执行引擎；codex 走原生 -C，claude/codebuddy/trae/dsh 用子进程 cwd，llm/arkclaw/openclaw 不支持（忽略并提示）")
@@ -222,6 +246,9 @@ func bindAskFlags(cmd *cobra.Command, opts *askOptions) {
 	f.BoolVar(&opts.titleForce, "title-force", false, "配合 --summarize-title：已有标题也重新归纳（默认命中缓存就直接返回，省一次 LLM 调用）")
 	f.StringVar(&opts.titleEngine, "title-engine", "llm", "--summarize-title 用哪个引擎归纳（默认 llm：纯文本、不带工具）")
 	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）")
@@ -244,8 +271,10 @@ func bindAskFlags(cmd *cobra.Command, opts *askOptions) {
 	f.BoolVar(&opts.engines, "engines", false, "列出支持的引擎、本机 CLI 可用性与各引擎当前支持的模型（JSON 数组；每行含 capabilities / models / workspace / streaming 能力字段；不可用的引擎带 install 一键安装命令）")
 	f.BoolVar(&opts.contract, "contract", false, "输出桌面/移动客户端契约：{\"contractVersion\":N,\"engines\":[...]}（engines 与 --engines 同构，另含 capabilities 静态能力字段）。默认不探测模型（快）；要模型写 --no-models=false")
 	f.BoolVar(&opts.noModels, "no-models", false, "配合 --engines / --contract：跳过各引擎的模型探测（只列引擎与可用性，不启动 CLI）")
+	f.BoolVar(&opts.quotas, "quotas", false, "只查各引擎账号的额度与每日签到（JSON 数组，字段与 --engines 同名；不探测引擎、不启动任何 CLI，秒级返回）")
 	f.StringVar(&opts.login, "login", "", "拉起指定引擎自己的交互式登录会话（如 codebuddy / codebuddy-ai）：自动带上该引擎的账号环境，进去执行 /login 即可；登录态落在该引擎自己的票据上，两个账号互不顶号")
 	f.StringVar(&opts.repairModels, "repair-models", "", "还原被覆盖写坏的桌面端 models.json（如 codebuddy / codebuddy-ai）：把对象格式改回桌面端的数组格式，官方模型清单不动；只在形状确实是坏的时候才改，且先留 .broken.bak 备份")
+	f.StringVar(&opts.checkin, "checkin", "", "领取指定引擎账号的每日积分（如 codebuddy / codebuddy-ai）：用该引擎自己的登录票据调账单接口，输出本次到账积分与连续天数；每天只能领一次")
 	f.BoolVar(&opts.jsonOut, "json", false, "兼容保留：--engines 已默认 JSON，本 flag 不再需要")
 	f.BoolVar(&opts.stream, "stream", false, "流式输出：正文/思考增量实时打到 stdout（text 模式思考走 stderr）")
 	f.BoolVar(&opts.events, "events", false, "配合 --stream：事件流带契约版本与行号（每行加 v / seq，并先发一行 ready），供客户端消费；老消费者不要开（形状与 --stream 不同）")
@@ -271,9 +300,11 @@ func bindTeamFlags(cmd *cobra.Command, opts *askOptions) {
 	f.DurationVar(&opts.teamTaskTO, "team-task-timeout", 0, "配合 --team：单个子任务超时（0 = 总超时的 1/2，上限 20m）")
 	f.StringArrayVar(&opts.teamRoutes, "team-route", nil,
 		"配合 --team：给某类子任务或某个角色指定引擎/模型，形如 image=llm/hunyuan-image-3.0 或 role:coder=claude/sonnet（可重复；类别：plan|text|code|image|video|game；角色用 role:<name>）")
+	f.StringArrayVar(&opts.teamFallbacks, "team-fallback", nil,
+		"配合 --team：给某类/某个角色指定**备用**引擎/模型，主引擎失败且零产出时自动降级，形如 image=dsh/v3 或 role:coder=codebuddy（可重复；键同 --team-route）")
 	f.StringVar(&opts.teamRunDir, "team-run-dir", "", "配合 --team：覆盖运行目录的父目录（空 = 选了空间落 <空间>/.magic/team，否则落 ~/.magic-agent/team）")
-	f.StringVar(&opts.teamPerm, "team-permission", string(agent.PermissionAcceptEdits),
-		"配合 --team：子任务的权限上限（默认 accept-edits —— 子任务不该继承主会话的完全访问）")
+	f.StringVar(&opts.teamPerm, "team-permission", "",
+		"配合 --team：子任务的权限上限（空 = 继承主会话 --permission；显式给档位可压低子任务权限，如 accept-edits）")
 	f.BoolVar(&opts.teamAdaptive, "team-adaptive", true,
 		"配合 --team：第一轮执行后按失败与未解决项再规划一轮补充任务（默认开；只补一轮、最多 3 个）")
 	f.StringVar(&opts.teamSplit, "team-split", "",
@@ -555,18 +586,29 @@ func runAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 
 	// 会话登记 + spawn 钩子：把引擎子进程 pid 记下来，之后任何进程都能
 	// `magic-agent --stop <session_id>` 精确停掉它（见 internal/session）。
-	h := beginSession(engine.Name(), req, opts.saveRegistry)
+	h, berr := beginSession(engine.Name(), req, opts.saveRegistry)
+	if berr != nil {
+		/* 登记失败 = 这一轮跑不起来（最典型：工作空间锁等超时）。**必须当失败返回**：
+		   继续跑的话，引擎会在没有登记的情况下开跑，客户端那边看到的是「在跑」，
+		   实际这一轮早该失败 —— 而失败原因只剩 stderr 里一行字。
+		   ⚠️ 用原 error 返回（不是 reportedError）：reportedError 的语义是
+		      「已经输出过了」，包上它 Execute 就不再打印，原因会被吞掉。 */
+		return berr
+	}
 	ctx := withSessionHook(cmd.Context(), h)
 
-	runner := &agent.Runner{
-		Engine:  engine,
-		Timeout: opts.timeout,
-		Retries: opts.retries,
-		Backoff: opts.backoff,
-		Verbose: opts.verbose,
-	}
-	resp, err := runner.Run(ctx, req)
+	/* 非流式路径同样支持主备降级：主引擎失败且没拿到正文时换备用再跑一次
+	   （提示写到 stderr —— 这条路径没有事件流可挂 notice）。 */
+	resp, fbInfo, err := agent.RunWithFallback(ctx, engine, req, agent.RunOptions{
+		Timeout: opts.timeout, Retries: opts.retries, Backoff: opts.backoff, Verbose: opts.verbose,
+	}, func(fe agent.FallbackEvent) {
+		note := agent.FallbackNoticeText(fe)
+		fmt.Fprintf(cmd.ErrOrStderr(), "magic-agent: %s\n", note)
+	})
 	if err != nil {
+		if fbInfo.Reason != "" {
+			fmt.Fprintf(cmd.ErrOrStderr(), "magic-agent: 本轮没有降级：%s\n", fbInfo.Reason)
+		}
 		finishSession(h, "", session.StateFailed)
 		attempts := 1 + opts.retries
 		// WriteError 已把失败信息（json envelope / text 行）写到 stderr，
@@ -587,7 +629,10 @@ func runAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 // ⚠️ saveRegistry=false 时**不落盘**（用户 2026-10-12：「会话登记也不需要」）：
 // 句柄照常分配（run_id 要给常驻会话的追加入口命名），只是磁盘上不留记录 ——
 // 代价是 --sessions / --stop 看不见它，--append 只能按 run_id 走约定路径。
-func beginSession(engine string, req agent.Request, saveRegistry bool) *session.Handle {
+//
+// 返回的 err 是登记失败的原因（最典型的是**工作空间锁等超时**）：
+// 吞掉它的话，调用方只知道「没有会话句柄」，真实原因查不出来。
+func beginSession(engine string, req agent.Request, saveRegistry bool) (*session.Handle, error) {
 	h, err := session.Begin(session.BeginOptions{
 		Engine:     engine,
 		Model:      req.Model,
@@ -600,10 +645,10 @@ func beginSession(engine string, req agent.Request, saveRegistry bool) *session.
 		NoPersist:  !saveRegistry,
 	})
 	if err != nil {
-		return nil
+		return nil, err
 	}
 	setActiveSession(h)
-	return h
+	return h, nil
 }
 
 // withSessionHook 给 ctx 挂上「子进程已启动」回调（h 为空时原样返回）。
@@ -655,8 +700,7 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	if err != nil {
 		return err
 	}
-	streamer := agent.AsStreamer(engine)
-	if streamer == nil {
+	if agent.AsStreamer(engine) == nil {
 		return &usageError{fmt.Errorf("engine %q does not support streaming", engine.Name())}
 	}
 
@@ -759,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 {
@@ -800,6 +847,10 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 				// runStreamAsk 的 error 分支写（stdout 一条 error 事件），这里只
 				// 保证 text 模式的调用方也**看得见**这一轮没有正常结束。
 				fmt.Fprint(stderr, "✗ 本轮异常收尾："+ev.Reason+"\n")
+			case agent.KindNotice:
+				/* 过程提示（max_tokens 截断 / 「工具不在当前工具集」等）。
+				   与 thinking、工具事件同走 stderr，stdout 正文保持干净。 */
+				fmt.Fprint(stderr, "· "+ev.Text+"\n")
 			}
 			wireLogger(ev)
 		}
@@ -822,7 +873,12 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	}
 
 	// 会话登记 + spawn 钩子（与 runAsk 同一套：--stop 靠它拿到引擎 pid）。
-	h := beginSession(engine.Name(), req, opts.saveRegistry)
+	h, berr := beginSession(engine.Name(), req, opts.saveRegistry)
+	if berr != nil {
+		/* 同 runAsk：登记失败就别开跑。真实原因（等锁超时等）直接报出去，
+		   免得整轮以「跑起来了但列表里没有」的形式收场。 */
+		return berr
+	}
 	ctx = withSessionHook(ctx, h)
 
 	/* 把「本次运行 id」也交给存档 writer（2026-10-15）：引擎还没吐 session_id 时，
@@ -832,7 +888,11 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	     · 引擎**整轮都不给 id** 的形态（dsh 的 headless 回退轮）不再白开 --save-history
 	       （此前那些事件一直躺在内存 buffer 里，收工时被丢光）。
 	   拿到 id 后 writer 自己改名为 <session_id>.jsonl（见 sessionlog.go 的 renameTo）。 */
-	if sessionLog != nil {
+	/* ⚠️ h 可能为 nil：session.Begin 失败（例如工作空间锁等超时）时 beginSession 返回 nil，
+	   而 h.RunID() 是值接收者 → nil 解引用直接 panic，整轮以一堆栈回溯收场，
+	   真实原因（等锁超时）反而被淹没。beginSession 的错误本来就该由调用方当失败处理，
+	   这里只保证不崩：没有 run id 就不设，存档 writer 继续用会话 id 命名。 */
+	if sessionLog != nil && h != nil {
 		sessionLog.setRunID(h.RunID())
 	}
 
@@ -870,6 +930,16 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 		onEvent = ka.wrapOnEvent(onEvent)
 	}
 
+	/* 控制应答通道（原地回审批，2026-10-25）：计划审批 ExitPlanMode / manual 档的工具授权
+	   都是引擎发 control_request **原地等 stdin 上的 control_response** —— 不写回去整轮就挂着
+	   （用户报障：「没看到审批」+ 一直转圈）。这条路与常驻会话无关：Windows 没有追加入口，
+	   但审批照样要能回，所以独立建通道（引擎侧会因此把 stdin 保持到本轮收尾，见 Request.Reply）。 */
+	var controlReplies chan string
+	if opts.control && agent.AskAnswerControlOf(engine.Name()) {
+		controlReplies = make(chan string, 8)
+		req.Reply = controlReplies
+	}
+
 	/* 控制通道：给调用方一条回传通道（打断 / 收工 / 回审批）。
 	   起在常驻会话之后 —— answer 依赖 ka。 */
 	var ctl *controlSession
@@ -884,6 +954,27 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 				cancelAll()
 			},
 			answer: func(text string) bool { return ka != nil && ka.Push(text) },
+			answerAsk: func(requestID string, allowed bool, message, toolName string) bool {
+				if controlReplies == nil {
+					return false
+				}
+				raw, eerr := agent.EncodeAskControlResponse(engine.Name(), &agent.AskRequest{
+					Engine:    engine.Name(),
+					Kind:      agent.AskKindPermission,
+					Source:    agent.AskSourceControlRequest,
+					RequestID: requestID,
+					ToolName:  toolName,
+				}, agent.AskAnswer{Denied: !allowed, Message: message})
+				if eerr != nil {
+					return false
+				}
+				select {
+				case controlReplies <- string(raw):
+					return true
+				default:
+					return false // 缓冲区满 = 引擎侧没在读，如实失败
+				}
+			},
 		})
 		defer ctl.Close()
 	}
@@ -961,6 +1052,18 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 		}
 	}
 	isCommand := isSlashCommand(lastUserMsg)
+	/* core 自己合成的帧（command / fallback）统一走这里：JSON 形态落盘 + 外发，
+	   text 形态只落 sessionlog（stdout 是正文通道）。 */
+	emitCoreFrame := func(ev agent.StreamEvent, textOnly bool) {
+		if format == agent.FormatJSON {
+			_ = sink.stream(ev)
+			wireLogger(ev)
+			return
+		}
+		if textOnly && sessionLog != nil {
+			sessionLog.push(sessionEvent{Kind: string(ev.Kind), Text: ev.Text})
+		}
+	}
 	emitCommand := func(status agent.StreamStatus) {
 		if !isCommand {
 			return
@@ -977,8 +1080,26 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	}
 	emitCommand(agent.StatusRunning)
 
-	res, err := streamer.Stream(ctx, req, onEvent)
+	/* 降级那一帧在 agent 层发出（走 onEvent），这里同时落 sessionlog —— 历史回放要能
+	   看到「这条回答是备用给的」。两个动作都放 onEvent 里：text 形态只落盘、JSON 形态
+	   落盘 + 外发（emitCoreFrame 的分支）。 */
+	if sessionLog != nil {
+		inner := onEvent
+		onEvent = func(ev agent.StreamEvent) {
+			if ev.Kind == agent.KindFallback {
+				sessionLog.push(sessionEvent{Kind: string(agent.KindFallback), Text: ev.Text})
+			}
+			inner(ev)
+		}
+	}
+	res, fbInfo, err := agent.StreamWithFallback(ctx, engine, req, onEvent)
+	/* 主备结论（2026-10-26）：**没降级的原因**补一条 notice —— 用户配过备用却看到一个
+	   普通的失败时，得能分辨「配错 / 能力不支持 / 主引擎已经出过正文」。
+	   只在失败路径报：成功轮不打扰（配了备用、主引擎也跑好了，这是常态）。 */
 	interrupted := ctl != nil && ctl.WasInterrupted()
+	if err != nil && !interrupted && fbInfo.Reason != "" {
+		emitCoreFrame(agent.StreamEvent{Kind: agent.KindNotice, Text: "本轮没有降级：" + fbInfo.Reason}, true)
+	}
 	if interrupted {
 		/* 打断的应答放在这里、而不是命令到达的那一刻：interrupt 的真实含义是
 		   「这一轮真的结束了」。失败链本身就是 context canceled，不必再包一层。 */
@@ -1360,6 +1481,16 @@ func prepareAsk(cmd *cobra.Command, args []string, opts *askOptions) (agent.Engi
 		t := opts.temperature
 		req.Temperature = &t
 	}
+	/* 备用引擎（2026-10-24）：指向不存在的引擎属于**配置错**，开跑前就报，
+	   别等主引擎失败后才发现降级目标也没有。与主引擎同名 = 没配（不重复跑一次）。 */
+	if fb := strings.TrimSpace(opts.fallbackEngine); fb != "" && !strings.EqualFold(fb, engine.Name()) {
+		if agent.Lookup(fb) == nil {
+			return nil, "", agent.Request{}, &usageError{fmt.Errorf(
+				"--fallback-engine %q 不存在（可用引擎见 magic-agent --engines）", fb)}
+		}
+		req.FallbackEngine = fb
+		req.FallbackModel = strings.TrimSpace(opts.fallbackModel)
+	}
 	if s := strings.TrimSpace(opts.jsonSchema); s != "" {
 		schema, err := parseJSONSchemaInline(s)
 		if err != nil {

package/internal/cli/ask_test.go

@@ -641,7 +641,7 @@ func unregisterLast() {}
 // ── --engines flag ───────────────────────────────────────────
 //
 // 注意：以下用例一律带 --no-models —— 模型探测会真的启动本机 CLI
-//（trae-cli / llm / codex / openclaw / codebuddy），单元测试不该依赖它们。
+//（traex / llm / codex / openclaw / codebuddy），单元测试不该依赖它们。
 // models 字段本身的行为由 TestEnginesFlagIncludesModels 用假引擎 + 假探测覆盖。
 
 // --engines 默认即输出 JSON 数组（含引擎名与是否可用），无需 --json。

package/internal/cli/checkin.go

@@ -0,0 +1,77 @@
+package cli
+
+// checkin.go - `--checkin <engine>`：领取该引擎账号的每日积分。
+//
+// 与 --login 同源：读该引擎自己的登录票据（codebuddy-ai 读隔离目录），
+// 调 CodeBuddy 账单接口 POST /billing/meter/daily-checkin。每天只能领一次，
+// 重复领取返回服务端业务错误（ok:false + message），不算命令失败（exit 0）。
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+	"github.com/spf13/cobra"
+)
+
+// checkinOutput `--checkin` 的输出形状（客户端 / 脚本都消费它）。
+type checkinOutput struct {
+	Engine string `json:"engine"`
+	// OK 本次是否真的领到（false 时看 message：已领 / 活动未开 / 未登录）。
+	OK bool `json:"ok"`
+	// Credit 本次到账积分（字符串，可能为空）。
+	Credit string `json:"credit,omitempty"`
+	// StreakDays 连续签到天数。
+	StreakDays int `json:"streak_days,omitempty"`
+	// CheckedToday 领取后恒为 true；失败时保留服务端语义（此处为 false）。
+	CheckedToday bool `json:"checked_today"`
+	// Message 业务失败原因。
+	Message string `json:"message,omitempty"`
+	// CreditLeft 领取后的账号剩余积分（能查到才给）。
+	CreditLeft string `json:"credit_left,omitempty"`
+}
+
+// runCheckin 处理 `--checkin <engine>`。
+func runCheckin(cmd *cobra.Command, opts *askOptions) error {
+	name := strings.TrimSpace(opts.checkin)
+	if name == "" {
+		return &usageError{fmt.Errorf("--checkin 需要引擎名：magic-agent --checkin <engine>（当前支持 codebuddy / codebuddy-ai）")}
+	}
+	eng := agent.Lookup(name)
+	if eng == nil {
+		return &usageError{fmt.Errorf("未知引擎 %q（当前支持 codebuddy / codebuddy-ai）", name)}
+	}
+	c, ok := eng.(agent.Checkiner)
+	if !ok {
+		return &usageError{fmt.Errorf("引擎 %s 不支持 --checkin：每日积分只有 codebuddy / codebuddy-ai 有", eng.Name())}
+	}
+
+	ctx, cancel := context.WithTimeout(cmd.Context(), 20*time.Second)
+	defer cancel()
+
+	out := checkinOutput{Engine: eng.Name()}
+	info, err := c.ClaimCheckin(ctx)
+	if err != nil {
+		out.OK = false
+		out.Message = err.Error()
+		if info.Message != "" {
+			out.Message = info.Message
+		}
+		// 「今天已签到」这类业务失败也带上真实状态，客户端能把「领取」翻成「今日已领」。
+		out.CheckedToday = info.CheckedToday
+		out.StreakDays = info.StreakDays
+		return printJSON(cmd.OutOrStdout(), out)
+	}
+	out.OK = true
+	out.Credit = info.Credit
+	out.StreakDays = info.StreakDays
+	out.CheckedToday = true
+
+	// 领取后顺手刷新剩余额度（查不到就省略；不让它影响领取结果）。
+	if cl, ok := eng.(agent.CreditLister); ok {
+		out.CreditLeft = cl.CreditLeft(ctx)
+	}
+	return printJSON(cmd.OutOrStdout(), out)
+}

package/internal/cli/clientcmd.go

@@ -36,7 +36,8 @@ func clientSubcommand() *cobra.Command {
 		Short: "客户端插件（magic-client）：后台启动 / 停止 / 看状态，手机据此连接",
 		Long: `把参数原样交给 magic-client（客户端插件，随 npm 包一起安装）。
 
-  magic-agent client start --lan     # 后台常驻，打印手机可用的地址与配对二维码
+  magic-agent client start           # 后台常驻（默认绑 0.0.0.0:9100），打印手机地址与配对二维码
+  magic-agent client start --local   # 只绑 127.0.0.1，手机连不上
   magic-agent client status          # 在不在、端口、手机地址、健康检查
   magic-agent client stop            # 停掉（本来没跑也算成功）
 
@@ -45,7 +46,7 @@ func clientSubcommand() *cobra.Command {
 状态文件（~/.magic-client/client.json），三个动作围绕它工作，令牌跨重启稳定
 （存 ~/.magic-client/token，删掉它才会换）。
 
-⚠️ --lan 只绑局域网：手机要和这台电脑在**同一个 Wi-Fi**。跨网访问不在本命令范围内。
+⚠️ 默认绑局域网（0.0.0.0:9100）：手机要和这台电脑在**同一个 Wi-Fi**。跨网访问不在本命令范围内。
 
 本命令不在 core 里实现，只负责转发（桌面 / 移动端是可选插件，core 不依赖它）。
 详细 flag 见 magic-client start --help。`,