magic-agent 2.1.5 → 2.3.0

package/internal/cli/suggest.go

@@ -0,0 +1,98 @@
+package cli
+
+// suggest.go - `--suggest-followups <file|->`：一轮结束后生成「用户下一句」的快捷回复。
+//
+// 为什么要单独一条 CLI（用户 2026-10-23：「在回复结束后 ai 自动生成下一轮的建议，
+// 点击即可发送」）：界面（移动端 / PC）不该自己拼提示词、自己调模型 —— 那样每端一份，
+// 同一轮回答在两处会给出不同建议。口径收进 core 之后只有一份（internal/suggest），
+// 客户端（magic-client 的 /desk/suggest）exec 这一条即可。
+//
+// 与 `--summarize-title` 同一套旁路调用：独立进程、新会话、ToolsOff，不续接当前对话，
+// 因此不会污染用户正在聊的那条上下文；也不写会话登记 / 日志（不经过 ask 主流程）。
+//
+// 退出码：
+//
+//	0  成功（哪怕建议为空数组 —— 「没有下一步」是合法结果，调用方不画按钮）
+//	1  引擎失败（不可用 / 超时 / 报错）
+//	2  参数错（请求 JSON 读不到 / 不合法 / 缺 reply）
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/darren/magic-agent/internal/suggest"
+)
+
+// runSuggestFollowups 读取请求 JSON → 调 suggest.Generate → 打印 JSON 结果。
+func runSuggestFollowups(cmd *cobra.Command, opts *askOptions) error {
+	body, err := readSuggestInput(cmd, opts.suggestInput)
+	if err != nil {
+		return &usageError{err}
+	}
+	/* 引擎：没显式传 -e 时用 llm（纯文本、无工具、没有 CLI 会话副作用，与 --title-engine 同口径）；
+	   传了就以调用方的为准 —— 移动端把当前引擎带下来，用户的机器上一定装过它。 */
+	engine := suggest.DefaultEngine
+	if flagChanged(cmd, "engine") {
+		engine = opts.engine
+	}
+	model := ""
+	if flagChanged(cmd, "model") {
+		model = opts.model
+	}
+	res, err := suggest.Generate(cmd.Context(), suggest.Request{
+		User:    body.User,
+		Reply:   body.Reply,
+		Engine:  engine,
+		Model:   model,
+		Timeout: suggest.DefaultTimeout,
+	})
+	if err != nil {
+		return fmt.Errorf("--suggest-followups: 生成失败: %w", err)
+	}
+	if res.Suggestions == nil {
+		res.Suggestions = []string{}
+	}
+	return printJSON(cmd.OutOrStdout(), res)
+}
+
+// readSuggestInput 读请求 JSON：`-` = stdin，其余按文件路径（支持 `@file` 写法）。
+// 上限 1MB：建议只该带「这一轮」的正文，超了说明调用方把整条会话塞进来了。
+func readSuggestInput(cmd *cobra.Command, spec string) (suggest.RequestBody, error) {
+	var body suggest.RequestBody
+	src := strings.TrimSpace(spec)
+	switch src {
+	case "":
+		return body, fmt.Errorf("--suggest-followups 需要请求 JSON：传文件路径或 \"-\"（stdin）")
+	case "-":
+		b, err := io.ReadAll(io.LimitReader(cmd.InOrStdin(), 1<<20))
+		if err != nil {
+			return body, fmt.Errorf("读 stdin 失败：%w", err)
+		}
+		if err := json.Unmarshal(b, &body); err != nil {
+			return body, fmt.Errorf("stdin 不是合法 JSON：%w", err)
+		}
+	default:
+		path := strings.TrimPrefix(src, "@")
+		if strings.HasPrefix(path, "~/") {
+			if home, herr := os.UserHomeDir(); herr == nil {
+				path = home + path[1:]
+			}
+		}
+		b, err := os.ReadFile(path)
+		if err != nil {
+			return body, fmt.Errorf("读请求文件失败：%w", err)
+		}
+		if err := json.Unmarshal(b, &body); err != nil {
+			return body, fmt.Errorf("请求文件不是合法 JSON：%w", err)
+		}
+	}
+	if strings.TrimSpace(body.Reply) == "" {
+		return body, fmt.Errorf(`请求 JSON 缺少 reply（本轮回答正文）：形如 {"user":"…","reply":"…"}`)
+	}
+	return body, nil
+}

package/internal/cli/suggest_test.go

@@ -0,0 +1,54 @@
+package cli
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/suggest"
+)
+
+// TestSuggestFollowupsJSON 走完整 CLI：读 stdin 的请求 JSON → 假引擎 → 输出建议。
+func TestSuggestFollowupsJSON(t *testing.T) {
+	registerFake(&stringEngine{
+		name: "fake-suggest-cli",
+		text: "这是建议：\n```json\n{\"suggestions\":[\"好的，执行吧\",\"先看一下 diff\"]}\n```",
+	})
+	body := `{"user":"改完了吗","reply":"要我继续吗？"}`
+	out, errOut, err := runAskCmd(t, body, "--suggest-followups", "-", "-e", "fake-suggest-cli")
+	if err != nil {
+		t.Fatalf("suggest: %v（stderr=%s）", err, errOut)
+	}
+	var res suggest.Result
+	if uerr := json.Unmarshal([]byte(out), &res); uerr != nil {
+		t.Fatalf("输出不是 JSON：%v\n%s", uerr, out)
+	}
+	if len(res.Suggestions) != 2 || res.Suggestions[0] != "好的，执行吧" {
+		t.Fatalf("Suggestions = %#v", res.Suggestions)
+	}
+	if res.Engine != "fake-suggest-cli" {
+		t.Fatalf("Engine = %q", res.Engine)
+	}
+}
+
+// TestSuggestFollowupsEmptyReply 没有 reply 是**参数错**，不能当成空建议静默成功。
+func TestSuggestFollowupsEmptyReply(t *testing.T) {
+	_, _, err := runAskCmd(t, `{"user":"只说了一句"}`, "--suggest-followups", "-", "-e", "fake-suggest-cli")
+	if err == nil {
+		t.Fatal("缺 reply 应报参数错")
+	}
+	if !strings.Contains(err.Error(), "reply") {
+		t.Fatalf("报错没说清缺什么：%v", err)
+	}
+}
+
+// TestSuggestFollowupsBadJSON 非法 JSON 也必须明确报错（exit 2 的语义）。
+func TestSuggestFollowupsBadJSON(t *testing.T) {
+	_, _, err := runAskCmd(t, `not json`, "--suggest-followups", "-", "-e", "fake-suggest-cli")
+	if err == nil {
+		t.Fatal("非法 JSON 应报参数错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Fatalf("应是 usageError（exit 2），实际 %T: %v", err, err)
+	}
+}

package/internal/cli/team.go

@@ -17,6 +17,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -98,7 +100,50 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	// 事件出口：--no-thinking 只压思考。
 	// 团队模式下主会话只出现任务列表快照（KindTasks）与汇总，子任务的过程事件
 	// 走各自子会话的日志（见 team_session.go），不再带 parent 转发进来。
-	emit := func(ev agent.StreamEvent) {
+	//
+	// ⚠️ 登记表的「还活着」靠这里续期（2026-10-22 报障：「团队模式子任务还在跑 主会话
+	// 就说结束了」）。流式路径（ask.go）对**每条事件**都写一次状态，团队路径此前只在
+	// 开跑前写一次 running —— 计划 + 子任务几分钟里 updated_at 一动不动，网关的尾随
+	// 连接（followStateEvery=5s）据 terminalSessionState 判「这一轮已结束」，画面落
+	// 红点收尾行，而子任务进程其实还在跑。团队模式没有 turn_end 可依，所以任何**主会话
+	// 自己发出的事件**（计划、任务列表快照、心跳、汇总）都当成一次「还在跑」。
+	// （h 在下面才建：闭包定义在这里不带值，第一次调用在 beginSession 之后。）
+	var emit func(agent.StreamEvent)
+
+	ctx := cmd.Context()
+	if !opts.keepAlive || flagChanged(cmd, "timeout") {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, opts.timeout)
+		defer cancel()
+	}
+	// --control 的打断：取消 ctx → 在跑的子任务进程组一起收。
+	var cancelAll context.CancelFunc
+	if opts.control {
+		ctx, cancelAll = context.WithCancel(ctx)
+		defer cancelAll()
+	}
+
+	h := beginSession(engine.Name(), req, opts.saveRegistry)
+	/* 团队模式**不挂** spawn hook：登记表里的 pid 必须一直是 magic-agent 自己。
+	   团队路径会多次 spawn 主引擎（计划 / 汇总 / 补充规划），hook 会把 pid 换成
+	   这些**短命**子进程的 pid；第一个（计划阶段）一退，normalizeDead 见 pid 不在
+	   就判整条主会话 gone —— 而此刻子任务正在跑。真机复现：24 分钟的一轮里主会话
+	   在第 32 秒就被判死，直到收尾才写回 done。
+	   子引擎进程不靠这条登记收：它们各有自己的子会话记录（openSubSession），
+	   异常退出时由 orphanSubs 按进程组收。 */
+	_ = withSessionHook
+	if h != nil {
+		// 开跑前就标上：计划阶段可能几十秒，这期间列表里已经能看到这条会话了。
+		h.SetMode(session.ModeTeam)
+		h.Mark(session.StateRunning)
+	}
+	emit = func(ev agent.StreamEvent) {
+		h.Mark(session.StateRunning)
+		/* 续期（2026-10-22 真机复现）：Mark 在新旧状态相同时**不写盘**，所以上面那一句
+		   对「已经 running」的会话等于空操作 —— updated_at 从第一条事件起就冻住了，
+		   网关尾随连接据此判终态，画面在子任务还在跑时就落「这一轮已结束」。
+		   Touch 才是真正的续期；5 秒节流对齐网关的 followStateEvery。 */
+		h.Touch(5 * time.Second)
 		if ev.Kind == agent.KindThinking && opts.noThinking {
 			return
 		}
@@ -136,27 +181,6 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 			})
 		}
 	}
-
-	ctx := cmd.Context()
-	if !opts.keepAlive || flagChanged(cmd, "timeout") {
-		var cancel context.CancelFunc
-		ctx, cancel = context.WithTimeout(ctx, opts.timeout)
-		defer cancel()
-	}
-	// --control 的打断：取消 ctx → 在跑的子任务进程组一起收。
-	var cancelAll context.CancelFunc
-	if opts.control {
-		ctx, cancelAll = context.WithCancel(ctx)
-		defer cancelAll()
-	}
-
-	h := beginSession(engine.Name(), req, opts.saveRegistry)
-	ctx = withSessionHook(ctx, h)
-	if h != nil {
-		// 开跑前就标上：计划阶段可能几十秒，这期间列表里已经能看到这条会话了。
-		h.SetMode(session.ModeTeam)
-		h.Mark(session.StateRunning)
-	}
 	if sessionLog != nil && h != nil {
 		sessionLog.setRunID(h.RunID())
 	}
@@ -180,6 +204,10 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	if h != nil {
 		runID = h.RunID()
 	}
+	/* 本次运行开出来的子会话（按 pid 收进程组用，见 orphanSubs）。
+	   写它的是跑子任务的 goroutine，读的是异常退出那一支 —— 加锁。 */
+	var mu sync.Mutex
+	var subs []*subSession
 	res, err := team.Run(ctx, team.Options{
 		Engine:            engine,
 		Model:             req.Model,
@@ -204,13 +232,48 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 		PlanOnly:          opts.teamPlanOnly,
 		Adaptive:          opts.teamAdaptive,
 		// 每个子任务 = 一条普通会话：登记记录 + 自己的日志，父指针挂在本会话下。
+		//
+		// 开出来的子会话都记进 subs：父进程异常退出时要按它们的 pid 收进程组
+		// （见下面的 orphan sweep），否则主会话没了、子引擎还在跑，列表里挂一条永远
+		// running 的子会话。
 		OpenSubSession: func(t team.Task, runDir, engine, model string) team.SubSession {
-			return openSubSession(h, opts.saveRegistry, opts.saveHistory, stderr, t, runDir, engine, model)
+			s := openSubSession(h, opts.saveRegistry, opts.saveHistory, stderr, t, runDir, engine, model)
+			if ss, ok := s.(*subSession); ok && ss != nil {
+				mu.Lock()
+				subs = append(subs, ss)
+				mu.Unlock()
+			}
+			return s
 		},
 		OnEvent: emit,
+		// 计划阶段不发事件的续期（见 team.Options.OnTick）。
+		OnTick: func() { h.Touch(0) },
 	})
+	mu.Lock()
+	running := append([]*subSession(nil), subs...)
+	mu.Unlock()
 	if err != nil {
-		finishSession(h, "", session.StateFailed)
+		/* 异常退出也要有**终态**（2026-10-22）：团队模式没有 turn_end 可依，父进程失败时
+		   一条终态事件都不发 —— 客户端只能看登记表，而登记表停在 running，网关按「还在跑」
+		   一直等（或按内核被杀归一成 gone）。这里补一条 turn_failed：走的是流式路径
+		   同一条收尾口径（turn_failed → 画面一行「本轮异常收尾」），调用方不必再猜。 */
+		interrupted := ctx.Err() != nil
+		reason := ""
+		if interrupted {
+			reason = "已中断（主进程被取消或被杀）"
+		} else {
+			reason = err.Error()
+		}
+		emit(agent.StreamEvent{Kind: agent.KindTurnFailed, Text: reason, Reason: reason})
+		state := session.StateFailed
+		if interrupted {
+			state = session.StateInterrupted
+		}
+		finishSession(h, "", state)
+		/* 子引擎是独立进程组（子会话上下文里挂的 SpawnHook 按组登记 pid）：
+		   父这一轮已经作废，把还在跑的一起收掉 —— 否则会话列表里永远挂着一条 running
+		   的子会话，用户点进去只看到半截过程，而且它会一直烧额度。 */
+		orphanSubs(running)
 		if format == agent.FormatJSON {
 			_ = sink.event(streamErrorPayload(engine.Name(), err))
 			_ = agent.WriteError(stderr, format, engine.Name(), 1, err)
@@ -253,6 +316,30 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	return nil
 }
 
+// orphanSubs 收掉还没落定的子会话对应的子引擎进程组。
+//
+// 只在团队这一轮**异常退出**时调：正常收尾时每个子会话都在 runTask 的 end() 里
+// Finish 过（进程已经自己退了）。这里兜的是「父进程这一轮作废、子引擎还在跑」那条路
+// —— 不收就是孤儿进程：它一边烧额度，一边让会话列表里那条子会话永远 running。
+//
+// 幂等：进程已经不在（PIDAlive=false）就只补登记表状态，不再发信号。
+func orphanSubs(list []*subSession) {
+	for _, s := range list {
+		if s == nil {
+			continue
+		}
+		rec := s.h.Record()
+		if rec.PID > 0 && agent.PIDAlive(rec.PID) {
+			_ = agent.KillPID(rec.PID, rec.KillGroup)
+		}
+		s.h.Finish(rec.SessionID, session.StateInterrupted)
+		if s.log != nil {
+			s.log.close()
+			s.log = nil
+		}
+	}
+}
+
 // agentRefs 把子任务结果按「类别 + 引擎 + 模型」归并成登记表里的 Agents。
 //
 // 为什么按类别归并而不是一个任务一条：登记表是列表页的数据源，一个 6 任务的团队会话

package/internal/client/service.go

@@ -221,6 +221,9 @@ func (s *Service) Handler() http.Handler {
 	// 按**绝对路径**读文本文件（Markdown / 日志 / 源码）：移动端产物卡「查看」在浮层里阅读。
 	mux.HandleFunc("/desk/path-read", s.guard(s.handlePathRead))
 	mux.HandleFunc("/desk/titles", s.guard(s.handleTitles))
+	// 下一轮快捷回复（2026-10-23）：一轮结束后生成 0-3 条「用户下一句」。
+	// 旁路调用 core 的 --suggest-followups（不续接会话），界面点击即发。
+	mux.HandleFunc("/desk/suggest", s.guard(s.handleSuggest))
 	// 移动端「环境配置」（引擎/模型/团队/空间选择）的远端存储：多客户端连同一台桌面时共用一份，
 	// 不再各存各的 localStorage（见 prefs.go）。
 	mux.HandleFunc("/desk/prefs", s.guard(s.handlePrefs))
@@ -1074,6 +1077,8 @@ func truncateForMsg(s string) string {
 // 2026-10-19：实现挪进 `session.Delete`（internal/session/delete.go）—— CLI 新增的
 // `--delete-session` 走的是同一份，两条路不再各写一遍（此前只有本接口能做真删除，
 // 于是桌面端只能在自己本地藏起来，出现「PC 删了、移动端还在」）。
+// 2026-10-23：`session.Delete` 会沿父指针级联删掉团队主会话下的子任务会话，
+// 本接口因此也一并生效（响应多一个只增字段 childSessionsRemoved）。
 func (s *Service) handleSessionDelete(w http.ResponseWriter, r *http.Request) {
 	id, action, ok := parseSessionPath(r.URL.Path)
 	if !ok || action != "" {
@@ -1085,7 +1090,12 @@ func (s *Service) handleSessionDelete(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, http.StatusBadRequest, fmt.Sprintf("删除会话 %s 失败：%v", id, err))
 		return
 	}
-	writeJSON(w, http.StatusOK, map[string]any{"id": res.ID, "recordsRemoved": res.RecordsRemoved})
+	// 子会话计数只增字段（旧客户端忽略）：告诉 UI「这次连子任务一起删了几条」。
+	writeJSON(w, http.StatusOK, map[string]any{
+		"id":                   res.ID,
+		"recordsRemoved":       res.RecordsRemoved,
+		"childSessionsRemoved": res.ChildSessionsRemoved,
+	})
 }
 
 // parseSessionPath 从 `/desk/session/{id}/{action}` 拆出 id 与 action，并做**路径安全校验**。

package/internal/client/suggest.go

@@ -0,0 +1,131 @@
+package client
+
+// suggest.go - `POST /desk/suggest`：生成「下一轮快捷回复」（一轮结束后可点的下一句）。
+//
+// 为什么放在插件而不是各端自己调模型（用户 2026-10-23：「在回复结束后 ai 自动生成
+// 下一轮的建议，点击即可发送」，先给了方案、选了「B. 模型生成」）：
+//  1. 提示词与解析口径只能有一份 —— 移动端 / PC 各写一份，同一轮回答会给出不同建议；
+//  2. 模型调用要落在桌面端（引擎 CLI、凭据、配额都在那台机器上），手机只拿结果；
+//  3. **不续接当前会话**：core 的 `--suggest-followups` 是一次独立旁路调用（ToolsOff、
+//     不带 SessionID），不会把「请生成建议」这类指令写进用户正在聊的上下文。
+//
+// 与 `/desk/session/{id}/title/summarize` 同一套做法：插件 exec core，不自己实现归纳/提炼。
+// 失败一律如实回错（502/504），界面侧静默不画按钮 —— 没有建议是合法结果，不拿模板凑。
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"os/exec"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"github.com/darren/magic-agent/internal/suggest"
+)
+
+const (
+	// suggestTimeout 单次生成的超时。界面侧 20s 就放弃（见 conversation.js），
+	// 这里留一点余量，避免「进程还没退、上下文已经被撤」的夹缝报错。
+	suggestTimeout = 25 * time.Second
+	// suggestMaxBody 请求体上限：只该带「这一轮」的问答，超了说明调用方塞了整条会话。
+	suggestMaxBody = 64 << 10
+	// suggestMaxUserRunes / suggestMaxReplyRunes 服务端兜底截断（core 还会再截一次）。
+	suggestMaxUserRunes  = 4000
+	suggestMaxReplyRunes = 16000
+)
+
+// suggestSlots 并发闸：建议是锦上添花，不能因为客户端重试/多开把引擎进程堆起来。
+// 2 = 允许「当前会话收尾」与「刚切过去的另一个会话」各一条，超出直接 429。
+var suggestSlots = make(chan struct{}, 2)
+
+// handleSuggest POST /desk/suggest。
+//
+// 请求：{"user":"用户上一句","reply":"本轮回答正文","engine":"可选","model":"可选"}
+// 响应：{"suggestions":["…", "…"], "engine":"llm", "elapsedMs":1234}
+func (s *Service) handleSuggest(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	var body struct {
+		User   string `json:"user"`
+		Reply  string `json:"reply"`
+		Engine string `json:"engine"`
+		Model  string `json:"model"`
+	}
+	if r.Body != nil {
+		if err := json.NewDecoder(io.LimitReader(r.Body, suggestMaxBody)).Decode(&body); err != nil {
+			writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+truncateForMsg(err.Error()))
+			return
+		}
+	}
+	body.Reply = strings.TrimSpace(body.Reply)
+	if body.Reply == "" {
+		writeErr(w, http.StatusBadRequest, `缺少 reply（本轮回答正文）：形如 {"user":"…","reply":"…"}`)
+		return
+	}
+	body.User = clipRunes(strings.TrimSpace(body.User), suggestMaxUserRunes)
+	body.Reply = clipRunes(body.Reply, suggestMaxReplyRunes)
+
+	select {
+	case suggestSlots <- struct{}{}:
+		defer func() { <-suggestSlots }()
+	default:
+		writeErr(w, http.StatusTooManyRequests, "建议生成太频繁：上一轮还没结束，请稍后")
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), suggestTimeout)
+	defer cancel()
+
+	payload, _ := json.Marshal(suggest.RequestBody{User: body.User, Reply: body.Reply})
+	args := []string{"--suggest-followups", "-"}
+	/* 引擎/模型由界面带（当前引擎一定装过）；不传则 core 用 llm（见 runSuggestFollowups）。 */
+	if e := strings.TrimSpace(body.Engine); e != "" {
+		args = append(args, "-e", e)
+	}
+	if m := strings.TrimSpace(body.Model); m != "" {
+		args = append(args, "-m", m)
+	}
+	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	cmd.Stdin = bytes.NewReader(payload)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		if ctx.Err() == context.DeadlineExceeded {
+			writeErr(w, http.StatusGatewayTimeout, "生成建议超时（>25s）：这一轮先不给建议")
+			return
+		}
+		msg := strings.TrimSpace(stderr.String())
+		if msg == "" {
+			msg = strings.TrimSpace(stdout.String())
+		}
+		if msg == "" {
+			msg = err.Error()
+		}
+		writeErr(w, http.StatusBadGateway, "生成建议失败："+truncateForMsg(msg))
+		return
+	}
+	var res suggest.Result
+	if err := json.Unmarshal(stdout.Bytes(), &res); err != nil {
+		// core 换了输出形状就如实报错，别静默回空（那会表现成「功能时灵时不灵」）。
+		writeErr(w, http.StatusBadGateway, "core 回的建议不是 JSON："+truncateForMsg(stdout.String()))
+		return
+	}
+	if res.Suggestions == nil {
+		res.Suggestions = []string{}
+	}
+	writeJSON(w, http.StatusOK, res)
+}
+
+// clipRunes 按 rune 截断（中文不能按字节切）。
+func clipRunes(s string, max int) string {
+	if max <= 0 || utf8.RuneCountInString(s) <= max {
+		return s
+	}
+	return string([]rune(s)[:max])
+}

package/internal/client/suggest_test.go

@@ -0,0 +1,116 @@
+package client
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// fakeSuggestCore 写一个假 core 脚本：记录 argv → 吃掉 stdin → 打印一份建议 JSON。
+func fakeSuggestCore(t *testing.T, dir, scriptBody string) (string, string) {
+	t.Helper()
+	argLog := filepath.Join(dir, "args.txt")
+	p := filepath.Join(dir, "magic-agent")
+	body := "#!/bin/sh\nprintf '%s' \"$*\" > " + argLog + "\ncat >/dev/null\n" + scriptBody + "\n"
+	if err := os.WriteFile(p, []byte(body), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return p, argLog
+}
+
+func TestSuggestEndpoint(t *testing.T) {
+	dir := t.TempDir()
+	core, argLog := fakeSuggestCore(t, dir, `printf '{"suggestions":["好的，执行吧","先看一下 diff"],"engine":"fake","elapsedMs":12}\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+
+	req := httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"改完了吗","reply":"都改完了，要我继续吗？","engine":"fake-engine","model":"fake-model"}`))
+	rec := httptest.NewRecorder()
+	s.handleSuggest(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("code = %d，body=%s", rec.Code, rec.Body.String())
+	}
+	var res struct {
+		Suggestions []string `json:"suggestions"`
+		Engine      string   `json:"engine"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &res); err != nil {
+		t.Fatalf("响应不是 JSON：%v", err)
+	}
+	if len(res.Suggestions) != 2 || res.Suggestions[0] != "好的，执行吧" {
+		t.Fatalf("suggestions = %#v", res.Suggestions)
+	}
+	args, _ := os.ReadFile(argLog)
+	if !strings.Contains(string(args), "--suggest-followups -") {
+		t.Fatalf("没走 --suggest-followups：%s", args)
+	}
+	if !strings.Contains(string(args), "-e fake-engine") || !strings.Contains(string(args), "-m fake-model") {
+		t.Fatalf("引擎/模型没透传：%s", args)
+	}
+}
+
+func TestSuggestEndpointBadRequests(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, `printf '{"suggestions":[]}\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+
+	cases := []struct {
+		name string
+		req  *http.Request
+		code int
+	}{
+		{"GET 不允许", httptest.NewRequest(http.MethodGet, "/desk/suggest", nil), http.StatusMethodNotAllowed},
+		{"缺 reply", httptest.NewRequest(http.MethodPost, "/desk/suggest", strings.NewReader(`{"user":"只说了半句"}`)), http.StatusBadRequest},
+		{"非法 JSON", httptest.NewRequest(http.MethodPost, "/desk/suggest", strings.NewReader(`nope`)), http.StatusBadRequest},
+	}
+	for _, c := range cases {
+		rec := httptest.NewRecorder()
+		s.handleSuggest(rec, c.req)
+		if rec.Code != c.code {
+			t.Errorf("%s：code = %d，期望 %d（body=%s）", c.name, rec.Code, c.code, rec.Body.String())
+		}
+	}
+}
+
+func TestSuggestEndpointCoreFailure(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, "echo 'llm CLI not found' >&2\nexit 3")
+	s := &Service{opts: Options{MagicAgent: core}}
+	rec := httptest.NewRecorder()
+	s.handleSuggest(rec, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"要我继续吗？"}`)))
+	if rec.Code != http.StatusBadGateway {
+		t.Fatalf("code = %d，期望 502", rec.Code)
+	}
+	if !strings.Contains(rec.Body.String(), "llm CLI not found") {
+		t.Fatalf("core 的失败原因没带回：%s", rec.Body.String())
+	}
+}
+
+func TestSuggestEndpointGarbageCoreOutput(t *testing.T) {
+	dir := t.TempDir()
+	core, _ := fakeSuggestCore(t, dir, `printf 'not json\n'`)
+	s := &Service{opts: Options{MagicAgent: core}}
+	rec := httptest.NewRecorder()
+	s.handleSuggest(rec, httptest.NewRequest(http.MethodPost, "/desk/suggest",
+		strings.NewReader(`{"user":"x","reply":"要我继续吗？"}`)))
+	if rec.Code != http.StatusBadGateway {
+		t.Fatalf("code = %d，期望 502", rec.Code)
+	}
+	if !strings.Contains(rec.Body.String(), "不是 JSON") {
+		t.Fatalf("应明确说 core 的输出不是 JSON：%s", rec.Body.String())
+	}
+}
+
+func TestClipRunes(t *testing.T) {
+	if got := clipRunes("一二三四五", 3); got != "一二三" {
+		t.Fatalf("clipRunes = %q", got)
+	}
+	if got := clipRunes("短", 10); got != "短" {
+		t.Fatalf("短文本不该变：%q", got)
+	}
+}