magic-agent 1.0.2 → 1.0.46

package/internal/agent/dsh.go

@@ -31,12 +31,14 @@ package agent
 //     → 与 trae/claude 同路，用子进程 cwd 落地（WorkspaceSupportOf = "cwd"）。
 //     SDK 通道同理：initialize 的 cwd 就是「每个 SDK 建的会话 header 上记的目录」，
 //     同时也仍用子进程 cwd 兜底（工具执行的相对路径跟着它走）。
-//   - 权限：新会话默认 workspace-write 预设（写入限制在工作区 + 平台临时目录），
-//     read-only 为另一预设，进程回退模式由环境变量 DSH_PERMISSION_MODE 决定。
-//     **没有命令行级 approval flag**，且这两个预设无法表达本项目四档模型里的
-//     「沙箱关闭 / 无审批」（第 4 档）→ 四档模型在 dsh 上**不接线**
-//     （PermissionSupportOf = "none"），显式传 --permission 会在 CLI 层 exit 2
-//     报错，而不是静默降级 —— 安全设置不做静默降级。
+//   - 权限：档位走**子进程环境变量** `DSH_PERMISSION_MODE`（dsh 是 profile 启动器，
+//     没有逐调用的权限 flag）。shipped 的 sdk profile 里 sandbox-policy.mode 与
+//     user-approval.policy 都直接读它，取值即 SandboxMode 词表：
+//     read-only / workspace-write / danger-full-access（最后一条 = 「沙箱关闭 + 无审批」，
+//     正是四档里的第 4 档）。四档映射与两处已知差异（dsh 无 LLM 分类器、ask 需要应答者
+//     而 SDK 通道拿不到审批请求）见 permission.go::dshPermissionMode。
+//     ⚠️ 2026-10-14 修正：本文件原先写「两个预设无法表达第 4 档 → 不接线（none）」，
+//     那是 dsh 0.1.x 的情况；0.2.0-rc.2 的 `--dump-config` 里已有 danger-full-access 预设。
 //   - 工具：DSH 自带 agent 工具循环（base bundle 的 read/write/edit + Bash 等），
 //     增删工具靠 profile bundle / cordis.patch.yml 配置，**无命令行级逐工具开关**
 //     → Request.Tools 整体忽略（与 openclaw 的「内嵌 agent」同构，见矩阵注 ③）。
@@ -48,21 +50,22 @@ package agent
 //
 //	Model        SDK：支持（initialize 的 provider/model，取 `route/model` 形态）
 //	             headless 回退：不支持（静默忽略 + 一行告警：换模型要改配置层）
-//	SessionID    两条通道都不支持 → **显式报错**，不静默开新会话
-//	             （headless 每次全新会话；SDK 的 sessionId 是「未知 id 惰性建会话」，
-//	              已存在的 id 会被 -32603 `session already exists` 拒掉，协议也没有
-//	              resume/load 方法 → 对「每次调用都是新进程」的 magic-agent 一样续不上）
-//	Continue     同上（无「最近一次会话」概念）→ 显式报错
+//	SessionID    走 headless 的 `--session-id <id>` 做**真续接**（dsh 自己持久化会话；
+//	             SDK 通道没有 resume 方法）→ 续接轮由 headless + --json 承载，
+//	             上下文由 dsh 接回来，工具/正文/推理与 SDK 通道同构上报（见 dsh_resume.go）
+//	Continue     同上：先按会话登记表找**同一 workspace** 下最近一条 dsh 会话，再走 --session-id
 //	MaxTokens    SDK：支持（initialize 的 maxTokens，官方语义「限制 SDK 创建的 agent
 //	             及其进程内后代的每次对话模型输出」）；headless 回退：静默忽略
 //	Temperature  不支持（无对应键）→ 静默忽略
 //	Tools        内嵌 agent（忽略，见上）
-//	Permission   未接线（none）→ 显式传则 CLI 层 exit 2
+//	Permission   环境变量 DSH_PERMISSION_MODE（四档 → read-only / workspace-write /
+//	             danger-full-access，见 permission.go::dshPermissionMode）
 //	SystemPrompt 无独立 system 注入 flag → 展平进 prompt 头部（与 trae/openclaw 同路）
 //	Timeout      进程级超时（CLI 无 flag）
 //	JSONSchema   无原生约束 → 走与 llm/openclaw/arkclaw 同一条「输出后处理抽 JSON」
 //	Workspace    子进程 cwd（SDK 通道另把 cwd 交给 initialize）
-//	Attachments  无原生输入通道 → 绝对路径写进提示词（与 trae/openclaw 同路）
+//	Attachments  SDK 通道：图片走协议原生 image 块（base64 inline，真进模型上下文）；
+//	             非图片附件与 headless 回退 → 绝对路径写进提示词（与 trae/openclaw 同路）
 //
 // 流式：实现了 Streamer，两通道能力不同（如实接线，不假装）：
 //
@@ -104,9 +107,9 @@ func (e *DshEngine) Name() string { return "dsh" }
 // DefaultDshTimeout 单次尝试默认超时。
 //
 // dsh 自带 agent 工具循环（读文件 / 跑命令），一轮任务常常是分钟级；
-// 取 10 分钟与 trae/openclaw 对齐。CLI 侧没有 --timeout，超时完全由外层
-// ctx 施加（超时会杀掉 dsh 及其 node worker 的整个进程组）。
-const DefaultDshTimeout = 10 * time.Minute
+// 2026-10-10 统一上调到 1 小时（与 CLI 的 -t 默认一致）。CLI 侧没有 --timeout，超时完全
+// 由外层 ctx 施加（超时会杀掉 dsh 及其 node worker 的整个进程组）。
+const DefaultDshTimeout = time.Hour
 
 // dshDefaultProfile headless 是一次性（非交互）入口。
 const dshDefaultProfile = "headless"
@@ -158,14 +161,18 @@ func (e *DshEngine) Detect() (bool, string) {
 	return true, p
 }
 
-// ListModels 实现 ModelLister：返回 `$DSH_HOME/settings.yaml` 里**已配置**的模型。
+// ListModels 实现 ModelLister：返回 dsh **已配置**的 `route/model` 清单。
 //
 // 为什么不查 CLI：dsh 启动器只有 profile / plugin / config-dump 三种模式，没有
 // `dsh models` 之类的只读子命令（headless 也没有 --model 参数）。
 //
-// 为什么不查网关的 `GET {baseURL}/models`：官方明确「settings.yaml 才是决定一条路由
-// 服务什么的东西」—— 网关列出的上百个模型并不都能用，只有 `models:` 里声明过的才会被
-// 路由接受。故**配置层才是权威**，也顺带避免了每次探测都发网络请求 + 需要解密凭据。
+// 为什么不查网关的 `GET {baseURL}/models`：官方明确「配置层才是决定一条路由服务
+// 什么的东西」—— 网关列出的上百个模型并不都能用，只有配置里声明过的才会被路由接受。
+// 故**配置层才是权威**，也顺带避免了每次探测都发网络请求 + 需要解密凭据。
+//
+// 配置位置随 dsh 版本变过（见 dshConfigDocs）：0.1.7 起是各 profile 的
+// cordis.patch.yml，之前是 $DSH_HOME/settings.yaml。两处都读、取并集 ——
+// 前者是 SDK 通道，后者是 headless 回退通道，magic-agent 两条都会用到。
 //
 // 输出形态 `provider/model`（与 openclaw 的 `provider/model` 同构）：dsh 的模型只在
 // 所属路由内有意义，同名模型可能出现在两条路由上，裸 id 会歧义。
@@ -174,21 +181,30 @@ func (e *DshEngine) Detect() (bool, string) {
 // provider/model 两个必填参数，见 dshResolveRoute）。回退 headless 后 `-m` 无作用
 // （无 --model 参数），引擎会打一行告警说明该改配置层。
 func (e *DshEngine) ListModels(_ context.Context) ([]string, error) {
+	docs := dshConfigDocs()
+	var models []string
+	for _, d := range docs {
+		models = append(models, parseDshModelRoutes(d.legacyText())...)
+	}
+	if models = dedupeModels(models); len(models) > 0 {
+		return models, nil
+	}
 	home := DshHome()
 	if home == "" {
 		return nil, fmt.Errorf("%w: 无法定位 $DSH_HOME（设置 DSH_HOME 或检查 HOME）", ErrNoModelSource)
 	}
-	data, err := os.ReadFile(filepath.Join(home, "settings.yaml"))
-	if err != nil {
-		return nil, fmt.Errorf("%w: 读不到 %s（模型由该文件的 agent-default-model / llm-pi-ai 段决定）: %v",
-			ErrNoModelSource, filepath.Join(home, "settings.yaml"), err)
+	paths := make([]string, 0, len(docs))
+	for _, d := range docs {
+		paths = append(paths, d.Path)
 	}
-	models := parseDshModelRoutes(string(data))
-	if len(models) == 0 {
-		return nil, fmt.Errorf("%w: %s 里没有已配置的模型（在 llm-pi-ai.providers.<id>.models 下列出，并设 agent-default-model）",
-			ErrNoModelSource, filepath.Join(home, "settings.yaml"))
+	tried := "（没有候选文件）"
+	if len(paths) > 0 {
+		tried = strings.Join(paths, "、")
 	}
-	return models, nil
+	return nil, fmt.Errorf("%w: 没有读到已配置的模型；找过 %s。"+
+		"dsh 0.1.7 起 provider 声明在 profile 的 cordis.patch.yml（可用 dsh 的「设置 → 模型」写入），"+
+		"更早的版本在 settings.yaml 的 llm-pi-ai.providers.<id>.models 段",
+		ErrNoModelSource, tried)
 }
 
 // sdkEnabled 是否走 SDK 通道（effectiveProfile == "sdk"）。
@@ -198,17 +214,6 @@ func (e *DshEngine) sdkEnabled() bool {
 	return e.effectiveProfile() == dshSDKProfile
 }
 
-// errDshNoSessionResume 会话续接在 dsh 上不可用（两条通道都不行，理由不同）。
-//
-// 明确报错而不是静默开新会话 —— 后者会让调用方以为上一轮上下文还在。
-var errDshNoSessionResume = errors.New(
-	"dsh: 不支持会话续接（-s/--session）—— headless 每次调用都是全新会话；" +
-		"SDK 通道的 sessionId 只在**同一个 runtime 进程内**可续（官方 Python SDK 文档：" +
-		"reuse a harness, home, and id），换进程拿旧 id 会被 -32603 `session already exists` 拒掉，" +
-		"协议也没有 resume 方法。要真正的多轮上下文请用常驻会话：" +
-		"`magic-agent -e dsh --stream --keep-alive \"首轮\"`，再用 " +
-		"`magic-agent --append <run_id|session_id> -p \"追加\"` 接着问")
-
 // dshModelLabel 本轮实际用的模型标签（`provider/model`，与 ListModels 同形态）。
 func dshModelLabel(res dshSDKTurnResult) string {
 	if res.Provider == "" || res.Model == "" {
@@ -221,7 +226,7 @@ func dshModelLabel(res dshSDKTurnResult) string {
 // 该 profile 不可用时回退 `dsh --profile headless "<prompt>"`。
 //
 // 执行流程：
-//  1. 拒掉续接参数（两条通道都续不上，静默忽略会让调用方误以为上下文接上了）
+//  1. 续接参数 → **回放式续接**（dsh 协议无 resume，见 dsh_resume.go）
 //  2. 展平 prompt（无独立 system 通道）+ 附件路径兜底
 //  3. SDK 通道：initialize + session/prompt，收 turn/end 时的正文
 //     （通道不可用 → 回退；服务端明确拒绝 → 直接报错，不吞）
@@ -234,23 +239,42 @@ func (e *DshEngine) Complete(ctx context.Context, req Request) (Response, error)
 		return Response{}, fmt.Errorf("dsh CLI not found; set MAGIC_AGENT_DSH_BIN")
 	}
 
-	if req.SessionID != "" || req.Continue {
-		return Response{}, errDshNoSessionResume
-	}
+	// 工作区规范化：会话是按 cwd 字符串记的，续接时 dsh 逐字比对（见 dshCanonicalWorkspace）。
+	// 必须放在 SDK 分支之前 —— 首轮的 initialize.cwd 也是记录值的一部分。
+	req.Workspace = dshCanonicalWorkspace(req.Workspace)
 
 	// 无独立 system 注入 flag：与 trae / openclaw 同路，展平进 prompt 头部。
 	// 这里不追加 noToolSuffix —— dsh 是自带工具循环的 agent harness，
 	// Request.Tools 在它上面没有落地通道（见文件头矩阵），后缀只会是噪音。
-	prompt := FlattenPrompt(req.SystemPrompt, req.Messages, false)
-	if prompt == "" {
+	basePrompt := FlattenPrompt(req.SystemPrompt, req.Messages, false)
+	if basePrompt == "" {
 		return Response{}, fmt.Errorf("dsh: empty prompt")
 	}
-	// 附件：dsh 没有附件输入参数，只能把绝对路径写进提示词
-	//（与 trae/openclaw 同一兜底；需要 dsh 侧的读文件工具能看到它）。
-	prompt = appendAttachmentSection(prompt, req.Attachments)
+	// 附件分两条路（见 dshSplitAttachments）：
+	//   SDK 通道  图片作为原生 image 块随 contentBlocks 发出去（真的进模型上下文）
+	//   headless  没有附件输入参数，只能把**绝对路径**写进提示词（与 trae/openclaw 同一兜底）
+	// 非图片附件（PDF/文本…）协议里没有内联类型，两条路都退化为路径。
+	_, byPath := dshSplitAttachments(req.Attachments)
+	sdkPrompt := appendAttachmentSection(basePrompt, byPath)
+	headlessPrompt := appendAttachmentSection(basePrompt, req.Attachments)
+
+	// 续接轮：dsh 的**真续接**（headless + --session-id）只在 headless 通道上，
+	// SDK 通道没有 resume 方法 → 这种轮次不走 SDK（见 dsh_resume.go）。
+	// 常驻会话（req.Append）是例外：它必须待在 SDK 通道（追加靠同一进程），
+	// 而且它本身就带着上下文，不需要 --session-id。
+	resumeID := ""
+	if req.Append == nil {
+		resumeID = dshResumeSessionID(req)
+	}
+	if resumeID != "" {
+		if !dshHeadlessCapabilities(ctx, bin).SessionID {
+			return Response{}, errors.New(dshResumeUnsupportedHint(bin))
+		}
+		return e.completeHeadless(ctx, req, bin, resumeID, headlessPrompt, start)
+	}
 
 	if e.sdkEnabled() {
-		res, sdkErr := dshSDKTurn(ctx, bin, req.Workspace, req, prompt, nil)
+		res, sdkErr := dshSDKTurn(ctx, bin, req.Workspace, req, sdkPrompt, nil)
 		if sdkErr == nil {
 			resp := Response{
 				Engine:  e.Name(),
@@ -283,25 +307,63 @@ func (e *DshEngine) Complete(ctx context.Context, req Request) (Response, error)
 		fmt.Fprintf(stderr, "  ⚠ dsh: SDK 通道不可用，本轮回退 headless（拿不到工具调用、正文不流式）：%v\n", sdkErr)
 	}
 
-	// 走到这里就是要用 headless 执行了 —— 它没有 --model 参数，模型由配置层决定。
-	// -m 在 headless 上不是透传是「无作用」：告警一次（与 arkclaw 一致），让用户知道
-	// 该去改 dsh 自己的配置。显式 Profile: "headless" 也走这里，同样告警。
-	if req.Model != "" {
+	// 走到这里就是 SDK 不可用、要用 headless 执行了（回退路径，无续接）。
+	return e.completeHeadless(ctx, req, bin, "", headlessPrompt, start)
+}
+
+// dshSplitAttachments 把附件分成「走 SDK 原生 image 块」与「只能写路径」两拨。
+//
+//	原生那拨   MIME 是 dsh SDK 内联图片认的四种（png/jpeg/webp/gif，见 dshNativeImageMIME）
+//	路径那拨   其余（PDF / bmp / 文本 / 未知类型）—— 协议里没有通用文件内联类型
+//
+// 路径那拨与 headless 回退一样，由调用方把绝对路径写进提示词末尾的「【附件】」清单。
+func dshSplitAttachments(atts []Attachment) (native, byPath []Attachment) {
+	for _, a := range atts {
+		if dshNativeImageMIME(a.MIME) {
+			native = append(native, a)
+		} else {
+			byPath = append(byPath, a)
+		}
+	}
+	return native, byPath
+}
+
+// dshNativeImageMIME dsh SDK 的 SdkEncodedImageBlock.mimeType 只接受这四种（协议原文）。
+// bmp / pdf 即便被嗅探成图片也不是合法内联类型，照旧走路径兜底。
+func dshNativeImageMIME(mime string) bool {
+	switch mime {
+	case "image/png", "image/jpeg", "image/webp", "image/gif":
+		return true
+	}
+	return false
+}
+
+// completeHeadless headless 通道：回退路径与**续接轮**共用。
+//
+// 形态：`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)
 	}
 
-	args := e.buildArgs(req, prompt)
+	args := dshHeadlessArgs(e.profile(), sessionID, prompt, false)
 
 	// workspace：dsh 的「调用时所在目录即默认 workspace 根」正是子进程 cwd 的语义。
-	stdout, stderrText, runErr := runCLIIn(ctx, req.Workspace, bin, args...)
+	// 档位同 SDK 通道：走 DSH_PERMISSION_MODE（dsh 没有逐调用的权限 flag）。
+	stdout, stderrText, runErr := runCLIEnvIn(ctx, req.Workspace, dshPermissionEnv(req.Permission), bin, args...)
 
 	resp := Response{
 		Engine: e.Name(),
-		// headless 的 stdout 就是最终助手正文（推理增量在 stderr，不混入）。
+		// headless 的 stdout 就是最终助手正文（推理增量走 stderr，不混入）。
 		Text: strings.TrimSpace(stdout),
 		// 模型名尽力而为：读 dsh 配置里的默认模型（读不到给 "config-default"）。
-		Model:   DshConfiguredModel(),
+		Model:   dshHeadlessModel(req, sessionID),
 		Latency: time.Since(start),
 	}
 	if resp.Model == "" {
@@ -315,7 +377,7 @@ func (e *DshEngine) Complete(ctx context.Context, req Request) (Response, error)
 	}
 	if runErr != nil {
 		// 非零退出 = turn/end 不是 completed；stderr 末尾通常就是终止原因，
-		// wrapCliError 会把它摘成可读摘要。
+		// wrapCliError 会把它摘成可读摘要（未知 session-id 也走这条，报 does not exist）。
 		return resp, wrapCliError("dsh", stdout, stderrText, runErr)
 	}
 	if resp.Text == "" {
@@ -324,33 +386,50 @@ func (e *DshEngine) Complete(ctx context.Context, req Request) (Response, error)
 	return resp, nil
 }
 
-// buildArgs 构造 dsh 回退路径（headless / 自定义 profile）的参数。
+// dshHeadlessModel headless 轮次对外报的模型标签。
 //
-// 形态（启动器 flags 在前，app 参数在后）：
+//	普通 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
+		}
+	}
+	return DshConfiguredModel()
+}
+
+// dshHeadlessArgs 构造 headless 的参数：**启动器 flag 在前，app 参数在后**。
 //
-//	dsh --profile headless "<prompt>"
+//	["--profile", <profile>] [+ "--session-id", <id>] [+ "--json"] + ["<prompt>"]
 //
-// prompt 走**位置参数**（headless 唯一的 app 参数，无 --prompt / stdin 通道）。
-// 代价是超长 prompt 会撞 ARG_MAX —— 与 trae 的 -p 同一个已知边界，
-// 需要喂超长文本时请先落成文件、让 dsh 用自己的读文件工具看（配合 -a 路径兜底同理）。
+// ⚠️ --session-id / --json 是 **headless 自己的 flag**（不是启动器 flag，见 dsh --help），
+// 必须排在 --profile 之后、任务文本之前 —— 启动器在第一个它不认识的 token 处结束解析。
+// prompt 走位置参数（headless 唯一的 app 参数，无 --prompt / stdin 通道），
+// 超长 prompt 会撞 ARG_MAX：需要喂超长文本时先落成文件，让 dsh 用读文件工具看。
 //
-// ⚠️ 只有回退路径用得到它：SDK 通道的 prompt 走 session/prompt 的 contentBlocks
+// ⚠️ 只有 headless 用得到它：SDK 通道的 prompt 走 session/prompt 的 contentBlocks
 // （见 dsh_sdk.go），既不占命令行也不受 ARG_MAX 限制。
-func (e *DshEngine) buildArgs(req Request, prompt string) []string {
-	// 统一参数矩阵：MaxTokens / Temperature 在 headless 上无对应 flag（静默忽略）；
-	// Tools 由 dsh 自己的工具循环决定（忽略）；Timeout 由外层 ctx 施加（忽略）。
-	_ = req.MaxTokens
-	_ = req.Temperature
-	_ = req.Tools
-	_ = req.Timeout
-	return []string{"--profile", e.profile(), prompt}
+func dshHeadlessArgs(profile, sessionID, prompt string, jsonEvents bool) []string {
+	args := []string{"--profile", profile}
+	if sessionID != "" {
+		args = append(args, "--session-id", sessionID)
+	}
+	if jsonEvents {
+		args = append(args, "--json")
+	}
+	return append(args, prompt)
 }
 
 // ── 流式（--stream）────────────────────────────────────────────
 //
-// dsh 有两条流式形态，能力不同，如实接线：
+// dsh 的流式形态与通道有关，如实接线：
 //
-//	SDK 通道（默认，见 dsh_sdk.go）
+//	SDK 通道（普通轮默认，见 dsh_sdk.go）
 //	  session.event 实时推送：
 //	    assistant/message 的 reasoning 块 → 逐条 KindThinking
 //	    assistant/message 的 text 块      → 逐 step KindText（真流式，不等 turn 结束）
@@ -358,45 +437,63 @@ func (e *DshEngine) buildArgs(req Request, prompt string) []string {
 //	    tool/result                      → KindToolResult（按 callId 关联）
 //	    turn/end                         → 收尾一条 KindTurnEnd
 //
-//	headless 回退（实测 2026-09-21，dsh 0.1.5-rc.2）
-//	  stderr：`dsh: reasoning:` 标题行之后，推理增量**逐段到达**（约 300ms 一批）
-//	  stdout：最终助手正文在 turn 结束时**一次性**到达
+//	headless + --json（**续接轮**与 SDK 不可用时的回退路径，见 dsh_resume.go）
+//	  stdout 是 NDJSON 事件流：session / status(turn/step) / thinking / text /
+//	  tool_call / tool_result / final
+//	  → 推理 / 正文 / 工具调用与 SDK 通道**同构**地上报（0.1.7+ 的官方 run 投影）
+//
+//	headless（老版本没有 --json）
+//	  stderr：`dsh: reasoning:` 标题行之后，推理增量逐段到达；stdout：收尾正文一次性到达
 //	  → 推理 → 逐条 KindThinking；正文 → 一条 KindText（收尾时）
-//	  ⚠️ 这条路上**没有任何工具调用通道**（官方 headless 的定位就是「stream reasoning
+//	  ⚠️ 这条路上**没有任何工具调用通道**（官方早期 headless 的定位就是「stream reasoning
 //	     to stderr, print the final assistant message, and exit」）—— 不是解析缺陷。
 
-// dshReasoningPrefix stderr 上推理增量的起始标记（官方 headless 的固定前缀）。
+// dshReasoningPrefix stderr 上推理增量的起始标记（老版 headless 的固定前缀）。
 const dshReasoningPrefix = "dsh: reasoning:"
 
-// Stream 实现 Streamer：默认走 SDK（推理/正文/工具调用全流式），
-// SDK 不可用时回退 headless（只有推理流式 + 收尾正文）。
+// Stream 实现 Streamer：普通轮默认走 SDK（推理/正文/工具调用全流式），
+// 续接轮与 SDK 不可用时走 headless（--json 事件流，能力见本节顶部）。
 func (e *DshEngine) Stream(ctx context.Context, req Request, onEvent func(StreamEvent)) (StreamResult, error) {
 	start := time.Now()
 	bin := e.bin()
 	if bin == "" {
 		return StreamResult{}, fmt.Errorf("dsh CLI not found; set MAGIC_AGENT_DSH_BIN")
 	}
-	// 与 Complete 同一条契约：dsh 两条通道都续不上，明确报错而不是静默开新会话。
-	if req.SessionID != "" || req.Continue {
-		return StreamResult{}, errDshNoSessionResume
-	}
 
-	prompt := FlattenPrompt(req.SystemPrompt, req.Messages, false)
-	if prompt == "" {
+	// 工作区规范化：与 Complete 同一条理由（见 dshCanonicalWorkspace），必须在 SDK 分支之前。
+	req.Workspace = dshCanonicalWorkspace(req.Workspace)
+
+	basePrompt := FlattenPrompt(req.SystemPrompt, req.Messages, false)
+	if basePrompt == "" {
 		return StreamResult{}, fmt.Errorf("dsh: empty prompt")
 	}
-	prompt = appendAttachmentSection(prompt, req.Attachments)
+	// 同 Complete：SDK 通道图片走原生 image 块，非图片附件/headless 走提示词路径。
+	_, byPath := dshSplitAttachments(req.Attachments)
+	sdkPrompt := appendAttachmentSection(basePrompt, byPath)
+	headlessPrompt := appendAttachmentSection(basePrompt, req.Attachments)
+
+	// 与 Complete 同一条契约：续接轮走 headless + --session-id（真续接，见 dsh_resume.go）。
+	resumeID := ""
+	if req.Append == nil {
+		resumeID = dshResumeSessionID(req)
+	}
+	if resumeID != "" {
+		if !dshHeadlessCapabilities(ctx, bin).SessionID {
+			return StreamResult{}, errors.New(dshResumeUnsupportedHint(bin))
+		}
+		return e.streamHeadless(ctx, req, bin, resumeID, headlessPrompt, onEvent, start)
+	}
 
 	if e.sdkEnabled() {
-		res, sdkErr := dshSDKTurn(ctx, bin, req.Workspace, req, prompt, onEvent)
+		res, sdkErr := dshSDKTurn(ctx, bin, req.Workspace, req, sdkPrompt, onEvent)
 		if sdkErr == nil {
 			resp := Response{
 				Engine: e.Name(),
 				Text:   strings.TrimSpace(res.Text),
 				Model:  dshModelLabel(res),
 				// 报出本轮会话 id：常驻会话里 `--append <session_id>` 能用它定位
-				//（会话登记表按 run_id 或 session_id 查找）。注意它**不能**当 -s 用 ——
-				// 跨进程续接拿不到（见 errDshNoSessionResume）。
+				//（会话登记表按 run_id 或 session_id 查找），下游 `-s` 也靠它找回上文
+				//（回放式续接，见 dsh_resume.go）。
 				SessionID: res.SessionID,
 				Latency:   time.Since(start),
 			}
@@ -426,38 +523,123 @@ func (e *DshEngine) Stream(ctx context.Context, req Request, onEvent func(Stream
 		fmt.Fprintf(stderr, "  ⚠ dsh: SDK 通道不可用，本轮回退 headless（拿不到工具调用、正文不流式）：%v\n", sdkErr)
 	}
 
-	// 同 Complete：headless 通道没有 --model 参数，-m 在这里是「无作用」，告警一次。
-	if req.Model != "" {
+	// SDK 不可用 → headless（有 --json 就是事件流），无续接。
+	return e.streamHeadless(ctx, req, bin, "", headlessPrompt, onEvent, start)
+}
+
+// streamHeadless headless 通道的流式实现：**续接轮**与回退路径共用。
+//
+// 有 --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)
 	}
 
-	args := e.buildArgs(req, prompt)
+	caps := dshHeadlessCapabilities(ctx, bin)
+	args := dshHeadlessArgs(e.profile(), sessionID, prompt, caps.JSON)
 
-	var thinking strings.Builder
-	inReasoning := false
-	stdout, stderrText, runErr := runStreamStderrIn(ctx, req.Workspace, bin, args, func(line string) error {
-		// 标题行本身不是内容；它出现即进入推理区段。
-		if strings.HasPrefix(line, dshReasoningPrefix) {
-			inReasoning = true
-			return nil
+	emit := func(ev StreamEvent) {
+		if onEvent != nil {
+			onEvent(ev)
 		}
-		if !inReasoning {
-			return nil // 非推理行（例如启动日志）不当作增量
+	}
+
+	var (
+		thinking  strings.Builder
+		tools     []ToolCall
+		callIdx   = map[string]int{}
+		final     string // `--json` 的 final 事件（整轮正文），权威
+		learnedID string // 会话抬头里的 id（老接口另用：本轮的会话 id）
+		streamed  bool   // 是否已逐条发过正文
+	)
+	onLine := func(line string) error {
+		ev, ok := parseDshJSONEvent(line)
+		if !ok {
+			return nil // 非事件行（启动日志 / 坏行）忽略
 		}
-		thinking.WriteString(line)
-		thinking.WriteByte('\n')
-		if onEvent != nil {
-			onEvent(StreamEvent{Kind: KindThinking, Text: line + "\n"})
+		switch ev.Type {
+		case "session":
+			// 会话抬头：headless 回的是**同一条会话**的 id，回报给「看历史」持久化。
+			learnedID = ev.SessionID
+			if learnedID != "" && req.OnSessionID != nil {
+				req.OnSessionID(learnedID)
+			}
+		case "thinking":
+			if ev.Text == "" {
+				return nil
+			}
+			thinking.WriteString(ev.Text)
+			emit(StreamEvent{Kind: KindThinking, Text: ev.Text})
+		case "text":
+			if ev.Text == "" {
+				return nil
+			}
+			streamed = true
+			emit(StreamEvent{Kind: KindText, Text: ev.Text})
+		case "tool_call":
+			callArgs := dshJSONArgs(ev.Input)
+			emit(StreamEvent{Kind: KindToolUse, Text: callArgs, Name: ev.Tool, ID: ev.CallID})
+			callIdx[ev.CallID] = len(tools)
+			tools = append(tools, ToolCall{Name: ev.Tool, ID: ev.CallID, Args: callArgs})
+		case "tool_result":
+			emit(StreamEvent{Kind: KindToolResult, Text: ev.Result, ID: ev.CallID})
+			if i, ok := callIdx[ev.CallID]; ok && tools[i].Result == "" {
+				tools[i].Result = ev.Result
+			}
+		case "final":
+			// 这里**不发**事件：final 出现在 status(turn_end) 之后（实测顺序
+			// status(turn_end) → final），逐条正文已由 text 事件发过；
+			// 它留作本轮正文的权威取值。
+			final = ev.Text
 		}
 		return nil
-	})
+	}
+
+	var (
+		stdout, stderrText string
+		runErr             error
+	)
+	if caps.JSON {
+		stdout, stderrText, runErr = runStreamLinesIn(ctx, req.Workspace, dshPermissionEnv(req.Permission), 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 {
+			// 标题行本身不是内容；它出现即进入推理区段。
+			if strings.HasPrefix(line, dshReasoningPrefix) {
+				inReasoning = true
+				return nil
+			}
+			if !inReasoning {
+				return nil // 非推理行（例如启动日志）不当作增量
+			}
+			thinking.WriteString(line)
+			thinking.WriteByte('\n')
+			emit(StreamEvent{Kind: KindThinking, Text: line + "\n"})
+			return nil
+		})
+	}
+
+	// 正文：final 事件最权威；没有（老版本 / 事件缺失）就用 stdout 全文。
+	text := strings.TrimSpace(final)
+	if text == "" {
+		text = strings.TrimSpace(stdout)
+	}
+
+	// 会话 id：续接轮回原请求的 id；新会话用会话抬头学到的那个（下一轮据此续接）。
+	sid := sessionID
+	if sid == "" {
+		sid = learnedID
+	}
 
 	resp := Response{
 		Engine:    e.Name(),
-		Text:      strings.TrimSpace(stdout),
-		Model:     DshConfiguredModel(),
-		SessionID: "", // dsh 不回可续接的会话 id（见 errDshNoSessionResume）
+		Text:      text,
+		Model:     dshHeadlessModel(req, sessionID),
+		SessionID: sid,
 		Latency:   time.Since(start),
 	}
 	if resp.Model == "" {
@@ -469,21 +651,26 @@ func (e *DshEngine) Stream(ctx context.Context, req Request, onEvent func(Stream
 		}
 	}
 	if runErr != nil {
-		return StreamResult{Response: resp, Thinking: thinking.String()},
+		return StreamResult{Response: resp, Thinking: thinking.String(), Tools: tools},
 			wrapCliError("dsh", stdout, stderrText, runErr)
 	}
 	if resp.Text == "" {
-		return StreamResult{Response: resp, Thinking: thinking.String()},
+		return StreamResult{Response: resp, Thinking: thinking.String(), Tools: tools},
 			fmt.Errorf("dsh CLI returned empty result")
 	}
 
-	// 正文一次性给出（headless 不流式正文，见本节顶部说明）。
-	if onEvent != nil {
-		onEvent(StreamEvent{Kind: KindText, Text: resp.Text})
-		// 同样补一轮结束事件：回退路径下宿主也该知道「本轮做完了」。
-		onEvent(StreamEvent{Kind: KindTurnEnd, Text: resp.Text})
+	// 正文兜底：`--json` 没给 text 事件（例如只有 final）时补一条，别让宿主一片空白。
+	if !streamed {
+		emit(StreamEvent{Kind: KindText, Text: resp.Text})
 	}
-	return StreamResult{Response: resp, Thinking: thinking.String()}, nil
+	// 收尾一条 turn_end：headless 一次调用就是一轮，宿主据此知道「本轮做完了」。
+	// ⚠️ 必须带上了会话 id（与 SDK 通道的 roundDone 一致）：客户端**只从 turn_end /
+	// turn_failed 学会话锚点**（见 client-ui/shared/conversation.js 的 render），
+	// 少了它这条通道就是「客户端拿到正文、却不知道这条是哪段会话」——
+	// 下一步追问自然就发成了新会话（真实报障：dsh 会话的追问变成了新任务）。
+	// 这条通道承载的正是**续接轮**（-s/-c）与 SDK 不可用时的回退轮，命中面不小。
+	emit(StreamEvent{Kind: KindTurnEnd, Text: resp.Text, SessionID: resp.SessionID})
+	return StreamResult{Response: resp, Thinking: thinking.String(), Tools: tools}, nil
 }
 
 // ── 配置层：DSH_HOME、模型清单与默认模型（尽力而为）────────────────
@@ -501,22 +688,169 @@ func DshHome() string {
 	return filepath.Join(home, ".dsh")
 }
 
-// DshConfiguredModel 尽力而为地报出 dsh 当前配置的默认模型
-// （$DSH_HOME/settings.yaml 的 agent-default-model 段）。
+// ── 配置文档：跨 dsh 版本定位 providers / agent-default-model ─────────
 //
-// 为什么需要它：headless 不回模型名（stdout 只有正文），而调用方（如观物台）
-// 通常要展示「这一轮是谁答的」。读不到就返回空串（调用方回落 "config-default"）——
-// 与 TraeDefaultModel 的「文件缺失 / 格式变化返回空串」同一约定，绝不因此阻断调用。
-func DshConfiguredModel() string {
+// dsh 存「已配置的 provider」的位置随版本变过：
+//
+//	≤ 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.1.7 首次启动会把旧的 settings.yaml 改名为 settings.yaml.imported
+//（官方 dsh-settings：改名先于首次写入，被组合拒绝的 section 只留在改名后的文件里）。
+// 该文件**已经不是 dsh 读取的配置**，所以这里刻意不把它当来源 —— 一旦采信它，
+// 用户就会在清单里看到运行时其实拒绝的 route（initialize 回
+// `no adapter registered for provider "..."`），正是它要防的误导。
+
+// dshConfigDoc 一份 dsh 配置候选：路径 + 是否 profile patch 形态 + 内容。
+type dshConfigDoc struct {
+	Path  string
+	Patch bool   // cordis.patch.yml（条目形态，需归一化）
+	Text  string // 读不到时为空串；仍留在候选列表里，便于说明「找过哪些」
+}
+
+// legacyText 返回可喂给「settings.yaml 那套解析器」的文本：
+// profile patch 先归一化成顶层键形态，其余原样。
+func (d dshConfigDoc) legacyText() string {
+	if d.Patch {
+		return dshPatchAsLegacy(d.Text)
+	}
+	return d.Text
+}
+
+// dshConfigDocs 按优先级返回 dsh 配置候选文档（含读不到的空壳）：
+//
+//	① 生效 profile 的 cordis.patch.yml —— SDK 通道，magic-agent 默认走 sdk
+//	   （MAGIC_AGENT_DSH_PROFILE 可改；headless 回退通道见 ②）
+//	② headless profile 的 cordis.patch.yml —— SDK 不可用时的回退通道，
+//	   列模型时不能漏（两条通道 magic-agent 都会用到）
+//	③ $DSH_HOME/settings.yaml —— 0.1.7 之前的位置，兼容未升级的装机
+func dshConfigDocs() []dshConfigDoc {
 	home := DshHome()
 	if home == "" {
-		return ""
+		return nil
+	}
+	names := []string{dshProfileName()}
+	if names[0] != dshDefaultProfile {
+		names = append(names, dshDefaultProfile)
 	}
-	data, err := os.ReadFile(filepath.Join(home, "settings.yaml"))
+	docs := make([]dshConfigDoc, 0, len(names)+1)
+	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")
+	return append(docs, dshConfigDoc{Path: p, Text: readFileOrEmpty(p)})
+}
+
+// dshProfileName 生效 profile 名：MAGIC_AGENT_DSH_PROFILE → 默认 sdk。
+//
+// 与 DshEngine.effectiveProfile 同规则；这里是包级函数（配置层读取没有引擎实例），
+// 故只看环境变量 —— 与 DshConfiguredModel / DshConfiguredRoute 一贯的行为一致。
+func dshProfileName() string {
+	if p := strings.TrimSpace(os.Getenv(DshProfileEnv)); p != "" {
+		return p
+	}
+	return dshSDKProfile
+}
+
+// readFileOrEmpty 读文件；读不到（不存在 / 无权限）返回空串 ——
+// 候选文件缺失是正常状态，不是错误。
+func readFileOrEmpty(path string) string {
+	data, err := os.ReadFile(path)
 	if err != nil {
 		return ""
 	}
-	return parseDshDefaultModel(string(data))
+	return string(data)
+}
+
+// dshPatchAsLegacy 把 profile patch（cordis.patch.yml）的**条目形态**改写成
+// settings.yaml 的**顶层键形态**，好让同一套轻量解析器同时吃两种文档。
+//
+// 规则一句话：条目 id 变成顶层键，`config:` 之下的内容整体上提一层。
+// 例如 `- id: llm-pi-ai` + `config:` + `providers:` 变成顶层 `llm-pi-ai:` + `providers:`；
+// `- id: agent-default-model` + `config: {provider, model}` 变成顶层 `agent-default-model:` 段。
+//
+// 只搬运 config: 之下的内容（同层的 disabled: 之类与旧形态无关，不搬）；
+// 没有 config 的条目跳过。归一化是**纯文本变换**，故解析器与它们的单测都不用改。
+func dshPatchAsLegacy(text string) string {
+	if text == "" {
+		return ""
+	}
+	lines := strings.Split(text, "\n")
+	// 顶层条目 = 行首无缩进的 "- id: xxx"；缩进更深的 "- id: xxx"
+	// 是条目内部（如 models 列表）的项，不能当边界。
+	entryStart := func(ln string) bool {
+		return ln == strings.TrimSpace(ln) && strings.HasPrefix(ln, "- id:")
+	}
+	var out strings.Builder
+	for i := 0; i < len(lines); {
+		if !entryStart(strings.TrimLeft(lines[i], " \t")) {
+			i++
+			continue
+		}
+		id := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(lines[i]), "- id:"))
+		j := i + 1
+		for j < len(lines) && !entryStart(lines[j]) {
+			j++
+		}
+		block := lines[i+1 : j]
+		i = j
+		if id == "" {
+			continue
+		}
+		// 找 config:（取块内第一处），其后缩进更深的行即内容。
+		cfgK, cfgIndent := -1, 0
+		for k, ln := range block {
+			if strings.TrimSpace(stripYAMLComment(ln)) != "config:" {
+				continue
+			}
+			cfgK = k
+			cfgIndent = len(ln) - len(strings.TrimLeft(ln, " \t"))
+			break
+		}
+		if cfgK < 0 {
+			continue
+		}
+		var body []string
+		minIndent := -1
+		for _, ln := range block[cfgK+1:] {
+			if strings.TrimSpace(ln) == "" {
+				continue
+			}
+			indent := len(ln) - len(strings.TrimLeft(ln, " \t"))
+			if indent <= cfgIndent {
+				break
+			}
+			if minIndent < 0 || indent < minIndent {
+				minIndent = indent
+			}
+			body = append(body, ln)
+		}
+		if len(body) == 0 {
+			continue
+		}
+		out.WriteString(id + ":\n")
+		for _, ln := range body {
+			out.WriteString("  " + ln[minIndent:] + "\n")
+		}
+	}
+	return out.String()
+}
+
+// DshConfiguredModel 尽力而为地报出 dsh 当前配置的默认模型
+// （agent-default-model 段；位置随版本变，见 dshConfigDocs）。
+//
+// 为什么需要它：headless 不回模型名（stdout 只有正文），而调用方（如观物台）
+// 通常要展示「这一轮是谁答的」。读不到就返回空串（调用方回落 "config-default"）——
+// 与 TraeDefaultModel 的「文件缺失 / 格式变化返回空串」同一约定，绝不因此阻断调用。
+func DshConfiguredModel() string {
+	for _, d := range dshConfigDocs() {
+		if m := parseDshDefaultModel(d.legacyText()); m != "" {
+			return m
+		}
+	}
+	return ""
 }
 
 // parseDshDefaultModel 轻量扫描 settings.yaml（不引入 yaml 依赖），取