magic-agent 1.0.3 → 1.0.49

package/internal/cli/keepalive_test.go

@@ -92,7 +92,7 @@ func shortSessionsDir(t *testing.T) string {
 
 func TestKeepAliveRequiresStream(t *testing.T) {
 	kaEngineForTest(t)
-	_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--keep-alive", "-p", "hi")
+	_, _, err := runAskCmd(t, "", "--save-registry", "-e", "codebuddy", "--keep-alive", "-p", "hi")
 	if err == nil {
 		t.Fatal("--keep-alive 不配 --stream 应报错")
 	}
@@ -143,7 +143,7 @@ func TestKeepAliveIsDefaultForStreaming(t *testing.T) {
 
 	done := make(chan error, 1)
 	go func() {
-		_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--stream", "--idle", "1s", "-p", "首轮")
+		_, _, err := runAskCmd(t, "", "--save-registry", "-e", "codebuddy", "--stream", "--idle", "1s", "-p", "首轮")
 		done <- err
 	}()
 
@@ -183,7 +183,7 @@ func TestKeepAliveCanBeDisabled(t *testing.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 {
+	if _, _, err := runAskCmd(t, "", "--save-registry", "-e", "fake-ka-off", "--stream", "--keep-alive=false", "hi"); err != nil {
 		t.Fatalf("ask: %v", err)
 	}
 	recs := mustListSessions(t, dir)
@@ -201,7 +201,7 @@ func TestKeepAliveNotAppliedToNonStream(t *testing.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 {
+	if _, _, err := runAskCmd(t, "", "--save-registry", "-e", "fake-ka-nostream", "hi"); err != nil {
 		t.Fatalf("ask: %v", err)
 	}
 	recs := mustListSessions(t, dir)
@@ -255,7 +255,7 @@ 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 {
+	if _, _, err := runAskCmd(t, "", "--save-registry", "-e", "fake-ka-none", "普通调用"); err != nil {
 		t.Fatalf("ask: %v", err)
 	}
 	rows := parseSessions(t, mustSessions(t))
@@ -283,7 +283,7 @@ func TestKeepAliveAppendEndToEnd(t *testing.T) {
 	// ① 起常驻会话（后台跑，空闲 1s 自动收工）
 	done := make(chan error, 1)
 	go func() {
-		_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--stream", "--keep-alive",
+		_, _, err := runAskCmd(t, "", "--save-registry", "-e", "codebuddy", "--stream", "--keep-alive",
 			"--idle", "1s", "-p", "首轮任务")
 		done <- err
 	}()
@@ -350,6 +350,101 @@ func TestKeepAliveAppendEndToEnd(t *testing.T) {
 	}
 }
 
+// TestKeepAliveAppendWithoutRegistry 默认不留档（不开 --save-registry）时，
+// --append 仍要能用 —— 走的是「按约定找 socket」那条路（session.AppendSocketPath）。
+//
+// 为什么这一条重要：常驻会话对 claude/codebuddy 是**默认开**的，而登记表默认不落。
+// 若 --append 只认登记表，用户会撞上「默认能常驻、却追加不了」这个自相矛盾的行为。
+// 代价是这条路径只认 run_id（session_id 要靠记录映射，没有记录就无从查起）。
+func TestKeepAliveAppendWithoutRegistry(t *testing.T) {
+	dir := shortSessionsDir(t)
+	t.Setenv(session.EnvDir, dir)
+
+	eng := kaEngineForTest(t)
+
+	// ① 起常驻会话（**不开** --save-registry）
+	done := make(chan error, 1)
+	go func() {
+		_, _, err := runAskCmd(t, "", "-e", "codebuddy", "--stream", "--keep-alive",
+			"--idle", "5s", "-p", "首轮任务")
+		done <- err
+	}()
+
+	// ② 登记表里什么都没有（这正是前提），只能等 socket 文件出现
+	if recs := mustListSessions(t, dir); len(recs) != 0 {
+		t.Fatalf("默认不该有登记记录，实际 %+v", recs)
+	}
+	var runID string
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) && runID == "" {
+		ents, _ := os.ReadDir(dir)
+		for _, e := range ents {
+			if strings.HasSuffix(e.Name(), ".sock") {
+				runID = strings.TrimSuffix(e.Name(), ".sock")
+			}
+		}
+		if runID == "" {
+			time.Sleep(50 * time.Millisecond)
+		}
+	}
+	if runID == "" {
+		t.Fatal("常驻会话没开出追加入口 socket")
+	}
+	// 按约定推出来的路径必须与实际建出来的同一个（两端算法唯一的交叉点）
+	if got, want := session.AppendSocketPath(runID), filepath.Join(dir, runID+".sock"); got != want {
+		t.Fatalf("AppendSocketPath = %q want %q", got, want)
+	}
+
+	// ③ 按 run_id 追加（记录不存在的路径）
+	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"`
+	}
+	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)
+	}
+
+	// ④ 引擎确实收到了；收工后 socket 照旧清掉
+	if got := waitAppend(t, eng, "不留档也能追加", 10*time.Second); got != "不留档也能追加" {
+		t.Errorf("引擎收到的追加 = %q", got)
+	}
+	// ⑤ --stop 依赖登记表（pid 只存在那里），所以不留档的会话**停不掉** ——
+	// 这是「默认不留痕」的已知代价，明写出来免得当成 bug 报回来。
+	if _, _, err := runAskCmd(t, "", "--stop", runID); err == nil {
+		t.Error("--stop 对不留档的会话应当报「找不到」（它靠登记表寻址）")
+	}
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("常驻会话收尾报错: %v", err)
+		}
+	case <-time.After(20 * time.Second):
+		t.Fatal("常驻会话没收工")
+	}
+}
+
+// waitAppend 等引擎收到追加内容（追加是异步投递的，socket 收到 ≠ 引擎已读）。
+func waitAppend(t *testing.T, eng *kaEngine, want string, d time.Duration) string {
+	t.Helper()
+	deadline := time.Now().Add(d)
+	for time.Now().Before(deadline) {
+		for _, got := range eng.received() {
+			if got == want {
+				return got
+			}
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	return ""
+}
+
 // mustListSessions 直接读登记表（比 --sessions 的 JSON 更直接，且能看到 append 字段）。
 func mustListSessions(t *testing.T, dir string) []session.Record {
 	t.Helper()

package/internal/cli/permission_test.go

@@ -139,7 +139,11 @@ func TestEnginesReportsPermission(t *testing.T) {
 	if seen["codebuddy-ai"] != "flag:--permission-mode" {
 		t.Errorf("codebuddy-ai 的 permission 字段 = %q, want flag:--permission-mode", seen["codebuddy-ai"])
 	}
-	for _, e := range []string{"trae", "llm", "codex", "openclaw", "dsh", "arkclaw"} {
+	// dsh 的档位不走 flag，走子进程环境变量 —— 能力串是 env:<VAR>，客户端据此放行。
+	if seen["dsh"] != "env:DSH_PERMISSION_MODE" {
+		t.Errorf("dsh 的 permission 字段 = %q, want env:DSH_PERMISSION_MODE", seen["dsh"])
+	}
+	for _, e := range []string{"trae", "llm", "codex", "openclaw", "arkclaw"} {
 		if v, ok := seen[e]; !ok {
 			t.Errorf("--engines 缺 %s 行", e)
 		} else if v != "none" {

package/internal/cli/root.go

@@ -17,7 +17,7 @@ package cli
 //	-f, --file <path>        从文件读 prompt（- 读 stdin）
 //	-a, --attach <path>      附件（截图/图片），可重复/逗号分隔；与提示词一起发给引擎
 //	-w, --workspace <dir>    工作目录：在该目录里执行引擎（详见下方「工作目录」）
-//	-t, --timeout <dur>      单次尝试超时（如 3m；默认 600s）
+//	-t, --timeout <dur>      单次尝试超时（如 3m；默认 1h）
 //	-r, --retries <n>        失败重试次数（默认 0）
 //	    --backoff <dur>      首次重试退避（默认 2s，指数翻倍，上限 30s）
 //	-o, --output <format>    输出：json（默认）| text
@@ -34,10 +34,19 @@ package cli
 //	--engines            列出引擎、可用性与支持的模型（JSON 数组；--json 兼容保留）
 //	--no-models          配合 --engines：跳过模型探测（只列引擎，快）
 //	--stop <id>          停止指定会话/运行（session_id 或 run_id），杀掉它的引擎进程组
-//	--sessions           列出会话登记表（JSON 数组：run_id / session_id / pid / engine / state）
+//	--delete-session <id> 删除一条会话：登记记录 + 事件历史 + 标题覆盖一起删，**全机生效**
+//	                     （各端读同一份登记表，一端删了处处都看不到）。幂等
+//	--sessions           列出会话登记表（JSON 数组：run_id / session_id / pid / engine /
+//	                     source / client / state；全机视图，不按 client 过滤）。
+//	                     ⚠️ 只见过**已存档**的会话（--save-registry，默认关）
+//	--save-registry      把会话登记落盘（<run_id>.json），让 --sessions / --stop 事后能按 id
+//	                     寻址。**默认关**：不留痕；不留档的会话停不掉
 //	--keep-alive         常驻会话（claude/codebuddy 默认开，dsh 需显式传；需配合 --stream）：
 //	                     首轮结束后不退出、等 --append 追加；--keep-alive=false 关闭
 //	--append <id>        向常驻会话追加一条消息（内容用 -p/位置参数给）
+//	--session-log <id>   读一段会话的事件历史（--after <seq> 可增量续读）
+//	--save-history       把流式会话的事件落盘存档（<session_id>.jsonl，供 --session-log
+//	                     与客户端回放历史）。**默认关**：一次性调用不留痕
 //	--idle <dur>         常驻会话空闲收工时长（默认 5m；0 = 本轮结束就收工）
 //	-v, --verbose            重试过程打到 stderr
 //
@@ -64,6 +73,7 @@ import (
 	"os"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -179,8 +189,9 @@ llm 引擎（包装 simonw/LLM CLI，模型/密钥由它自管）：
     codex     codex debug models
     openclaw  openclaw models list --json
     arkclaw   无清单（模型由网关按 claw_id 绑定）→ 输出 models_note 说明
-    dsh       $DSH_HOME/settings.yaml 里已配置的模型（llm-pi-ai.providers.<route>.models，
-              输出 route/model）；headless 无 --model，换模型要改该文件
+    dsh       配置文件里已配置的模型（0.1.7+ 读 profile 的 cordis.patch.yml，
+              更早读 $DSH_HOME/settings.yaml；输出 route/model）；
+              headless 无 --model，换模型要改配置
   探测会真的启动这些 CLI 的只读子命令（最慢 openclaw ~2.5s），故并发执行、
   单引擎上限 30s；拿不到清单不报错，原因写进该行的 models_note。
   --no-models 整段跳过探测（只列引擎与可用性，不启动任何 CLI）。
@@ -232,19 +243,20 @@ dsh 引擎（DeepSeek Harness，本机 dsh CLI）：
   说明：
     · 模型：SDK 通道下 -m 生效（转成 initialize 的 provider/model，取 route/model 形态，
       可用值见 --engines 的 models 字段）；回退 headless 后 -m 不生效（无 --model 参数），
-      模型由 dsh 自己的配置决定（$DSH_HOME/settings.yaml 的 agent-default-model 段 +
-      llm-pi-ai.providers，密钥放 $DSH_HOME/.credentials.yaml 或 .env），此时会打一行告警。
-    · 工具调用只在 SDK 通道上有：headless 的 stdout/stderr 里都没有工具事件（官方定位就是
-      「推理走 stderr、正文走 stdout、然后退出」）→ 要工具事件请确保走 SDK 通道。
-    · --stream：SDK 通道下推理 → thinking、正文 → 逐 step text、工具 → tool_use/tool_result、
-      收尾一条 turn_end；回退 headless 后只流推理（stderr 的 "dsh: reasoning:" 增量），
-      正文在 turn 结束时一次性给出。
-    · 多轮上下文：用**常驻会话**（SDK 通道下同一进程内对同一会话继续 prompt，官方推荐的续接方式）：
-        magic-agent -e dsh --stream --keep-alive "记住 42"        # 首轮（dsh 的常驻默认关，要显式传）
-        magic-agent --append <run_id|session_id> -p "刚才那个数是多少"  # 追问，上下文接得上
-      不支持按 id 续接（-s/--session）：headless 每次调用都是全新会话；SDK 的 sessionId
-      只在**同一个 runtime 进程内**可续，换进程拿旧 id 会被 -32603 "session already exists"
-      拒掉（协议只有 initialize / session/prompt / shutdown，没有 resume 方法）。
+      模型由 dsh 自己的配置决定（0.1.7+ 在 $DSH_HOME/profiles/<profile>/cordis.patch.yml
+      的 llm-pi-ai.providers + agent-default-model，更早在 $DSH_HOME/settings.yaml；
+      密钥放 $DSH_HOME/.credentials.yaml 或 .env），此时会打一行告警。
+    · 工具调用与流式：SDK 通道（普通轮）与 headless + --json（续接轮 / 回退）都能上报
+      thinking / text / tool_use / tool_result；老版 dsh（headless 没有 --json）只能流
+      stderr 的 "dsh: reasoning:" 推理增量、正文收尾一次给出，**没有工具事件**。
+    · 多轮上下文（三种，按需选）：
+        magic-agent -e dsh -s <session_id> -p "追问"               # 真续接：dsh 自己恢复上下文
+        magic-agent -e dsh --stream --keep-alive "记住 42"         # 常驻会话首轮（同进程内续接）
+        magic-agent --append <run_id|session_id> -p "刚才那个数"    # 往常驻会话追加
+      -s/--session <id> 走 headless 的 --session-id：会话由 dsh 持久化在
+      $DSH_HOME/sessions/<cwd>/，上下文由 dsh 自己接回来（SDK 通道没有 resume 方法，
+      所以续接轮由 headless + --json 承载）。⚠️ 会话按**工作区**分桶：换了 -w 就找不到
+      那条会话，dsh 会明确报 does not exist。
     · --permission 未接线（dsh 的权限预设是配置层概念，无法表达四档里的「沙箱关闭」档）。
     · --tools 由 dsh 自己的工具循环决定（无命令行级逐工具开关），传入即忽略。
     · --json-schema 支持（走与 llm/openclaw 相同的输出后处理抽 JSON）。
@@ -324,7 +336,7 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
   追加进来的轮次照常以事件流输出（每轮收尾发一个 turn_end 事件，便于调用方知道「这轮完了」）。
   收工：最后一轮结束后 --idle（默认 5m）内没人追加 → 优雅退出；--idle 0 = 本轮结束就收工
   （追加窗口只在任务运行期间）；也可随时 --stop。
-  常驻生效期间不套 -t 默认超时（长任务+追加不受 600s 限制），显式给 -t 才套。
+  常驻生效期间不套 -t 默认超时（长任务+追加不受 1h 限制），显式给 -t 才套。
   不生效的形态会自动忽略（非 --stream 调用、不支持追加的引擎）；显式传 --keep-alive 却
   不满足条件则明确报错（exit 2）。Windows 无 unix socket，暂不支持。
   注意：常驻进程会在最后一轮结束后继续存活 --idle 那么久 —— 调用方若要「一轮完成」
@@ -333,7 +345,8 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
   --stream 调用以为命令卡住了；要开就显式 --keep-alive。
 
 停止指定会话（--stop / --sessions）：
-  每次调用都会往会话登记表落一条记录（~/.magic-agent/sessions/<run_id>.json，MAGIC_AGENT_SESSIONS 可改目录），
+  开了 --save-registry 时，每次调用都会往会话登记表落一条记录
+  （~/.magic-agent/sessions/<run_id>.json，MAGIC_AGENT_SESSIONS 可改目录），
   里面记着**引擎子进程的 pid** 与引擎/模型/工作目录/会话 id。为什么需要它：
     · 引擎 CLI 在独立进程组里跑（Setpgid），调用方 kill 掉 magic-agent 的进程组**带不走它**；
     · 进程句柄只活在调用方内存里，应用重启后之前 detach 出去的会话就再也停不掉。
@@ -344,6 +357,34 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
   行为：先 SIGTERM，2s 内不退再 SIGKILL（连它的 node worker 一起带走），然后回写 state=stopped。
   幂等：进程已不在 / 会话已结束 → stopped=false + reason，退出码仍是 0；id 不存在 → 退出码 1（多半写错了）。
   另：magic-agent 自己收到 SIGINT/SIGTERM 时也会先带走自己的引擎子进程再退出，不留孤儿。
+  ⚠️ **默认不落盘**（用户 2026-10-12：「会话登记也不需要」）：不带 --save-registry 时上面这些
+     命令看不见本次调用 —— 默认不留痕是有意的（手工跑一轮 / CI / 脚本编排事后没人寻址）。
+     代价：不留档的会话**停不掉**（pid 只存在记录里），--append 也只能按 run_id 走约定路径。
+
+删除会话（--delete-session <session_id|run_id>）：
+  登记记录 + 事件日志（<id>.jsonl）+ 标题覆盖一起删掉，**全机生效**：
+  各端（PC 的 --sessions、移动端 H5 的 /desk/sessions）读的都是同一份登记表，
+  一端删了处处都看不到。与插件的 DELETE /desk/session/{id} 是同一份实现
+  （internal/session/delete.go），两条路可互换。
+    magic-agent --delete-session <session_id>      # 删掉这条会话（含历史）
+  幂等：id 不认识 / 文件本来就不在 → 退出码 0，JSON 里 records_removed=0。
+  ⚠️ 是**物理删除**：删完历史就回放不了了。客户端把它当成「删除」的唯一实现，
+     只在本地藏起来（记墓碑）的话，别的客户端照样列着（2026-10-19 用户报的
+     「从pc端删除的会话移动端还在显示」就是这么来的）。
+
+会话历史存档（--save-history，默认关）：
+  会话的**内容**（每条事件）另存一份 ~/.magic-agent/sessions/<session_id>.jsonl，
+  --session-log / 客户端「看历史」读的就是它；只有 --stream 才写。**默认不写**：
+  没人会回看，写下来却会一直堆在磁盘上（登记表有 24h 保留期在清，jsonl 没有）。
+    magic-agent -e claude --stream -p "跑一遍测试"                    # 不存档（默认）
+    magic-agent -e claude --stream --save-history -p "跑一遍测试"      # 存档，事后可 --session-log 回看
+    magic-agent --session-log <session_id|run_id>                     # 读存档（没存档就是空数组）
+  ⚠️ 没存档的会话在客户端列表里 has_log=false —— 能看到、能续接，但点开没有历史内容。
+  magic-client 恒传 --save-registry 与 --save-history（客户端本来就要列会话 + 回放历史），
+  所以界面里的会话既在列表里、也有历史。
+  ⚠️ **不等终点事件就落盘**（2026-10-15）：一开跑就按 <run_id>.jsonl 写，引擎的
+  session_id 到手后改名为 <session_id>.jsonl（读侧两个名字都认）——
+  于是「正在跑的会话」在别的客户端里当场可读，引擎整轮不给 id 的形态也不白开存档。
 
 附件（-a/--attach：文件＋提示词，比如截图加提示词）：
   每个引擎尽量用**自己的原生方式**收附件，能力见 --engines 的 attachments 字段：
@@ -355,7 +396,8 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
     arkclaw    part:file          A2A 原生 file part（base64 inline；远端看不到本机路径）
     trae       prompt             无原生通道 → 把**绝对路径**写进提示词（需要 --tools 非 off）
     openclaw   prompt             同上
-    dsh        prompt             同上（headless 无附件参数；dsh 自己的工具能读文件）
+    dsh        sdk:content-blocks SDK 通道把图片作为原生 image 块发出（base64 inline，
+                                  真进模型上下文）；非图片附件 / headless 回退 → 路径写进提示词
     codebuddy-gateway
                prompt             走 payload.attachments 原生字段，但网关把它渲染成路径清单
                                   塞进 prompt（图不会以图片形式进模型上下文）
@@ -409,14 +451,29 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 				// 与 --stop 同理：用「传过没有」判断，`--session-log ""` 要走参数校验（报要 id），
 				// 而不是掉进下面的「提问」分支报 empty prompt。
 				return runSessionLog(cmd, opts)
+			case flagChanged(cmd, "summarize-title"):
+				// 同上：空 id 走参数校验，不要掉进「提问」分支。
+				return runSummarizeTitle(cmd, opts)
+			case flagChanged(cmd, "session-title"):
+				return runSessionTitle(cmd, opts)
+			case flagChanged(cmd, "title-force"):
+				// --title-force 只在 --summarize-title 下成立：单给它必然是调用方误解了
+				// （想要「强制重新归纳」却没给 id）。明说，不静默忽略。
+				return &usageError{fmt.Errorf("--title-force 只在 --summarize-title 下成立：请配合 --summarize-title <id> 使用")}
 			case flagChanged(cmd, "after"):
 				// --after 只在 --session-log 下成立：给了却没给 --session-log 就**明说**，
 				// 不静默忽略（静默忽略是本项目反复踩的坑）。
 				return &usageError{fmt.Errorf("--after 只在 --session-log 下成立：请配合 --session-log <id> 使用")}
+			case flagChanged(cmd, "before"), flagChanged(cmd, "limit"):
+				// 同上：--before / --limit 是 --session-log 的翻页参数，单给必然是误解。
+				return &usageError{fmt.Errorf("--before / --limit 只在 --session-log 下成立：请配合 --session-log <id> 使用")}
 			case flagChanged(cmd, "stop"):
 				// 用「传过没有」而不是「值非空」判断：`--stop ""` 也要走参数校验
 				//（exit 2 提示要 id），而不是掉进「提问」分支报 empty prompt。
 				return runStop(cmd, opts)
+			case flagChanged(cmd, "delete-session"):
+				// 同上：空 id 走参数校验（`--delete-session ""` 不该被当成提问）。
+				return runDeleteSession(cmd, opts)
 			case flagChanged(cmd, "append"):
 				return runAppend(cmd, args, opts)
 			case opts.contract:
@@ -430,6 +487,11 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 		},
 	}
 	bindAskFlags(root, opts)
+	/* 唯一的子命令：`client start|stop|status`。
+	   为什么破例留一个子命令：它管的是**另一个常驻进程**（magic-client），
+	   生命周期与 core 的一次性调用完全不同，硬塞成一排 --client-* flags 会让
+	   「这些 flag 和提问无关」这件事看不出来（用户 2026-10-20：「提供启动停止 client 的子命令」）。 */
+	root.AddCommand(clientSubcommand())
 	/* `--login` / `--repair-models` 忘带引擎名时，cobra 在解析阶段就报错，**走不到**
 	   runLogin / runRepairModels 的校验分支，默认文案是英文的
 	   "flag needs an argument: ..."（且退出码 1）。这里翻成与传空串一致的中文
@@ -540,6 +602,12 @@ func rejectRemovedSubcommands(cmd *cobra.Command, args []string) error {
 
 // exitCodeOf 从错误推断退出码。
 func exitCodeOf(err error) int {
+	// 转发型子命令（`client`）自带退出码：2 = 参数错这种约定要原样带给调用方，
+	// 否则脚本拿到一律为 1 就分不出「用错了」和「跑失败了」。
+	var ec *exitCodeError
+	if errors.As(err, &ec) && ec.code > 0 {
+		return ec.code
+	}
 	if _, ok := err.(*usageError); ok {
 		return exitUsage
 	}
@@ -560,6 +628,67 @@ var probeEngineCredits = func(ctx context.Context, l agent.ModelCreditLister) ma
 	return l.ModelCredits(ctx)
 }
 
+// modelListCacheTTL 模型清单 / 积分倍率探测结果的缓存有效期（30 分钟）。
+//
+// 模型清单来自 CLI 只读子命令或本地缓存文件，30 分钟内几乎不会变；缓存让重复跑
+// --engines / --contract 不必每次重新启动 CLI 进程或重读文件。瞬时失败（CLI 没装 /
+// 探测超时）与空清单**不进缓存**，避免把错误钉死 30 分钟 —— 只有真正拿到模型清单
+// 才落缓存。缓存是进程级的：单次 magic-agent 进程只会探测一次，跨进程的重复调用
+// （如客户端反复拉 --contract）也能省掉 CLI 启动开销。
+const modelListCacheTTL = 30 * time.Minute
+
+// modelListCacheEntry 一条缓存：模型清单 + 积分倍率 + 过期时间。
+type modelListCacheEntry struct {
+	models    []string
+	credits   map[string]string
+	expiresAt time.Time
+}
+
+var (
+	modelListCacheMu sync.Mutex
+	modelListCache   = map[string]*modelListCacheEntry{}
+)
+
+// cachedModelList 带 30 分钟缓存地探测某引擎的模型清单与积分倍率。
+//
+// key 一般用引擎名（codebuddy / codebuddy-ai / trae …）；命中且未过期的缓存直接返回，
+// 不触碰 CLI / 文件。底层走 probeEngineModels / probeEngineCredits（可被测试替换）。
+// ListModels 出错或返回空清单时**不缓存**（视为瞬时态，下次重探）。
+func cachedModelList(ctx context.Context, key string, l agent.ModelLister) (models []string, credits map[string]string, note string) {
+	modelListCacheMu.Lock()
+	if it, ok := modelListCache[key]; ok && time.Now().Before(it.expiresAt) {
+		modelListCacheMu.Unlock()
+		return it.models, it.credits, ""
+	}
+	modelListCacheMu.Unlock()
+
+	models, err := probeEngineModels(ctx, l)
+	if err != nil {
+		return nil, nil, err.Error()
+	}
+	if len(models) == 0 {
+		return nil, nil, "no models reported"
+	}
+	if cl, ok := l.(agent.ModelCreditLister); ok {
+		credits = probeEngineCredits(ctx, cl)
+	}
+	modelListCacheMu.Lock()
+	modelListCache[key] = &modelListCacheEntry{
+		models:    models,
+		credits:   credits,
+		expiresAt: time.Now().Add(modelListCacheTTL),
+	}
+	modelListCacheMu.Unlock()
+	return models, credits, ""
+}
+
+// clearModelListCache 清空模型清单缓存（测试用，避免用例之间互相命中缓存）。
+func clearModelListCache() {
+	modelListCacheMu.Lock()
+	modelListCache = map[string]*modelListCacheEntry{}
+	modelListCacheMu.Unlock()
+}
+
 // flagChanged 报告某个 flag 是否被显式传过（用于「传了就走这条分支」的开关型参数）。
 func flagChanged(cmd *cobra.Command, name string) bool {
 	f := cmd.Flags().Lookup(name)
@@ -666,8 +795,10 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 		//   stdin:stream-json claude / codebuddy 原生 stream-json input（图片走 content block）
 		//   flag:-a           llm CLI 原生 --attachment（直连模型走 image_url content parts）
 		//   part:file         arkclaw 走 A2A 原生 file part（base64 inline）
+		//   sdk:content-blocks dsh 的 SDK 通道把图片作为原生 image content block 发出去
+		//                     （base64 inline，真进模型上下文）；显式切 headless 后为 prompt
 		//   prompt            无原生通道：把绝对路径写进提示词，靠引擎读文件
-		//                     （trae/openclaw/dsh/codebuddy-gateway）
+		//                     （trae/openclaw/codebuddy-gateway）
 		Attachments string `json:"attachments,omitempty"`
 		// Append 是否支持「常驻会话 + 追加消息」（`--stream --keep-alive` 与 `--append`）。
 		// claude / codebuddy 为 true（stream-json 输入可持续喂 user 消息）；
@@ -686,6 +817,12 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 		//                            且网关会把远程任务的权限强制切到 bypassPermissions）
 		// 调用方据此决定是否下发 --permission 与那几个沙箱/规则类 flags。
 		Permission string `json:"permission,omitempty"`
+		// Reasoning 该引擎是否接受 `--reasoning <档>`（machine-readable，见
+		// agent.ReasoningSupportOf）：claude / codebuddy / codebuddy-ai / codex 为 true；
+		// 其余引擎未接线 —— core 对它们**静默忽略**该 flag（不报错、不下传）。
+		// 新增（2026-10-20，只增字段不升 contractVersion）：老版 CLI 没有这个字段，
+		// 客户端据此判断「能不能安全下发 --reasoning」（缺失 = 不下发，避免 exit 2）。
+		Reasoning bool `json:"reasoning"`
 		// Capabilities 该引擎**静态声明**的能力 id 集合（字典序，稳定、无重复）。
 		// 与运行态分开：ok / streaming / models / version 说的是「此刻如何」，
 		// capabilities 说的是「能做什么」，二者的推导见 internal/agent/capability.go。
@@ -707,7 +844,8 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 			Attachments: agent.AttachmentSupportOf(e.Name()),
 			Append:      agent.AppendSupportOf(e.Name()),
 			Ask:         agent.AskSupportOf(e.Name()),
-			Permission:  agent.PermissionSupportOf(e.Name())}
+			Permission:  agent.PermissionSupportOf(e.Name()),
+			Reasoning:   agent.ReasoningSupportOf(e.Name())}
 		if ok {
 			r.Bin, r.Note = note, ""
 		}
@@ -738,26 +876,30 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 			continue
 		}
 		wg.Add(1)
-		go func(i int, l agent.ModelLister) {
+		go func(i int, name string, l agent.ModelLister) {
 			defer wg.Done()
 			ctx, cancel := context.WithTimeout(cmd.Context(), agent.DefaultModelProbeTimeout)
 			defer cancel()
-			models, err := probeEngineModels(ctx, lister)
+			models, credits, note := cachedModelList(ctx, name, l)
+			// codebuddy 系：展示时剥掉自定义模型 id 的 "custom-local:" 前缀（噪点）；
+			// -m 实际传值时由引擎按裸名补回前缀（见 codebuddyCore.modelArg），
+			// 自定义模型依旧可用。
+			if name == "codebuddy" || name == "codebuddy-ai" {
+				models = agent.StripCustomLocalPrefix(models)
+				credits = agent.StripCustomLocalPrefixCredits(credits)
+			}
 			switch {
-			case err != nil:
-				// 失败不致命：原因进 models_note，models 留空。
-				rows[i].ModelsNote = err.Error()
+			case note != "":
+				rows[i].ModelsNote = note
 			case len(models) == 0:
 				rows[i].ModelsNote = "no models reported"
 			default:
 				rows[i].Models = models
-				// 积分倍率与 models 同链同源（同一批缓存文件），探测失败/缺省
-				// 不致命：该字段整体省略（omitempty），不影响 models。
-				if cl, ok := l.(agent.ModelCreditLister); ok {
-					rows[i].ModelCredits = probeEngineCredits(ctx, cl)
+				if credits != nil {
+					rows[i].ModelCredits = credits
 				}
 			}
-		}(i, lister)
+		}(i, e.Name(), lister)
 	}
 	wg.Wait()
 	if !envelope {