magic-agent 1.0.0

package/internal/cli/events_test.go

@@ -0,0 +1,166 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// sinkSamples 覆盖全部事件类型：用来钉住「--stream 与 --events 的字段集只差 v / seq」。
+func sinkSamples() []agent.StreamEvent {
+	return []agent.StreamEvent{
+		{Kind: agent.KindText, Text: "正文"},
+		{Kind: agent.KindThinking, Text: "思考"},
+		{Kind: agent.KindToolUse, Text: `{"command":"ls"}`, Name: "Bash", ID: "toolu_1"},
+		{Kind: agent.KindToolResult, Text: "输出", ID: "toolu_1"},
+		{Kind: agent.KindTurnEnd, Text: "本轮正文", SessionID: "sess_abc"},
+		{Kind: agent.KindAsk, Text: "要选一个"},
+	}
+}
+
+func decodeEventLine(t *testing.T, s string) map[string]any {
+	t.Helper()
+	var m map[string]any
+	if err := json.Unmarshal([]byte(strings.TrimSpace(s)), &m); err != nil {
+		t.Fatalf("解析事件行失败: %v（%q）", err, s)
+	}
+	return m
+}
+
+// TestEventSinkShapeParity 老形状（--stream）与新形状（--stream --events）的字段集
+// 必须只差 v / seq，取值逐项相同。
+//
+// 这条是本文件里最重要的断言：两个形状共用 streamEventPayload()，但 envelope 那一步
+// 做了「marshal → 加字段 → marshal」的往返，字段丢失或改名只会在新形状里发生。
+func TestEventSinkShapeParity(t *testing.T) {
+	for _, ev := range sinkSamples() {
+		var plain, enriched bytes.Buffer
+		if err := newEventSink(&plain, "claude", false).stream(ev); err != nil {
+			t.Fatalf("%s: 老形状 %v", ev.Kind, err)
+		}
+		if err := newEventSink(&enriched, "claude", true).stream(ev); err != nil {
+			t.Fatalf("%s: 新形状 %v", ev.Kind, err)
+		}
+
+		a := decodeEventLine(t, plain.String())
+		b := decodeEventLine(t, enriched.String())
+
+		if _, ok := b["v"]; !ok {
+			t.Errorf("%s: --events 形态缺 v 字段: %v", ev.Kind, b)
+		}
+		if _, ok := b["seq"]; !ok {
+			t.Errorf("%s: --events 形态缺 seq 字段: %v", ev.Kind, b)
+		}
+		delete(b, "v")
+		delete(b, "seq")
+		if !reflect.DeepEqual(a, b) {
+			t.Errorf("%s: 两条路径不一致\n  老形状: %v\n  新形状: %v", ev.Kind, a, b)
+		}
+	}
+}
+
+// TestEventSinkSeqMonotonic 行号从 1 起、逐行 +1；每行都带契约版本。
+func TestEventSinkSeqMonotonic(t *testing.T) {
+	var buf bytes.Buffer
+	s := newEventSink(&buf, "claude", true)
+	for _, ev := range sinkSamples() {
+		if err := s.stream(ev); err != nil {
+			t.Fatal(err)
+		}
+	}
+	lines := strings.Split(strings.TrimSpace(buf.String()), "\n")
+	if len(lines) != len(sinkSamples()) {
+		t.Fatalf("行数 = %d want %d", len(lines), len(sinkSamples()))
+	}
+	for i, ln := range lines {
+		m := decodeEventLine(t, ln)
+		if got := int(m["seq"].(float64)); got != i+1 {
+			t.Errorf("第 %d 行 seq = %d want %d", i, got, i+1)
+		}
+		if got := int(m["v"].(float64)); got != agent.ContractVersion {
+			t.Errorf("第 %d 行 v = %d want %d", i, got, agent.ContractVersion)
+		}
+	}
+}
+
+// TestEventSinkSessionSticky 会话 id 一旦拿到，后续每行都带（客户端据此绑定会话）。
+func TestEventSinkSessionSticky(t *testing.T) {
+	var buf bytes.Buffer
+	s := newEventSink(&buf, "claude", true)
+	if err := s.stream(agent.StreamEvent{Kind: agent.KindTurnEnd, Text: "done", SessionID: "sess_x"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.stream(agent.StreamEvent{Kind: agent.KindText, Text: "下一轮"}); err != nil {
+		t.Fatal(err)
+	}
+	lines := strings.Split(strings.TrimSpace(buf.String()), "\n")
+	if m := decodeEventLine(t, lines[1]); m["session_id"] != "sess_x" {
+		t.Errorf("turn_end 之后的正文应带 session_id=sess_x，实际 %v", m["session_id"])
+	}
+}
+
+// TestEventSinkNewEventsGated ready 与控制应答只在 --events 下输出 ——
+// 老消费者不认识新事件类型，往老形状里注入它们是静默的形状变更。
+func TestEventSinkNewEventsGated(t *testing.T) {
+	var off bytes.Buffer
+	offSink := newEventSink(&off, "claude", false)
+	if err := offSink.ready("hy3"); err != nil {
+		t.Fatal(err)
+	}
+	if err := offSink.notice("pong", nil); err != nil {
+		t.Fatal(err)
+	}
+	if off.Len() != 0 {
+		t.Errorf("未开 --events 时不该输出 ready / 控制应答，实际 %q", off.String())
+	}
+
+	var on bytes.Buffer
+	onSink := newEventSink(&on, "claude", true)
+	if err := onSink.ready("hy3"); err != nil {
+		t.Fatal(err)
+	}
+	if err := onSink.notice("pong", nil); err != nil {
+		t.Fatal(err)
+	}
+	lines := strings.Split(strings.TrimSpace(on.String()), "\n")
+	if m := decodeEventLine(t, lines[0]); m["type"] != "ready" || m["engine"] != "claude" || m["model"] != "hy3" {
+		t.Errorf("ready 行不对: %v", m)
+	}
+	m := decodeEventLine(t, lines[1])
+	if m["type"] != "pong" {
+		t.Errorf("pong 行不对: %v", m)
+	}
+	if _, ok := m["v"]; !ok {
+		t.Error("控制应答也应带 v")
+	}
+}
+
+// TestStreamFlagsRequireStream 给了 --events / --control 却没给 --stream 要报错。
+// 本项目的立场：静默忽略是 bug 的温床（超时被静默忽略那类事故）。
+func TestStreamFlagsRequireStream(t *testing.T) {
+	for _, flag := range []string{"--events", "--control"} {
+		_, _, err := runAskCmd(t, "", flag, "hi")
+		if err == nil {
+			t.Errorf("%s 不带 --stream 应当报错", flag)
+			continue
+		}
+		if !strings.Contains(err.Error(), "--stream") {
+			t.Errorf("%s 的报错应提到 --stream，实际: %v", flag, err)
+		}
+	}
+}
+
+// TestControlConflictsWithStdinPrompt --control 占用 stdin，与「从 stdin 读提示词」互斥。
+func TestControlConflictsWithStdinPrompt(t *testing.T) {
+	_, _, err := runAskCmd(t, "提示词", "--stream", "--control", "-f", "-")
+	if err == nil {
+		t.Fatal("--control 与 -f - 应当冲突并报错")
+	}
+	if !strings.Contains(err.Error(), "stdin") {
+		t.Errorf("报错应解释 stdin 冲突，实际: %v", err)
+	}
+}

package/internal/cli/keepalive_test.go

@@ -0,0 +1,391 @@
+package cli
+
+// keepalive_test.go - CLI 侧「常驻会话 + 追加消息」的测试。
+//
+// 用户需求（2026-09-18）：「按路线 2 实现，先支持 claude 和 codebuddy 的追加功能」。
+//
+// 覆盖：--keep-alive 的前置校验（必须 --stream / 引擎必须支持 / --idle 必须为正）/
+// --append 的参数校验与错误路径 / 端到端（起常驻会话 → --append 投递 → 空闲收工）。
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+	"github.com/darren/magic-agent/internal/session"
+)
+
+// kaEngine 假引擎：模拟 claude/codebuddy 的常驻会话 —— 消费 req.Append，
+// 每收到一条就发一个 turn_end（真实引擎在 result 行时发）。
+type kaEngine struct {
+	name string
+	mu   sync.Mutex
+	got  []string
+}
+
+func (k *kaEngine) Name() string           { return k.name }
+func (k *kaEngine) Detect() (bool, string) { return true, "fake://" + k.name }
+func (k *kaEngine) Complete(context.Context, agent.Request) (agent.Response, error) {
+	return agent.Response{Text: "complete", Model: "fake-model"}, nil
+}
+func (k *kaEngine) Stream(_ context.Context, req agent.Request, onEvent func(agent.StreamEvent)) (agent.StreamResult, error) {
+	if req.Append == nil {
+		return agent.StreamResult{}, errors.New("kaEngine 需要 Append 通道")
+	}
+	for msg := range req.Append {
+		k.mu.Lock()
+		k.got = append(k.got, msg)
+		k.mu.Unlock()
+		if onEvent != nil {
+			onEvent(agent.StreamEvent{Kind: agent.KindTurnEnd, Text: "ok"})
+		}
+	}
+	return agent.StreamResult{
+		Response: agent.Response{Engine: k.name, Text: "done", SessionID: "sid-ka", Model: "fake-model"},
+	}, nil
+}
+func (k *kaEngine) received() []string {
+	k.mu.Lock()
+	defer k.mu.Unlock()
+	return append([]string(nil), k.got...)
+}
+func (k *kaEngine) reset() {
+	k.mu.Lock()
+	k.got = nil
+	k.mu.Unlock()
+}
+
+// ⚠️ 整包共用一个 "codebuddy" 假引擎：`agent.Lookup` 取注册表里**首个**同名匹配，
+// 每个用例各注册一个的话，后注册的永远不被使用（我第一版就是这么挂的：
+// 追加投递成功、断言却打在另一个实例上）。用前 reset 即可。
+var (
+	kaRegisterOnce sync.Once
+	kaShared       = &kaEngine{name: "codebuddy"}
+)
+
+func kaEngineForTest(t *testing.T) *kaEngine {
+	t.Helper()
+	kaRegisterOnce.Do(func() { registerFake(kaShared) })
+	kaShared.reset()
+	return kaShared
+}
+
+// shortSessionsDir 给测试一个**短**的登记表目录（unix socket 路径有 104 字节上限）。
+func shortSessionsDir(t *testing.T) string {
+	t.Helper()
+	dir, err := os.MkdirTemp("/tmp", "mas-cli-")
+	if err != nil {
+		t.Fatalf("MkdirTemp: %v", err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(dir) })
+	return dir
+}
+
+// ── 前置校验 ─────────────────────────────────────────────────
+
+func TestKeepAliveRequiresStream(t *testing.T) {
+	kaEngineForTest(t)
+	_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--keep-alive", "-p", "hi")
+	if err == nil {
+		t.Fatal("--keep-alive 不配 --stream 应报错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("应是 usageError(exit 2), got %T: %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "--stream") {
+		t.Errorf("错误信息应点明要 --stream: %v", err)
+	}
+}
+
+// 不支持的引擎：直接测能力分支（不走注册表 —— cli 包测试里的引擎是假的，
+// 且同名只认首个注册，用 -e trae 跑真流程会先撞上别的假引擎的「不支持流式」）。
+func TestKeepAliveUnsupportedEngine(t *testing.T) {
+	t.Setenv(session.EnvDir, shortSessionsDir(t))
+	cmd := NewRootCommand()
+	opts := newAskOptions()
+	opts.keepAlive, opts.stream, opts.idle = true, true, time.Second
+
+	_, err := startKeepAlive(cmd, opts, "trae", nil)
+	if err == nil {
+		t.Fatal("不支持的引擎应报错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("应是 usageError(exit 2), got %T: %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "claude") || !strings.Contains(err.Error(), "codebuddy") {
+		t.Errorf("错误信息应说明当前支持 claude/codebuddy: %v", err)
+	}
+}
+
+func TestKeepAliveRejectsNegativeIdle(t *testing.T) {
+	kaEngineForTest(t)
+	_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--stream", "--idle", "-1s", "-p", "hi")
+	if err == nil {
+		t.Fatal("--idle 负值应报错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("应是 usageError, got %T: %v", err, err)
+	}
+}
+
+// 默认就是常驻：claude/codebuddy 的 --stream 调用不传 --keep-alive 也会开出追加入口。
+func TestKeepAliveIsDefaultForStreaming(t *testing.T) {
+	dir := shortSessionsDir(t)
+	t.Setenv(session.EnvDir, dir)
+	eng := kaEngineForTest(t)
+
+	done := make(chan error, 1)
+	go func() {
+		_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--stream", "--idle", "1s", "-p", "首轮")
+		done <- err
+	}()
+
+	var runID string
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) && runID == "" {
+		for _, rec := range mustListSessions(t, dir) {
+			if rec.Append != "" {
+				runID = rec.RunID
+			}
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	if runID == "" {
+		t.Fatal("默认（不传 --keep-alive）也该开出追加入口")
+	}
+	// 追加可用
+	if _, _, err := runAskCmd(t, "", "--append", runID, "-p", "默认模式下的追加"); err != nil {
+		t.Fatalf("--append: %v", err)
+	}
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("收尾报错: %v", err)
+		}
+	case <-time.After(20 * time.Second):
+		t.Fatal("没收工")
+	}
+	if got := eng.received(); len(got) != 1 || got[0] != "默认模式下的追加" {
+		t.Errorf("引擎收到的追加 = %v", got)
+	}
+}
+
+// --keep-alive=false 关掉常驻：不建 socket，turn 结束即退出（老行为）。
+func TestKeepAliveCanBeDisabled(t *testing.T) {
+	dir := shortSessionsDir(t)
+	t.Setenv(session.EnvDir, dir)
+	registerFake(&streamingEngine{name: "fake-ka-off", text: "ok"})
+
+	if _, _, err := runAskCmd(t, "", "-e", "fake-ka-off", "--stream", "--keep-alive=false", "hi"); err != nil {
+		t.Fatalf("ask: %v", err)
+	}
+	recs := mustListSessions(t, dir)
+	if len(recs) != 1 {
+		t.Fatalf("登记表条数 = %d", len(recs))
+	}
+	if recs[0].Append != "" {
+		t.Errorf("--keep-alive=false 不该开追加入口: %q", recs[0].Append)
+	}
+}
+
+// 非流式调用默认不常驻（否则普通提问会挂住等追加）。
+func TestKeepAliveNotAppliedToNonStream(t *testing.T) {
+	dir := shortSessionsDir(t)
+	t.Setenv(session.EnvDir, dir)
+	registerFake(&stringEngine{name: "fake-ka-nostream", text: "ok"})
+
+	if _, _, err := runAskCmd(t, "", "-e", "fake-ka-nostream", "hi"); err != nil {
+		t.Fatalf("ask: %v", err)
+	}
+	recs := mustListSessions(t, dir)
+	if len(recs) != 1 || recs[0].Append != "" {
+		t.Errorf("非流式调用不该开追加入口: %+v", recs)
+	}
+}
+
+// ── --append 错误路径 ────────────────────────────────────────
+
+func TestAppendRequiresIDAndText(t *testing.T) {
+	t.Setenv(session.EnvDir, shortSessionsDir(t))
+
+	_, _, err := runAskCmd(t, "", "--append", "")
+	if err == nil {
+		t.Fatal("空 id 应报错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("空 id 应是 usageError, got %T: %v", err, err)
+	}
+
+	_, _, err = runAskCmd(t, "", "--append", "some-id")
+	if err == nil {
+		t.Fatal("没有内容应报错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("空内容应是 usageError, got %T: %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "-p") {
+		t.Errorf("错误信息应说明怎么给内容: %v", err)
+	}
+}
+
+func TestAppendUnknownSession(t *testing.T) {
+	t.Setenv(session.EnvDir, shortSessionsDir(t))
+
+	_, _, err := runAskCmd(t, "", "--append", "no-such-session", "-p", "追加")
+	if err == nil {
+		t.Fatal("未知 id 应报错")
+	}
+	if _, ok := err.(*usageError); ok {
+		t.Errorf("未知 id 不是参数错（不该 exit 2）: %v", err)
+	}
+	if !strings.Contains(err.Error(), "no such session") {
+		t.Errorf("错误信息应点明找不到: %v", err)
+	}
+}
+
+// 普通（非常驻）会话不能追加 —— 错误要指出用 --keep-alive 启动、已结束用 --session 续接。
+func TestAppendToNonKeepAliveSession(t *testing.T) {
+	t.Setenv(session.EnvDir, shortSessionsDir(t))
+	registerFake(&stringEngine{name: "fake-ka-none", text: "ok"})
+
+	if _, _, err := runAskCmd(t, "", "-e", "fake-ka-none", "普通调用"); err != nil {
+		t.Fatalf("ask: %v", err)
+	}
+	rows := parseSessions(t, mustSessions(t))
+	if len(rows) != 1 {
+		t.Fatalf("登记表条数 = %d", len(rows))
+	}
+
+	_, _, err := runAskCmd(t, "", "--append", rows[0].RunID, "-p", "追加")
+	if err == nil {
+		t.Fatal("没有追加入口应报错")
+	}
+	if !strings.Contains(err.Error(), "--keep-alive") {
+		t.Errorf("错误信息应点明要用 --keep-alive 启动: %v", err)
+	}
+}
+
+// ── 端到端：常驻会话 + 追加 + 空闲收工 ────────────────────────
+
+func TestKeepAliveAppendEndToEnd(t *testing.T) {
+	dir := shortSessionsDir(t)
+	t.Setenv(session.EnvDir, dir)
+
+	eng := kaEngineForTest(t)
+
+	// ① 起常驻会话（后台跑，空闲 1s 自动收工）
+	done := make(chan error, 1)
+	go func() {
+		_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--stream", "--keep-alive",
+			"--idle", "1s", "-p", "首轮任务")
+		done <- err
+	}()
+
+	// ② 等登记表里出现追加入口
+	var runID string
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) {
+		for _, rec := range mustListSessions(t, dir) {
+			if rec.Append != "" && rec.State == session.StateRunning {
+				runID = rec.RunID
+			}
+		}
+		if runID != "" {
+			break
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	if runID == "" {
+		t.Fatal("常驻会话没在登记表里开出追加入口")
+	}
+
+	// ③ 追加一条（走真实的 unix socket 通道）
+	stdout, _, err := runAskCmd(t, "", "--append", runID, "-p", "追加：顺便跑一下测试")
+	if err != nil {
+		t.Fatalf("--append: %v", err)
+	}
+	var out struct {
+		Type   string `json:"type"`
+		Queued bool   `json:"queued"`
+		State  string `json:"state"`
+	}
+	if err := json.Unmarshal([]byte(strings.TrimSpace(stdout)), &out); err != nil {
+		t.Fatalf("--append 输出不是 JSON: %v (%s)", err, stdout)
+	}
+	if out.Type != "append" || !out.Queued {
+		t.Errorf("--append 结果不对: %+v", out)
+	}
+
+	// ④ 空闲 1s 后应自动收工（不需要 --stop）
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("常驻会话收尾报错: %v", err)
+		}
+	case <-time.After(20 * time.Second):
+		t.Fatal("空闲超时后常驻会话没收工")
+	}
+
+	// ⑤ 引擎确实收到了追加内容
+	if got := eng.received(); len(got) != 1 || got[0] != "追加：顺便跑一下测试" {
+		t.Errorf("引擎收到的追加 = %v", got)
+	}
+	// ⑥ 会话记录收尾为 done，socket 文件被清掉
+	recs := mustListSessions(t, dir)
+	if len(recs) != 1 {
+		t.Fatalf("登记表条数 = %d", len(recs))
+	}
+	if recs[0].State != session.StateDone {
+		t.Errorf("会话状态 = %q want done", recs[0].State)
+	}
+	if _, err := os.Stat(filepath.Join(dir, runID+".sock")); !os.IsNotExist(err) {
+		t.Errorf("收工后 socket 文件应被删掉: %v", err)
+	}
+}
+
+// mustListSessions 直接读登记表（比 --sessions 的 JSON 更直接，且能看到 append 字段）。
+func mustListSessions(t *testing.T, dir string) []session.Record {
+	t.Helper()
+	t.Setenv(session.EnvDir, dir)
+	recs, err := session.List()
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	return recs
+}
+
+// --engines 要暴露「能不能追加」这个能力（观物台据此决定是否提供追加入口）。
+func TestEnginesFlagCarriesAppendCapability(t *testing.T) {
+	kaEngineForTest(t)                        // codebuddy（支持）
+	registerFake(&stringEngine{name: "trae"}) // 不支持
+	registerFake(&stringEngine{name: "claude"})
+
+	stdout, _, err := runAskCmd(t, "", "--engines", "--no-models")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+	var rows []struct {
+		Engine string `json:"engine"`
+		Append bool   `json:"append"`
+	}
+	if err := json.Unmarshal([]byte(strings.TrimSpace(stdout)), &rows); err != nil {
+		t.Fatalf("解析 --engines 输出失败: %v (%s)", err, stdout)
+	}
+	got := map[string]bool{}
+	for _, r := range rows {
+		got[r.Engine] = r.Append
+	}
+	if !got["codebuddy"] {
+		t.Error("codebuddy 的 append 应为 true")
+	}
+	if got["trae"] {
+		t.Error("trae 的 append 应为 false")
+	}
+}

package/internal/cli/login.go

@@ -0,0 +1,78 @@
+package cli
+
+// login.go - `--login <engine>`：拉起某引擎自己的交互式登录会话。
+//
+// 为什么需要它：codebuddy / codebuddy-ai 跑的是**同一个 CLI 的两个账号**，
+// 登录时必须带上各自的账号环境（配置目录 + ACC_PRODUCT_CONFIG_V3 里的
+// authentication.id），否则登录结果会写进**另一个账号**的票据文件。
+// 这几个变量只有引擎自己知道（见 internal/agent/login.go 的 LoginRunner），
+// 所以这里只负责 exec 与 stdio 直通，不重复拼环境。
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+
+	"github.com/darren/magic-agent/internal/agent"
+	"github.com/spf13/cobra"
+)
+
+// runLogin 处理 `--login <engine>`。
+func runLogin(cmd *cobra.Command, opts *askOptions) error {
+	name := strings.TrimSpace(opts.login)
+	if name == "" {
+		return &usageError{fmt.Errorf("--login 需要引擎名：magic-agent --login <engine>（可用：%s）", loginCapableEngines())}
+	}
+	eng := agent.Lookup(name)
+	if eng == nil {
+		return &usageError{fmt.Errorf("未知引擎 %q；可用：%s", name, loginCapableEngines())}
+	}
+	lr, ok := eng.(agent.LoginRunner)
+	if !ok {
+		return &usageError{fmt.Errorf(
+			"引擎 %s 不需要 --login：它的登录态由自己的 CLI 管理，直接运行该 CLI 登录即可", eng.Name())}
+	}
+
+	bin, args, extraEnv, err := lr.LoginCommand()
+	if err != nil {
+		return err
+	}
+
+	// stdio 直通：交互式界面必须拿到真的 TTY。
+	c := exec.Command(bin, args...)
+	c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
+	c.Env = agent.ChildEnvWith(extraEnv)
+	if wd, werr := os.Getwd(); werr == nil {
+		c.Dir = wd
+	}
+
+	// 提示走 stderr：stdout 留给子进程的交互界面，不被污染。
+	fmt.Fprintf(cmd.ErrOrStderr(),
+		"magic-agent: 已按 %s 的账号环境启动 %s\n"+
+			"            在里面执行 /login 完成登录（退出后本命令结束）\n", eng.Name(), bin)
+
+	if runErr := c.Run(); runErr != nil {
+		var ee *exec.ExitError
+		if errors.As(runErr, &ee) {
+			return fmt.Errorf("%s 会话退出码 %d", eng.Name(), ee.ExitCode())
+		}
+		return fmt.Errorf("启动 %s 失败: %w", bin, runErr)
+	}
+	return nil
+}
+
+// loginCapableEngines 列出实现了 LoginRunner 的引擎名（报错提示用）。
+func loginCapableEngines() string {
+	var names []string
+	for _, e := range agent.Engines() {
+		if _, ok := e.(agent.LoginRunner); ok {
+			names = append(names, e.Name())
+		}
+	}
+	if len(names) == 0 {
+		return "(无)"
+	}
+	return strings.Join(names, " / ")
+}