magic-agent 2.4.3 → 2.6.0

package/internal/client/service.go

@@ -22,6 +22,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"reflect"
 	"sort"
 	"strconv"
 	"strings"
@@ -38,8 +39,8 @@ import (
  *  1) 契约校验：启动时读 core 的 --contract，版本或能力不匹配就**明确报错**，
  *     不带着不匹配的能力跑起来 —— 这类漂移的表现是界面空白，最难定位。
  *  2) 只走 core 的公开面：spawn `magic-agent` 子进程收 NDJSON 事件，**不解析引擎输出**。
- *  3) 默认只绑 127.0.0.1 且要令牌：本地服务对同机所有进程可见，不开鉴权等于把
- *     引擎执行权交给任意本机进程。
+ *  3) 默认绑 0.0.0.0:9100 且强制令牌：局域网内端口能被扫到，令牌是唯一门锁；
+ *     只想本机访问时用 --local 绑回 127.0.0.1。
  */
 
 // RequiredContractVersion 本插件能解析的 core 契约版本。
@@ -73,7 +74,7 @@ type Options struct {
 	// APKPath 可选：要分发给移动端的 APK 路径。空 = 自动在包内 npm/apk/ 下找
 	// （见 apk.go）。显式给路径主要给测试与特殊布局用。
 	APKPath string
-	// Lan 是否绑到了局域网（--lan）。移动端「环境」菜单要靠它拿到手机可用的入口，
+	// Lan 是否绑到了局域网（默认开启，--local 关闭）。移动端「环境」菜单要靠它拿到手机可用的入口，
 	// 否则用户只能手抄 IP。绑回环时不报（报了也连不上）。
 	Lan bool
 	// BrowseUA 内置浏览器中转使用的 User-Agent；空 = 用内置的 Android Chrome。
@@ -114,9 +115,17 @@ type Service struct {
 	browseOnce sync.Once
 	browseHTTP *http.Client
 
+	// 浏览器输入中继（/browse-input，见 browseinput.go）：页面内 relay 脚本 viewer
+	// 与未来的 MCP driver 之间的枢纽，惰性建。
+	inputHubOnce sync.Once
+	inputHubRef  *browseInputHub
+
 	// 需求自动归纳的调度状态（每工作区一个防抖计时器，见 requirements.go）。
 	reqAuto reqAuto
 
+	// 脚本清单与运行态（「发现 → 脚本」，见 scripts.go）。
+	scripts *scriptManager
+
 	// 随包发布的移动端 APK（空 = 这个包里没带）。见 apk.go。
 	apkPath string
 
@@ -126,6 +135,15 @@ type Service struct {
 	pubURL  string
 	pubExp  time.Time
 	pubBusy bool
+
+	/* 知识库（OpenViking）的最新版本缓存 + 安装互斥（见 knowledge.go）。
+	   成功缓存 6h、失败缓存 15min —— 失败不该每次开页面都重试一次外网。
+	   ovBusy 挡住两个客户端同时点安装（会抢同一个 venv）。 */
+	ovMu       sync.Mutex
+	ovLatest   string
+	ovLatestOK bool
+	ovLatestAt time.Time
+	ovBusy     bool
 }
 
 // Contract core `--contract` 里本插件关心的部分。
@@ -193,7 +211,7 @@ func New(opts Options) (*Service, error) {
 
 	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
 	defer cancel()
-	out, err := exec.CommandContext(ctx, opts.MagicAgent, "--contract").Output()
+	out, err := newCoreCmd(ctx, opts.MagicAgent, "--contract").Output()
 	if err != nil {
 		return nil, fmt.Errorf("读 core 契约失败（%s --contract）：%w", opts.MagicAgent, err)
 	}
@@ -213,6 +231,8 @@ func New(opts Options) (*Service, error) {
 	/* 作业队列：服务端权威的排队层（多客户端串行 / 幂等 / 重启恢复）。
 	   必须在 New 里就建好：/desk/ask 第一次进来就要能入队。 */
 	s.jobs = newJobQueue(s)
+	// 脚本管理器同理：清单要跨重启保留，运行中的脚本要靠 pid 探活。
+	s.scripts = newScriptManager(s)
 	return s, nil
 }
 
@@ -227,11 +247,16 @@ func (s *Service) Handler() http.Handler {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/desk/health", s.guard(s.handleHealth))
 	mux.HandleFunc("/desk/contract", s.guard(s.handleContract))
+	/* 重启后台实例（2026-10-24，移动端「我的 → 重启服务」）。见 restart.go：
+	   本进程发完响应后由一个脱离终端的助手停旧起新，令牌 / 端口沿用。 */
+	mux.HandleFunc("/desk/restart", s.guard(s.handleRestart))
 	// 移动端 APK：版本信息 + 安装包本身（版本号跟 npm 包走，见 apk.go）。
 	mux.HandleFunc("/desk/app", s.guard(s.handleAppInfo))
 	// 系统浏览器/下载器带不了自定义头，这个接口靠 guard 支持的 ?token= 过鉴权。
 	mux.HandleFunc("/desk/app.apk", s.guard(s.handleAppAPK))
 	mux.HandleFunc("/desk/engines", s.guard(s.handleEngines))
+	// 每日积分领取（2026-10-24）：core --checkin <engine>，用该引擎自己的票据。
+	mux.HandleFunc("/desk/checkin", s.guard(s.handleCheckin))
 	mux.HandleFunc("/desk/profile", s.guard(s.handleProfile))
 	mux.HandleFunc("/desk/modules", s.guard(s.handleModules))
 	mux.HandleFunc("/desk/sessions", s.guard(s.handleSessions))
@@ -258,11 +283,25 @@ func (s *Service) Handler() http.Handler {
 	// 需求聚合（2026-10-22，见 requirements.go）：读清单 / 手动整理一轮。
 	// 自动归纳不在这里 —— 它是每轮 /desk/ask 收尾后的防抖动作。
 	mux.HandleFunc("/desk/requirements", s.guard(s.handleRequirements))
+	mux.HandleFunc("/desk/requirements/graph", s.guard(s.handleRequirementsGraph))
 	mux.HandleFunc("/desk/requirements/consolidate", s.guard(s.handleRequirementsConsolidate))
+	// 页面完成情况截图（2026-10-25）：body = PNG 原始字节，参数走查询串。
+	mux.HandleFunc("/desk/requirements/shots", s.guard(s.handleRequirementsShots))
+	// 服务端 agent-browser 截图（2026-10-25 MCP 改基 agent-browser）：
+	// body = {"url":…}，服务端真实 Chromium 截全页图落 uploads。
+	mux.HandleFunc("/desk/requirements/shot-remote", s.guard(s.handleRequirementShotRemote))
 	// 插件目录（magic-shorts / magic-video 两个工程的 CLI）：介绍、安装状态、安装/升级。
 	// 与引擎无关 —— core 不认识它们，所以放在这一层而不是 core 的 --engines 里。
 	mux.HandleFunc("/desk/plugins", s.guard(s.handlePlugins))
 	mux.HandleFunc("/desk/plugins/", s.guard(s.handlePluginAction))
+	// 知识库目录（OpenViking：面向 Agent 的上下文数据库）：本机是否已安装、当前版本、
+	// 与 PyPI 最新版本的差距，以及一键安装 / 升级。与插件同源：不是引擎，放在这一层。
+	mux.HandleFunc("/desk/knowledge", s.guard(s.handleKnowledge))
+	mux.HandleFunc("/desk/knowledge/", s.guard(s.handleKnowledgeAction))
+	// 脚本清单与启停（「发现 → 脚本」）：用户登记脚本，服务端负责启停与日志。
+	// 命令**只来自登记过的脚本定义**（不过 shell），客户端不能传任意命令行。
+	mux.HandleFunc("/desk/scripts", s.guard(s.handleScripts))
+	mux.HandleFunc("/desk/scripts/", s.guard(s.handleScriptSub))
 	mux.HandleFunc("/desk/dirs", s.guard(s.handleDirs))
 	// /desk/session/{id}/messages 是**前缀匹配**路由 —— 标准 ServeMux 把它挂上后，
 	// 该前缀下任何 path 都先进这里（其它挂载顺序靠后也拦不住）。
@@ -287,6 +326,9 @@ func (s *Service) Handler() http.Handler {
 	// 内置浏览器的**服务端中转**：/b/<scheme>/<host><path>。走桌面端网络抓取并改写，
 	// 见 browse.go。注意它自己鉴权（cookie/查询令牌），不再套 s.guard。
 	mux.HandleFunc("/b/", s.handleBrowse)
+	// 浏览器输入中继：/browse-input?role=viewer|driver。鉴权同 /b/（查询令牌/cookie），
+	// 不套 s.guard —— 页面内注入的 relay 脚本只带 cookie。见 browseinput.go。
+	mux.HandleFunc(browseWSPath, s.handleBrowseInput)
 	// SOCKS5 over WebSocket：让 SOCKS5 能穿过 HTTP 隧道（Cloudflare 等）到公网，见 wsproxy.go。
 	mux.HandleFunc(proxyWSPath, s.handleProxyWS)
 	mux.HandleFunc("/", s.handleStatic)
@@ -426,6 +468,11 @@ func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
 		// 服务端作业队列（2026-10-23）：有它才谈得上「多客户端串行 + 幂等」。
 		// 老插件没有该字段 → 客户端退回本地排队（见 client-ui-mobile 的 fallback）。
 		"jobs": true,
+		// 重启标志（2026-10-25，只增字段）：本实例已受理「重启服务」、定时器还没到点。
+		// 探活语义：true = 旧实例认账、即将下线（见 restart.go 的标志 + 定时器链路）；
+		// 再探到该字段为假的 200 才是新一代起来。老插件没有该字段 → 客户端照旧
+		// 「先看到连不上、再看到 200」的判据。
+		"restarting": restartRequested(),
 		// 服务实例的稳定 id（2026-10-23，只增字段）：同一台桌面的本地 / 局域网 / 公网
 		// 入口可能有多条 URL，客户端据此把它们归一成同一个环境（队列与设置共用）。
 		// 老插件没有该字段 → 客户端退回按连接各自算环境。
@@ -647,7 +694,7 @@ var extraSessionClients = []string{"magic-test", "magic-agent"}
 func (s *Service) handleSessions(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
 	defer cancel()
-	out, err := exec.CommandContext(ctx, s.opts.MagicAgent, "--sessions").Output()
+	out, err := newCoreCmd(ctx, s.opts.MagicAgent, "--sessions").Output()
 	if err != nil {
 		writeErr(w, http.StatusBadGateway,
 			fmt.Sprintf("%s --sessions 失败：%v", s.opts.MagicAgent, err))
@@ -1079,7 +1126,7 @@ func (s *Service) handleSessionTitleSummarize(w http.ResponseWriter, r *http.Req
 	if body.Force {
 		args = append(args, "--title-force")
 	}
-	out, err := exec.CommandContext(ctx, s.opts.MagicAgent, args...).Output()
+	out, err := newCoreCmd(ctx, s.opts.MagicAgent, args...).Output()
 	if err != nil {
 		// core 的失败原因写在 stderr，原样带回：只回「归纳失败」调用方没法排障。
 		msg := strings.TrimSpace(string(out))
@@ -1650,7 +1697,7 @@ var errCoreTimeout = errors.New("core 命令超时未返回")
 func (s *Service) runCore(ctx context.Context, args ...string) ([]byte, error) {
 	ctx, cancel := context.WithTimeout(ctx, proxyCoreTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	cmd := newCoreCmd(ctx, s.opts.MagicAgent, args...)
 	/* WaitDelay 是有界返回的最后一道保险：exec 给 Stdout/Stderr 建的是内部管道，
 	   只要 core 的某个后代进程（引擎 CLI 的 node worker）还握着写端，Wait 就永远不返回 ——
 	   症状正是「弹层永远停在正在探测引擎与模型…」。设了 WaitDelay 后，ctx 到期再等这么久
@@ -1736,6 +1783,56 @@ func saveEnginesCache(out []byte) {
 	_ = os.Rename(tmp, p)
 }
 
+// patchEnginesCacheAfterCheckin 领取（或发现「今天已签」）后，把兜底缓存里该引擎的
+// 签到状态就地改掉：下一次打开选择器立刻看到「今日已领」，不用等后台重探。
+// 只改缓存、不重探 —— 重探要起所有引擎 CLI，弹层会卡几十秒。
+func patchEnginesCacheAfterCheckin(out []byte) {
+	var res struct {
+		Engine       string `json:"engine"`
+		CheckedToday bool   `json:"checked_today"`
+		CreditLeft   string `json:"credit_left"`
+	}
+	if json.Unmarshal(out, &res) != nil || !res.CheckedToday || res.Engine == "" {
+		return
+	}
+	p, err := enginesCachePath()
+	if err != nil {
+		return
+	}
+	raw, err := os.ReadFile(p)
+	if err != nil {
+		return
+	}
+	var rows []map[string]any
+	if json.Unmarshal(raw, &rows) != nil {
+		return
+	}
+	changed := false
+	for _, r := range rows {
+		if name, _ := r["engine"].(string); name != res.Engine {
+			continue
+		}
+		r["checkin_today"] = true
+		r["checkin_credit"] = ""
+		if res.CreditLeft != "" {
+			r["credit_left"] = res.CreditLeft
+		}
+		changed = true
+	}
+	if !changed {
+		return
+	}
+	b, err := json.Marshal(rows)
+	if err != nil {
+		return
+	}
+	tmp := p + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, p)
+}
+
 // loadEnginesCache 读上次成功的清单；过期 / 损坏都当没有。
 func loadEnginesCache() ([]byte, time.Time, bool) {
 	p, err := enginesCachePath()
@@ -1795,6 +1892,9 @@ func (s *Service) probeEnginesAsync() {
 // 这样弹层永远是秒开：用户这次看到的是上次的结果，下一次打开就是新的。
 func (s *Service) proxyEngines(w http.ResponseWriter, r *http.Request) {
 	if cached, at, ok := loadEnginesCache(); ok {
+		/* 模型清单用缓存，额度 / 签到现查：额度会随用量与 key 变化，跟着缓存一起
+		   冻 24 小时就是用户看到的「额度不刷新」（2026-10-25 报障）。 */
+		cached = s.mergeLiveQuota(r.Context(), cached)
 		w.Header().Set("X-Magic-Engines-Stale", at.Format(time.RFC3339))
 		writeCoreJSON(w, cached)
 		s.probeEnginesAsync()
@@ -1813,12 +1913,133 @@ func (s *Service) proxyEngines(w http.ResponseWriter, r *http.Request) {
 	writeErr(w, code, fmt.Sprintf("%s --engines 失败：%v", s.opts.MagicAgent, err))
 }
 
+// quotaFields core --quotas 里允许覆盖到引擎清单上的字段（与 --engines 同名同义）。
+var quotaFields = []string{
+	"credit_left", "credit_suffix", "model_quota", "checkin_today", "checkin_credit", "logged_in", "account",
+}
+
+// mergeLiveQuota 用 core --quotas 的最新结果覆盖引擎清单里的额度 / 签到字段。
+//
+// 为什么不整体重探：模型清单要逐个启动引擎 CLI（秒级起步），而额度只读本机票据 +
+// 一两条只读请求。分开之后选择器依旧秒开，额度却是这次现查的。
+// 查询失败（老 core 没有 --quotas / 网络抖动）就原样返回缓存 —— 不能因为额度
+// 查不到让整份引擎清单变成错误。
+func (s *Service) mergeLiveQuota(ctx context.Context, engines []byte) []byte {
+	// core 内部还有 6s 上限；这里再兜一层，避免异常时钟 / 挂起的子进程拖住响应。
+	ctx, cancel := context.WithTimeout(ctx, 8*time.Second)
+	defer cancel()
+	quotas, err := s.runCore(ctx, "--quotas")
+	if err != nil {
+		return engines
+	}
+	return mergeQuotaJSON(engines, quotas)
+}
+
+// mergeQuotaJSON 把 --quotas 的行按 engine 合并进 --engines 的数组（纯函数，便于单测）。
+// 只覆盖「这次查到了的」字段：空串 / 空对象不覆盖，避免一次网络失败把已有数字抹掉。
+func mergeQuotaJSON(engines, quotas []byte) []byte {
+	var rows []map[string]any
+	if json.Unmarshal(engines, &rows) != nil {
+		return engines
+	}
+	var qs []map[string]any
+	if json.Unmarshal(quotas, &qs) != nil {
+		return engines
+	}
+	byEngine := make(map[string]map[string]any, len(qs))
+	for _, q := range qs {
+		if name, _ := q["engine"].(string); name != "" {
+			byEngine[name] = q
+		}
+	}
+	changed := false
+	for _, r := range rows {
+		name, _ := r["engine"].(string)
+		q := byEngine[name]
+		if q == nil {
+			continue
+		}
+		for _, k := range quotaFields {
+			v, ok := q[k]
+			if !ok || emptyQuotaValue(v) || reflect.DeepEqual(r[k], v) {
+				continue
+			}
+			r[k] = v
+			changed = true
+		}
+	}
+	if !changed {
+		return engines
+	}
+	out, err := json.Marshal(rows)
+	if err != nil {
+		return engines
+	}
+	return out
+}
+
+// emptyQuotaValue --quotas 里「没查到」的值形态（omitempty 后本不该出现，
+// 但显式空串 / 空对象也要当成没有，别覆盖缓存里的旧值）。
+func emptyQuotaValue(v any) bool {
+	switch t := v.(type) {
+	case nil:
+		return true
+	case string:
+		return strings.TrimSpace(t) == ""
+	case map[string]any:
+		return len(t) == 0
+	case []any:
+		return len(t) == 0
+	}
+	return false
+}
+
+// handleCheckin POST /desk/checkin：领取某引擎账号的每日积分（core --checkin <engine>）。
+//
+// 只做转发：读本机票据、调账单接口都在 core；这里负责参数校验与有界返回。
+// 业务失败（如「今天已经领过了」）也是 200 —— 响应体是 core 的
+// {engine, ok:false, message}，客户端直接显示原因，不当成网络错误。
+func (s *Service) handleCheckin(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "/desk/checkin 只支持 POST")
+		return
+	}
+	var req struct {
+		Engine string `json:"engine"`
+	}
+	if err := json.NewDecoder(io.LimitReader(r.Body, 1<<16)).Decode(&req); err != nil {
+		writeErr(w, http.StatusBadRequest, `请求体不是合法 JSON：需要 {"engine":"codebuddy"}`)
+		return
+	}
+	engine := strings.TrimSpace(req.Engine)
+	if engine == "" {
+		writeErr(w, http.StatusBadRequest, "缺少 engine")
+		return
+	}
+	out, err := s.runCore(r.Context(), "--checkin", engine)
+	if err != nil {
+		code := http.StatusBadGateway
+		if errors.Is(err, errCoreTimeout) {
+			code = http.StatusGatewayTimeout
+		}
+		writeErr(w, code, fmt.Sprintf("--checkin %s 失败：%v", engine, err))
+		return
+	}
+	// 领到 / 发现「今天已签」后同步兜底缓存，避免重开弹层又显示「领取」。
+	patchEnginesCacheAfterCheckin(out)
+	writeCoreJSON(w, out)
+}
+
 // askRequest POST /desk/ask 的请求体。
 type askRequest struct {
-	Engine    string `json:"engine"`
-	Prompt    string `json:"prompt"`
-	Model     string `json:"model,omitempty"`
-	Workspace string `json:"workspace,omitempty"`
+	Engine string `json:"engine"`
+	Prompt string `json:"prompt"`
+	Model  string `json:"model,omitempty"`
+	// FallbackEngine / FallbackModel 主引擎的备用（2026-10-24，只增字段）。
+	// 主引擎失败且**零产出**时 core 自动降级一次；空 = 不降级（老客户端行为不变）。
+	FallbackEngine string `json:"fallbackEngine,omitempty"`
+	FallbackModel  string `json:"fallbackModel,omitempty"`
+	Workspace      string `json:"workspace,omitempty"`
 	// Permission 四档权限模型（manual | accept-edits | auto | full），透传给 core 的
 	// --permission。空 = 不传，由 core 用它自己的默认值（agent.DefaultPermissionTier）。
 	// ⚠️ core 只在**显式传过** --permission 时才校验引擎是否支持（当前 claude / codebuddy /
@@ -1893,6 +2114,10 @@ type teamRequest struct {
 type teamRoute struct {
 	Engine string `json:"engine,omitempty"`
 	Model  string `json:"model,omitempty"`
+	// FallbackEngine / FallbackModel 这一路的备用（2026-10-24，只增字段）。
+	// 主引擎失败且零产出时自动降级一次；空 = 不降级。
+	FallbackEngine string `json:"fallbackEngine,omitempty"`
+	FallbackModel  string `json:"fallbackModel,omitempty"`
 }
 
 // askRun 一次 ask（跑完的还会短时保留，供断线续传补拉终态）。
@@ -1919,6 +2144,12 @@ type askRun struct {
 	   登记表里这条会话只有 run_id，/desk/asks 要把两者都给客户端才能认领。受 mu 保护。 */
 	run string
 
+	/* fbEngine / fbModel 本轮**由备用引擎接上**时记下是谁（扫 type=fallback 事件，
+	   2026-10-26）。作业记录靠它回答「主备到底生效没有」—— 以前那份记录里只有
+	   配置、没有结果，用户报障时无从判断。受 mu 保护；没降级时为空。 */
+	fbEngine string
+	fbModel  string
+
 	/* 事件回放缓冲（2026-10-19 断线续传）：core 的每一行原样留一份，客户端拿
 	   `GET /desk/ask/{id}/events?after=<seq>` 按 seq 增量补拉。
 	   为什么不直接复用会话日志（`/desk/session/{id}/events`）：
@@ -2015,6 +2246,19 @@ func (r *askRun) appendEvent(line string) {
 	if seq > r.seq {
 		r.seq = seq
 	}
+	/* 主备降级帧（2026-10-26）：只留 to 端，作业收尾时写进作业记录。
+	   只在长度够时才解析 —— 绝大多数行都不是 fallback。 */
+	if len(line) > 24 && strings.Contains(line, `"type":"fallback"`) {
+		var fe struct {
+			Fallback *struct {
+				ToEngine string `json:"to_engine"`
+				ToModel  string `json:"to_model"`
+			} `json:"fallback"`
+		}
+		if json.Unmarshal([]byte(line), &fe) == nil && fe.Fallback != nil {
+			r.fbEngine, r.fbModel = fe.Fallback.ToEngine, fe.Fallback.ToModel
+		}
+	}
 	r.events = append(r.events, askEvent{seq: seq, data: []byte(line)})
 	size := 0
 	for _, e := range r.events {
@@ -2053,6 +2297,13 @@ func (r *askRun) finish(code int) {
 	r.mu.Unlock()
 }
 
+// fallbackState 本轮降级到了哪个引擎 / 模型（没降级返回空）。
+func (r *askRun) fallbackState() (engine, model string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.fbEngine, r.fbModel
+}
+
 // snapshot 取 seq > after 的事件（after=0 时额外放行网关合成的用户提问，seq=0）。
 // 与 handleAskEvents 的返回口径一致，供 SSE 中继与作业事件共用。
 func (r *askRun) snapshot(after uint64) (out []askEvent, lastSeq uint64, done bool, code int, stderr string) {
@@ -2172,6 +2423,17 @@ func (s *Service) prepareAsk(req askRequest) (string, []string, int, error) {
 	if req.Model != "" {
 		args = append(args, "-m", req.Model)
 	}
+	/* 主备（2026-10-24）：备用引擎同样要过白名单，否则会绕过「这台桌面允许用哪些引擎」。
+	   主引擎失败且零产出时由 core 自动降级（见 agent/fallback.go）。 */
+	if fb := strings.TrimSpace(req.FallbackEngine); fb != "" {
+		if !s.opts.Profile.AllowsEngine(fb) {
+			return "", nil, http.StatusForbidden, fmt.Errorf("profile 白名单不允许备用引擎 %q", fb)
+		}
+		args = append(args, "--fallback-engine", fb)
+		if m := strings.TrimSpace(req.FallbackModel); m != "" {
+			args = append(args, "--fallback-model", m)
+		}
+	}
 	if req.Workspace != "" {
 		args = append(args, "-w", req.Workspace)
 	}
@@ -2250,16 +2512,20 @@ stdout 全部进 askRun 的回放缓冲，谁来读（SSE / /desk/ask/{id}/event
 */
 func (s *Service) startAsk(req askRequest, engine string, args []string, source string) (*askRun, error) {
 	ctx := context.WithoutCancel(context.Background())
-	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	cmd := newCoreCmd(ctx, s.opts.MagicAgent, args...)
 	/* 两个「谁发起的」维度随环境变量传给 core，落到会话登记表：
 	   · EnvSource  设备形态（mobile / pc）—— 按请求 Origin 判定，列表页显示设备标志；
 	   · EnvClient  发起方应用（本插件的 AppID）—— 列表页据此**只显示本客户端发起的会话**。
-	   另外注入工作空间锁（选入式，见 internal/session/workspace_lock.go）：core 在 Begin
-	   时先抢锁再写 running，让直接跑 CLI 的进程也参与同一套串行。 */
+	   工作空间锁（选入式，见 internal/session/workspace_lock.go）**只对串行作业注入**：
+	   core 在 Begin 时先抢锁再写 running，让直接跑 CLI 的进程也参与同一套串行；
+	   并行作业注入了锁就会在同空间的 core Begin 处重新排队，把「并行」架空 ——
+	   模式互斥的裁决只在队列这一层做（jobs.go dispatch）。 */
 	cmd.Env = append(os.Environ(),
 		session.EnvSource+"="+source,
-		session.EnvClient+"="+s.opts.Profile.AppID(),
-		session.EnvWorkspaceLock+"=1")
+		session.EnvClient+"="+s.opts.Profile.AppID())
+	if req.Serial == nil || *req.Serial {
+		cmd.Env = append(cmd.Env, session.EnvWorkspaceLock+"=1")
+	}
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
 		return nil, fmt.Errorf("stdin pipe: %w", err)
@@ -2422,13 +2688,20 @@ func (s *Service) handleAskSub(w http.ResponseWriter, r *http.Request) {
 		Op     string `json:"op"`
 		Text   string `json:"text,omitempty"`
 		Reason string `json:"reason,omitempty"`
+		/* ask_answer（原地回审批，2026-10-25）：这三项必须原样透传给 core 的 --control。
+		   顶层 decode 只认 op/text/reason 的话，它们会在 re-marshal 时被丢掉，
+		   症状是客户端明明点了「允许」，core 却回 control_error「需要 request_id」。 */
+		RequestID string `json:"request_id,omitempty"`
+		Allowed   *bool  `json:"allowed,omitempty"`
+		Message   string `json:"message,omitempty"`
+		ToolName  string `json:"tool_name,omitempty"`
 	}
 	if err := json.NewDecoder(io.LimitReader(r.Body, 1<<20)).Decode(&cmd); err != nil {
 		writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
 		return
 	}
 	if strings.TrimSpace(cmd.Op) == "" {
-		writeErr(w, http.StatusBadRequest, "op 不能为空（ping / interrupt / stop / answer）")
+		writeErr(w, http.StatusBadRequest, "op 不能为空（ping / interrupt / stop / answer / ask_answer）")
 		return
 	}
 	b, _ := json.Marshal(cmd)
@@ -2577,6 +2850,19 @@ func (s *Service) handleStatic(w http.ResponseWriter, r *http.Request) {
 	}
 	p := strings.TrimPrefix(r.URL.Path, "/")
 	if p == "" {
+		// 手机浏览器打开根地址 → 直接给移动端界面（/m/）。
+		// "/" 是 PC 宿主页（见 client-ui/index.html 的文件头），手机上打开只会得到
+		// 被窄屏挤压的桌面布局；移动端有专门的 client-ui-mobile。
+		// 只跳「/m/ 真的能给出页面」的情况（hasMobileUI），否则照旧给 PC 页 —— 否则
+		// 手机用户会落到一个 404 上。
+		if isMobileUA(r.UserAgent()) && s.hasMobileUI() {
+			target := "/m/"
+			if q := r.URL.RawQuery; q != "" {
+				target += "?" + q
+			}
+			http.Redirect(w, r, target, http.StatusFound)
+			return
+		}
 		p = s.opts.Profile.UI.Entry
 		if p == "" {
 			p = "index.html"
@@ -2590,6 +2876,18 @@ func (s *Service) handleStatic(w http.ResponseWriter, r *http.Request) {
 	http.ServeFile(w, r, full)
 }
 
+// isMobileUA 粗判手机浏览器（够用即可，不追求 UA 库的完备度）。
+// iPadOS 13+ 默认发桌面 UA（Macintosh），这里刻意不认 —— 它本来就更适合桌面布局。
+func isMobileUA(ua string) bool {
+	ua = strings.ToLower(ua)
+	for _, k := range []string{"iphone", "ipod", "android", "mobile", "windows phone"} {
+		if strings.Contains(ua, k) {
+			return true
+		}
+	}
+	return false
+}
+
 // mobileRoot 解析移动端界面目录：显式 --mobile-dir 优先，否则取与 --ui-dir 同级的 client-ui-mobile。
 func (s *Service) mobileRoot() string {
 	if d := strings.TrimSpace(s.opts.MobileRoot); d != "" {
@@ -2852,10 +3150,16 @@ func isMediaFile(head []byte, path string) bool {
 	if strings.HasPrefix(ct, "image/") || strings.HasPrefix(ct, "video/") || strings.HasPrefix(ct, "audio/") {
 		return true
 	}
+	// HTML 产物（2026-10-24）：对话内核的产物卡用 <iframe src=/desk/media?path=…> 就地预览
+	// .html/.htm —— 放行 text/html（内容嗅探为主、扩展名兜底，与图 / 视频同一口径）。
+	if strings.HasPrefix(ct, "text/html") {
+		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":
+		".mp3", ".wav", ".m4a", ".aac", ".ogg", ".flac",
+		".html", ".htm", ".xhtml":
 		return true
 	}
 	return false

package/internal/client/service_test.go

@@ -718,6 +718,57 @@ func TestModulesStatic(t *testing.T) {
 	}
 }
 
+// TestRootServesMobileUIToPhone 手机打开 "/" 必须落到移动端界面，且令牌随查询串带过去；
+// 桌面 UA、以及「移动端界面不存在」两种情况仍给 PC 页 —— 后者保证不会把手机送进 404。
+func TestRootServesMobileUIToPhone(t *testing.T) {
+	const iphoneUA = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
+	const desktopUA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36"
+
+	uiDir, mobileDir := t.TempDir(), t.TempDir()
+	for dir, body := range map[string]string{uiDir: "PC", mobileDir: "MOBILE"} {
+		if err := os.WriteFile(filepath.Join(dir, "index.html"), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// 直接构造 Service、只测 handleStatic：这条逻辑不碰 core，测试也就不需要假 core 子进程
+	// （那是个 sh 脚本，Windows 上跑不起来，见 fakeCore）。
+	newSvc := func(mobileRoot string) *Service {
+		return &Service{opts: Options{Profile: DefaultProfile(), UIRoot: uiDir, MobileRoot: mobileRoot}}
+	}
+	get := func(t *testing.T, svc *Service, path, ua string) *httptest.ResponseRecorder {
+		t.Helper()
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		req.Header.Set("User-Agent", ua)
+		rec := httptest.NewRecorder()
+		svc.handleStatic(rec, req)
+		return rec
+	}
+
+	t.Run("手机访问根路径跳移动端", func(t *testing.T) {
+		rec := get(t, newSvc(mobileDir), "/?token=tok", iphoneUA)
+		if rec.Code != http.StatusFound {
+			t.Fatalf("应 302，实际 %d", rec.Code)
+		}
+		if loc := rec.Header().Get("Location"); loc != "/m/?token=tok" {
+			t.Errorf("跳转目标不对：%s", loc)
+		}
+	})
+
+	t.Run("桌面访问根路径仍是PC页", func(t *testing.T) {
+		rec := get(t, newSvc(mobileDir), "/?token=tok", desktopUA)
+		if rec.Code != http.StatusOK || rec.Body.String() != "PC" {
+			t.Errorf("桌面应拿到 PC 页，实际 %d / %q", rec.Code, rec.Body.String())
+		}
+	})
+
+	t.Run("没有移动端界面时不跳", func(t *testing.T) {
+		rec := get(t, newSvc(t.TempDir()), "/?token=tok", iphoneUA) // 空目录 ⇒ hasMobileUI=false
+		if rec.Code != http.StatusOK || rec.Body.String() != "PC" {
+			t.Errorf("应退回 PC 页，实际 %d / %q", rec.Code, rec.Body.String())
+		}
+	})
+}
+
 func TestUploadReadBackAndTraversalGuard(t *testing.T) {
 	svc, err := New(Options{MagicAgent: fakeCore(t, goodContract), Profile: DefaultProfile(), Token: "tok"})
 	if err != nil {