magic-agent 1.0.3 → 1.0.49

package/internal/client/service.go

@@ -2,18 +2,26 @@ package client
 
 import (
 	"bufio"
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"image"
+	"image/draw"
+	_ "image/gif"
+	"image/jpeg"
+	"image/png"
 	"io"
 	"log"
+	"math"
 	"net/http"
 	"net/http/httputil"
 	"net/url"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 	"sync"
@@ -47,9 +55,17 @@ type Options struct {
 	Profile    Profile
 	// UIRoot 静态资源目录（开发态从磁盘加载；发布态由调用方指向内置资源解包目录）。
 	UIRoot string
+	// MobileRoot 移动端界面目录（client-ui-mobile）。非空时提供 /m/ 路由 ——
+	// APK 壳配对后**远程加载**它，于是改界面只改桌面文件、不用重打 APK。
+	// 空 = 自动取与 --ui-dir 同级的 client-ui-mobile。
+	MobileRoot string
 	// Token 访问令牌；空 = 启动时随机生成。
 	Token  string
 	Logger *log.Logger
+	// BrowseUA 内置浏览器中转使用的 User-Agent；空 = 用内置的 Android Chrome。
+	// 为什么可配：UA 会决定站点给哪一版页面。中国大陆出口 + 移动 UA 时，Google 会跳到
+	// http://www.google.cn/m（该路径本身就是 404）；换成桌面 UA 则走香港跳转、可正常打开。
+	BrowseUA string
 }
 
 // Service 本地服务。
@@ -64,6 +80,11 @@ type Service struct {
 	mu   sync.Mutex
 	runs map[string]*askRun
 	seq  int64
+
+	// 内置浏览器中转用的 HTTP 客户端（惰性建、带 cookie jar，按上游 host 存会话）。
+	// 见 browse.go —— 它让 iframe 的流量走**桌面端网络**，而不是手机直连。
+	browseOnce sync.Once
+	browseHTTP *http.Client
 }
 
 // Contract core `--contract` 里本插件关心的部分。
@@ -135,6 +156,21 @@ func (s *Service) Handler() http.Handler {
 	mux.HandleFunc("/desk/profile", s.guard(s.handleProfile))
 	mux.HandleFunc("/desk/modules", s.guard(s.handleModules))
 	mux.HandleFunc("/desk/sessions", s.guard(s.handleSessions))
+	mux.HandleFunc("/desk/upload", s.guard(s.handleUpload))
+	// 回读已上传附件（缩略图 / 历史回看）：<img> 带不了自定义头，靠 guard 支持的 ?token= 过鉴权。
+	mux.HandleFunc("/desk/uploads/", s.guard(s.handleUploadGet))
+	// 按**绝对路径**回读本机图片 / 视频 / 音频：工具卡缩略图、会话产物（路径在 core 机器上）。
+	mux.HandleFunc("/desk/media", s.guard(s.handleMediaFile))
+	// 一批本机路径的存在性探测：内核画「会话产物」只画真的落在盘上的那些。
+	mux.HandleFunc("/desk/path-probe", s.guard(s.handlePathProbe))
+	// 按**绝对路径**读文本文件（Markdown / 日志 / 源码）：移动端产物卡「查看」在浮层里阅读。
+	mux.HandleFunc("/desk/path-read", s.guard(s.handlePathRead))
+	mux.HandleFunc("/desk/titles", s.guard(s.handleTitles))
+	// 插件目录（magic-shorts / magic-video 两个工程的 CLI）：介绍、安装状态、安装/升级。
+	// 与引擎无关 —— core 不认识它们，所以放在这一层而不是 core 的 --engines 里。
+	mux.HandleFunc("/desk/plugins", s.guard(s.handlePlugins))
+	mux.HandleFunc("/desk/plugins/", s.guard(s.handlePluginAction))
+	mux.HandleFunc("/desk/dirs", s.guard(s.handleDirs))
 	// /desk/session/{id}/messages 是**前缀匹配**路由 —— 标准 ServeMux 把它挂上后，
 	// 该前缀下任何 path 都先进这里（其它挂载顺序靠后也拦不住）。
 	// 它同时承担 /desk/session/{id}/events（断线续读）的分派，见 handleSessionMessages。
@@ -151,6 +187,15 @@ func (s *Service) Handler() http.Handler {
 	mux.HandleFunc("/pair", s.guard(s.handlePairPage))
 	mux.HandleFunc("/pair/qr.png", s.guard(s.handlePairQR))
 	mux.HandleFunc("/desk/pair", s.guard(s.handlePairInfo))
+	// 远程移动端界面：APK 壳配对后直接加载 /m/ —— 改界面只改桌面文件，不重打 APK。
+	// 静态页本身不带令牌（与 "/" 一致）；数据接口仍由 /desk/* 的令牌把关。
+	mux.HandleFunc("/m", s.handleMobileUI)
+	mux.HandleFunc("/m/", s.handleMobileUI)
+	// 内置浏览器的**服务端中转**：/b/<scheme>/<host><path>。走桌面端网络抓取并改写，
+	// 见 browse.go。注意它自己鉴权（cookie/查询令牌），不再套 s.guard。
+	mux.HandleFunc("/b/", s.handleBrowse)
+	// SOCKS5 over WebSocket：让 SOCKS5 能穿过 HTTP 隧道（Cloudflare 等）到公网，见 wsproxy.go。
+	mux.HandleFunc(proxyWSPath, s.handleProxyWS)
 	mux.HandleFunc("/", s.handleStatic)
 	return s.withCORS(mux)
 }
@@ -218,6 +263,34 @@ func localOrigin(origin string) bool {
 	return false
 }
 
+// originSource 由请求 Origin 判定**来源端**：容器自定义 scheme = 移动端，
+// 其余（桌面壳 / 插件同源页面 / 无 Origin）= 桌面端。
+//
+// 与 localOrigin 的分工：localOrigin 回答「浏览器让不让读」（移动容器与 loopback
+// 都算本机）；这里只回答「是谁发起的」，所以两者不是一回事，不能合并。
+func originSource(origin string) string {
+	switch strings.TrimSpace(origin) {
+	case "capacitor://localhost", "ionic://localhost":
+		return session.SourceMobile
+	default:
+		return session.SourcePC
+	}
+}
+
+// requestSource 定来源端：**客户端自报优先**，没自报才退回按 Origin 猜。
+//
+// 为什么自报优先：移动端是加载 /m/ 页面跑起来的，与桌面同源，Origin 一模一样，
+// 靠 Origin 分不出来；客户端自己最清楚它是谁。Origin 只作为旧客户端/直连的兜底。
+func requestSource(client, origin string) string {
+	switch strings.ToLower(strings.TrimSpace(client)) {
+	case session.SourceMobile:
+		return session.SourceMobile
+	case session.SourcePC:
+		return session.SourcePC
+	}
+	return originSource(origin)
+}
+
 // guard 鉴权：`X-Magic-Token` 头或 `token` 查询参数。静态资源不鉴权（它不含密钥，
 // 真正的执行面都在 /desk/* 后面）。
 func (s *Service) guard(next http.HandlerFunc) http.HandlerFunc {
@@ -236,12 +309,17 @@ func (s *Service) guard(next http.HandlerFunc) http.HandlerFunc {
 }
 
 func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
+	// core 由本插件 spawn、继承本进程的 cwd；而 core 不传 -w 时默认工作空间就是 cwd。
+	// 所以这里的 cwd 就是「桌面默认工作空间」，客户端用它给空 workspace 的会话归类。
+	wd, _ := os.Getwd()
 	writeJSON(w, http.StatusOK, map[string]any{
-		"ok":              true,
-		"contractVersion": s.contract.ContractVersion,
-		"features":        s.contract.Features,
-		"app":             s.opts.Profile.App.Name,
-		"engines":         len(s.contract.Engines),
+		"ok":               true,
+		"contractVersion":  s.contract.ContractVersion,
+		"features":         s.contract.Features,
+		"app":              s.opts.Profile.App.Name,
+		"engines":          len(s.contract.Engines),
+		"defaultWorkspace": wd,
+		"workspacesRoot":   filepath.Dir(wd),
 	})
 }
 
@@ -263,11 +341,59 @@ func (s *Service) handleProfile(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, s.opts.Profile)
 }
 
-// handleAsks 会话登记表（core 的 `--sessions`）：列表页的「最近会话」用它。
+// extraSessionClients 移动端 H5 的会话列表**额外放行**的来源客户端（2026-10-15）。
+//
+// 背景：handleSessions 原先只回「本插件 AppID（Profile.AppID）」发起的会话。但掌天瓶
+// （magic-test）桌面壳**不经本插件发起** —— 它直接 exec core，并注入
+// MAGIC_AGENT_CLIENT=magic-test（见 magic-test/desktop/agent-cli.cjs 的 AGENT_CLIENT）。
+// 只按 AppID 过滤会把它整条滤掉，于是「掌天瓶新建的会话」在移动端根本看不见
+// （用户 2026-10-15：「通过 magic-test 新建的会话要在 magic-agent 移动端 h5 上看到，
+// 同时 magic-agent 上可以看到 magic-test 和 magic-agent 来源的会话」）。
+//
+// 名单两项：magic-test = 掌天瓶桌面壳；magic-agent = core 自身/直连 CLI 的显式标识。
+// ⚠️ 只放行**同族的 magic-* 来源**：匿名（空 client = 手工跑 / CI）与不相干应用仍被挡在
+// 外面 —— 这正是原过滤要避免的「把别人的任务混进本应用的会话列表」。
+var extraSessionClients = []string{"magic-test", "magic-agent"}
+
+// handleSessions 会话登记表（core 的 `--sessions`）：列表页的「最近会话」用它。
 // 与 /desk/asks 的区别：asks 是**本进程正在跑的轮次**（内存里），sessions 是 core 的
 // 持久登记表（跨进程、含已结束的）。
+//
+// ⚠️ 只回「本客户端」与「同族 magic-* 来源」的会话：登记表目录是全机共享的
+// （~/.magic-agent/sessions），直接跑 CLI（匿名）、CI、别的 magic-* 应用都在往里写 ——
+// 原样转发等于把别人的任务混进本应用的会话列表。认客户端靠 core 落的 Record.Client
+// （本插件在 /desk/ask 时注入自己的 AppID；掌天瓶桌面壳注入 magic-test）。
+// 放行名单见 extraSessionClients（2026-10-15 起，不再是「只认自己」）。
 func (s *Service) handleSessions(w http.ResponseWriter, r *http.Request) {
-	s.proxyCore(w, r, "--sessions")
+	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, s.opts.MagicAgent, "--sessions").Output()
+	if err != nil {
+		writeErr(w, http.StatusBadGateway,
+			fmt.Sprintf("%s --sessions 失败：%v", s.opts.MagicAgent, err))
+		return
+	}
+	/* 解成 map 再原样编码，而不是在这里定一个结构体：core 往后给会话行加字段时
+	   插件不用跟着改 —— 它只用到 client 一个字段。解不动就**原样透传**：core 换了
+	   输出形状时宁可让客户端看到异常，也不要静默给一个空列表（空列表看起来像
+	   「压根没有会话」，是最难查的一种）。 */
+	var rows []map[string]any
+	if err := json.Unmarshal(out, &rows); err != nil {
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		_, _ = w.Write(out)
+		return
+	}
+	allowed := map[string]bool{s.opts.Profile.AppID(): true}
+	for _, c := range extraSessionClients {
+		allowed[c] = true
+	}
+	mine := make([]map[string]any, 0, len(rows))
+	for _, row := range rows {
+		if c, _ := row["client"].(string); allowed[c] {
+			mine = append(mine, row)
+		}
+	}
+	writeJSON(w, http.StatusOK, mine)
 }
 
 // handleSessionMessages 「看历史」持久化落盘的会话事件（`GET /desk/session/{id}/messages`）。
@@ -289,8 +415,31 @@ func (s *Service) handleSessions(w http.ResponseWriter, r *http.Request) {
 // 后注册的 pattern 并不会自动赢；而带 `{id}` 通配的新式 pattern 需要 Go 1.22+。
 // 在入口处显式分派既不看 Go 版本脸色，也让「有哪些子路径」集中在一处可读。
 func (s *Service) handleSessionMessages(w http.ResponseWriter, r *http.Request) {
+	if r.Method == http.MethodDelete {
+		s.handleSessionDelete(w, r)
+		return
+	}
+	// POST / PUT 只服务**标题**这两条子路径（写标题 / 让 core 归纳标题）。
+	// 别的子路径（messages / events）上这两个方法仍然是「方法不允许」——
+	// 不能因为新增了 title 路由就把 POST /messages 从 405 变成 400：
+	// 405 说的是「这个方法在这个资源上不行」，400 说的是「请求本身不合法」，含义不同。
+	if r.Method == http.MethodPost || r.Method == http.MethodPut {
+		id, action, ok := parseSessionPath(r.URL.Path)
+		if ok && (action == "title" || action == "title/summarize") {
+			if action == "title" {
+				// POST 与 PUT 同义：都是**写**标题（人工重命名）。客户端用哪个都行。
+				s.handleSessionTitle(w, r, id)
+			} else {
+				s.handleSessionTitleSummarize(w, r, id)
+			}
+			return
+		}
+		writeErr(w, http.StatusMethodNotAllowed,
+			"POST / PUT 只支持 /desk/session/{id}/title 与 /desk/session/{id}/title/summarize")
+		return
+	}
 	if r.Method != http.MethodGet {
-		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		writeErr(w, http.StatusMethodNotAllowed, "GET / DELETE / POST / PUT only")
 		return
 	}
 	id, action, ok := parseSessionPath(r.URL.Path)
@@ -315,14 +464,190 @@ func (s *Service) handleSessionMessages(w http.ResponseWriter, r *http.Request)
 		writeErr(w, http.StatusInternalServerError, "读历史失败：找不到历史目录："+derr.Error())
 		return
 	}
-	evs, err := session.ReadSessionLog(dir, id, sessionEventMapFromJSON)
+	/* 客户端手里的 id 可能还是 run_id（正在跑的会话在引擎吐 session_id 之前，
+	   登记表里只有 run_id）—— 日志文件名按 session_id 落，先翻一次名，
+	   否则「点开正在跑的会话」读到空历史（静默失败）。见 session.ResolveLogID。
+	   翻出来的 id 照实回报（下面的 session 字段）：客户端因此能拿到真正的 session_id。 */
+	id = session.ResolveLogID(dir, id)
+	/* lean 要在**解码前**生效：snapshot 是二次方膨胀的累积串（实测单会话 283MB），
+	   先 Unmarshal 再删字段等于把这份开销白付一遍 —— 读一次 6~7s。
+	   ReadSessionLogLean 在字节层整段摘掉它，输出字段集与「先读后删」一致。 */
+	lean := queryLean(r)
+	var evs []map[string]any
+	var err error
+	/* `?before=N&limit=M`：反向分页（默认只画最近一轮，上翻再要更早的）。
+	   `before` 是「从文件尾跳过多少条非空行」，不是 seq —— 老日志每轮 seq 从 1 重来，
+	   拿 seq 当游标会在 run 边界整段丢掉更早的历史（见 session.ReadSessionLogBefore）。
+	   只要请求没带 `before`，行为与字段与旧版逐字段一致（只增参数，不升契约版本）。 */
+	if q := r.URL.Query(); q.Has("before") {
+		before, plerr := strconv.ParseUint(strings.TrimSpace(q.Get("before")), 10, 64)
+		if plerr != nil {
+			writeErr(w, http.StatusBadRequest, "before 必须是非负整数："+q.Get("before"))
+			return
+		}
+		limit := 200
+		if v := strings.TrimSpace(q.Get("limit")); v != "" {
+			n, lerr := strconv.Atoi(v)
+			if lerr != nil || n <= 0 {
+				writeErr(w, http.StatusBadRequest, "limit 必须是正整数："+v)
+				return
+			}
+			if n > 2000 {
+				n = 2000
+			}
+			limit = n
+		}
+		// 一页必须含轮次起点：客户端按轮渲染，页头切在轮中间会让思考/正文各半截。
+		alignToUser := func(e map[string]any) bool { return eventKind(e) == "user" }
+		var nextBefore uint64
+		var more bool
+		if lean {
+			evs, nextBefore, more, err = session.ReadSessionLogBeforeLean(dir, id, before, limit, alignToUser, sessionEventMapFromJSON)
+		} else {
+			evs, nextBefore, more, err = session.ReadSessionLogBefore(dir, id, before, limit, alignToUser, sessionEventMapFromJSON)
+		}
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, "读历史失败："+err.Error())
+			return
+		}
+		if lean {
+			evs = leanSessionEvents(evs)
+		}
+		var firstSeq uint64
+		if len(evs) > 0 {
+			firstSeq = mapSeqOf(evs[0])
+		}
+		writeJSON(w, http.StatusOK, map[string]any{
+			"session": id, "count": len(evs), "firstSeq": firstSeq,
+			"nextBefore": nextBefore, "more": more, "events": evs,
+		})
+		return
+	}
+	if lean {
+		/* 走「after=0 的增量读」而不是 ReadSessionLogLean：两者输出完全一致，但前者
+		   会顺带算出文件最大 seq 并留下尾部游标（见 session.tailMark）—— 客户端紧接着
+		   用 /events?after=<最后一条 seq> 轮询时就能直接 seek 到尾部，否则首次轮询还要
+		   把整份文件再全量扫一遍（长会话 = 又赔 2~3s）。 */
+		evs, _, err = session.ReadSessionLogAfterLean(dir, id, 0, mapSeqOf, sessionEventMapFromJSON)
+	} else {
+		evs, err = session.ReadSessionLog(dir, id, sessionEventMapFromJSON)
+	}
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, "读历史失败："+err.Error())
 		return
 	}
+	if lean {
+		evs = leanSessionEvents(evs)
+	}
 	writeJSON(w, http.StatusOK, map[string]any{"session": id, "events": evs})
 }
 
+// queryLean 解析 `?lean=1`：与 CLI 的 `--session-log-lean` 同一口径（**只增参数**，
+// 不传时输出与旧版逐字段一致 —— 所以不需要升 contractVersion）。
+//
+// 为什么 HTTP 侧也要这个开关：移动端（client-ui-mobile）与 PC Web UI 都直接吃
+// 这两个接口，CLI 侧的裁剪对它们无效。长会话里 snapshot 是二次方膨胀
+// （实测 9.4 万条 thinking = 283MB 快照），不裁就要在手机上解析整份 300MB+ JSON。
+func queryLean(r *http.Request) bool {
+	switch strings.ToLower(strings.TrimSpace(r.URL.Query().Get("lean"))) {
+	case "1", "true", "yes", "on":
+		return true
+	}
+	return false
+}
+
+// leanToolOutMax 是 lean 输出里单条 tool_result 的字符上限。
+//
+// 与对话内核的 QA_TOOL_OUT_MAX（client-ui/shared/conv/09-stream-apply.js）取同一个值：
+// 渲染侧本来就把工具输出截到这里，再多传的字节**一个都不会显示**。实测一条 338MB
+// 的会话，404 条 tool_result 全文占 26.9MB（最长单条 1.6MB），截断后整包从 51MB 降到 25MB。
+// 按 rune 截断（不是字节），避免把中文/emoji 切成半个字符。
+const leanToolOutMax = 12000
+
+// leanSessionEvents 输出侧做三件事：裁快照、截超长工具输出、合并相邻思考增量。
+//
+// 与 CLI 的 stripSnapshots 同源：回放只用增量 `text` 自己拼，全仓没有消费方读
+// 事件级 snapshot（见 cli/sessionlog.go 的说明）。删键而不是置空串：CLI 侧
+// 该字段是 omitempty，两边输出才能继续「逐字段对齐」（见 CLIENT-CONTRACT 3.4）。
+//
+// 相邻 thinking 合并：日志是按流式增量落盘的（实测一条长会话 95838 条事件里
+// 94015 条是 ~3 字符的思考分片）。客户端的思考区本来就是「一段连续 thinking
+// 一块」，逐条喂只是把同一段文本追加九万次 —— 手机浏览器实测这一步独占 16s
+// （整段回放 19.6s 的长任务）。合并后同一条会话只剩 2020 条事件，画面完全等价。
+// ⚠️ 只合并**相邻**的（中间夹了别的 kind 就断开），且保留末条的 seq/at/status：
+// 客户端游标按 seq 前进，取首条会让它下次重拉同一批。
+// ⚠️ 只改输出，磁盘上的 jsonl 原样保留。
+func leanSessionEvents(evs []map[string]any) []map[string]any {
+	if len(evs) == 0 {
+		return evs // 空日志保持 nil / 原样：/messages 的 null 语义已有测试钉着
+	}
+	out := make([]map[string]any, 0, len(evs))
+	for i := 0; i < len(evs); i++ {
+		e := evs[i]
+		delete(e, "snapshot")
+		kind, _ := e["kind"].(string)
+		if kind == "thinking" {
+			j := i + 1
+			for j < len(evs) && eventKind(evs[j]) == "thinking" {
+				delete(evs[j], "snapshot")
+				j++
+			}
+			if j > i+1 {
+				var b strings.Builder
+				for k := i; k < j; k++ {
+					s, _ := evs[k]["text"].(string)
+					b.WriteString(s)
+				}
+				merged := make(map[string]any, len(e)+1)
+				for k, v := range e {
+					merged[k] = v
+				}
+				last := evs[j-1]
+				for _, k := range []string{"seq", "at", "item_revision", "status"} {
+					if v, ok := last[k]; ok {
+						merged[k] = v
+					}
+				}
+				merged["text"] = b.String()
+				e = merged
+				i = j - 1
+			}
+			out = append(out, e)
+			continue
+		}
+		if kind == "tool_result" {
+			if text, ok := e["text"].(string); ok && len(text) > leanToolOutMax {
+				e["text"] = truncRunes(text, leanToolOutMax)
+			}
+		}
+		out = append(out, e)
+	}
+	return out
+}
+
+func eventKind(e map[string]any) string {
+	k, _ := e["kind"].(string)
+	return k
+}
+
+// truncRunes 把 s 截到最多 max 个字符（rune），max <= 0 视为不截。
+//
+// 为什么不写 []rune(s)[:max]：工具输出可能是几 MB，整串转 []rune 要按 4 字节/字符
+// 重新分配一遍；这里只在 rune 边界上前进到第 max 个就返回，代价与截断长度成正比。
+func truncRunes(s string, max int) string {
+	if max <= 0 {
+		return s
+	}
+	n := 0
+	for i := range s {
+		if n == max {
+			return s[:i]
+		}
+		n++
+	}
+	return s
+}
+
 // sessionEventMapFromJSON 把 jsonl 的一行解析成 map（plugin 不依赖 cli 的 schema）。
 func sessionEventMapFromJSON(line []byte) (map[string]any, error) {
 	var m map[string]any
@@ -332,6 +657,197 @@ func sessionEventMapFromJSON(line []byte) (map[string]any, error) {
 	return m, nil
 }
 
+// ── 会话标题 ─────────────────────────────────────────────────────────────
+// core 的会话标题原本是从首条提示词派生的（prompt_head），没有「可改标题」的存储；
+// 覆盖表由本插件维护（落 ~/.magic-agent/session-titles.json），由 GET /desk/titles
+// 传给客户端合并（不改动 core 的 --sessions 输出）。
+//
+// 2026-10-15：归纳口径收进 core（internal/session/title.go 的 Summarize）之后，
+// **存储也跟着搬到 core** —— 两份实现意味着两份磁盘格式，迟早不一致。
+// 这里改成薄转发：读写都走 session 包，落盘路径不变（用户已有的重命名结果不丢）。
+// 另：--sessions 现在直接给 `title` 字段（core 已合并「覆盖 → prompt_head」），
+// 客户端可以只读它；/desk/titles 保留给仍在用覆盖表合并的老客户端。
+func titleStorePath() (string, error) { return session.TitleStorePath() }
+func loadTitles() map[string]string   { return session.Titles() }
+func saveTitles(m map[string]string) error {
+	// 整表覆盖的语义在 core 侧是「按 id 逐条改」，这里转一遍：
+	// 先把差异算出来，只写真实变化的那几条，避免无谓的写盘与并发覆盖。
+	want := map[string]string{}
+	for k, v := range m {
+		if cur := session.TitleFor(k); cur != v {
+			want[k] = v
+		}
+	}
+	for k := range session.Titles() {
+		if _, keep := m[k]; !keep {
+			want[k] = "" // 空标题 = 清除覆盖
+		}
+	}
+	var firstErr error
+	for k, v := range want {
+		if err := session.SetTitle(k, v); err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	return firstErr
+}
+
+// handleDirs GET /desk/dirs?path=<abs>：列某目录下的子目录（默认 = 工作空间根 = 插件 cwd 的父目录）。
+// 只允许浏览 $HOME 之内的路径 —— 令牌只是本机访问控制，别把它当成整个文件系统的浏览器。
+func (s *Service) handleDirs(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	home, _ := os.UserHomeDir()
+	p := strings.TrimSpace(r.URL.Query().Get("path"))
+	if p == "" {
+		wd, _ := os.Getwd()
+		p = filepath.Dir(wd)
+	}
+	abs, err := filepath.Abs(p)
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "路径不合法："+err.Error())
+		return
+	}
+	if home != "" && abs != home && !strings.HasPrefix(abs, home+string(filepath.Separator)) {
+		writeErr(w, http.StatusForbidden, "只允许浏览家目录内的路径")
+		return
+	}
+	ents, err := os.ReadDir(abs)
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "读取目录失败："+err.Error())
+		return
+	}
+	dirs := make([]map[string]any, 0, len(ents))
+	for _, e := range ents {
+		if !e.IsDir() || strings.HasPrefix(e.Name(), ".") {
+			continue
+		}
+		dirs = append(dirs, map[string]any{"name": e.Name(), "path": filepath.Join(abs, e.Name())})
+	}
+	sort.Slice(dirs, func(i, j int) bool { return dirs[i]["name"].(string) < dirs[j]["name"].(string) })
+	writeJSON(w, http.StatusOK, map[string]any{"path": abs, "dirs": dirs})
+}
+
+// handleTitles GET /desk/titles：返回全部 sid→标题 覆盖（客户端拿去与 /desk/sessions 合并）。
+func (s *Service) handleTitles(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	writeJSON(w, http.StatusOK, loadTitles())
+}
+
+// handleSessionTitle PUT /desk/session/{id}/title：设置/清除会话标题（空标题 = 清除覆盖）。
+func (s *Service) handleSessionTitle(w http.ResponseWriter, r *http.Request, id string) {
+	var body struct {
+		Title string `json:"title"`
+	}
+	if err := json.NewDecoder(io.LimitReader(r.Body, 1<<16)).Decode(&body); err != nil {
+		writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
+		return
+	}
+	if err := session.SetTitle(id, body.Title); err != nil {
+		writeErr(w, http.StatusInternalServerError, "保存标题失败："+err.Error())
+		return
+	}
+	t := strings.TrimSpace(body.Title)
+	if t == "" {
+		t = session.TitleFor(id)
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"id": id, "title": t})
+}
+
+// handleSessionTitleSummarize POST /desk/session/{id}/title/summarize：
+// 让 **core** 归纳这条会话的标题（`magic-agent --summarize-title <id>`）。
+//
+// 为什么要有这条（用户 2026-10-15：「应该 magic-agent 统一归纳作为会话标题」）：
+// 归纳此前只有业务项目在做，于是同一会话在 PC 与移动端显示不同标题，且**从本插件
+// （/desk/ask）发起的会话根本没人替它归纳** —— 只能回落 prompt_head 首问原文。
+// 口径收进 core 之后，两个客户端都调这一条，同一句话必然得到同一个标题。
+//
+// 输入不给原文、由 core 从会话历史自己取：调用方不再各截各的（截断长度不同 → 归纳不同）。
+//
+// 幂等：core 侧已有覆盖就直接返回（cached=true），不重复调 LLM。force=true 才重来一次。
+func (s *Service) handleSessionTitleSummarize(w http.ResponseWriter, r *http.Request, id string) {
+	if r.Method != http.MethodPost && r.Method != http.MethodPut {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	var body struct {
+		Force bool `json:"force"`
+	}
+	// 允许空体：客户端只想「帮我归纳」时不必凑 JSON。
+	if r.Body != nil {
+		_ = json.NewDecoder(io.LimitReader(r.Body, 1<<16)).Decode(&body)
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
+	defer cancel()
+	args := []string{"--summarize-title", id}
+	if body.Force {
+		args = append(args, "--title-force")
+	}
+	out, err := exec.CommandContext(ctx, s.opts.MagicAgent, args...).Output()
+	if err != nil {
+		// core 的失败原因写在 stderr，原样带回：只回「归纳失败」调用方没法排障。
+		msg := strings.TrimSpace(string(out))
+		if ee, ok := err.(*exec.ExitError); ok && len(ee.Stderr) > 0 {
+			msg = strings.TrimSpace(string(ee.Stderr))
+		}
+		if msg == "" {
+			msg = err.Error()
+		}
+		writeErr(w, http.StatusBadGateway, "归纳标题失败："+truncateForMsg(msg))
+		return
+	}
+	var res session.SummaryResult
+	if err := json.Unmarshal(out, &res); err != nil {
+		// core 换了输出形状就如实报错，不要静默给空标题（那正是「两端不一致」的温床）。
+		writeErr(w, http.StatusBadGateway, "core 回的归纳结果不是 JSON："+truncateForMsg(string(out)))
+		return
+	}
+	writeJSON(w, http.StatusOK, res)
+}
+
+// truncateForMsg 报错文案截断（core 的 stderr 可能带整段提示词回显）。
+func truncateForMsg(s string) string {
+	s = strings.TrimSpace(s)
+	const cap = 200
+	r := []rune(s)
+	if len(r) <= cap {
+		return s
+	}
+	return string(r[:cap]) + "…"
+}
+
+// handleSessionDelete DELETE /desk/session/{id}：删掉一个会话 —— 登记表记录（可多条 run）
+// 与落盘的事件日志。id 可以是 session_id 或 run_id。
+//
+// 为什么两个都删：列表(/desk/sessions)读登记表、历史(/messages)读日志文件 —— 只删一个会
+// 留下「列表有、点开空」或「看不见、磁盘还占着」的错位状态。
+//
+// ⚠️ 日志文件**两个名字都要试**（2026-10-18 修）：文件按 session_id 落是**理想**，而引擎
+// 不调 OnSessionID 时（codex 这一脉）它整轮都叫 `<run_id>.jsonl`（见 session.ResolveLogID
+// 那段注释）。只删 `<session_id>.jsonl` 的话，客户端按 session_id 删（列表页的主键就是它）
+// 会留下一个 175KB 的孤儿日志 —— 列表里没了、磁盘上还占着。
+// 2026-10-19：实现挪进 `session.Delete`（internal/session/delete.go）—— CLI 新增的
+// `--delete-session` 走的是同一份，两条路不再各写一遍（此前只有本接口能做真删除，
+// 于是桌面端只能在自己本地藏起来，出现「PC 删了、移动端还在」）。
+func (s *Service) handleSessionDelete(w http.ResponseWriter, r *http.Request) {
+	id, action, ok := parseSessionPath(r.URL.Path)
+	if !ok || action != "" {
+		writeErr(w, http.StatusBadRequest, "session id 不能为空，且不接受子路径")
+		return
+	}
+	res, err := session.Delete(id)
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, fmt.Sprintf("删除会话 %s 失败：%v", id, err))
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"id": res.ID, "recordsRemoved": res.RecordsRemoved})
+}
+
 // parseSessionPath 从 `/desk/session/{id}/{action}` 拆出 id 与 action，并做**路径安全校验**。
 //
 // 返回 ok=false 的唯一情形是 id 为空或等于 `.` / `..`（调用方回 400）。
@@ -398,7 +914,17 @@ func (s *Service) handleSessionEvents(w http.ResponseWriter, r *http.Request, id
 		writeErr(w, http.StatusInternalServerError, "读历史失败：找不到历史目录："+derr.Error())
 		return
 	}
-	evs, maxSeq, err := session.ReadSessionLogAfter(dir, id, after, mapSeqOf, sessionEventMapFromJSON)
+	// 同 /messages：run_id 先翻成 session_id（正在跑的会话只有 run_id 可用）。
+	id = session.ResolveLogID(dir, id)
+	lean := queryLean(r)
+	var evs []map[string]any
+	var maxSeq uint64
+	var err error
+	if lean {
+		evs, maxSeq, err = session.ReadSessionLogAfterLean(dir, id, after, mapSeqOf, sessionEventMapFromJSON)
+	} else {
+		evs, maxSeq, err = session.ReadSessionLogAfter(dir, id, after, mapSeqOf, sessionEventMapFromJSON)
+	}
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, "读历史失败："+err.Error())
 		return
@@ -408,6 +934,9 @@ func (s *Service) handleSessionEvents(w http.ResponseWriter, r *http.Request, id
 	if evs == nil {
 		evs = []map[string]any{}
 	}
+	if lean {
+		evs = leanSessionEvents(evs)
+	}
 	writeJSON(w, http.StatusOK, map[string]any{
 		"session": id,
 		"events":  evs,
@@ -526,11 +1055,35 @@ func (s *Service) handleAsks(w http.ResponseWriter, r *http.Request) {
 		ID      string `json:"id"`
 		Engine  string `json:"engine"`
 		Started string `json:"started"`
+		// Session 这一轮挂在哪个会话上（2026-10-20 打开运行中会话续传）。
+		// 客户端打开某个会话时用它认出「这条会话还有一轮在跑」，从而接回实时流。
+		// 空 = 新会话（core 还没吐出 session_id 之前也可能为空）。
+		Session string `json:"session,omitempty"`
+		// Run 本次运行的 run_id（core 的 ready 行带出）。新会话首轮引擎可能整轮都不吐
+		// session_id，此时登记表（/desk/sessions）里这条会话只有 run_id —— 客户端
+		// 拿它与会话 id 比对才能认领这一轮。
+		Run string `json:"run,omitempty"`
 	}
 	s.mu.Lock()
 	items := make([]item, 0, len(s.runs))
 	for _, run := range s.runs {
-		items = append(items, item{ID: run.id, Engine: run.engine, Started: run.started.Format(time.RFC3339)})
+		// 跑完的 ask 会在 s.runs 里多留 askRetention（供断线续传补拉终态），
+		// 但「正在跑」列表不能把它们算进去，否则客户端会以为还有任务在排队。
+		run.mu.Lock()
+		ended := run.ended
+		sid := run.session
+		rid := run.run
+		run.mu.Unlock()
+		if ended {
+			continue
+		}
+		items = append(items, item{
+			ID:      run.id,
+			Engine:  run.engine,
+			Started: run.started.Format(time.RFC3339),
+			Session: sid,
+			Run:     rid,
+		})
 	}
 	s.mu.Unlock()
 	writeJSON(w, http.StatusOK, items)
@@ -561,6 +1114,12 @@ type askRequest struct {
 	// codebuddy-ai）；所以这里只在客户端真的要选档位时才加这个参数，不要替 core 猜默认值，
 	// 否则会把「显式指定」与「沿用默认」两种语义混成一种。
 	Permission string `json:"permission,omitempty"`
+	// Reasoning 思考档位（off | minimal | low | medium | high | xhigh | max），透传给
+	// core 的 --reasoning（2026-10-20 只增字段）。空 = 不传 —— core 自己的默认档是 max
+	// （开着），所以「关闭思考」必须**显式传 off**，省略等于开着 + 最高档。
+	// ⚠️ 只有 /desk/engines 里 reasoning=true 的引擎才该传；老版本 core 不认识该 flag
+	// （exit 2），客户端据该字段缺失来决定不下发。
+	Reasoning string `json:"reasoning,omitempty"`
 	// Session 续接一个已有会话（传 /desk/sessions 里的 session_id 或 run_id）。
 	// 空 = 新会话。
 	Session    string `json:"session,omitempty"`
@@ -568,9 +1127,17 @@ type askRequest struct {
 	// Idle 常驻会话空闲收工时长；默认 0 = 本轮结束就收工（客户端驱动的轮次语义）。
 	// >0 才留常驻窗口（此时 answer 命令在轮次结束后仍可用）。
 	Idle string `json:"idle,omitempty"`
+	// Attachments 附件**本机绝对路径**清单（移动端先 POST /desk/upload 拿到路径再回传）。
+	// 逐条透传给 core 的 -a/--attach；core 侧再校验存在性与体积。附件是本地路径，
+	// 只有 core 所在的这台机器认识它（跨机路径无意义）。
+	Attachments []string `json:"attachments,omitempty"`
+	// Client 发起方自报的客户端类型：mobile | pc。
+	// 为什么不能只看 Origin：移动端是**加载 /m/ 页面**（与桌面同源）跑起来的，
+	// 同源请求分不出手机还是电脑，所以由客户端显式声明（见 shared/transport-http.js）。
+	Client string `json:"client,omitempty"`
 }
 
-// askRun 一次正在跑的 ask。
+// askRun 一次 ask（跑完的还会短时保留，供断线续传补拉终态）。
 type askRun struct {
 	id      string
 	engine  string
@@ -578,8 +1145,145 @@ type askRun struct {
 	cmd     *exec.Cmd
 	stdin   io.WriteCloser
 	done    chan struct{}
-	code    int
 	stderr  *cappedBuffer
+
+	/* session 这一轮所属的会话 id（供 /desk/asks 暴露，客户端据此把「打开中的会话」
+	   接回实时流）。建 run 时取请求里的 session；请求没带（新会话）就等第一条带
+	   session_id 的事件到达时补写（见 appendEvent）。受 mu 保护。 */
+	session string
+
+	/* run core 本次运行的 run_id（ready 行里带出）。引擎不吐 session_id 时，
+	   登记表里这条会话只有 run_id，/desk/asks 要把两者都给客户端才能认领。受 mu 保护。 */
+	run string
+
+	/* 事件回放缓冲（2026-10-19 断线续传）：core 的每一行原样留一份，客户端拿
+	   `GET /desk/ask/{id}/events?after=<seq>` 按 seq 增量补拉。
+	   为什么不直接复用会话日志（`/desk/session/{id}/events`）：
+	   日志里的 seq 是**跨轮接号**的（文件级），而 SSE 实时流里的 seq 是**每轮从 1**
+	   重来（进程级）—— 客户端手里的游标与日志对不上，续读会把整轮事件重新发一遍
+	   或者一条都不发。这份缓冲存的正是**与实时流同一套 seq** 的行。 */
+	mu      sync.Mutex
+	events  []askEvent
+	seq     uint64 // 已缓冲的最大 seq（事件自带 seq 缺失时它也不会退）
+	dropped bool   // 缓冲超限裁过旧事件（游标落在窗口外 ⇒ snapshotRequired）
+	ended   bool
+	code    int
+}
+
+// askEvent 缓冲里的一条：seq 用于增量过滤，data 是 core 原样的 NDJSON 行。
+type askEvent struct {
+	seq  uint64
+	data []byte
+}
+
+// askBufMaxEvents / askBufMaxBytes 一轮事件缓冲的上限（约 16MB）。
+//
+// 缓冲只活在「任务运行中 + 结束后保留期」这一段，正常一轮几十 KB 到几 MB；
+// 上限是给失控输出兜底的 —— 超过就丢最旧的并置 dropped，宁可少补中间几行，
+// 也不能让一个跑飞的引擎把网关进程撑爆。
+const (
+	askBufMaxEvents = 20000
+	askBufMaxBytes  = 16 << 20
+	// askRetention 跑完的 ask 保留多久（断线重连 / 补拉终态的时间窗）。
+	askRetention = 10 * time.Minute
+)
+
+// appendPrompt 把本轮的用户提问合成一条 `type:"user"` 事件塞进回放缓冲（2026-10-20）。
+//
+// 为什么必须在网关合成：core 的 stdout 事件流**从不发 user 事件**（`kind:"user"` 只写进
+// 会话日志），而断线续传补的是这份 ask 缓冲 —— 用户自己刚问的那句在补出来的画面上一个字
+// 都没有（真实报障：PC 端发了新追问，移动端打开只剩「生成中」）。
+//
+// 三条约束：
+//   - **只进缓冲、不进 SSE 直播流**（见 handleAsk）：实时那条路径上客户端已经自己画过
+//     用户气泡了，再中继一次就是两个气泡；
+//   - seq 固定 0：core 的流 seq 每轮从 1 起，0 不会与任何真实事件撞号，也不会推进客户端
+//     游标（handleAskEvents 里 `after == 0` 才放行它）；
+//   - `prompt_id` 是客户端去重的键：core 首行到达前客户端会反复以 after=0 轮询，没有它
+//     同一句提问会被画很多遍（见 client-ui/shared/conversation.js 的 render）。
+func (r *askRun) appendPrompt(text string, attachments []string) {
+	atts := make([]map[string]string, 0, len(attachments))
+	for _, p := range attachments {
+		if p = strings.TrimSpace(p); p != "" {
+			atts = append(atts, map[string]string{"path": p})
+		}
+	}
+	ev := map[string]any{
+		"type":      "user",
+		"text":      text,
+		"prompt_id": "u1",
+		"at":        r.started.UTC().Format(time.RFC3339Nano),
+	}
+	if len(atts) > 0 {
+		ev["attachments"] = atts
+	}
+	b, err := json.Marshal(ev)
+	if err != nil {
+		return
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	// 必须排在本轮所有 core 事件之前：数组顺序就是续传画面的顺序。调用点在 cmd.Start
+	// 之前（读 stdout 的 goroutine 还没起来），所以直接追加头一条即可。
+	r.events = append(r.events, askEvent{seq: 0, data: b})
+}
+
+// appendEvent 缓冲一行 core 事件（在**读 stdout 的 goroutine**里调用）。
+func (r *askRun) appendEvent(line string) {
+	seq, sid, rid := eventMetaOf(line)
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if sid != "" && r.session == "" {
+		// 新会话的 run 建的时候还不知道 session id，靠第一条带 session_id 的事件补上。
+		r.session = sid
+	}
+	if rid != "" && r.run == "" {
+		r.run = rid
+	}
+	if seq == 0 {
+		// core --events 的每一行都带 seq；真出现不带的行（历史版本 / 畸形行）就按
+		// 「到达序号」兜一个 —— 只用于续传过滤，不写回事件本身。
+		seq = r.seq + 1
+	}
+	if seq > r.seq {
+		r.seq = seq
+	}
+	r.events = append(r.events, askEvent{seq: seq, data: []byte(line)})
+	size := 0
+	for _, e := range r.events {
+		size += len(e.data)
+	}
+	drop := 0
+	for drop < len(r.events) && (len(r.events)-drop > askBufMaxEvents || size > askBufMaxBytes) {
+		size -= len(r.events[drop].data)
+		drop++
+	}
+	if drop > 0 {
+		r.events = append([]askEvent(nil), r.events[drop:]...)
+		r.dropped = true
+	}
+}
+
+// eventMetaOf 从一行 NDJSON 里取 seq / session_id / run_id（取不到就是零值）。
+// 同一行只 unmarshal 一次：这几个字段都要用，拆成多次解析纯属浪费。
+func eventMetaOf(line string) (uint64, string, string) {
+	var probe struct {
+		Seq       uint64 `json:"seq"`
+		SessionID string `json:"session_id"`
+		RunID     string `json:"run_id"`
+	}
+	if json.Unmarshal([]byte(line), &probe) != nil {
+		return 0, "", ""
+	}
+	return probe.Seq, probe.SessionID, probe.RunID
+}
+
+// finish 标记任务结束并记录退出码（读 stdout 的 goroutine 在 cmd.Wait 之后调用）。
+func (r *askRun) finish(code int) {
+	r.mu.Lock()
+	r.ended = true
+	r.code = code
+	r.mu.Unlock()
 }
 
 // handleAsk 发起一轮并**把 core 的 NDJSON 事件原样中继**给调用方（SSE）。
@@ -618,6 +1322,11 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 		"-e", engine,
 		"--stream", "--events", "--control",
 		"--idle", idle,
+		// 客户端要「列出/停止会话」与「点开看历史」，所以两个存档开关都恒开
+		// （core 侧默认都关，见 --save-registry / --save-history）：
+		//   · 少了 --save-registry → 会话不出现在列表、不能按 id 追加；
+		//   · 少了 --save-history  → has_log=false，进详情页历史空白（静默失败）。
+		"--save-registry", "--save-history",
 	}
 	if req.Model != "" {
 		args = append(args, "-m", req.Model)
@@ -629,18 +1338,63 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 	if p := strings.TrimSpace(req.Permission); p != "" {
 		args = append(args, "--permission", p)
 	}
+	// 思考档位：同样只在显式给了才传（空 = core 的默认 max）。
+	// off 也是显式值，不能因为「看起来像关闭」就省略 —— 省略恰好是「开着 + max」。
+	if r := strings.TrimSpace(req.Reasoning); r != "" {
+		args = append(args, "--reasoning", r)
+	}
 	if req.Session != "" {
 		args = append(args, "--session", req.Session)
 	}
 	if req.NoThinking {
 		args = append(args, "--no-thinking")
 	}
+	// 附件：逐个 -a/--attach。这里先做与 core 同口径的校验（普通文件 + 32MB 上限），
+	// 免得把非法路径丢给 core 再让它以 usage error 退出（那时错误更难定位）。
+	for _, a := range req.Attachments {
+		p := strings.TrimSpace(a)
+		if p == "" {
+			continue
+		}
+		if abs, err := filepath.Abs(p); err == nil {
+			p = abs
+		}
+		st, err := os.Stat(p)
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, "附件不可访问："+p)
+			return
+		}
+		if !st.Mode().IsRegular() {
+			writeErr(w, http.StatusBadRequest, "附件不是普通文件："+p)
+			return
+		}
+		if st.Size() > maxUploadBytes {
+			writeErr(w, http.StatusBadRequest, fmt.Sprintf("附件超过 %dMB：%s", maxUploadBytes>>20, p))
+			return
+		}
+		args = append(args, "-a", p)
+	}
 	args = append(args, "-p", req.Prompt)
 
-	ctx, cancel := context.WithCancel(r.Context())
-	defer cancel()
+	/* 子进程**不绑 HTTP 请求的生命周期**（2026-10-19）：此前用 r.Context()，手机端 SSE
+	   一断（锁屏 / 切后台 / WebView 回收 / 页面刷新）就会 SIGKILL core —— core 来不及写
+	   终态，登记表里那条会话就永远停在 running：界面显示「一直不结束」，移动端的串行门
+	   （同空间有 running 就排队）还会被它永久挡住，新任务发不出去。
+	   客户端断连只意味着「没人看直播了」，不是「取消任务」；任务只应由显式控制
+	   （/desk/ask/{id}/control 的 stop）或自然结束来终止。
+	   WithoutCancel 保留请求里的值（便于排障），但不继承取消信号。
+	   也**不能**在这里 WithCancel + defer cancel：handler 断连就会返回，defer 一执行
+	   就等于把仍在跑的任务杀掉 —— 那正是要修的行为。 */
+	ctx := context.WithoutCancel(r.Context())
 
 	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	/* 两个「谁发起的」维度随环境变量传给 core，落到会话登记表：
+	   · EnvSource  设备形态（mobile / pc）—— 按请求 Origin 判定，列表页显示设备标志；
+	   · EnvClient  发起方应用（本插件的 AppID）—— 列表页据此**只显示本客户端发起的会话**，
+	     不把直接跑 CLI / 别的应用的任务混进来（用户 2026-10-12）。 */
+	cmd.Env = append(os.Environ(),
+		session.EnvSource+"="+requestSource(req.Client, r.Header.Get("Origin")),
+		session.EnvClient+"="+s.opts.Profile.AppID())
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
 		writeErr(w, http.StatusInternalServerError, "stdin pipe: "+err.Error())
@@ -659,8 +1413,12 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 		stdin:   stdin,
 		done:    make(chan struct{}),
 		stderr:  newCappedBuffer(8 << 10),
+		session: strings.TrimSpace(req.Session),
 	}
 	cmd.Stderr = run.stderr
+	/* 用户这条提问先落进回放缓冲（不进 SSE 直播流）：core 的事件流里没有 user 事件，
+	   断线重连 / 打开运行中会话时补出来的画面会缺「用户问的是什么」。 */
+	run.appendPrompt(req.Prompt, req.Attachments)
 	if err := cmd.Start(); err != nil {
 		writeErr(w, http.StatusBadGateway, "启动 core 失败："+err.Error())
 		return
@@ -668,11 +1426,8 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 	s.mu.Lock()
 	s.runs[run.id] = run
 	s.mu.Unlock()
-	defer func() {
-		s.mu.Lock()
-		delete(s.runs, run.id)
-		s.mu.Unlock()
-	}()
+	// 注意：这里**不** defer 摘除 s.runs —— 断连后 handler 会先返回，任务仍在跑；
+	// 摘除由后台读 stdout 的 goroutine 在 core 真正退出时做（见下）。
 
 	// SSE 头必须在**第一行事件之前**发出，否则客户端拿到的是 application/json。
 	w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
@@ -691,43 +1446,114 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 	}
 	send("open", map[string]any{"id": run.id, "engine": engine, "core": s.opts.MagicAgent})
 
-	sc := bufio.NewScanner(stdout)
-	sc.Buffer(make([]byte, 0, 64*1024), 4<<20)
-	for sc.Scan() {
-		line := strings.TrimSpace(sc.Text())
-		if line == "" {
-			continue
+	/* SSE 心跳（2026-10-19 真实报障：手机端 17.7s 就「连接中断」，而 core 在首段输出前
+	   静默了约 27s —— 期间一个字节都没写，移动网络 / WebView 会把这条连接当成死连接掐掉，
+	   服务端任务其实一直跑到了 turn_end）。
+	   注释帧（以 ':' 开头、没有 data 行）按 SSE 规范会被客户端忽略，
+	   本仓库的 transport-http.js 解析器也只认 data 行，因此安全。 */
+	ping := time.NewTicker(10 * time.Second)
+	defer ping.Stop()
+
+	/* 读 stdout 与写 SSE 分开成两个 goroutine（2026-10-19）：
+	   客户端断连时 handler 立即返回，但**后台必须继续把 core 的 stdout 抽干** ——
+	   否则管道写满后 core 会阻塞在写事件上，任务反而被卡死。
+	   handler 走人之前关掉 detached，后台就改为「只 drain、不再入队」。 */
+	lines := make(chan string, 64)
+	detached := make(chan struct{})
+	finished := make(chan int, 1)
+	go func() {
+		sc := bufio.NewScanner(stdout)
+		sc.Buffer(make([]byte, 0, 64*1024), 4<<20)
+		gone := false
+		for sc.Scan() {
+			line := strings.TrimSpace(sc.Text())
+			if line == "" {
+				continue
+			}
+			// 先入回放缓冲，再判断有没有人在看直播：断连之后客户端要靠这份缓冲
+			// 按 seq 续传，漏掉「gone 之后」的行就等于把断点之后的内容丢了。
+			run.appendEvent(line)
+			if gone {
+				continue // 没人看了：只 drain，避免 core 写满管道
+			}
+			select {
+			case lines <- line:
+			case <-detached:
+				gone = true
+			}
 		}
-		// 原样中继：核心事件流自己就是 NDJSON，不再包一层。
-		fmt.Fprintf(w, "data: %s\n\n", line)
-		if flusher != nil {
-			flusher.Flush()
+		close(lines)
+		werr := cmd.Wait()
+		code := 0
+		if werr != nil {
+			var ee *exec.ExitError
+			if errors.As(werr, &ee) {
+				code = ee.ExitCode()
+			} else {
+				code = -1
+			}
 		}
-	}
-	werr := cmd.Wait()
-	code := 0
-	if werr != nil {
-		var ee *exec.ExitError
-		if errors.As(werr, &ee) {
-			code = ee.ExitCode()
-		} else {
-			code = -1
+		run.finish(code)
+		close(run.done)
+		/* 任务结束后**不立刻摘除**：客户端可能在断线重连后在补拉终态
+		   （`GET /desk/ask/{id}/events`），留 askRetention 的时间窗。
+		   保留期内若同一个 id 被重新登记（不可能，id 唯一）也不覆盖。
+		   handleAsks 会按 ended 过滤，所以这个「僵尸条目」不会出现在运行中列表。 */
+		time.AfterFunc(askRetention, func() {
+			s.mu.Lock()
+			if cur := s.runs[run.id]; cur == run {
+				delete(s.runs, run.id)
+			}
+			s.mu.Unlock()
+		})
+		finished <- code
+	}()
+	// 断连后后台继续跑完任务；handler 只负责把已有事件送出去。
+	defer close(detached)
+
+	for {
+		select {
+		case line, ok := <-lines:
+			if !ok {
+				lines = nil // 等 finished（stdout 已读尽，core 正在退出）
+				continue
+			}
+			// 原样中继：核心事件流自己就是 NDJSON，不再包一层。
+			fmt.Fprintf(w, "data: %s\n\n", line)
+			if flusher != nil {
+				flusher.Flush()
+			}
+		case code := <-finished:
+			send("end", map[string]any{"id": run.id, "code": code, "stderr": run.stderr.String()})
+			return
+		case <-ping.C:
+			// 心跳：只养连接，不下发业务数据（解析端会忽略没有 data 行的帧）。
+			fmt.Fprint(w, ": ping\n\n")
+			if flusher != nil {
+				flusher.Flush()
+			}
+		case <-r.Context().Done():
+			return
 		}
 	}
-	run.code = code
-	close(run.done)
-	send("end", map[string]any{"id": run.id, "code": code, "stderr": run.stderr.String()})
 }
 
-// handleAskSub 处理 `/desk/ask/{id}/control`：把一条控制命令写进 core 的 stdin。
-//
-// 这就是「手机回审批」的服务侧路径 —— 命令格式与 core 的 --control 契约一致，
-// 插件不解释 op，只转发（解析权在 core）。
+// handleAskSub 处理 `/desk/ask/{id}/{action}`：
+//   - `control`：把一条控制命令写进 core 的 stdin；
+//   - `events` ：按 seq 增量补拉本轮事件（断线续传 / 补拉终态）。
 func (s *Service) handleAskSub(w http.ResponseWriter, r *http.Request) {
 	rest := strings.TrimPrefix(r.URL.Path, "/desk/ask/")
 	parts := strings.Split(strings.Trim(rest, "/"), "/")
-	if len(parts) != 2 || parts[1] != "control" {
-		writeErr(w, http.StatusNotFound, "用法：POST /desk/ask/{id}/control")
+	if len(parts) != 2 {
+		writeErr(w, http.StatusNotFound, "用法：POST /desk/ask/{id}/control 或 GET /desk/ask/{id}/events?after=<seq>")
+		return
+	}
+	if parts[1] == "events" {
+		s.handleAskEvents(w, r, parts[0])
+		return
+	}
+	if parts[1] != "control" {
+		writeErr(w, http.StatusNotFound, "用法：POST /desk/ask/{id}/control 或 GET /desk/ask/{id}/events?after=<seq>")
 		return
 	}
 	if r.Method != http.MethodPost {
@@ -741,6 +1567,13 @@ func (s *Service) handleAskSub(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, http.StatusNotFound, "没有这个 ask（可能已结束）："+parts[0])
 		return
 	}
+	run.mu.Lock()
+	runEnded := run.ended
+	run.mu.Unlock()
+	if runEnded {
+		writeErr(w, http.StatusConflict, "本轮已结束，不能再下发控制："+parts[0])
+		return
+	}
 	var cmd struct {
 		Op     string `json:"op"`
 		Text   string `json:"text,omitempty"`
@@ -762,6 +1595,83 @@ func (s *Service) handleAskSub(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusAccepted, map[string]any{"queued": true, "op": cmd.Op, "id": run.id})
 }
 
+/*
+	handleAskEvents GET /desk/ask/{id}/events?after=<seq>
+
+断线续传的服务端一半（2026-10-19）：客户端手里只有 SSE 流里的 seq（每轮从 1 起），
+不能用会话日志的跨轮 seq 续读，所以这里回放的是**与实时流同一套 seq** 的原始事件行。
+
+返回：
+  - events         ：seq > after 的事件对象（core 原样的 NDJSON，已解成 JSON）
+  - lastSeq        ：本轮已缓冲的最大 seq（客户端下次带它来）
+  - done / code    ：本轮是否结束 + 退出码（结束前 code 无意义）
+  - stderr         ：结束后的 stderr（仅 done 时返回）
+  - snapshotRequired：游标落在被裁掉的窗口之前，客户端应重建本轮视角（清空重放）
+*/
+func (s *Service) handleAskEvents(w http.ResponseWriter, r *http.Request, id string) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	var after uint64
+	if v := strings.TrimSpace(r.URL.Query().Get("after")); v != "" {
+		n, err := strconv.ParseUint(v, 10, 64)
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, "after 必须是十进制序号："+v)
+			return
+		}
+		after = n
+	}
+	s.mu.Lock()
+	run := s.runs[id]
+	s.mu.Unlock()
+	if run == nil {
+		writeErr(w, http.StatusNotFound, "没有这个 ask（已过保留期）："+id)
+		return
+	}
+	run.mu.Lock()
+	events := make([]json.RawMessage, 0, len(run.events))
+	for _, e := range run.events {
+		/* seq == 0 是网关合成的「用户提问」（见 appendPrompt）：它不是 core 流里的序号，
+		   固定为 0、只在**从头补**（after == 0）时给一次 —— 客户端拿 prompt_id 去重。 */
+		if e.seq > after || (e.seq == 0 && after == 0) {
+			events = append(events, json.RawMessage(append([]byte(nil), e.data...)))
+		}
+	}
+	lastSeq := run.seq
+	dropped := run.dropped
+	firstSeq := uint64(0)
+	for _, e := range run.events {
+		// 跳过合成的提问事件（seq=0）：裁剪窗口的判据只认 core 事件的真实序号。
+		if e.seq > 0 {
+			firstSeq = e.seq
+			break
+		}
+	}
+	done := run.ended
+	code := run.code
+	run.mu.Unlock()
+
+	// after 落在裁剪窗口之前（或缓冲裁过且 after 追不上首条）⇒ 客户端缺了中间事件，
+	// 只能重建本轮画面；after >= firstSeq-1 表示断点仍在窗口内，可以安全增量。
+	snapshotRequired := dropped && len(events) > 0 && (firstSeq == 0 || after+1 < firstSeq)
+
+	resp := map[string]any{
+		"id":               id,
+		"events":           events,
+		"count":            len(events),
+		"after":            after,
+		"lastSeq":          lastSeq,
+		"done":             done,
+		"snapshotRequired": snapshotRequired,
+	}
+	if done {
+		resp["code"] = code
+		resp["stderr"] = run.stderr.String()
+	}
+	writeJSON(w, http.StatusOK, resp)
+}
+
 // handleModulesStatic 业务模块的静态资源：**先**项目的模块目录（profile 的 ui.modulesDir），
 // 再退回插件的 UI 目录（--ui-dir）。
 //
@@ -836,6 +1746,63 @@ func (s *Service) handleStatic(w http.ResponseWriter, r *http.Request) {
 	http.ServeFile(w, r, full)
 }
 
+// mobileRoot 解析移动端界面目录：显式 --mobile-dir 优先，否则取与 --ui-dir 同级的 client-ui-mobile。
+func (s *Service) mobileRoot() string {
+	if d := strings.TrimSpace(s.opts.MobileRoot); d != "" {
+		return d
+	}
+	if d := strings.TrimSpace(s.opts.UIRoot); d != "" {
+		return filepath.Join(filepath.Dir(d), "client-ui-mobile")
+	}
+	return ""
+}
+
+// handleMobileUI 远程移动端界面。
+//
+//	/m/            → <mobile>/index.html（页面本身）
+//	/m/assets/*    → <mobile>/assets/*（字体等）
+//	/m/shared/*    → <ui-dir>/shared/*（公共对话组件唯一来源，不在移动端目录里再存一份）
+//
+// 这样 APK 壳只要加载 <base>/m/?token=… 就能跑最新界面，改界面无需重打 APK。
+func (s *Service) handleMobileUI(w http.ResponseWriter, r *http.Request) {
+	mobile := s.mobileRoot()
+	if mobile == "" {
+		writeErr(w, http.StatusNotFound, "没有配置移动端界面目录（--mobile-dir）")
+		return
+	}
+	rel := strings.TrimPrefix(r.URL.Path, "/m")
+	if rel == "" || rel == "/" {
+		rel = "/index.html"
+	}
+	var root string
+	if strings.HasPrefix(rel, "/shared/") && strings.TrimSpace(s.opts.UIRoot) != "" {
+		root, _ = filepath.Abs(s.opts.UIRoot) // shared 复用 --ui-dir 下的那一份
+	} else {
+		root, _ = filepath.Abs(mobile)
+	}
+	full := filepath.Join(root, filepath.Clean("/"+rel))
+	if !strings.HasPrefix(full, root) {
+		writeErr(w, http.StatusForbidden, "路径越界")
+		return
+	}
+	f, err := os.Open(full)
+	if err != nil {
+		writeErr(w, http.StatusNotFound, "移动端资源不存在："+rel)
+		return
+	}
+	defer f.Close()
+	st, err := f.Stat()
+	if err != nil || st.IsDir() {
+		writeErr(w, http.StatusNotFound, "移动端资源不存在："+rel)
+		return
+	}
+	// 远程界面必须「改完立即生效」：不设这个头，WebView 会按启发式缓存把旧 HTML 留着，
+	// 桌面端改了界面、手机却还是老样子（今天就踩了一次）。no-cache = 每次回源校验。
+	w.Header().Set("Cache-Control", "no-cache")
+	// 与 /modules/ 同理：不用 ServeFile，避免 `/index.html` 触发 301 到 `/`。
+	http.ServeContent(w, r, st.Name(), st.ModTime(), f)
+}
+
 func (s *Service) nextID() string {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -877,6 +1844,455 @@ func hasStr(list []string, want string) bool {
 	return false
 }
 
+// maxUploadBytes 上传/附件单文件大小上限，与 core 的 maxAttachBytes（32MB）同口径。
+const maxUploadBytes = 32 << 20
+
+// handleUpload 收移动端上传的附件，落到 core 所在机器的临时目录，返回其**绝对路径**。
+// 路径随后由 /desk/ask 的 attachments 透传给 core 的 -a/--attach —— 附件是本地路径，
+// 只有 core 这台机器认识它，所以远端文件必须先上传过来。
+func (s *Service) handleUpload(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	r.Body = http.MaxBytesReader(w, r.Body, maxUploadBytes)
+	if err := r.ParseMultipartForm(maxUploadBytes); err != nil {
+		writeErr(w, http.StatusBadRequest, "解析上传失败："+err.Error())
+		return
+	}
+	file, hdr, err := r.FormFile("file")
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "缺少 file 字段："+err.Error())
+		return
+	}
+	defer file.Close()
+	dir := filepath.Join(os.TempDir(), "magic-client-uploads")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		writeErr(w, http.StatusInternalServerError, "创建上传目录失败："+err.Error())
+		return
+	}
+	name := sanitizeUploadName(hdr.Filename)
+	final := filepath.Join(dir, strconv.FormatInt(time.Now().UnixNano(), 10)+"-"+name)
+	out, err := os.OpenFile(final, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
+	if err != nil {
+		writeErr(w, http.StatusInternalServerError, "写入失败："+err.Error())
+		return
+	}
+	n, err := io.Copy(out, file)
+	cerr := out.Close()
+	if err != nil || cerr != nil {
+		_ = os.Remove(final)
+		writeErr(w, http.StatusInternalServerError, "写入失败")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"path": final, "name": name, "size": n, "mime": hdr.Header.Get("Content-Type"),
+		// url 供 <img src> 回读（缩略图 / 历史回看）：相对路径，客户端拼上自己的 base + token。
+		"url": "/desk/uploads/" + url.PathEscape(filepath.Base(final)),
+	})
+}
+
+// handleUploadGet GET /desk/uploads/{name}：回读已上传的附件（缩略图 / 历史回看）。
+// 只允许读上传目录内、文件名不含路径分隔的单层文件 —— 防目录穿越。
+// <img> 带不了 X-Magic-Token 自定义头，所以这条路径靠 guard 支持的 ?token= 过鉴权。
+func (s *Service) handleUploadGet(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodHead {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	name := strings.TrimSpace(strings.TrimPrefix(r.URL.Path, "/desk/uploads/"))
+	if name == "" || name == "." || name == ".." ||
+		strings.ContainsAny(name, `/\`) || filepath.Base(name) != name {
+		writeErr(w, http.StatusBadRequest, "非法文件名")
+		return
+	}
+	full := filepath.Join(os.TempDir(), "magic-client-uploads", name)
+	f, err := os.Open(full)
+	if err != nil {
+		writeErr(w, http.StatusNotFound, "文件不存在")
+		return
+	}
+	defer f.Close()
+	st, err := f.Stat()
+	if err != nil || st.IsDir() {
+		writeErr(w, http.StatusNotFound, "文件不存在")
+		return
+	}
+	// ?w=<px>：移动端慢网下按需缩放（仅图片；解不了就原样回）。
+	if tw := thumbWidth(r); tw > 0 {
+		if data, mime, ok := scaledImageData(full, st, tw); ok {
+			w.Header().Set("Content-Type", mime)
+			w.Header().Set("Cache-Control", "private, max-age=86400")
+			http.ServeContent(w, r, st.Name(), st.ModTime(), bytes.NewReader(data))
+			return
+		}
+	}
+	w.Header().Set("Cache-Control", "private, max-age=86400")
+	http.ServeContent(w, r, st.Name(), st.ModTime(), f)
+}
+
+// handleMediaFile GET /desk/media?path=<abs>：按**绝对路径**回读一个本机媒体文件。
+// 用途：对话里「被操作过的文件」出缩略图、会话产物出预览（图 / 视频 / 音频）—— 那些路径
+// 在 core 这台机器上，且不在上传目录里，所以不能走 /desk/uploads。
+//
+// ⚠️ 这是一条「按路径取文件」的通道，所以**只放行媒体**（内容嗅探为主、扩展名兜底）
+// 且限体积，避免变成任意文件读取。<img>/<video> 带不了 X-Magic-Token 自定义头，故支持 ?token=。
+// http.ServeContent 自带 Range：视频可以拖进度。
+func (s *Service) handleMediaFile(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodHead {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	p := strings.TrimSpace(r.URL.Query().Get("path"))
+	if p == "" || !filepath.IsAbs(p) {
+		writeErr(w, http.StatusBadRequest, "path 必须是绝对路径")
+		return
+	}
+	f, err := os.Open(filepath.Clean(p))
+	if err != nil {
+		writeErr(w, http.StatusNotFound, "文件不存在")
+		return
+	}
+	defer f.Close()
+	st, err := f.Stat()
+	if err != nil || !st.Mode().IsRegular() {
+		writeErr(w, http.StatusNotFound, "文件不存在")
+		return
+	}
+	if st.Size() > maxUploadBytes {
+		writeErr(w, http.StatusRequestEntityTooLarge, "文件过大")
+		return
+	}
+	head := make([]byte, 512)
+	n, _ := f.Read(head)
+	if !isMediaFile(head[:n], p) {
+		writeErr(w, http.StatusUnsupportedMediaType, "仅支持图片 / 视频 / 音频")
+		return
+	}
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		writeErr(w, http.StatusInternalServerError, "读取失败："+err.Error())
+		return
+	}
+	// ?w=<px>：移动端慢网下按需缩放（仅图片；解不了就原样回）。
+	if tw := thumbWidth(r); tw > 0 {
+		if data, mime, ok := scaledImageData(filepath.Clean(p), st, tw); ok {
+			w.Header().Set("Content-Type", mime)
+			w.Header().Set("Cache-Control", "private, max-age=86400")
+			http.ServeContent(w, r, filepath.Base(p), st.ModTime(), bytes.NewReader(data))
+			return
+		}
+	}
+	w.Header().Set("Cache-Control", "private, max-age=300")
+	http.ServeContent(w, r, filepath.Base(p), st.ModTime(), f)
+}
+
+// isMediaFile 媒体判定：按内容嗅探为主（http.DetectContentType），扩展名兜底。
+// 与前端 qaArtKind 的后缀表同口径（shared/conv/19-attachments.js）。
+func isMediaFile(head []byte, path string) bool {
+	ct := http.DetectContentType(head)
+	if strings.HasPrefix(ct, "image/") || strings.HasPrefix(ct, "video/") || strings.HasPrefix(ct, "audio/") {
+		return true
+	}
+	switch strings.ToLower(filepath.Ext(path)) {
+	case ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp",
+		".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi",
+		".mp3", ".wav", ".m4a", ".aac", ".ogg", ".flac":
+		return true
+	}
+	return false
+}
+
+// maxProbePaths 一次路径探测的上限（内核一批最多 12 条，这里留余量）。
+const maxProbePaths = 50
+
+// handlePathProbe POST /desk/path-probe：一批本机路径的**存在性探测**。
+// 用途：内核画「会话产物」时只画真的落在盘上的路径（正文里提到的 app.js、远端 URL 不画）。
+// 入参 {base, paths[]}：相对路径按 base（会话的 workspace）解析；`~/` 展开成 home，
+// `file://` 前缀按本机路径处理。出参 {ok:true, items:[{path, abs, exists, size}]}。
+// ⚠️ 只回「有没有 / 在哪 / 多大」，**类型判定不在这里**（渲染层按后缀分档，见 qaArtKind）。
+func (s *Service) handlePathProbe(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	var req struct {
+		Base  string   `json:"base"`
+		Paths []string `json:"paths"`
+	}
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&req); err != nil {
+		writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
+		return
+	}
+	base := strings.TrimSpace(req.Base)
+	paths := req.Paths
+	if len(paths) > maxProbePaths {
+		paths = paths[:maxProbePaths]
+	}
+	items := make([]map[string]any, 0, len(paths))
+	for _, raw := range paths {
+		p := strings.TrimSpace(raw)
+		if p == "" {
+			continue
+		}
+		p = strings.TrimPrefix(p, "file://")
+		if p == "~" || strings.HasPrefix(p, "~/") {
+			if home, err := os.UserHomeDir(); err == nil {
+				p = filepath.Join(home, strings.TrimPrefix(p, "~/"))
+			}
+		}
+		it := map[string]any{"path": raw, "abs": "", "exists": false, "size": int64(0)}
+		if !filepath.IsAbs(p) {
+			if base == "" {
+				items = append(items, it)
+				continue
+			}
+			p = filepath.Join(base, p)
+		}
+		p = filepath.Clean(p)
+		it["abs"] = p
+		if st, err := os.Stat(p); err == nil && st.Mode().IsRegular() {
+			it["exists"] = true
+			it["size"] = st.Size()
+		}
+		items = append(items, it)
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "items": items})
+}
+
+// maxReadBytes 单次文本读取上限（与桌面端 desk:path-read 同口径：512KB）。
+const maxReadBytes = 512 << 10
+
+// handlePathRead POST /desk/path-read：按路径读一个**文本**文件给移动端阅读浮层。
+// 出参与桌面端 desk:path-read 一致（统一 200 + ok 标志，只有方法 / JSON 错才 4xx）：
+//
+//	{ok:true, text, size, path} | {ok:true, tooBig:true, size} |
+//	{ok:true, binary:true, size} | {ok:false, error}
+//
+// 入参 {path, base}：相对路径按 base（会话 workspace）解析，`~/` 展开，`file://` 前缀剥离。
+// ⚠️ 只读文本：前 8000 字节含 NUL 就判二进制，超 512KB 判 tooBig —— 不给任意大文件通道。
+func (s *Service) handlePathRead(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	var req struct {
+		Path string `json:"path"`
+		Base string `json:"base"`
+	}
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&req); err != nil {
+		writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
+		return
+	}
+	p := strings.TrimSpace(req.Path)
+	if p == "" {
+		writeJSON(w, http.StatusOK, map[string]any{"ok": false, "error": "path 为空"})
+		return
+	}
+	p = strings.TrimPrefix(p, "file://")
+	if p == "~" || strings.HasPrefix(p, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			p = filepath.Join(home, strings.TrimPrefix(p, "~/"))
+		}
+	}
+	if !filepath.IsAbs(p) {
+		base := strings.TrimSpace(req.Base)
+		if base == "" {
+			writeJSON(w, http.StatusOK, map[string]any{"ok": false, "error": "相对路径缺少 base"})
+			return
+		}
+		p = filepath.Join(base, p)
+	}
+	p = filepath.Clean(p)
+	st, err := os.Stat(p)
+	if err != nil || !st.Mode().IsRegular() {
+		writeJSON(w, http.StatusOK, map[string]any{"ok": false, "error": "文件不存在：" + p})
+		return
+	}
+	size := st.Size()
+	if size > maxReadBytes {
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true, "tooBig": true, "size": size})
+		return
+	}
+	data, err := os.ReadFile(p)
+	if err != nil {
+		writeJSON(w, http.StatusOK, map[string]any{"ok": false, "error": "读取失败：" + err.Error()})
+		return
+	}
+	head := data
+	if len(head) > 8000 {
+		head = head[:8000]
+	}
+	if bytes.IndexByte(head, 0) >= 0 {
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true, "binary": true, "size": size})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"ok": true, "text": string(data), "size": size, "path": p,
+	})
+}
+
+// 缩略图参数与缓存上限：移动端慢网下按需缩放，图省流量。
+const (
+	minThumbPx    = 64
+	maxThumbPx    = 4096
+	maxThumbCache = 64 << 20
+)
+
+type thumbEntry struct {
+	data []byte
+	mime string
+}
+
+var thumbCache = struct {
+	sync.Mutex
+	total int
+	items map[string]thumbEntry
+}{items: map[string]thumbEntry{}}
+
+// thumbWidth 解析 ?w=<px>；0 = 不缩放（没带 / 非法 / 越界都当没带）。
+func thumbWidth(r *http.Request) int {
+	raw := strings.TrimSpace(r.URL.Query().Get("w"))
+	if raw == "" {
+		return 0
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil || n < minThumbPx || n > maxThumbPx {
+		return 0
+	}
+	return n
+}
+
+// scaledImageData 按目标宽度等比缩放并重编码；解不了 / 本来就更小 / 缩完更大 → ok=false 走原文件。
+// 缓存 key 带 mtime+size：文件改了自然失效。
+func scaledImageData(p string, st os.FileInfo, targetW int) (data []byte, mime string, ok bool) {
+	key := p + "|" + strconv.FormatInt(st.ModTime().UnixNano(), 10) + "|" +
+		strconv.FormatInt(st.Size(), 10) + "|" + strconv.Itoa(targetW)
+	thumbCache.Lock()
+	if e, hit := thumbCache.items[key]; hit {
+		thumbCache.Unlock()
+		return e.data, e.mime, true
+	}
+	thumbCache.Unlock()
+
+	f, err := os.Open(p)
+	if err != nil {
+		return nil, "", false
+	}
+	defer f.Close()
+	src, _, err := image.Decode(f) // gif/jpeg/png 已注册；webp 等解不了就走原文件
+	if err != nil {
+		return nil, "", false
+	}
+	b := src.Bounds()
+	sw, sh := b.Dx(), b.Dy()
+	if sw <= targetW || sh <= 0 {
+		return nil, "", false
+	}
+	th := int(math.Round(float64(sh) * float64(targetW) / float64(sw)))
+	if th < 1 {
+		th = 1
+	}
+	dst := scaleBilinear(src, targetW, th)
+	var buf bytes.Buffer
+	if isOpaque(dst) {
+		mime = "image/jpeg"
+		if err := jpeg.Encode(&buf, dst, &jpeg.Options{Quality: 78}); err != nil {
+			return nil, "", false
+		}
+	} else {
+		mime = "image/png"
+		if err := png.Encode(&buf, dst); err != nil {
+			return nil, "", false
+		}
+	}
+	out := buf.Bytes()
+	if int64(len(out)) >= st.Size() {
+		return nil, "", false // 缩完反而更大（小图 / 纯色图），没意义
+	}
+	thumbCache.Lock()
+	if thumbCache.total+len(out) > maxThumbCache {
+		thumbCache.items = map[string]thumbEntry{}
+		thumbCache.total = 0
+	}
+	thumbCache.items[key] = thumbEntry{data: out, mime: mime}
+	thumbCache.total += len(out)
+	thumbCache.Unlock()
+	return out, mime, true
+}
+
+// scaleBilinear 标准库实现的等比双线性缩放（不引 golang.org/x/image）。
+// 先转成 NRGBA 再插值：避开每像素 At() 接口调用，大图也够快。
+func scaleBilinear(src image.Image, w, h int) *image.NRGBA {
+	sb := src.Bounds()
+	sw, sh := sb.Dx(), sb.Dy()
+	flat := image.NewNRGBA(image.Rect(0, 0, sw, sh))
+	draw.Draw(flat, flat.Bounds(), src, sb.Min, draw.Src)
+	dst := image.NewNRGBA(image.Rect(0, 0, w, h))
+	sp, ss := flat.Pix, flat.Stride
+	dp, ds := dst.Pix, dst.Stride
+	for y := 0; y < h; y++ {
+		fy := (float64(y)+0.5)*float64(sh)/float64(h) - 0.5
+		y0 := int(math.Floor(fy))
+		ty := fy - float64(y0)
+		if y0 < 0 {
+			y0, ty = 0, 0
+		}
+		if y0 > sh-1 {
+			y0, ty = sh-1, 0
+		}
+		y1 := y0 + 1
+		if y1 > sh-1 {
+			y1 = sh - 1
+		}
+		for x := 0; x < w; x++ {
+			fx := (float64(x)+0.5)*float64(sw)/float64(w) - 0.5
+			x0 := int(math.Floor(fx))
+			tx := fx - float64(x0)
+			if x0 < 0 {
+				x0, tx = 0, 0
+			}
+			if x0 > sw-1 {
+				x0, tx = sw-1, 0
+			}
+			x1 := x0 + 1
+			if x1 > sw-1 {
+				x1 = sw - 1
+			}
+			o00 := y0*ss + x0*4
+			o10 := y0*ss + x1*4
+			o01 := y1*ss + x0*4
+			o11 := y1*ss + x1*4
+			d := y*ds + x*4
+			for c := 0; c < 4; c++ {
+				top := float64(sp[o00+c])*(1-tx) + float64(sp[o10+c])*tx
+				bot := float64(sp[o01+c])*(1-tx) + float64(sp[o11+c])*tx
+				dp[d+c] = uint8(top*(1-ty) + bot*ty + 0.5)
+			}
+		}
+	}
+	return dst
+}
+
+// isOpaque 全不透明 → 可以编成 JPEG（比 PNG 小得多）。
+func isOpaque(img *image.NRGBA) bool {
+	p := img.Pix
+	for i := 3; i < len(p); i += 4 {
+		if p[i] != 0xff {
+			return false
+		}
+	}
+	return true
+}
+
+// sanitizeUploadName 只取文件名部分并去掉路径分隔，避免目录穿越。
+func sanitizeUploadName(name string) string {
+	name = filepath.Base(strings.TrimSpace(name))
+	if name == "" || name == "." || name == string(filepath.Separator) {
+		name = "upload"
+	}
+	return strings.ReplaceAll(name, string(filepath.Separator), "_")
+}
+
 func writeJSON(w http.ResponseWriter, code int, v any) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	w.WriteHeader(code)