magic-agent 2.4.3 → 2.6.3

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。
@@ -88,6 +89,25 @@ type Options struct {
 	// 打开它 = 任意网页都能**读**响应；真正的门锁仍是令牌（没有 X-Magic-Token 一律 401）。
 	// `--lan` 时默认开启（都绑 0.0.0.0 了，再按 loopback 卡 Origin 没有意义）。
 	AllowAnyOrigin bool
+	/* StatePath 本实例（若是 `magic-client start` 起的）状态文件路径，来自 `--state` /
+	   MAGIC_CLIENT_STATE。升级与重启要「认领自己」：同机可能还跑着别的实例，按路径找状态
+	   文件比按默认路径猜准（默认路径下存的是另一个实例时，重启会重启别人）。 */
+	StatePath string
+	/* SelfStatePath 前台 serve 自登记的状态文件（<数据目录>/serve.json，见 daemon.go）。
+	   与 StatePath 分开两个字段而不是复用一个：两者的语义不同 —— StatePath 是
+	   `start` 的实例记录（还决定日志/令牌位置），SelfStatePath 只是「我是谁」，
+	   重启与升级靠它认领自己。空 = 本实例是 start 起的（走 StatePath / 默认路径）。 */
+	SelfStatePath string
+	/* FeishuAppID / FeishuAppSecret 飞书自建应用的凭据（2026-10-26，「登录后推送通知」）。
+	   优先级：移动端写入的本机 feishu-notify.json > 环境变量 MAGIC_FEISHU_APP_ID/SECRET
+	   > 这里（config.json 的 feishu 节）。空 = 没配置，界面提示去填。见 feishu.go。 */
+	FeishuAppID     string
+	FeishuAppSecret string
+	/* HostPID 托管本服务的父进程（桌面壳 / 测试宿主）。0 = 没人托管。
+	   重启出来的新实例是 detach 的（必须如此，否则旧实例退出会连带杀掉它），
+	   壳就再也杀不到它 —— 于是由服务自己盯着这个 pid：主人没了就优雅退出，
+	   免得孤儿占着端口与单实例锁让下次开壳「插件启动即退出」。见 WatchHost。 */
+	HostPID int
 }
 
 // Service 本地服务。
@@ -109,23 +129,80 @@ type Service struct {
 	// inst 服务实例的稳定 id（见 instance.go）：同一台桌面的多个入口靠它归一。
 	inst instanceIDCache
 
+	/* 本进程的启动时刻（2026-10-27）。
+	 *
+	 * 为什么需要：重启换的是**进程**，会话、任务、设置全在磁盘上，所以界面重启前后
+	 * 长得一模一样 —— 用户点了「重启服务」，看到列表没变，只会得出「没效果」。
+	 * `instanceId` 帮不上忙：它是**同一台桌面**的稳定身份（多入口归一要靠它），
+	 * 跨重启必须不变，所以不能用它判断新旧代。
+	 * 这里给 /desk/health 补一对「这次真的是新进程」的证据：pid + 启动时刻。
+	 * 只增字段，不升 contractVersion；老插件没有 → 客户端退回原判据。 */
+	startedAt time.Time
+
 	// 内置浏览器中转用的 HTTP 客户端（惰性建、带 cookie jar，按上游 host 存会话）。
 	// 见 browse.go —— 它让 iframe 的流量走**桌面端网络**，而不是手机直连。
 	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
+
+	// 工作台应用（「发现 → 应用」，见 apps.go）：magic-shorts / magic-video 的本地
+	// 工作台在这里启停，并经 /workbench/{id}/ 反代给手机内置浏览器。
+	apps *appManager
+
+	/* 会话清单（/desk/sessions）的短 TTL 缓存 + 单飞（2026-10-26，见 sessions_cache.go）。
+	   为什么必须缓存：这个接口每次请求都 spawn 一个 core 进程（`--sessions` 本身约 20ms，
+	   但在负载高的机器上、且 core 是 npm 转发脚本时要 200~900ms）。而列表页是**轮询**驱动的
+	   —— 移动端主列表每 5s 拉一次，一次 loadSessions 还会并发问 5 个接口；PC 左栏在有会话
+	   跑着时每 30s 一次。用户报「会话列表显示很慢」实测就是这个：同一个 core 直连 20ms，
+	   经本插件 400~900ms，10 并发时每个都到 1.6s。 */
+	sessCache sessionsCache
+
 	// 随包发布的移动端 APK（空 = 这个包里没带）。见 apk.go。
 	apkPath string
 
+	// coreTarget 覆盖「桌面端 CLI 的最新版 + 该升哪一份」的解析（只给测试用，见
+	// coreupgrade.go::coreUpgradeTarget）。nil = 按本机真实探测。
+	coreTarget func(context.Context) coreUpgradeTarget
+	// procStartOverride 覆盖「本进程启动时刻」（只给测试用，见 coreupgrade.go::replacedAfterStart）。
+	procStartOverride func() (time.Time, bool)
+	// latestFn 覆盖「问 npm registry 最新版」（只给测试用：不联网）。nil = 真去问。
+	latestFn func(context.Context) string
+
 	/* 公网入口探测（2026-10-22）：隧道是**壳**起的，插件不知道它的域名，而 quick tunnel
-	   每次启动都换域名。这里缓存 probePublicURL 的结果，让 /desk/health 不必每次都扫端口。 */
-	pubMu   sync.Mutex
-	pubURL  string
-	pubExp  time.Time
-	pubBusy bool
+	   每次启动都换域名。这里缓存 probePublicURL 的结果，让 /desk/health 不必每次都扫端口。
+	   2026-10-25：结果**落盘**（见 publicurl.go）—— 客户端重启不该让手机把公网地址换成
+	   局域网地址。pubLoaded 保证只读一次盘；pubMiss 记连续探空次数（两次才认定隧道真没了）；
+	   pubGraceTo 是重启后的宽限期，期内探空不撤已知域名。 */
+	pubMu      sync.Mutex
+	pubURL     string
+	pubExp     time.Time
+	pubBusy    bool
+	pubLoaded  bool
+	pubMiss    int
+	pubGraceTo time.Time
+
+	/* 知识库（OpenViking）的最新版本缓存 + 安装互斥（见 knowledge.go）。
+	   成功缓存 6h、失败缓存 15min —— 失败不该每次开页面都重试一次外网。
+	   ovBusy 挡住两个客户端同时点安装（会抢同一个 venv）。 */
+	ovMu       sync.Mutex
+	ovLatest   string
+	ovLatestOK bool
+	ovLatestAt time.Time
+	ovBusy     bool
+
+	// 飞书推送（/desk/feishu*，见 feishu.go）：惰性建，状态落 ~/.magic-agent/feishu-notify.json。
+	feishuOnce sync.Once
+	feishuN    *feishuNotifier
 }
 
 // Contract core `--contract` 里本插件关心的部分。
@@ -168,10 +245,12 @@ func New(opts Options) (*Service, error) {
 	if opts.Logger == nil {
 		opts.Logger = log.New(os.Stderr, "magic-client: ", 0)
 	}
-	if strings.TrimSpace(opts.MagicAgent) == "" {
-		opts.MagicAgent = "magic-agent"
-	}
-	s := &Service{opts: opts, log: opts.Logger, runs: map[string]*askRun{}}
+	/* core 用**绝对路径**（优先同目录的真二进制），别让 exec 走 PATH ——
+	   PATH 上可能是 npm 的 node 转发脚本，宿主 IDE 的环境足以让它在 require 阶段就崩。
+	   详见 coreexe.go 顶部那段 2026-10-26 的真机记录。 */
+	selfExe, _ := os.Executable()
+	opts.MagicAgent = resolveCoreExe(opts.MagicAgent, selfExe)
+	s := &Service{opts: opts, log: opts.Logger, runs: map[string]*askRun{}, startedAt: time.Now()}
 	// 移动端 APK：显式路径优先；否则在包内 npm/apk/ 找（随 npm 包发布，见 apk.go）。
 	s.apkPath = strings.TrimSpace(opts.APKPath)
 	if s.apkPath == "" {
@@ -193,7 +272,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 +292,8 @@ func New(opts Options) (*Service, error) {
 	/* 作业队列：服务端权威的排队层（多客户端串行 / 幂等 / 重启恢复）。
 	   必须在 New 里就建好：/desk/ask 第一次进来就要能入队。 */
 	s.jobs = newJobQueue(s)
+	// 脚本管理器同理：清单要跨重启保留，运行中的脚本要靠 pid 探活。
+	s.scripts = newScriptManager(s)
 	return s, nil
 }
 
@@ -222,16 +303,63 @@ func (s *Service) Contract() Contract { return s.contract }
 // MagicAgentPath 实际使用的 core 可执行文件。
 func (s *Service) MagicAgentPath() string { return s.opts.MagicAgent }
 
+/* WatchHost 盯着托管本服务的父进程：它没了就调用 quit（2026-10-26）。
+ *
+ * ── 为什么需要 ──
+ * 「手机点重启」要求新实例 detach（独立会话），否则旧实例退出时会把同组的它一起带走。
+ * 可 detach 之后，掌天瓶壳的 `will-quit` 里那句 `r.stop()`（杀的是它 spawn 的那个句柄）
+ * 就管不到新实例了 —— 壳退出、服务还在，占着端口和单实例锁，下次开壳直接「插件启动即退出」，
+ * 用户只能去终端 magic-client stop 救。
+ *
+ * 这里把「主人是谁」变成服务自己的一条退出条件：壳没了，服务主动收摊。于是
+ * 「壳托管」这个语义在重启前后保持一致，不需要壳那边配合改任何东西。
+ *
+ * `magic-client start` 起的常驻实例 HostPID = 0（没人托管）→ 直接返回，行为不变。
+ *
+ * ⚠️ 只在**启动时**判一次「主人在不在」，之后每 2 秒看一次：
+ *    重启链路里父进程可能恰好在我们起来之前退出，那种情况下这个实例本来就没人要了。 */
+func (s *Service) WatchHost(quit func()) {
+	host := s.opts.HostPID
+	if host <= 0 || quit == nil {
+		return
+	}
+	go func() {
+		for {
+			if !HostAlive(host) {
+				s.log.Printf("托管进程（pid %d）已退出：本服务跟着收摊，避免留下孤儿占着端口", host)
+				quit()
+				return
+			}
+			time.Sleep(hostPollInterval)
+		}
+	}()
+}
+
+// hostPollInterval 盯父进程的轮询间隔。
+// 2 秒：壳退出到端口释放要在用户下次开壳前完成，这个粒度足够；又不会太密去打扰系统调用。
+// 是 var 不是 const：用例要把它压到毫秒级，否则测一次要等两秒。
+var hostPollInterval = 2 * time.Second
+
 // Handler 路由。
 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))
+	/* 桌面端 CLI（npm 那份）的版本与升级（见 coreupgrade.go）。2026-10-26 用户：
+	   「版本检测需要同时考虑 apk 和 npm，都要支持升级」—— 升级链路一直有，但这两条
+	   路由从没挂上过（只有测试里手挂），手机根本问不到；这次补上。 */
+	mux.HandleFunc("/desk/core", s.guard(s.handleCoreInfo))
+	mux.HandleFunc("/desk/core/upgrade", s.guard(s.handleCoreUpgrade))
 	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))
@@ -255,14 +383,39 @@ func (s *Service) Handler() http.Handler {
 	// 移动端「环境配置」（引擎/模型/团队/空间选择）的远端存储：多客户端连同一台桌面时共用一份，
 	// 不再各存各的 localStorage（见 prefs.go）。
 	mux.HandleFunc("/desk/prefs", s.guard(s.handlePrefs))
+	/* 飞书推送（2026-10-26）：绑定码 / 绑定 / 开关 / 测试 / 幂等推送，见 feishu.go。
+	   子树路由、一个入口分派 —— 与 /desk/session/ 同一个理由（「有哪些子路径」集中在一处）。 */
+	mux.HandleFunc("/desk/feishu", s.guard(s.handleFeishu))
+	mux.HandleFunc("/desk/feishu/", s.guard(s.handleFeishu))
 	// 需求聚合（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))
+	/* 应用（2026-10-26）：magic-shorts / magic-video 的本地工作台，手机「发现 → 应用」起停。
+	   见 apps.go。反代入口 /workbench/{id}/ 不套 s.guard（与 /b/ 同理）：它只转给
+	   127.0.0.1 上那个工作台，工作台自己要不要鉴权是它的事；页面在根路径下跑时，
+	   由 handleStatic 按 Referer 转发（同样不套 guard —— 工作台的静态资源本就不带令牌）。 */
+	mux.HandleFunc("/desk/apps", s.guard(s.handleApps))
+	mux.HandleFunc("/desk/apps/", s.guard(s.handleAppAction))
+	mux.HandleFunc("/workbench/", s.handleWorkbench)
 	mux.HandleFunc("/desk/dirs", s.guard(s.handleDirs))
 	// /desk/session/{id}/messages 是**前缀匹配**路由 —— 标准 ServeMux 把它挂上后，
 	// 该前缀下任何 path 都先进这里（其它挂载顺序靠后也拦不住）。
@@ -272,7 +425,10 @@ func (s *Service) Handler() http.Handler {
 	mux.HandleFunc("/desk/ask", s.guard(s.handleAsk))
 	mux.HandleFunc("/desk/ask/", s.guard(s.handleAskSub))
 	// 业务模块的路由：原样转发到项目自己的后端（见 Profile.Backend 的注释）。
-	mux.HandleFunc("/api/", s.guard(s.handleProjectAPI))
+	/* /api/* 先看是不是工作台页面发出来的（发现 → 应用）：工作台的工作台页面在根路径下跑，
+	   页面里的 '/api/…' 是根相对的，不能落到项目后端引导师头上。判定见 apps.go 的 workbenchFor，
+	   命中就交给工作台，未命中再照旧（鉴权 + 转给 profile 的 backend）。 */
+	mux.HandleFunc("/api/", s.routeAPI)
 	// 业务模块的静态资源：优先项目自己的模块目录（profile 的 ui.modulesDir）。
 	mux.HandleFunc("/modules/", s.handleModulesStatic)
 	// 二维码配对：把「桌面地址 + 令牌」给手机扫。内容等同于令牌，所以用普通鉴权把门
@@ -287,6 +443,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)
@@ -410,7 +569,12 @@ 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()
+	//
+	// ⚠️ 走 defaultWorkspace() 而不是直接 os.Getwd()（2026-10-26）：插件被 `cd /`
+	// 起来时 cwd 是文件系统根，把它当默认工作区会让移动端新建的会话全归到 `/`，
+	// 同空间冲突判定与 core 的工作空间锁也随之退化成「全机一个空间」。
+	// 规则与作业队列同源（defaultWorkspace：cwd 有意义用它，否则退回上次用的）。
+	wd := defaultWorkspace()
 	writeJSON(w, http.StatusOK, map[string]any{
 		"ok":              true,
 		"contractVersion": s.contract.ContractVersion,
@@ -426,6 +590,16 @@ 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(),
+		// 重启交接（2026-10-25，只增字段）：本实例受理重启、且已算出新实例的样子时，
+		// {urls:[手机可用入口，不带令牌], token:新实例令牌}。手机在「重启服务」的探活里
+		// 顺走它，改完原环境的连接地址与令牌再连 —— 地址随网卡变化、令牌重发都不会让
+		// 手机永远掉线（见 restart.go 的 restartHandoff）。不重启 / 算不出来 → 缺失。
+		"restartHandoff": restartHandoff(),
 		// 服务实例的稳定 id（2026-10-23，只增字段）：同一台桌面的本地 / 局域网 / 公网
 		// 入口可能有多条 URL，客户端据此把它们归一成同一个环境（队列与设置共用）。
 		// 老插件没有该字段 → 客户端退回按连接各自算环境。
@@ -449,6 +623,14 @@ func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
 		// 团队角色清单（2026-10-22）：移动端「团队模式」页要按角色配路由，
 		// 角色名不能由客户端硬编码。老 core 没有 teamRoles → null，客户端回落内置清单。
 		"teamRoles": s.contract.TeamRoles,
+		/* 「这次真的是新进程」的证据（2026-10-27，只增字段，不升 contractVersion）。
+		 *
+		 * 为什么加：重启换的是进程，会话/任务/设置全在盘上，界面重启前后一模一样 ——
+		 * 用户点了「重启服务」看见列表没变，只会说「没效果」（当天真机原话）。
+		 * instanceId 不能担此任：它是同一台桌面的稳定身份，跨重启**必须不变**。
+		 * → pid 变 + startedAt 变才是「换了一代」的硬证据，客户端据此把「已重启」说实。 */
+		"pid":       os.Getpid(),
+		"startedAt": s.startedAt.UTC().Format(time.RFC3339),
 	})
 }
 
@@ -494,9 +676,23 @@ const (
 // /quicktunnel 里，扫一小段端口就能拿到候选，再用**本服务自己的令牌**回打一次
 // /desk/health 确认「这条隧道确实指向我」（别人的隧道令牌不同 → 401）。
 //
-// 空返回 = 没开公网 / 还没扫到；调用方（移动端）退回局域网地址，不假装有。
+// 为什么还要落盘（2026-10-25 用户：「重启也尽量不要变 cloudflare 域名就可以了」）：
+// 域名只随**隧道**重启而变，magic-client 重启并不碰 cloudflared。可探测结果只在内存里，
+// 客户端一重启就空，手机就退回局域网地址 —— 表现成「重启后地址变了」。所以启动先读回
+// 上次的域名立刻顶上，后台探测再纠正（见 publicurl.go）。
+//
+// 空返回 = 没开公网 / 已确认没了；调用方（移动端）退回局域网地址，不假装有。
 func (s *Service) publicURL() string {
 	s.pubMu.Lock()
+	if !s.pubLoaded {
+		s.pubLoaded = true
+		if v := s.loadSavedPublicURL(); v != "" {
+			s.pubURL = v
+			/* exp 保持零值 = 立刻触发一次后台探测（只是别让 health 等它）；
+			   grace 期内探不到也不撤这个已知域名。 */
+			s.pubGraceTo = time.Now().Add(publicGrace)
+		}
+	}
 	cur, exp, busy := s.pubURL, s.pubExp, s.pubBusy
 	s.pubMu.Unlock()
 	if busy || time.Now().Before(exp) {
@@ -510,31 +706,95 @@ func (s *Service) publicURL() string {
 	s.pubBusy = true
 	s.pubMu.Unlock()
 
-	go func() {
-		u := s.probePublicURL()
-		s.pubMu.Lock()
-		changed := u != s.pubURL
-		s.pubURL = u
-		s.pubExp = time.Now().Add(publicTTL)
-		s.pubBusy = false
-		s.pubMu.Unlock()
-		if changed && s.log != nil {
-			if u == "" {
-				s.log.Printf("公网入口：未发现（本机没有指向本服务的 cloudflared quick tunnel）")
-			} else {
-				s.log.Printf("公网入口：%s", u)
-			}
-		}
-	}()
+	go func() { s.applyProbeResult(s.probePublicURL()) }()
 	return cur
 }
 
+// applyProbeResult 收下一次探测的结果：更新缓存、落盘、记探空次数。
+//
+// 抽成方法是为了能直接测（各人机器上网卡/隧道千差万别，靠真起 cloudflared 测不稳）。
+// 规则见 publicGrace 与 publicTTL 的注释：宽限期内探空不动已知域名；连续两次探空
+// 且过了宽限期才认定隧道真没了。
+func (s *Service) applyProbeResult(u string) {
+	s.pubMu.Lock()
+	prev := s.pubURL
+	inGrace := time.Now().Before(s.pubGraceTo)
+	/* 宽限期内探不到 → 已知域名继续顶着（cloudflared 可能比我们起得慢）。
+	   真探到了就以新值为准（隧道重起换了域名）。 */
+	next := u
+	if u == "" && inGrace && prev != "" {
+		next = prev
+	}
+	changed := next != prev
+	s.pubURL = next
+	s.pubExp = time.Now().Add(publicTTL)
+	s.pubBusy = false
+	if u == "" {
+		s.pubMiss++
+	} else {
+		s.pubMiss = 0
+	}
+	miss := s.pubMiss
+	s.pubMu.Unlock()
+
+	/* 落盘：探到了就存；连续两次探空（且过了宽限期）才认定隧道真没了、删掉旧域名。
+	   只探空一次就删太激进 —— cloudflared 刚起、metrics 还没就绪时也会空。 */
+	switch {
+	case u != "":
+		s.savePublicURL(u)
+	case miss >= 2 && !inGrace:
+		s.clearSavedPublicURL()
+	}
+
+	if changed && s.log != nil {
+		if next == "" {
+			s.log.Printf("公网入口：未发现（本机没有指向本服务的 cloudflared quick tunnel）")
+		} else {
+			s.log.Printf("公网入口：%s", next)
+		}
+	}
+}
+
 // probePublicURL 扫 cloudflared 的 metrics 端口，找出指向本服务的那条 quick tunnel。
 func (s *Service) probePublicURL() string {
 	tok := strings.TrimSpace(s.opts.Token)
 	if tok == "" {
 		return ""
 	}
+	cands := quickTunnelHosts()
+	if len(cands) == 0 {
+		return ""
+	}
+
+	// 用本服务的令牌回打一次：只有真正指向本服务的隧道才认这个令牌。
+	var (
+		mu    sync.Mutex
+		found string
+		wg    sync.WaitGroup
+	)
+	for _, h := range cands {
+		wg.Add(1)
+		go func(host string) {
+			defer wg.Done()
+			if !healthOK("https://"+host, tok, 3*time.Second) {
+				return
+			}
+			mu.Lock()
+			if found == "" {
+				found = "https://" + host
+			}
+			mu.Unlock()
+		}(h)
+	}
+	wg.Wait()
+	return found
+}
+
+// quickTunnelHosts 列出本机 cloudflared 当前挂在 metrics 端口上的 quick tunnel 域名。
+//
+// 单独抽出来是为了「验证式取址」：缓存里的域名可能是**上一轮隧道**留下的（进程重启
+// 就换域名），手机上表现为「卡片里的地址打不开」。发消息前要拿这份**当前**清单重新验。
+func quickTunnelHosts() []string {
 	hosts := make(chan string, quickTunnelPortHi-quickTunnelPortLo+1)
 	for p := quickTunnelPortLo; p <= quickTunnelPortHi; p++ {
 		go func(port int) {
@@ -561,46 +821,32 @@ func (s *Service) probePublicURL() string {
 			cands = append(cands, h)
 		}
 	}
-	if len(cands) == 0 {
-		return ""
-	}
+	return cands
+}
 
-	// 用本服务的令牌回打一次：只有真正指向本服务的隧道才认这个令牌。
-	var (
-		mu    sync.Mutex
-		found string
-		wg    sync.WaitGroup
-	)
-	for _, h := range cands {
-		wg.Add(1)
-		go func(host string) {
-			defer wg.Done()
-			req, err := http.NewRequest(http.MethodGet, "https://"+host+"/desk/health", nil)
-			if err != nil {
-				return
-			}
-			req.Header.Set("X-Magic-Token", tok)
-			resp, err := (&http.Client{Timeout: 3 * time.Second}).Do(req)
-			if err != nil {
-				return
-			}
-			defer resp.Body.Close()
-			if resp.StatusCode != http.StatusOK {
-				return
-			}
-			var v map[string]any
-			if json.NewDecoder(resp.Body).Decode(&v) != nil || v["ok"] != true {
-				return
-			}
-			mu.Lock()
-			if found == "" {
-				found = "https://" + host
-			}
-			mu.Unlock()
-		}(h)
+// healthOK 用本服务的令牌回打一次 /desk/health：只有真指向本服务的入口才会 200 + ok。
+// 这是「地址能不能用」的唯一可信判据 —— 不能只看域名像不像、也不能信缓存。
+func healthOK(base, tok string, timeout time.Duration) bool {
+	req, err := http.NewRequest(http.MethodGet, strings.TrimRight(base, "/")+"/desk/health", nil)
+	if err != nil {
+		return false
 	}
-	wg.Wait()
-	return found
+	if tok != "" {
+		req.Header.Set("X-Magic-Token", tok)
+	}
+	resp, err := (&http.Client{Timeout: timeout}).Do(req)
+	if err != nil {
+		return false
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return false
+	}
+	var v map[string]any
+	if json.NewDecoder(resp.Body).Decode(&v) != nil {
+		return false
+	}
+	return v["ok"] == true
 }
 
 // handleContract 原样转发 core 的契约（客户端拿它做能力降级，不需要经过插件再解释一遍）。
@@ -630,11 +876,54 @@ func (s *Service) handleProfile(w http.ResponseWriter, r *http.Request) {
 // （用户 2026-10-15：「通过 magic-test 新建的会话要在 magic-agent 移动端 h5 上看到，
 // 同时 magic-agent 上可以看到 magic-test 和 magic-agent 来源的会话」）。
 //
-// 名单两项：magic-test = 掌天瓶桌面壳；magic-agent = core 自身/直连 CLI 的显式标识。
-// ⚠️ 只放行**同族的 magic-* 来源**：匿名（空 client = 手工跑 / CI）与不相干应用仍被挡在
-// 外面 —— 这正是原过滤要避免的「把别人的任务混进本应用的会话列表」。
+// ⚠️ 2026-10-26（用户：「多个客户端要能拉到同样的会话历史」）：**从「认名字」改成
+// 「认同族」**。此前是钉死的两个字符串 `{magic-test, magic-agent}`，于是每接一个新
+// 客户端（另一个 magic-* 桌面应用、改了 bundleId 的构建、用户自己起的 magic-xxx）
+// 都得回来改这句常量 —— 忘了改的表现是**静默少一堆会话**，而且只有那个客户端看不见，
+// 极难归因。改成按前缀判定后不再有这个维护点。
+//
+// 判据（见 sessionClientVisible）：本插件自己的 AppID / 同族 magic-* 前缀 /
+// 本仓认得的历史遗留名。匿名（空 client = 手工跑 / CI）与不相干应用仍被挡住 ——
+// 那正是这次过滤要避免的「把别人的任务混进本应用的会话列表」。
 var extraSessionClients = []string{"magic-test", "magic-agent"}
 
+/*
+	sessionClientVisible 这个来源客户端该不该出现在本客户端的会话列表里。
+
+//
+// 三条放行理由，任一成立即可：
+//
+//	① 就是我（Profile.AppID）—— 从这台机器上、经本插件发起的；
+//	② 同族（前缀 magic-）—— 掌天瓶、别的 magic-* 桌面应用、直连 CLI 的显式标识。
+//	   族内互看是用户 2026-10-15 定的口径，2026-10-26 的多客户端需求只是把它推广开；
+//	③ 名单里显式列出的历史遗留名（extraSessionClients）。
+//
+// ⚠️ 为什么不干脆全放行（把 client 过滤整个删掉）：登记表在 ~/.magic-agent/sessions，
+// 是**全机共享**的 —— 用户手工跑的、CI 跑的、别的产品写的都在里面，client 为空。
+// 全放行的结果是把「不知道哪来的」会话混进本应用列表，那比少显示几条更难查。
+//
+// ⚠️ 前缀故意用 `magic-` 而不是更宽的 `magic`：`magic` 会把 magicclient、magical 之类
+// 的第三方标识也认进来，前缀带连字符才是这一族的命名约定。
+*/
+func sessionClientVisible(client, selfID string) bool {
+	c := strings.TrimSpace(client)
+	if c == "" {
+		return false // 匿名 = 手工跑 / CI / 旧记录：不混进本应用列表
+	}
+	if c == strings.TrimSpace(selfID) {
+		return true // ①
+	}
+	if strings.HasPrefix(c, "magic-") {
+		return true // ②
+	}
+	for _, allowed := range extraSessionClients {
+		if c == allowed {
+			return true // ③
+		}
+	}
+	return false
+}
+
 // handleSessions 会话登记表（core 的 `--sessions`）：列表页的「最近会话」用它。
 // 与 /desk/asks 的区别：asks 是**本进程正在跑的轮次**（内存里），sessions 是 core 的
 // 持久登记表（跨进程、含已结束的）。
@@ -643,11 +932,17 @@ var extraSessionClients = []string{"magic-test", "magic-agent"}
 // （~/.magic-agent/sessions），直接跑 CLI（匿名）、CI、别的 magic-* 应用都在往里写 ——
 // 原样转发等于把别人的任务混进本应用的会话列表。认客户端靠 core 落的 Record.Client
 // （本插件在 /desk/ask 时注入自己的 AppID；掌天瓶桌面壳注入 magic-test）。
-// 放行名单见 extraSessionClients（2026-10-15 起，不再是「只认自己」）。
+// 放行判据见 sessionClientVisible（2026-10-26 起按**同族前缀**判，不再认死名字）。
 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()
+	/* 短 TTL 缓存 + 单飞（见 sessions_cache.go）：列表页是轮询驱动的，而这里每次都 spawn
+	   一个 core 进程 —— 实测同一个 core 直连 20ms、经本插件 200~900ms，10 并发各 1.6s。
+	   缓存的是 core 的**原始输出**，所以下面按 selfID 过滤仍然逐请求做（每个实例的
+	   AppID 不同，缓存过滤结果会让第二个实例看到别人的列表）。 */
+	out, err := s.sessCache.get(ctx, sessionsTTL(), func(ctx context.Context) ([]byte, error) {
+		return newCoreCmd(ctx, s.opts.MagicAgent, "--sessions").Output()
+	})
 	if err != nil {
 		writeErr(w, http.StatusBadGateway,
 			fmt.Sprintf("%s --sessions 失败：%v", s.opts.MagicAgent, err))
@@ -663,17 +958,18 @@ func (s *Service) handleSessions(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write(out)
 		return
 	}
-	allowed := map[string]bool{s.opts.Profile.AppID(): true}
-	for _, c := range extraSessionClients {
-		allowed[c] = true
-	}
+	selfID := s.opts.Profile.AppID()
 	mine := make([]map[string]any, 0, len(rows))
 	for _, row := range rows {
-		if c, _ := row["client"].(string); allowed[c] {
+		c, _ := row["client"].(string)
+		if sessionClientVisible(c, selfID) {
 			mine = append(mine, row)
 		}
 	}
-	writeJSON(w, http.StatusOK, mine)
+	/* 按会话折叠多轮记录（见 sessions_fold.go）：411 行里 302 行是同一会话的其它轮次，
+	   列表是**会话**视图，一屏也只画 60 行 —— 「最新那条会话排不进去」正是折叠前的问题。
+	   顺序在过滤之后：可见性逐行判（只看 client），折叠再按 session_id 归并，两步互不干扰。 */
+	writeJSON(w, http.StatusOK, foldSessionRuns(mine))
 }
 
 // handleSessionMessages 「看历史」持久化落盘的会话事件（`GET /desk/session/{id}/messages`）。
@@ -1043,6 +1339,8 @@ func (s *Service) handleSessionTitle(w http.ResponseWriter, r *http.Request, id
 		writeErr(w, http.StatusInternalServerError, "保存标题失败："+err.Error())
 		return
 	}
+	// 改名后列表里的标题要立刻变（见 sessions_cache.go）。
+	s.invalidateSessionsCache()
 	t := strings.TrimSpace(body.Title)
 	if t == "" {
 		t = session.TitleFor(id)
@@ -1079,7 +1377,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))
@@ -1098,6 +1396,10 @@ func (s *Service) handleSessionTitleSummarize(w http.ResponseWriter, r *http.Req
 		writeErr(w, http.StatusBadGateway, "core 回的归纳结果不是 JSON："+truncateForMsg(string(out)))
 		return
 	}
+	/* 归纳出了新标题 → 列表要立刻换（见 sessions_cache.go）。这条尤其重要：客户端
+	   补归纳是「列表画完之后逐条异步打」的（移动端 ensureTitle），如果缓存不失效，
+	   归纳结果要等一个 TTL 才反映到列表上，用户会以为没生效。 */
+	s.invalidateSessionsCache()
 	writeJSON(w, http.StatusOK, res)
 }
 
@@ -1126,6 +1428,9 @@ func truncateForMsg(s string) string {
 // 还没拿到轮次 id」）。
 func (s *Service) handleSessionStop(w http.ResponseWriter, r *http.Request, id string) {
 	res, err := session.Stop(id)
+	/* 停会话改了登记表的 state → 列表必须立刻反映（否则用户看到「停了但还在跑」
+	   停留一个 TTL）。见 sessions_cache.go。缓存没建立时这一步是空操作。 */
+	s.invalidateSessionsCache()
 	if err != nil {
 		writeErr(w, http.StatusNotFound, fmt.Sprintf("停止会话 %s 失败：%v", id, err))
 		return
@@ -1155,6 +1460,8 @@ func (s *Service) handleSessionDelete(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	res, err := session.Delete(id)
+	// 删掉了一条 → 列表必须立刻反映（见 sessions_cache.go）。
+	s.invalidateSessionsCache()
 	if err != nil {
 		writeErr(w, http.StatusBadRequest, fmt.Sprintf("删除会话 %s 失败：%v", id, err))
 		return
@@ -1551,6 +1858,18 @@ func (s *Service) handleModules(w http.ResponseWriter, r *http.Request) {
 //  2. **凭据服务端注入**：profile 里的 backend.token 由插件加进请求头，不进浏览器。
 //  3. **支持流式**：项目的后端可能用 SSE 推进度（magic-test 的派发流就是），
 //     所以用 ReverseProxy + 立即 flush，不缓冲整段响应。
+//
+// routeAPI 是 /api/* 的总入口：工作台页面发来的走工作台反代，其余走项目后端转发。
+func (s *Service) routeAPI(w http.ResponseWriter, r *http.Request) {
+	if spec, port, ok := s.workbenchFor(r); ok {
+		/* 路径原样交给工作台（'/api/…' 就是工作台的 '/api/…'）：serveWorkbench 的第三个参数
+		   是「要改写成什么路径」，传空 = 不改写。 */
+		s.serveWorkbench(w, r, spec, port, "")
+		return
+	}
+	s.guard(s.handleProjectAPI)(w, r)
+}
+
 func (s *Service) handleProjectAPI(w http.ResponseWriter, r *http.Request) {
 	target := strings.TrimSpace(s.opts.Profile.Backend.URL)
 	if target == "" || s.backend == nil {
@@ -1650,7 +1969,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 +2055,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 +2164,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 +2185,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 /
@@ -1867,6 +2360,17 @@ type askRequest struct {
 	// Serial 是否参与「同一 workspace 单槽」串行（nil / true = 参与）。
 	// 客户端「并行模式」显式传 false；服务端仍会套一层全局并发上限。
 	Serial *bool `json:"serial,omitempty"`
+	/* Mode 任务模式（2026-10-26，只增）：**每个会话提交都过这一道**。
+	   "auto"     = 由服务端判「本轮与同空间运行中的任务是否冲突」再裁决串行/并行；
+	   "parallel" = 一律并行，不判定；
+	   "serial"   = 同空间单槽串行，不判定；
+	   空 / 其它  = 沿用 Serial 的老语义（老客户端一行不改也保持原有行为）。
+	 两者同时给时**以 Mode 为准**（用户选的那个说了算，Serial 只当缺省回退）。 */
+	Mode string `json:"mode,omitempty"`
+	/* JudgeEngine / JudgeModel 判定用哪个引擎（前端传用户配的「建议引擎」）。
+	   空 = core 默认 llm。判定预算是异步的，提交侧不等待（见 jobs_auto.go）。 */
+	JudgeEngine string `json:"judgeEngine,omitempty"`
+	JudgeModel  string `json:"judgeModel,omitempty"`
 }
 
 // teamRequest 团队模式的请求体（POST /desk/ask 的 team 字段）。
@@ -1893,6 +2397,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 +2427,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 +2529,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 +2580,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) {
@@ -2115,7 +2649,17 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 
 	ctx := r.Context()
 	run, ok := s.jobs.waitStarted(ctx, job, func(pos int) {
-		send("queued", map[string]any{"job": job.ID, "state": JobQueued, "position": pos})
+		ev := map[string]any{"job": job.ID, "state": JobQueued, "position": pos}
+		/* 自动模式的判定结论随排队事件一起下发（2026-10-26，只增字段）：客户端要能
+		   当场说「为什么在排队」，否则只会显示一句「等待中」，看起来像模式开关没生效。
+		   判定是异步的，job 是提交时的副本 —— 这里重新取一次最新状态。 */
+		if cur := s.jobs.get(job.ID); cur != nil {
+			if cur.Auto != nil {
+				ev["auto"] = cur.Auto
+			}
+			ev["serial"] = cur.Serial
+		}
+		send("queued", ev)
 	})
 	if !ok {
 		/* 排队期间客户端断开：匿名提交（没有 request_id）没人会再来接，直接撤掉；
@@ -2172,6 +2716,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)
 	}
@@ -2241,6 +2796,24 @@ func (s *Service) prepareAsk(req askRequest) (string, []string, int, error) {
 	return engine, args, http.StatusOK, nil
 }
 
+/* workspaceLockEnv 决定给 core 传什么工作空间锁开关（2026-10-26）。
+ *
+ * 背景：core 的锁**默认生效**。于是"串行"是免费的（什么都不传），"并行"必须显式关。
+ * 这条以前是反的（只有传 `=1` 才开），语义一翻转就必须集中在一处 —— 散在 startAsk
+ * 里没人测得出来，而这正是会「看着开了、实际没生效」的那种 bug。
+ *
+ * 返回值：nil = 不追加任何环境变量（走 core 默认 = 串行）；否则是一条 K=V。
+ *   · serial 未指定（nil）→ 按串行处理，与 jobs.go 的默认值同一口径；
+ *   · serial=false → 显式 `=0`，让同空间的并行作业真能并行；
+ *   · serial=true → nil（不必冗余地写 `=1`，core 的默认就是开）。
+ */
+func workspaceLockEnv(serial *bool) []string {
+	if serial == nil || *serial {
+		return nil
+	}
+	return []string{session.EnvWorkspaceLock + "=0"}
+}
+
 /*
 	startAsk 真正拉起 core 并开始吸收 stdout（不绑任何 HTTP 请求）。
 
@@ -2250,16 +2823,18 @@ 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 的进程也参与同一套串行。 */
-	cmd.Env = append(os.Environ(),
+	   · EnvClient  发起方应用（本插件的 AppID）—— 列表页据此**只显示本客户端发起的会话。
+	   工作空间锁按 workspaceLockEnv 的裁决传（串行 = 不传，并行 = 显式关）——
+	   细节与所以然都在那个函数上，别在这里再写一份判据。 */
+	/* cleanHostEnv：摘掉宿主 IDE 塞进来的 node 垫片与假命令目录 —— 否则引擎子进程
+	   连不上宿主的 broker，每条任务都 failed（2026-10-26 真机，见 hostenv.go）。 */
+	cmd.Env = append(cleanHostEnv(os.Environ()),
 		session.EnvSource+"="+source,
-		session.EnvClient+"="+s.opts.Profile.AppID(),
-		session.EnvWorkspaceLock+"=1")
+		session.EnvClient+"="+s.opts.Profile.AppID())
+	cmd.Env = append(cmd.Env, workspaceLockEnv(req.Serial)...)
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
 		return nil, fmt.Errorf("stdin pipe: %w", err)
@@ -2422,13 +2997,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)
@@ -2575,8 +3157,28 @@ func (s *Service) handleStatic(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, http.StatusInternalServerError, err.Error())
 		return
 	}
+	/* 工作台在根路径下跑（见 apps.go 的文件头）：页面用 '/api/…' 这种根相对地址，
+	   它们带着 Referer=…/workbench/{id}/，先转给工作台 —— 必须先于下面所有静态判定，
+	   否则 '/api/*' 会被当成 UI 目录里的文件（404），页面能出来、数据全空。 */
+	if spec, port, ok := s.workbenchFor(r); ok {
+		s.serveWorkbench(w, r, spec, port, "")
+		return
+	}
 	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 +3192,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 +3466,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