magic-agent 2.4.3 → 2.6.3

package/internal/agent/dsh.go

@@ -84,6 +84,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 )
@@ -170,16 +171,17 @@ func (e *DshEngine) Detect() (bool, string) {
 // 什么的东西」—— 网关列出的上百个模型并不都能用，只有配置里声明过的才会被路由接受。
 // 故**配置层才是权威**，也顺带避免了每次探测都发网络请求 + 需要解密凭据。
 //
-// 配置位置随 dsh 版本变过（见 dshConfigDocs）：0.1.7 起是各 profile 的
-// cordis.patch.yml，之前是 $DSH_HOME/settings.yaml。两处都读、取并集 ——
+// 配置位置随 dsh 版本变过（见 dshConfigDocs）：0.1.7 起是 cordis.patch.yml
+// （profile 级，0.2.1 起也会写在 home 级 $DSH_HOME/cordis.patch.yml），之前是
+// $DSH_HOME/settings.yaml。各处都读、取并集 ——
 // 前者是 SDK 通道，后者是 headless 回退通道，magic-agent 两条都会用到。
 //
 // 输出形态 `provider/model`（与 openclaw 的 `provider/model` 同构）：dsh 的模型只在
 // 所属路由内有意义，同名模型可能出现在两条路由上，裸 id 会歧义。
 //
-// 这份清单**就是** `-m` 的可取值 —— 但只在 SDK 通道下生效（转成 initialize 的
-// provider/model 两个必填参数，见 dshResolveRoute）。回退 headless 后 `-m` 无作用
-// （无 --model 参数），引擎会打一行告警说明该改配置层。
+// 这份清单**就是** `-m` 的可取值：SDK 通道转成 initialize 的 provider/model
+// （见 dshResolveRoute）；headless 通道没有 --model，改由每轮临时 `--patch` 覆盖配置层的
+// agent-default-model（见 dshHeadlessPatchFor）—— 两条通道都能按 -m 换模型。
 func (e *DshEngine) ListModels(_ context.Context) ([]string, error) {
 	docs := dshConfigDocs()
 	var models []string
@@ -202,7 +204,7 @@ func (e *DshEngine) ListModels(_ context.Context) ([]string, error) {
 		tried = strings.Join(paths, "、")
 	}
 	return nil, fmt.Errorf("%w: 没有读到已配置的模型；找过 %s。"+
-		"dsh 0.1.7 起 provider 声明在 profile 的 cordis.patch.yml（可用 dsh 的「设置 → 模型」写入），"+
+		"dsh 0.1.7 起 provider 声明在 cordis.patch.yml（profile 级或 home 级，可用 dsh 的「设置 → 模型」写入），"+
 		"更早的版本在 settings.yaml 的 llm-pi-ai.providers.<id>.models 段",
 		ErrNoModelSource, tried)
 }
@@ -343,27 +345,24 @@ func dshNativeImageMIME(mime string) bool {
 // 形态：`dsh --profile headless [--session-id <id>] "<prompt>"`，stdout 即最终正文。
 // --session-id 是 dsh 自己的续接入口（见 dsh_resume.go），只在续接轮带上。
 func (e *DshEngine) completeHeadless(ctx context.Context, req Request, bin, sessionID, prompt string, start time.Time) (Response, error) {
-	// headless 没有 --model 参数：-m 在这里「不生效」，告警一次（与 arkclaw 一致），
-	// 让用户知道该去改 dsh 自己的配置。显式 Profile: "headless" 也走这里，同样告警。
-	// ⚠️ **续接轮不告警**：那种轮的模型由那条会话自己决定，-m 本来就不该有作用
-	//（客户端每轮都会带 -m，不区分的话每次追问都会刷一行无意义的告警）。
-	if req.Model != "" && sessionID == "" {
-		fmt.Fprintf(stderr, "  ⚠ dsh: headless 通道下 --model %s 不生效（无 --model 参数）；"+
-			"换模型请改 $DSH_HOME/settings.yaml 的 agent-default-model 段，或用 dsh 的 Settings → Models\n", req.Model)
-	}
+	// headless 没有 --model 参数：-m 只能经 `--patch` 覆盖配置层的 agent-default-model
+	//（见 dshHeadlessPatchFor）。拿不到 --patch 才退回「配置默认模型」，并告警一次。
+	patchPath, cleanup := dshHeadlessPatchFor(ctx, bin, req.Model)
+	defer cleanup()
 
-	args := dshHeadlessArgs(e.profile(), sessionID, prompt, false)
+	promptArg, stdinText := dshHeadlessPromptArg(prompt)
+	args := dshHeadlessArgs(e.profile(), sessionID, patchPath, promptArg, false)
 
 	// workspace：dsh 的「调用时所在目录即默认 workspace 根」正是子进程 cwd 的语义。
 	// 档位同 SDK 通道：走 DSH_PERMISSION_MODE（dsh 没有逐调用的权限 flag）。
-	stdout, stderrText, runErr := runCLIEnvIn(ctx, req.Workspace, dshPermissionEnv(req.Permission), bin, args...)
+	stdout, stderrText, runErr := runCLIEnvInStdin(ctx, req.Workspace, dshPermissionEnv(req.Permission), stdinText, bin, args...)
 
 	resp := Response{
 		Engine: e.Name(),
 		// headless 的 stdout 就是最终助手正文（推理增量走 stderr，不混入）。
 		Text: strings.TrimSpace(stdout),
-		// 模型名尽力而为：读 dsh 配置里的默认模型（读不到给 "config-default"）。
-		Model:   dshHeadlessModel(req, sessionID),
+		// 模型标签：本轮真的用哪个（有 -m 且 patch 生效 → -m；否则配置默认）。
+		Model:   dshHeadlessModelLabel(req, patchPath),
 		Latency: time.Since(start),
 	}
 	if resp.Model == "" {
@@ -386,18 +385,19 @@ func (e *DshEngine) completeHeadless(ctx context.Context, req Request, bin, sess
 	return resp, nil
 }
 
-// dshHeadlessModel headless 轮次对外报的模型标签。
+// dshHeadlessModelLabel headless 轮次对外报的模型标签（= 本轮真正用的那个）。
 //
-//	普通 headless 轮：读 $DSH_HOME 配置里的 agent-default-model（读不到返回空串，
-//	                  调用方回落 "config-default"）—— 这轮真的用它。
-//	续接轮：        dsh 不回会话的模型，而配置层默认值**很可能不是**这条会话的模型
-//	                （实测：会话是 modelverse/… 建的，配置默认是 deepseek-v4-flash）。
-//	                调用方每轮都会带同一个 -m（客户端 1 任务 = 1 会话 = 1 模型），
-//	                所以拿它当**最佳近似**比报配置默认值更接近事实。
-func dshHeadlessModel(req Request, sessionID string) string {
-	if sessionID != "" {
-		if m := strings.TrimSpace(req.Model); m != "" {
-			return m
+//	patch 生效（有 -m 且 dsh 支持 --patch）→ 就是 -m 解析出的 `provider/model`
+//	没有 -m                              → 读 $DSH_HOME 的 agent-default-model
+//	                                       （读不到返回空串，调用方回落 "config-default"）
+//
+// 旧实现里续接轮直接回 `req.Model` 当「最佳近似」，但实际跑的是配置默认模型 ——
+// 2026-10-25 用户报障就是被这个假标签误导（界面写 volcengine/…，真实是 minimax/…）。
+// 现在模型真的经 --patch 落到配置层，标签才跟事实一致。
+func dshHeadlessModelLabel(req Request, patchPath string) string {
+	if patchPath != "" {
+		if p, m := dshResolveRoute(req.Model); p != "" && m != "" {
+			return p + "/" + m
 		}
 	}
 	return DshConfiguredModel()
@@ -405,17 +405,26 @@ func dshHeadlessModel(req Request, sessionID string) string {
 
 // dshHeadlessArgs 构造 headless 的参数：**启动器 flag 在前，app 参数在后**。
 //
-//	["--profile", <profile>] [+ "--session-id", <id>] [+ "--json"] + ["<prompt>"]
+//	[--patch <file>] ["--profile", <profile>] [+ "--session-id", <id>] [+ "--json"] + ["<prompt>"]
+//
+// ⚠️ 三类 flag 的归属不同（顺序不能错）：
+//   - `--patch` 是**启动器 flag**（LauncherOptions），必须在 --profile **之前** —— 放在
+//     后面会被 headless 当成未知 app 参数（实测 `dsh --profile headless --patch` → unknown option）。
+//   - --session-id / --json 是 **headless 自己的 flag**，排在 --profile 之后、任务文本之前。
+//   - 启动器在第一个它不认识的 token 处结束解析，剩下的全交给 app。
 //
-// ⚠️ --session-id / --json 是 **headless 自己的 flag**（不是启动器 flag，见 dsh --help），
-// 必须排在 --profile 之后、任务文本之前 —— 启动器在第一个它不认识的 token 处结束解析。
-// prompt 走位置参数（headless 唯一的 app 参数，无 --prompt / stdin 通道），
-// 超长 prompt 会撞 ARG_MAX：需要喂超长文本时先落成文件，让 dsh 用读文件工具看。
+// prompt 默认走位置参数（headless 唯一的 app 参数，无 --prompt）。Windows 上改走 stdin
+// 的 `-`（见 dshHeadlessPromptArg）；位置参数形态下超长 prompt 会撞 ARG_MAX：需要喂超长
+// 文本时先落成文件，让 dsh 用读文件工具看。
 //
 // ⚠️ 只有 headless 用得到它：SDK 通道的 prompt 走 session/prompt 的 contentBlocks
 // （见 dsh_sdk.go），既不占命令行也不受 ARG_MAX 限制。
-func dshHeadlessArgs(profile, sessionID, prompt string, jsonEvents bool) []string {
-	args := []string{"--profile", profile}
+func dshHeadlessArgs(profile, sessionID, patchPath, prompt string, jsonEvents bool) []string {
+	args := make([]string, 0, 8)
+	if patchPath != "" {
+		args = append(args, "--patch", patchPath)
+	}
+	args = append(args, "--profile", profile)
 	if sessionID != "" {
 		args = append(args, "--session-id", sessionID)
 	}
@@ -425,6 +434,67 @@ func dshHeadlessArgs(profile, sessionID, prompt string, jsonEvents bool) []strin
 	return append(args, prompt)
 }
 
+// dshHeadlessPromptArg 决定 headless 的提示词怎么进 dsh：位置参数，还是 stdin（"-"）。
+//
+// Windows 上必须走 stdin：dsh 在 PATH 上解析到 npm 的 `dsh.cmd`，launchWrap 会以
+// `powershell -Command "& 'dsh.cmd' …"` 启动，参数还要再过一层 cmd.exe 的 `%*` 重解析 ——
+// **多行位置参数会被整段丢掉**（2026-10-25 实测：单行正常，带换行的提示词模型收到的是空消息）。
+// dsh 的 headless 原生支持 `-` 读 stdin（help 原文：task `-` reads stdin），走 stdin 既绕开
+// cmd 解析层，也顺带避开 ARG_MAX。unix 无此问题，保持原来的位置参数形态。
+func dshHeadlessPromptArg(prompt string) (arg, stdinText string) {
+	if platformIsWindows() {
+		return "-", prompt
+	}
+	return prompt, ""
+}
+
+// dshHeadlessPatchFor 把本轮 `-m` 落成一份临时 `--patch`（只覆盖 agent-default-model）。
+//
+// 为什么需要：headless 通道**没有 --model**（`dsh --profile headless --help` 只有
+// --json / --session-id），模型只由配置层 agent-default-model 决定；而续接轮又**必须**
+// 走 headless（SDK 没有 resume，见 dsh_resume.go）。2026-10-25 用户报障就是这条缝：
+// 界面选 volcengine/deepseek-v4.1-flash-1017，续接轮实际跑配置默认的 minimax/MiniMax-M3.1-Flash，
+// 报的是 MiniMax 的「Token Plan 用量上限」，看上去像模型选错了。
+//
+// 顶层启动器支持 `dsh --patch <path>`（profile 之上再叠一层），所以每轮按 -m 写一份临时
+// patch，进程结束后删掉 —— 模型选择在续接轮 / 回退轮同样生效。
+//
+// 返回 (路径, 清理函数)；没有 -m / 拆不出 provider/model / dsh 不认 --patch 时返回 "",
+// 此时沿用配置默认模型并告警一次（旧行为，但不再谎报模型）。
+func dshHeadlessPatchFor(ctx context.Context, bin, reqModel string) (string, func()) {
+	model := strings.TrimSpace(reqModel)
+	if model == "" {
+		return "", func() {}
+	}
+	if !dshHeadlessCapabilities(ctx, bin).Patch {
+		fmt.Fprintf(stderr, "  ⚠ dsh: 这台 dsh 不认 --patch，headless 通道无法按 -m %s 换模型"+
+			"（实跑配置默认模型）；请升级 dsh，或改 $DSH_HOME 的 agent-default-model\n", model)
+		return "", func() {}
+	}
+	provider, id := dshResolveRoute(model)
+	if provider == "" || id == "" {
+		fmt.Fprintf(stderr, "  ⚠ dsh: 无法从 -m %s 拆出 provider/model，本轮沿用配置默认模型\n", model)
+		return "", func() {}
+	}
+	f, err := os.CreateTemp("", "magic-agent-dsh-model-*.yml")
+	if err != nil {
+		fmt.Fprintf(stderr, "  ⚠ dsh: 写临时 patch 失败（%v），本轮沿用配置默认模型\n", err)
+		return "", func() {}
+	}
+	// YAML 双引号标量 = JSON 字符串，用 strconv.Quote 免得模型 id 里的特殊字符破坏结构。
+	content := "- id: agent-default-model\n  config:\n    provider: " + strconv.Quote(provider) +
+		"\n    model: " + strconv.Quote(id) + "\n"
+	_, werr := f.WriteString(content)
+	cerr := f.Close()
+	if werr != nil || cerr != nil {
+		_ = os.Remove(f.Name())
+		fmt.Fprintf(stderr, "  ⚠ dsh: 写临时 patch 失败（%v），本轮沿用配置默认模型\n", errors.Join(werr, cerr))
+		return "", func() {}
+	}
+	path := f.Name()
+	return path, func() { _ = os.Remove(path) }
+}
+
 // ── 流式（--stream）────────────────────────────────────────────
 //
 // dsh 的流式形态与通道有关，如实接线：
@@ -532,14 +602,12 @@ func (e *DshEngine) Stream(ctx context.Context, req Request, onEvent func(Stream
 // 有 --json 时按事件流逐条上报（推理 / 正文 / 工具调用，能力与 SDK 通道同构）；
 // 老版本没有 --json 就退回「stderr 推理增量 + stdout 收尾正文」，工具调用拿不到 —— 如实说明。
 func (e *DshEngine) streamHeadless(ctx context.Context, req Request, bin, sessionID, prompt string, onEvent func(StreamEvent), start time.Time) (StreamResult, error) {
-	// 同 completeHeadless：headless 没有 --model；续接轮的模型由会话决定，不告警。
-	if req.Model != "" && sessionID == "" {
-		fmt.Fprintf(stderr, "  ⚠ dsh: headless 通道下 --model %s 不生效（无 --model 参数）；"+
-			"换模型请改 $DSH_HOME/settings.yaml 的 agent-default-model 段，或用 dsh 的 Settings → Models\n", req.Model)
-	}
-
+	// 同 completeHeadless：-m 经 --patch 覆盖配置层（headless 没有 --model）。
 	caps := dshHeadlessCapabilities(ctx, bin)
-	args := dshHeadlessArgs(e.profile(), sessionID, prompt, caps.JSON)
+	patchPath, cleanup := dshHeadlessPatchFor(ctx, bin, req.Model)
+	defer cleanup()
+	promptArg, stdinText := dshHeadlessPromptArg(prompt)
+	args := dshHeadlessArgs(e.profile(), sessionID, patchPath, promptArg, caps.JSON)
 
 	emit := func(ev StreamEvent) {
 		if onEvent != nil {
@@ -607,11 +675,11 @@ func (e *DshEngine) streamHeadless(ctx context.Context, req Request, bin, sessio
 		runErr             error
 	)
 	if caps.JSON {
-		stdout, stderrText, runErr = runStreamLinesIn(ctx, req.Workspace, dshPermissionEnv(req.Permission), bin, args, true, onLine)
+		stdout, stderrText, runErr = runStreamLinesInStdin(ctx, req.Workspace, dshPermissionEnv(req.Permission), stdinText, bin, args, true, onLine)
 	} else {
 		// 老版本：推理增量在 stderr（"dsh: reasoning:" 起头），正文在 stdout 收尾时一次给出。
 		inReasoning := false
-		stdout, stderrText, runErr = runStreamLinesIn(ctx, req.Workspace, dshPermissionEnv(req.Permission), bin, args, false, func(line string) error {
+		stdout, stderrText, runErr = runStreamLinesInStdin(ctx, req.Workspace, dshPermissionEnv(req.Permission), stdinText, bin, args, false, func(line string) error {
 			// 标题行本身不是内容；它出现即进入推理区段。
 			if strings.HasPrefix(line, dshReasoningPrefix) {
 				inReasoning = true
@@ -650,7 +718,7 @@ func (e *DshEngine) streamHeadless(ctx context.Context, req Request, bin, sessio
 	resp := Response{
 		Engine:    e.Name(),
 		Text:      text,
-		Model:     dshHeadlessModel(req, sessionID),
+		Model:     dshHeadlessModelLabel(req, patchPath),
 		SessionID: sid,
 		Latency:   time.Since(start),
 	}
@@ -711,6 +779,9 @@ func DshHome() string {
 //	≤ 0.1.6   $DSH_HOME/settings.yaml（顶层段 agent-default-model / llm-pi-ai）
 //	≥ 0.1.7   各 profile 的 $DSH_HOME/profiles/<name>/cordis.patch.yml
 //	          （settings 体系重构后，providers 由「设置 → 模型」页面写进这份 patch）
+//	≥ 0.2.1   也会写在 home 级 $DSH_HOME/cordis.patch.yml（对所有 profile 生效；
+//	          2026-10-23 实测 0.2.1-rc.2 重写配置后 profile 级 patch 清成空 [],
+//	          provider 只剩 home 级这一份 —— 不读它就整条链空手而归）
 //
 // ⚠️ 0.1.7 首次启动会把旧的 settings.yaml 改名为 settings.yaml.imported
 //（官方 dsh-settings：改名先于首次写入，被组合拒绝的 section 只留在改名后的文件里）。
@@ -740,7 +811,8 @@ func (d dshConfigDoc) legacyText() string {
 //	   （MAGIC_AGENT_DSH_PROFILE 可改；headless 回退通道见 ②）
 //	② headless profile 的 cordis.patch.yml —— SDK 不可用时的回退通道，
 //	   列模型时不能漏（两条通道 magic-agent 都会用到）
-//	③ $DSH_HOME/settings.yaml —— 0.1.7 之前的位置，兼容未升级的装机
+//	③ $DSH_HOME/cordis.patch.yml —— home 级 patch，对所有 profile 生效
+//	④ $DSH_HOME/settings.yaml —— 0.1.7 之前的位置，兼容未升级的装机
 func dshConfigDocs() []dshConfigDoc {
 	home := DshHome()
 	if home == "" {
@@ -750,12 +822,14 @@ func dshConfigDocs() []dshConfigDoc {
 	if names[0] != dshDefaultProfile {
 		names = append(names, dshDefaultProfile)
 	}
-	docs := make([]dshConfigDoc, 0, len(names)+1)
+	docs := make([]dshConfigDoc, 0, len(names)+2)
 	for _, name := range names {
 		p := filepath.Join(home, "profiles", name, "cordis.patch.yml")
 		docs = append(docs, dshConfigDoc{Path: p, Patch: true, Text: readFileOrEmpty(p)})
 	}
-	p := filepath.Join(home, "settings.yaml")
+	p := filepath.Join(home, "cordis.patch.yml")
+	docs = append(docs, dshConfigDoc{Path: p, Patch: true, Text: readFileOrEmpty(p)})
+	p = filepath.Join(home, "settings.yaml")
 	return append(docs, dshConfigDoc{Path: p, Text: readFileOrEmpty(p)})
 }
 

package/internal/agent/dsh_caps_cache_test.go

@@ -0,0 +1,184 @@
+package agent
+
+// dsh_caps_cache_test.go - dsh 能力探测的**磁盘**缓存（2026-10-26）。
+//
+// 为什么单测必须钉住这件事：dshCapsCache 是进程内 sync.Map，而 magic-agent
+// 每轮 ask 都是新进程 —— 没有磁盘那层，「一进程一次」实际是「一轮一次」，
+// 每轮续接白等 7~9 秒（实测 dsh 0.2.0-rc.2 的 --profile headless --help）。
+// 这类「看着有缓存、其实每轮都在重探」的回归用眼睛看不出来，只能靠计数。
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// fakeDshCapsBin 造一个假 dsh：把每次被调用的参数记进 calls 文件，并回 help 文本。
+//
+// helpPatch=false 模拟老版本（顶层 --help 里没有 --patch）。
+func fakeDshCapsBin(t *testing.T, helpPatch bool) (bin, callsPath string) {
+	t.Helper()
+	dir := t.TempDir()
+	bin = filepath.Join(dir, "dsh")
+	callsPath = filepath.Join(dir, "calls.txt")
+	patchLine := ""
+	if helpPatch {
+		patchLine = `echo "  --patch <path>   apply a patch file"`
+	}
+	script := `#!/bin/sh
+echo "$@" >> ` + callsPath + `
+case "$1" in
+  --help)
+    echo "Usage: dsh [--profile <name>] [--patch <path>] <prompt>"
+    ` + patchLine + `
+    ;;
+  --profile)
+    echo "Usage: dsh-headless [--session-id <id>] [--json] <prompt>"
+    ;;
+esac
+exit 0
+`
+	if err := os.WriteFile(bin, []byte(script), 0o755); err != nil {
+		t.Fatalf("write fake dsh: %v", err)
+	}
+	return bin, callsPath
+}
+
+// countCalls 读假 dsh 被调用的次数。
+func countCalls(t *testing.T, callsPath string) int {
+	t.Helper()
+	b, err := os.ReadFile(callsPath)
+	if err != nil {
+		return 0
+	}
+	return len(strings.Split(strings.TrimSpace(string(b)), "\n"))
+}
+
+// resetDshCapsCache 清掉进程内缓存（每个用例都从「冷进程」起）。
+func resetDshCapsCache() {
+	dshCapsCache = sync.Map{}
+}
+
+// TestDshCapsDiskCacheAvoidsSecondProbe 第二轮（新进程语义）不该再起子进程。
+//
+// 这是本改动的**核心断言**：把进程内缓存清掉再问一次，如果还是去起进程，
+// 说明磁盘那层没生效 —— 用户侧表现就是每轮续接多等 7~9 秒。
+func TestDshCapsDiskCacheAvoidsSecondProbe(t *testing.T) {
+	cachePath := filepath.Join(t.TempDir(), "dsh-caps.json")
+	t.Setenv("MAGIC_AGENT_DSH_CAPS_CACHE", cachePath)
+
+	bin, callsPath := fakeDshCapsBin(t, true)
+	resetDshCapsCache()
+
+	ctx := context.Background()
+	first := dshHeadlessCapabilities(ctx, bin)
+	if got := countCalls(t, callsPath); got != 2 {
+		t.Fatalf("首轮应探测 2 次（headless help + 顶层 help），实际 %d 次", got)
+	}
+	if !first.SessionID || !first.JSON || !first.Patch {
+		t.Fatalf("首轮 caps = %+v，期望三项都为 true", first)
+	}
+
+	// 模拟「下一个 core 进程」：进程内缓存全清，只剩磁盘。
+	resetDshCapsCache()
+	second := dshHeadlessCapabilities(ctx, bin)
+	if got := countCalls(t, callsPath); got != 2 {
+		t.Errorf("第二轮不该再起子进程，调用次数仍是 %d（磁盘缓存没命中）", got)
+	}
+	if second != first {
+		t.Errorf("磁盘缓存读回 %+v，与首次探测 %+v 不一致", second, first)
+	}
+}
+
+// TestDshCapsDiskCacheInvalidatedByBinChange dsh 换了二进制（指纹变）就必须重探。
+//
+// 反过来的风险更严重：升级 dsh 后还拿老结论，续接会被判成「不支持 --session-id」
+// 而直接报错，或者更糟 —— 静默按老形态拼参数。
+func TestDshCapsDiskCacheInvalidatedByBinChange(t *testing.T) {
+	cachePath := filepath.Join(t.TempDir(), "dsh-caps.json")
+	t.Setenv("MAGIC_AGENT_DSH_CAPS_CACHE", cachePath)
+
+	// 第一版：顶层 --help 里有 --patch。
+	bin, callsPath := fakeDshCapsBin(t, true)
+	resetDshCapsCache()
+	if !dshHeadlessCapabilities(context.Background(), bin).Patch {
+		t.Fatal("第一版应探测到 --patch")
+	}
+
+	// 换内容并确保 mtime 确实变化（同一纳秒内重写会让指纹看不出差别）。
+	time.Sleep(20 * time.Millisecond)
+	if err := os.WriteFile(bin, []byte(`#!/bin/sh
+echo "$@" >> `+callsPath+`
+case "$1" in
+  --help) echo "Usage: dsh [--profile <name>] <prompt>" ;;
+  --profile) echo "Usage: dsh-headless [--session-id <id>] [--json] <prompt>" ;;
+esac
+exit 0
+`), 0o755); err != nil {
+		t.Fatalf("rewrite fake dsh: %v", err)
+	}
+	before := countCalls(t, callsPath)
+	resetDshCapsCache()
+
+	caps := dshHeadlessCapabilities(context.Background(), bin)
+	if countCalls(t, callsPath) == before {
+		t.Error("二进制变了却没重探（指纹判据失效）")
+	}
+	if caps.Patch {
+		t.Error("新版本没有 --patch，重探后不该还是 true")
+	}
+	if !caps.SessionID || !caps.JSON {
+		t.Errorf("caps = %+v，--session-id / --json 应仍为 true", caps)
+	}
+}
+
+// TestDshCapsCanceledProbeNotCached 探测被取消时不落盘。
+//
+// 为什么值得一条用例：探测中途超时只拿到半截输出，按「探测不到不等于不支持」
+// 的约定会保留乐观默认值。那本来是对的 —— 但**不能把它写进磁盘**，否则
+// 一次抖动会让后续每一轮都跳过真正的探测。
+func TestDshCapsCanceledProbeNotCached(t *testing.T) {
+	cachePath := filepath.Join(t.TempDir(), "dsh-caps.json")
+	t.Setenv("MAGIC_AGENT_DSH_CAPS_CACHE", cachePath)
+
+	dir := t.TempDir()
+	bin := filepath.Join(dir, "dsh-slow")
+	// 故意慢：探测的 ctx 已经取消了，这个脚本还在睡。
+	if err := os.WriteFile(bin, []byte("#!/bin/sh\nsleep 5\nexit 0\n"), 0o755); err != nil {
+		t.Fatalf("write slow fake dsh: %v", err)
+	}
+	resetDshCapsCache()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // 进函数时就是取消态
+	_ = dshHeadlessCapabilities(ctx, bin)
+
+	if b, err := os.ReadFile(cachePath); err == nil && len(b) > 0 {
+		t.Errorf("取消态下不该落盘，却写入了：%s", string(b))
+	}
+}
+
+// TestDshBinFingerprintChangesWithSize 指纹同时看 mtime 和大小。
+func TestDshBinFingerprintChangesWithSize(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "f")
+	if err := os.WriteFile(p, []byte("a"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	fp1 := dshBinFingerprint(p)
+	if fp1 == "" {
+		t.Fatal("指纹为空")
+	}
+	if err := os.WriteFile(p, []byte("abcdef"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if fp2 := dshBinFingerprint(p); fp2 == fp1 {
+		t.Error("文件大小变了，指纹却没变")
+	}
+	if got := dshBinFingerprint(filepath.Join(t.TempDir(), "missing")); got != "" {
+		t.Errorf("不存在的文件指纹应为空，得到 %q", got)
+	}
+}

package/internal/agent/dsh_resume.go

@@ -155,28 +155,164 @@ func dshSessionDir() string {
 
 // ── 能力探测：这台 dsh 的 headless 认不认 --session-id / --json ──
 
-// dshHeadlessCaps headless 支持的两个 flag。
+// dshHeadlessCaps headless 支持的两个 flag（外加顶层启动器的 --patch）。
 type dshHeadlessCaps struct {
 	SessionID bool // --session-id（0.1.7+ 才有；没有就当不了真续接）
 	JSON      bool // --json（事件流；没有就走旧版 stderr 推理增量）
+	// Patch 顶层启动器的 `--patch <path>`（在 profile 之上再叠一层配置）。
+	// headless 没有 --model，续接轮要按 -m 换模型只能靠它（见 dshHeadlessModelPatch）。
+	Patch bool
 }
 
-var dshCapsCache sync.Map // bin → dshHeadlessCaps
+var dshCapsCache sync.Map // 缓存 key → dshHeadlessCaps
 
-// dshHeadlessCapabilities 探测这台 dsh 支持哪些 headless flag（按 bin 路径缓存）。
+// dshCapsCachePath 能力探测结果的**磁盘**缓存（2026-10-26）。
+//
+// 为什么必须有磁盘这一层：dshCapsCache 是进程内的 sync.Map，而 magic-agent 每次
+// ask 都是**新进程**（客户端 spawn 一个 core 跑一轮）。于是「一进程一次」实际是
+// 「一轮一次」—— 每轮续接都要重跑两条 --help。
+//
+// 实测代价（2026-10-26，dsh 0.2.0-rc.2）：
+//
+//	dsh --profile headless --help   7.09s / 9.01s / 7.66s（本机环境变量齐全时）
+//	                               1.31s（干净 env）
+//	dsh --help                      0.28s
+//
+// 也就是说**每一轮续接白等 7~9 秒**，而且这段是在 turn/start 之前，用户看到的就是
+// 「发出去半天没动静」。本机实测一轮的 7.09s 空窗与此**完全吻合**。
+//
+// 缓存失效判据是 dsh 二进制的指纹（mtime + size）：升级/替换 dsh 后指纹变，自动重探。
+// 不用 `--version` 取版本号当 key —— 那要额外起一次进程（0.3s），而 stat 是零成本，
+// 且「换了二进制」正是唯一需要重探的时机。
+func dshCapsCachePath() string {
+	if p := strings.TrimSpace(os.Getenv("MAGIC_AGENT_DSH_CAPS_CACHE")); p != "" {
+		return p
+	}
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".magic-agent", "dsh-caps.json")
+}
+
+// dshBinFingerprint dsh 二进制的身份（mtime 纳秒 + 大小）。取不到 → 空串（不缓存）。
+func dshBinFingerprint(bin string) string {
+	st, err := os.Stat(bin)
+	if err != nil || st.IsDir() {
+		return ""
+	}
+	return fmt.Sprintf("%d-%d", st.ModTime().UnixNano(), st.Size())
+}
+
+// dshCapsDiskEntry 磁盘缓存的一条记录。
+type dshCapsDiskEntry struct {
+	Bin         string `json:"bin"`
+	Fingerprint string `json:"fingerprint"`
+	SessionID   bool   `json:"sessionId"`
+	JSON        bool   `json:"json"`
+	Patch       bool   `json:"patch"`
+	ProbedAt    string `json:"probedAt,omitempty"`
+}
+
+// dshCapsDiskFile 磁盘缓存文件（按 bin 路径分条，多份 dsh 并存也各自有效）。
+type dshCapsDiskFile struct {
+	Version int                         `json:"version"`
+	Entries map[string]dshCapsDiskEntry `json:"entries"`
+}
+
+func dshLoadCapsFromDisk(bin, fp string) (dshHeadlessCaps, bool) {
+	path := dshCapsCachePath()
+	if path == "" || fp == "" {
+		return dshHeadlessCaps{}, false
+	}
+	b, err := os.ReadFile(path)
+	if err != nil || len(b) == 0 {
+		return dshHeadlessCaps{}, false
+	}
+	var f dshCapsDiskFile
+	if err := json.Unmarshal(b, &f); err != nil {
+		return dshHeadlessCaps{}, false
+	}
+	e, ok := f.Entries[bin]
+	if !ok || e.Fingerprint != fp {
+		return dshHeadlessCaps{}, false
+	}
+	return dshHeadlessCaps{SessionID: e.SessionID, JSON: e.JSON, Patch: e.Patch}, true
+}
+
+// dshStoreCapsToDisk 写回一条。失败静默 —— 缓存只是提速手段，写不动不能让调用失败。
+func dshStoreCapsToDisk(bin, fp string, caps dshHeadlessCaps) {
+	path := dshCapsCachePath()
+	if path == "" || fp == "" {
+		return
+	}
+	var f dshCapsDiskFile
+	if b, err := os.ReadFile(path); err == nil && len(b) > 0 {
+		_ = json.Unmarshal(b, &f)
+	}
+	if f.Entries == nil {
+		f.Entries = map[string]dshCapsDiskEntry{}
+	}
+	f.Version = 1
+	/* 顺手清掉**已经不存在的二进制**留下的条目。
+	   不清理的话这个文件会只增不减 —— 测试里的临时 dsh、卸载过的旧版本、换过的
+	   node 版本路径都会一直留着（实测跑一轮全量测试就塞进十几条 /var/folders 下的
+	   临时路径）。每条都要 stat 一次，所以放在写回时才做，读路径上不碰。 */
+	for k := range f.Entries {
+		if strings.TrimSpace(k) == "" {
+			delete(f.Entries, k)
+			continue
+		}
+		if st, err := os.Stat(k); err != nil || st.IsDir() {
+			delete(f.Entries, k)
+		}
+	}
+	f.Entries[bin] = dshCapsDiskEntry{
+		Bin:         bin,
+		Fingerprint: fp,
+		SessionID:   caps.SessionID,
+		JSON:        caps.JSON,
+		Patch:       caps.Patch,
+		ProbedAt:    time.Now().Format(time.RFC3339),
+	}
+	if dir := filepath.Dir(path); dir != "" {
+		_ = os.MkdirAll(dir, 0o700)
+	}
+	out, err := json.MarshalIndent(f, "", "  ")
+	if err != nil {
+		return
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, append(out, '\n'), 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, path)
+}
+
+// dshHeadlessCapabilities 探测这台 dsh 支持哪些 headless flag。
+//
+// 三级缓存：进程内 sync.Map → 磁盘（按二进制指纹校验）→ 真起进程探。
+// 见 dshCapsCachePath 的注释：没有磁盘这层，等于每轮续接白等 7~9 秒。
 //
 // 为什么必须探测：dsh 启动器在**第一个它不认识的 token 处结束**解析，剩下的都当
 // app 参数交给 headless —— 老版本不认这俩 flag 时，它们会被拼进**任务文本**
-// （静默改写提示词），比直接报错难查得多。探测代价约一次 `--help`，一进程一次。
+// （静默改写提示词），比直接报错难查得多。
 //
 // ⚠️ 只有在输出**确实是 headless 的 help**（同时含 "Usage:" 与 "--profile"）时才据它判断；
 // 否则（--help 跑不起来、被包装脚本吞掉、输出被截断）一律按「都支持」处理 ——
 // 「探测不到」不等于「不支持」，宁可让现代 dsh 正常工作，也不因一次探测抖动把续接判死。
 func dshHeadlessCapabilities(ctx context.Context, bin string) dshHeadlessCaps {
-	if v, ok := dshCapsCache.Load(bin); ok {
+	fp := dshBinFingerprint(bin)
+	key := bin + "|" + fp
+	if v, ok := dshCapsCache.Load(key); ok {
 		return v.(dshHeadlessCaps)
 	}
-	caps := dshHeadlessCaps{SessionID: true, JSON: true}
+	// 磁盘命中：连一次子进程都不用起。
+	if caps, ok := dshLoadCapsFromDisk(bin, fp); ok {
+		dshCapsCache.Store(key, caps)
+		return caps
+	}
+	caps := dshHeadlessCaps{SessionID: true, JSON: true, Patch: true}
 	if stdout, stderr, err := runCLI(ctx, bin, "--profile", "headless", "--help"); err == nil {
 		help := stdout + stderr
 		if strings.Contains(help, "Usage:") && strings.Contains(help, "--profile") {
@@ -184,7 +320,21 @@ func dshHeadlessCapabilities(ctx context.Context, bin string) dshHeadlessCaps {
 			caps.JSON = strings.Contains(help, "--json")
 		}
 	}
-	dshCapsCache.Store(bin, caps)
+	// --patch 是**顶层启动器**的 flag，不在 headless 的 app help 里 —— 单独探一次。
+	// 同样只在输出确实像 help 时才据它判断（否则保留乐观默认 true）。
+	if stdout, stderr, err := runCLI(ctx, bin, "--help"); err == nil {
+		help := stdout + stderr
+		if strings.Contains(help, "Usage:") {
+			caps.Patch = strings.Contains(help, "--patch")
+		}
+	}
+	// ⚠️ 探测**中途被取消 / 超时**时不落盘：那两秒可能连 help 都没跑完，
+	// 存下去等于把「没探到」永久固化成「都支持」—— 后续每轮都照着错的判断走，
+	// 而用户再也不会遇到一次会纠正它的探测。落盘的必须是完整探完的结果。
+	if ctx.Err() == nil && fp != "" {
+		dshStoreCapsToDisk(bin, fp, caps)
+	}
+	dshCapsCache.Store(key, caps)
 	return caps
 }