magic-agent 2.6.0 → 2.6.3

package/internal/client/apps.go

@@ -0,0 +1,1078 @@
+package client
+
+// apps.go - 「发现 → 应用」：magic-* 工程自带的工作台（Web App）在手机上挂号。
+//
+// ## 这个功能是什么
+//
+// magic-shorts / magic-video 各自带一个本地工作台（magic-shorts serve → :8899、
+// magic-video workbench → :7789）。它们绑在桌面端的 127.0.0.1 上，手机连不上；
+// 想在手机上看，就得有人在桌面上起进程、再把地址送到手机。这一页就是这个中间人：
+//
+//	手机 → GET  /desk/apps               → 有哪些应用、装没装、跑没跑、地址
+//	手机 → POST /desk/apps/{id}/start    → 在**桌面端**起工作台（后台进程组），等端口应答再回
+//	手机 → POST /desk/apps/{id}/stop     → 连它起的子进程一起收掉
+//	手机 → GET  /workbench/{id}/…        → 反代到 127.0.0.1:<port>（手机内置浏览器的中转入口）
+//	手机 → GET  /{根路径}（Referer 是 /workbench/{id}/） → 同样转给工作台
+//
+// 最后一条是必须的：两个工作台的页面全用**根相对地址**（fetch('/api/…')、
+// '/api/media?…'、模板封面 url 也是 '/api/…'）。只挂在子路径下时页面能出来、数据全空。
+// 所以手机打开时先到 /workbench/{id}/（探活 + 跳转），再让页面**在根路径下**跑，
+// 由 handleStatic 按 Referer 认出「这是那个工作台」并转发（见 service.go）。
+//
+// ## 为什么放在插件（magic-client）这一侧而不是 core
+//
+// 与 plugins.go / scripts.go 的理由同源：这不是「跑一轮 agent」，而是一个**常驻的
+// Web 服务**。core 进程跑完一轮就退出，不知道「这个服务现在还活着」。只有常驻的
+// 插件知道，也只有它能 spawn / 杀 / 反代。
+//
+// ## ── 纪律 ──
+//
+//  1) **命令只来自下面这张表**。客户端只传 id 与动作，接口不接受命令行 ——
+//     否则这就是一个任意命令执行器。
+//  2) **不假装成功**：起不来就把输出尾巴（stderr）原样回给手机；`running` 以
+//     **端口探活**为准，不看「我 spawn 过没有」。别人（菜单栏 App / 终端）起的同一个
+//     工作台，这里也如实显示成「运行中（外部）」，并且能正常打开。
+//  3) **停止只杀自己起的**：外部实例如实回报「请到桌面端停」—— 我们自己起的进程组
+//     能从外面整组带走；别人起的，杀了就是杀了人家正在干的活儿。
+//  4) **反代只连回环**：目标固定成 127.0.0.1:<该应用的端口>，请求路径里进不来主机名。
+//
+// ## 存储
+//
+//	~/.magic-agent/apps/runs.json    运行态（仅自己起的：pid / 端口 / 启动时刻 / 输出尾巴）
+//	~/.magic-agent/apps/logs/<id>.log 完整输出（起不来时看原因）
+//
+// 服务重启后工作台进程还在（脱离的进程组），但插件忘了它 —— 运行态落盘后靠 pid 探活
+// 认领回来，否则会出现「明明在跑，界面说已停止，点启动又报端口被占」。
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+/* ─────────────── 数据形状（CLIENT-CONTRACT §2 GET /desk/apps） ─────────────── */
+
+// AppState 运行态。State: stopped | starting | running。
+type AppState struct {
+	State string `json:"state"`
+	// Running 端口上真的有人应答（与 Managed 无关：别人起的工作台也算运行中）。
+	Running bool `json:"running"`
+	// Managed 是本客户端起的（能从这里停）；false + Running = 外部起的。
+	Managed bool `json:"managed"`
+	PID     int  `json:"pid,omitempty"`
+	// Port 工作台现在实际监听的端口（没在跑 = 0）。
+	Port int `json:"port,omitempty"`
+	// URL 手机可用的入口（相对地址，见 OpenURL）—— 内置浏览器打开的就是它。
+	URL string `json:"url,omitempty"`
+	// LocalURL 桌面端自己的地址（手机打不开，给人看的）。
+	LocalURL string `json:"localUrl,omitempty"`
+	// LogTail 最近几行输出（起不来时就是原因，不让人去桌面翻）。
+	LogTail   []string `json:"logTail,omitempty"`
+	StartedAt int64    `json:"startedAt,omitempty"`
+	// Error 人话说明（为什么是这个状态）。
+	Error string `json:"error,omitempty"`
+	// PortBusy 端口上有人听，但**不是**这套工作台（2026-10-27）。
+	//
+	// 为什么需要：端口探活只证明「有东西在听」。magic-video 上就撞见过 —— 7789 被一个
+	// 10 天前起的旧实例占着，它只服务 /api/*、/ 返回 404，于是手机点「打开」永远是一张
+	// 白板，而界面还写着「运行中」。这种状态必须与 running 分开说：先告诉人「端口被占」，
+	// 再给原因（GET / 返回了什么），别让人对着「运行中」猜。
+	PortBusy bool `json:"portBusy,omitempty"`
+}
+
+// AppItem GET /desk/apps 的一项。
+type AppItem struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Tagline     string `json:"tagline"`
+	Description string `json:"description,omitempty"`
+	Homepage    string `json:"homepage,omitempty"`
+	CLI         string `json:"cli"`
+	// Landscape 建议手机横屏打开（内置浏览器据此自动转屏，见 appSpec.Landscape）。
+	Landscape  bool     `json:"landscape,omitempty"`
+	Command    string   `json:"command"`
+	Port       int      `json:"port"`
+	Installed  bool     `json:"installed"`
+	SourcePath string   `json:"sourcePath,omitempty"`
+	State      AppState `json:"state"`
+	// Note 服务端对「装没装 / 起没起」的一句话解释，客户端原样显示，不自己编。
+	Note string `json:"note,omitempty"`
+	// OpenURL 手机内置浏览器该打开的地址（相对本服务）。
+	//
+	// 为什么不直接打开页面本身：手机入口可能是局域网 IP、回环或隧道，相对地址永远
+	// 跟着当前入口走；先到这个入口是为了**探活**（没在跑就回一句人话，而不是一个
+	// 打不开的白屏），再由服务端跳转到 "/" 让工作台在根路径下跑（见文件头）。
+	OpenURL string `json:"openUrl,omitempty"`
+}
+
+/* ─────────────── 注册表（服务端固定表，不接受客户端输入） ─────────────── */
+
+type appSpec struct {
+	ID          string
+	Name        string
+	Tagline     string
+	Description string
+	Homepage    string
+	// CLI PATH 上的命令名（探测装没装用）。
+	CLI string
+	// Port 工作台端口。**显式**传给它 —— 不传的话两端都会「从上次端口文件里捡」，
+	// 换项目 / 换机器后手机拿到的地址就是坏的。
+	Port int
+	// Repo 源码目录（默认 ~/.openclaw/workspace/<工程>，可被环境变量覆盖）。
+	Repo string
+	// Install 装法（手机上展示；实际安装在「发现 → 插件」那一页）。
+	Install string
+	/* Landscape 这个工作台按**桌面宽屏**排版（2026-10-27）。
+	 *
+	 * 只影响手机：内置浏览器竖屏打开时先转成横屏，并把「切回竖屏」摆在明面上。
+	 * 为什么不让前端自己量：magic-video 的页面是响应式的，竖屏下 scrollWidth 只溢出
+	 * 三十几像素（恰好切掉顶栏那排 tab），按「溢出多少」判永远判不出来 —— 但它三栏
+	 * 时间线在竖屏里确实难用。这种事让应用自己声明，比让浏览器猜准。 */
+	Landscape bool
+	// Build 由源码目录构造启动命令（argv，不过 shell）。返回 nil = 起不来（并给出原因）。
+	Build func(repo string, node string) ([]string, error)
+	// Urls 这台机器上「这个工作台现在到底在哪」的探测顺序：先看应用自己写到
+	// 数据目录的端口文件（~/.magic-video/workbench.port），再看默认端口。
+	// 外部起的实例（端口被显式换过）靠它也能被认出来。
+	Urls func() []int
+}
+
+// nodeBin 找 node 可执行文件：PATH 上没有时，顺着 PATH 上的 npm / npx 的链接找同目录的 node。
+//
+// 为什么要这么绕：桌面端若从 GUI（菜单栏 / 启动项）起，PATH 往往只有 /usr/bin:/bin，
+// Homebrew / nvm 的 node 不在里面 —— `magic-shorts serve` 直接「找不到 node」。
+// 顺着 npm 的符号链接走，是最不依赖具体安装方式的一条路。
+func nodeBin() (string, bool) {
+	if p, err := exec.LookPath("node"); err == nil {
+		return p, true
+	}
+	for _, tool := range []string{"npm", "npx"} {
+		p, err := exec.LookPath(tool)
+		if err != nil {
+			continue
+		}
+		if real, err := filepath.EvalSymlinks(p); err == nil {
+			p = real
+		}
+		dir := filepath.Dir(p)
+		for _, name := range []string{"node", "node.exe"} {
+			cand := filepath.Join(dir, name)
+			if st, err := os.Stat(cand); err == nil && !st.IsDir() {
+				return cand, true
+			}
+		}
+	}
+	return "", false
+}
+
+// appSpecs 返回注册表与「本机能做什么」的提示（例如没有 node）。
+func appSpecs() ([]appSpec, []string) {
+	home, _ := os.UserHomeDir()
+	workspace := filepath.Join(home, ".openclaw", "workspace")
+	if v := strings.TrimSpace(os.Getenv("MAGIC_CLIENT_WORKSPACE")); v != "" {
+		workspace = v
+	}
+	dataHome := func(app string) string {
+		if v := strings.TrimSpace(os.Getenv("MAGIC_CLIENT_APPS_HOME")); v != "" {
+			return filepath.Join(v, "."+app)
+		}
+		return filepath.Join(home, "."+app)
+	}
+	// portFilePorts 读应用写下的端口文件（一行整数），再补上默认端口（去重保序）。
+	portFilePorts := func(defaultPort int, files ...string) func() []int {
+		return func() []int {
+			out := []int{defaultPort}
+			for _, f := range files {
+				b, err := os.ReadFile(f)
+				if err != nil {
+					continue
+				}
+				n, err := strconv.Atoi(strings.TrimSpace(string(b)))
+				if err != nil || n <= 0 || n > 65535 {
+					continue
+				}
+				dup := false
+				for _, x := range out {
+					if x == n {
+						dup = true
+					}
+				}
+				if !dup {
+					out = append([]int{n}, out...)
+				}
+			}
+			return out
+		}
+	}
+
+	specs := []appSpec{
+		{
+			ID:      "magic-shorts",
+			Name:    "magic-shorts",
+			Tagline: "知识短视频工作台：选题 → 脚本 → 配音 → 素材 → 成片",
+			Description: "magic-shorts 的本地工作台：按项目看六个阶段的进度、跑单阶段、看脚本与成片。" +
+				"启动后在手机内置浏览器里打开（走桌面端的网络）。",
+			Homepage: "https://github.com/javacn/magic-shorts",
+			CLI:      "magic-shorts",
+			Port:     8899,
+			Repo:     filepath.Join(workspace, "magic-shorts"),
+			Install:  "npm install -g <magic-shorts 源码目录>",
+			Build: func(repo, node string) ([]string, error) {
+				server := filepath.Join(repo, "server.js")
+				if _, err := os.Stat(server); err != nil {
+					return nil, fmt.Errorf("%s 里没有 server.js", repo)
+				}
+				if node == "" {
+					return nil, errors.New("这台桌面找不到 node")
+				}
+				return []string{node, server}, nil
+			},
+			Urls: portFilePorts(8899, filepath.Join(dataHome("magic-shorts"), "workbench.port")),
+		},
+		{
+			ID:      "magic-video",
+			Name:    "magic-video",
+			Tagline: "短剧 / 小说 / 视频分镜工作台：一站式平台",
+			Description: "magic-video 的本地工作台：小说、短剧、视频三条线的管线可视化与运行控制。" +
+				"启动后在手机内置浏览器里打开（走桌面端的网络）。",
+			Homepage: "https://github.com/javacn/magic-video",
+			CLI:      "magic-video",
+			Port:     7789,
+			Repo:     filepath.Join(workspace, "magic-video"),
+			Install:  "npm install -g @magicstock/magic-cli",
+			// 三栏 + 时间线 + 分章表格：竖屏里顶栏那排 tab 直接被切（2026-10-27 实测）。
+			Landscape: true,
+			Build: func(repo, node string) ([]string, error) {
+				dir := filepath.Join(repo, "workbench")
+				server := filepath.Join(dir, "server.js")
+				if _, err := os.Stat(server); err != nil {
+					return nil, fmt.Errorf("%s 里没有 workbench/server.js", repo)
+				}
+				if node == "" {
+					return nil, errors.New("这台桌面找不到 node")
+				}
+				// server.js 在 cwd 里找 workbench/lib/*，所以要先进 workbench/。
+				// 端口显式给：不给时它会对「上次端口」做粘性探测，而反代目标固定，两边必须一致。
+				script := "process.chdir(" + jsQuote(dir) + ");" +
+					"require(" + jsQuote(server) + ").start(" + strconv.Itoa(7789) + ");"
+				return []string{node, "-e", script}, nil
+			},
+			Urls: portFilePorts(7789, filepath.Join(dataHome("magic-video"), "workbench.port")),
+		},
+	}
+	// 允许用环境变量指向别处的源码（与 plugins.go 的 MAGIC_CLIENT_*_DIR 同一套名字）。
+	for i := range specs {
+		env := "MAGIC_CLIENT_VIDEO_DIR"
+		if specs[i].ID == "magic-shorts" {
+			env = "MAGIC_CLIENT_SHORTS_DIR"
+		}
+		if v := strings.TrimSpace(os.Getenv(env)); v != "" {
+			specs[i].Repo = v
+		}
+	}
+	var notes []string
+	if _, ok := nodeBin(); !ok {
+		notes = append(notes, "这台桌面找不到 node —— 工作台起不来")
+	}
+	return specs, notes
+}
+
+// jsQuote 把路径转成 JS 字符串字面量（桌面路径里可能有空格 / 反斜杠 / 中文）。
+func jsQuote(s string) string {
+	b, _ := json.Marshal(s)
+	return string(b)
+}
+
+func findApp(id string) (appSpec, bool) {
+	specs, _ := appSpecs()
+	id = strings.TrimSpace(strings.ToLower(id))
+	for _, s := range specs {
+		if s.ID == id {
+			return s, true
+		}
+	}
+	return appSpec{}, false
+}
+
+/* ─────────────── 管理器 ─────────────── */
+
+// appRun 自己起的一次运行（落盘）。
+type appRun struct {
+	PID       int      `json:"pid"`
+	Port      int      `json:"port"`
+	StartedAt int64    `json:"startedAt"`
+	Lines     []string `json:"lines,omitempty"`
+}
+
+type appManager struct {
+	path string // ~/.magic-agent/apps/runs.json；空 = 不落盘
+
+	mu   sync.Mutex
+	runs map[string]*appRun
+	// probe 端口探活缓存：手机页面会轮询，不能每次探两遍（启动/停止后强制刷新）。
+	probe map[int]appProbe
+	/* specOf 覆盖注册表里的某几项（只给测试用：把真实端口 8899 / 7789 换成临时端口，
+	   否则本机开着的工作台会把用例短路成「运行中（外部）」）。nil = 用注册表原样。 */
+	specOf func(appSpec) appSpec
+}
+
+// spec 取注册表项（应用测试覆盖）。
+func (m *appManager) spec(spec appSpec) appSpec {
+	if m.specOf != nil {
+		return m.specOf(spec)
+	}
+	return spec
+}
+
+type appProbe struct {
+	at      time.Time
+	running bool
+	// busy = 端口有人在听，但探针认不出它是工作台（见 appManager.probePort）。
+	busy bool
+	// why = 为什么判成 busy（「GET / 返回 404」这种人话），直接给用户看。
+	why string
+}
+
+const (
+	envAppsDir = "MAGIC_CLIENT_APPS_DIR"
+	// appProbeTTL 端口探活结果的缓存时长。
+	appProbeTTL = 1 * time.Second
+	// appStartWait 起工作台时最多等多久（Node 起一个工作台通常 1–3 秒；
+	// magic-shorts 首次还要做素材时长预热，多留些余量）。
+	appStartWait = 20 * time.Second
+	// appLogLines 落盘保留的输出行数（手机上只需要尾巴）。
+	appLogLines = 40
+)
+
+func newAppManager(s *Service) *appManager {
+	m := &appManager{runs: map[string]*appRun{}, probe: map[int]appProbe{}}
+	dir := strings.TrimSpace(os.Getenv(envAppsDir))
+	if dir == "" {
+		if home, err := os.UserHomeDir(); err == nil && home != "" {
+			dir = filepath.Join(home, ".magic-agent", "apps")
+		}
+	}
+	if dir == "" {
+		return m
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		if s.log != nil {
+			s.log.Printf("应用目录创建失败 %s（%v），运行态将不落盘", dir, err)
+		}
+		return m
+	}
+	m.path = filepath.Join(dir, "runs.json")
+	if b, err := os.ReadFile(m.path); err == nil && json.Valid(b) {
+		var runs map[string]*appRun
+		if json.Unmarshal(b, &runs) == nil {
+			for id, r := range runs {
+				if r == nil || r.PID <= 0 || !agent.PIDAlive(r.PID) {
+					continue // 早退了：当作没起过
+				}
+				m.runs[id] = r
+			}
+		}
+	}
+	return m
+}
+
+func (s *Service) appMgr() *appManager {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.apps == nil {
+		s.apps = newAppManager(s)
+	}
+	return s.apps
+}
+
+// saveRuns 落盘运行态（调用方持锁或单 goroutine 场景；内部自己加锁）。
+func (m *appManager) saveRuns() {
+	if m.path == "" {
+		return
+	}
+	m.mu.Lock()
+	b, err := json.MarshalIndent(m.runs, "", "  ")
+	m.mu.Unlock()
+	if err != nil {
+		return
+	}
+	tmp := m.path + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, m.path)
+}
+
+// probeRunning 探测 127.0.0.1:port 上有没有 HTTP 服务（任何状态码都算在跑）。
+func (m *appManager) probeRunning(port int, fresh bool) bool {
+	return m.probePort(port, fresh).running
+}
+
+/* probePort 探一个端口：**光有东西在听不算数**，还得是这套工作台的页面。
+ *
+ * 判据是 GET / 的响应：2xx/3xx + Content-Type 是 text/html。三条都满足才算 running。
+ * 只听端口（旧行为）会把「别的程序占着端口」误报成「运行中」，手机上于是点开一片白 ——
+ * magic-video 的 7789 就是这么被一个只用 API 的旧实例骗过去的（/ 返回 404）。
+ *
+ * 监听但没有页面 → busy：不是运行中，但也不是「没起」，得分开告诉用户。
+ */
+func (m *appManager) probePort(port int, fresh bool) appProbe {
+	if port <= 0 {
+		return appProbe{}
+	}
+	if !fresh {
+		m.mu.Lock()
+		p, ok := m.probe[port]
+		m.mu.Unlock()
+		if ok && time.Since(p.at) < appProbeTTL {
+			return p
+		}
+	}
+	client := http.Client{Timeout: 1200 * time.Millisecond}
+	resp, err := client.Get("http://127.0.0.1:" + strconv.Itoa(port) + "/")
+	p := appProbe{at: time.Now()}
+	if err != nil {
+		// 连不上：要么没人听，要么只听了 TCP 不说 HTTP（都按「没在跑」算）。
+		m.mu.Lock()
+		m.probe[port] = p
+		m.mu.Unlock()
+		return p
+	}
+	_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 4096))
+	resp.Body.Close()
+	ctype := strings.ToLower(resp.Header.Get("Content-Type"))
+	switch {
+	case resp.StatusCode >= 500:
+		p.why = fmt.Sprintf("GET / 返回 %d", resp.StatusCode)
+	case resp.StatusCode >= 400:
+		p.why = fmt.Sprintf("端口 %d 上有个程序在听，但它不提供工作台页面（GET / 返回 %d）", port, resp.StatusCode)
+	case !strings.Contains(ctype, "text/html"):
+		p.why = fmt.Sprintf("端口 %d 上有个程序在听，但返回的不是页面（%s）", port, strings.TrimSpace(ctype))
+	default:
+		p.running = true
+	}
+	p.busy = !p.running
+	m.mu.Lock()
+	m.probe[port] = p
+	m.mu.Unlock()
+	return p
+}
+
+// locate 探测这个工作台现在在哪：先看自己起的 pid 对应的端口，再按应用自己的端口文件顺序探。
+// 返回 (端口, 是否在跑)。
+func (m *appManager) locate(spec appSpec, fresh bool) (int, bool) {
+	port, running, _, _ := m.locateDetail(spec, fresh)
+	return port, running
+}
+
+// locateDetail 同 locate，但把「端口被占」的原因也带出来（给 info 用）。
+func (m *appManager) locateDetail(spec appSpec, fresh bool) (port int, running bool, busy bool, why string) {
+	spec = m.spec(spec)
+	m.mu.Lock()
+	run := m.runs[spec.ID]
+	m.mu.Unlock()
+	ports := []int{}
+	if run != nil && agent.PIDAlive(run.PID) {
+		ports = append(ports, run.Port)
+	}
+	if spec.Urls != nil {
+		ports = append(ports, spec.Urls()...)
+	} else {
+		ports = append(ports, spec.Port)
+	}
+	for _, p := range ports {
+		if p <= 0 {
+			continue
+		}
+		pr := m.probePort(p, fresh)
+		if pr.running {
+			return p, true, false, ""
+		}
+		if pr.busy && !busy {
+			port, busy, why = p, true, pr.why
+		}
+	}
+	return port, false, busy, why
+}
+
+// info 组装一个应用的当前状态（不启动任何东西）。
+func (m *appManager) info(spec appSpec, fresh bool) AppItem {
+	item := AppItem{
+		ID: spec.ID, Name: spec.Name, Tagline: spec.Tagline, Description: spec.Description,
+		Homepage: spec.Homepage, CLI: spec.CLI, Landscape: spec.Landscape,
+		Command: "PORT=" + strconv.Itoa(spec.Port) + " " + spec.CLI +
+			" " + appLaunchArg(spec) + "   # 由本客户端等价启动（node 直接跑工作台入口）",
+		Port: spec.Port,
+	}
+	if _, err := exec.LookPath(spec.CLI); err == nil {
+		item.Installed = true
+	}
+	if st, err := os.Stat(spec.Repo); err == nil && st.IsDir() {
+		item.SourcePath = spec.Repo
+	}
+	m.mu.Lock()
+	run := m.runs[spec.ID]
+	m.mu.Unlock()
+
+	st := AppState{State: "stopped", URL: workbookBase(spec.ID)}
+	if run != nil && !agent.PIDAlive(run.PID) {
+		// 进程没了（自己退了 / 在桌面强杀）：清掉记录，别让它一直挂着。
+		m.mu.Lock()
+		delete(m.runs, spec.ID)
+		m.mu.Unlock()
+		m.saveRuns()
+		run = nil
+	}
+	if run != nil {
+		st.PID = run.PID
+		st.StartedAt = run.StartedAt
+		st.LogTail = tailLines(run.Lines, 8)
+	}
+
+	port, running, busy, why := m.locateDetail(spec, fresh)
+	switch {
+	case running:
+		st.State = "running"
+		st.Running = true
+		st.Port = port
+		st.LocalURL = fmt.Sprintf("http://127.0.0.1:%d/", port)
+		item.OpenURL = st.URL
+		if run != nil {
+			st.Managed = true
+			item.Note = "运行中（本客户端启动），可以从手机停止"
+		} else {
+			item.Note = "运行中（桌面端终端 / 菜单栏起的）：手机可以打开，停止请到桌面端"
+			if last := tailFile(m.logDir(), spec.ID, 8); len(last) > 0 {
+				st.LogTail = last
+			}
+		}
+	case run != nil:
+		st.State = "starting"
+		st.Port = run.Port
+		item.Note = "启动中…"
+	case busy:
+		/* 端口被占、但占着的不是这套工作台：状态既不是 running 也不是 stopped。
+		   说清「谁占了、为什么打开是白的」，并给出唯一的出路（桌面端先停掉那个）。 */
+		st.State = "blocked"
+		st.Port = port
+		st.PortBusy = true
+		st.Error = why
+		item.Note = why + " —— 先到桌面端把它停掉，再从这里启动"
+	default:
+		switch {
+		case item.SourcePath == "" && !item.Installed:
+			item.Note = "未找到：" + spec.Repo + " 不在，PATH 上也没有 " + spec.CLI
+		case item.SourcePath == "":
+			item.Note = "源码目录不在：" + spec.Repo + "（PATH 上有 " + spec.CLI + "，但不是这套工作台的源码）"
+		default:
+			item.Note = "已停止：启动后由手机内置浏览器打开（走桌面端的网络）"
+		}
+	}
+	item.State = st
+	return item
+}
+
+// appLaunchArg 命令展示用的子命令名（只是给人看的说明，不是真实 argv）。
+func appLaunchArg(spec appSpec) string {
+	if spec.ID == "magic-video" {
+		return "workbench --no-browser"
+	}
+	return "serve"
+}
+
+func workbookBase(id string) string { return workbenchPrefix + id + "/" }
+
+func (m *appManager) logDir() string {
+	if m.path == "" {
+		return ""
+	}
+	return filepath.Join(filepath.Dir(m.path), "logs")
+}
+
+// tailFile 读自己起过的进程留下的输出尾巴（外部实例读不到，给空）。
+func tailFile(dir, id string, n int) []string {
+	if dir == "" {
+		return nil
+	}
+	b, err := os.ReadFile(filepath.Join(dir, id+".log"))
+	if err != nil {
+		return nil
+	}
+	return tailLines(strings.Split(strings.TrimRight(string(b), "\r\n"), "\n"), n)
+}
+
+// tailLines 取最后 n 行（feishu.go 里的 tail 是「截最后 n 个字符」，别混）。
+func tailLines(lines []string, n int) []string {
+	lines = append([]string(nil), lines...)
+	if len(lines) <= n {
+		return lines
+	}
+	return lines[len(lines)-n:]
+}
+
+// list 全部应用（不启动任何东西；外部实例也如实显示为运行中）。
+func (m *appManager) list() []AppItem {
+	specs, _ := appSpecs()
+	items := make([]AppItem, 0, len(specs))
+	for _, s := range specs {
+		items = append(items, m.info(s, false))
+	}
+	return items
+}
+
+// start 起一个工作台，等到端口真的应答再返回。
+func (m *appManager) start(spec appSpec) (AppItem, error) {
+	// 日志目录跟着**管理器**走（测试里是临时目录）。
+	logDir := m.logDir()
+	if m.specOf != nil {
+		orig := spec
+		spec = m.spec(spec)
+		if orig.Build != nil {
+			spec.Build = orig.Build
+		}
+	}
+	m.mu.Lock()
+	busy := m.runs[spec.ID] != nil && agent.PIDAlive(m.runs[spec.ID].PID)
+	m.mu.Unlock()
+	if busy {
+		return AppItem{}, errAppStarting
+	}
+	// 端口上已经有人在跑这套工作台（终端 / 菜单栏起的）→ 不重复起，直接给现状。
+	if _, ok := m.locate(spec, true); ok {
+		return m.info(spec, true), nil
+	}
+	/* 端口被别的程序占着（典型：上一版只服务 /api 的旧实例）：
+	   与其等 node 报 EADDRINUSE 再翻译，不如现在就把「谁占了、为什么」说清楚。 */
+	if _, _, busy, why := m.locateDetail(spec, true); busy {
+		return AppItem{}, errors.New(why + " —— 先到桌面端把它停掉，再从这里启动")
+	}
+
+	node, _ := nodeBin()
+	argv, err := spec.Build(spec.Repo, node)
+	if err != nil {
+		return AppItem{}, fmt.Errorf("起不来：%v（源码目录：%s，可用环境变量指向别处）", err, spec.Repo)
+	}
+
+	var lf *os.File
+	if logDir != "" {
+		if err := os.MkdirAll(logDir, 0o700); err == nil {
+			if f, err := os.OpenFile(filepath.Join(logDir, spec.ID+".log"), os.O_CREATE|os.O_WRONLY, 0o600); err == nil {
+				lf = f
+				// 上一次运行的输出不该混进这一次的尾巴里：每次启动前清空。
+				_ = f.Truncate(0)
+				fmt.Fprintf(f, "── %s %s ──\n", time.Now().Format("2006-01-02 15:04:05"), strings.Join(argv, " "))
+			}
+		}
+	}
+
+	/* 进程组 + 不绑请求 context：与 scripts.go 同一套。手机断连 / 退后台不该把工作台
+	   带走 —— 工作台是给人刷的，人一离开页面它就没了才叫离谱。 */
+	cmd := exec.Command(argv[0], argv[1:]...)
+	cmd.Dir = spec.Repo
+	cmd.Env = agent.ChildEnvWith([]string{"PORT=" + strconv.Itoa(spec.Port), "HOST=127.0.0.1"})
+	agent.ConfigureProcGroup(cmd)
+	noConsole(cmd)
+	if lf != nil {
+		cmd.Stdout = lf
+		cmd.Stderr = lf
+	}
+	if err := cmd.Start(); err != nil {
+		if lf != nil {
+			fmt.Fprintf(lf, "启动失败：%v\n", err)
+			lf.Close()
+		}
+		return AppItem{}, fmt.Errorf("启动工作台失败：%w", err)
+	}
+	if lf != nil {
+		_ = lf.Close() // 子进程已经继承了 fd
+	}
+	pid := cmd.Process.Pid
+	run := &appRun{PID: pid, Port: spec.Port, StartedAt: time.Now().UnixMilli()}
+	m.mu.Lock()
+	m.runs[spec.ID] = run
+	m.mu.Unlock()
+	m.saveRuns()
+
+	exited := make(chan struct{})
+	go func() {
+		_ = cmd.Wait() // 收尸：不 Wait 会留僵尸进程
+		close(exited)
+		m.mu.Lock()
+		if r := m.runs[spec.ID]; r != nil && r.PID == pid {
+			if lines := tailFile(logDir, spec.ID, appLogLines); len(lines) > 0 {
+				r.Lines = lines
+			}
+		}
+		m.mu.Unlock()
+		m.saveRuns()
+		m.probeRunning(spec.Port, true)
+	}()
+
+	deadline := time.Now().Add(appStartWait)
+	for time.Now().Before(deadline) {
+		if m.probeRunning(spec.Port, true) {
+			m.mu.Lock()
+			if r := m.runs[spec.ID]; r != nil && r.PID == pid {
+				r.Lines = tailFile(logDir, spec.ID, appLogLines)
+			}
+			m.mu.Unlock()
+			m.saveRuns()
+			return m.info(spec, true), nil
+		}
+		if !agent.PIDAlive(pid) {
+			break
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+
+	// 起不来：收掉进程组，把输出尾巴交给手机 —— 原因写在日志里，别让人去桌面翻。
+	alive := agent.PIDAlive(pid)
+	if alive {
+		_ = agent.KillPID(pid, true)
+	}
+	/* 等收尸：进程自己退出（例如端口被占时 node 直接抛错）时，cmd.Wait 的 goroutine
+	   与日志写盘都还没跑完，立刻读会读到空 —— 那样手机上只剩「进程已退出」四个字，
+	   真正的原因（EADDRINUSE …）被吞掉。最多等 2 秒。 */
+	select {
+	case <-exited:
+	case <-time.After(2 * time.Second):
+	}
+	m.mu.Lock()
+	if r := m.runs[spec.ID]; r != nil && r.PID == pid {
+		delete(m.runs, spec.ID)
+	}
+	m.mu.Unlock()
+	m.saveRuns()
+	m.probeRunning(spec.Port, true)
+
+	reason := fmt.Sprintf("%d 秒内端口 %d 没有应答", int(appStartWait.Seconds()), spec.Port)
+	if !alive {
+		reason = "进程已退出"
+	}
+	// tail 去掉第一行（这次的启动标题），只给真正的输出。
+	lines := tailFile(logDir, spec.ID, 13)
+	if len(lines) > 1 {
+		lines = lines[1:]
+	}
+	if len(lines) == 0 {
+		return AppItem{}, fmt.Errorf("%s 启动失败：%s", spec.Name, reason)
+	}
+	return AppItem{}, fmt.Errorf("%s 启动失败：%s\n%s", spec.Name, reason, strings.Join(lines, "\n"))
+}
+
+var (
+	errAppStarting = errors.New("这个工作台正在启动，稍等片刻")
+	errAppExternal = errors.New("这个工作台不是在手机上启动的（桌面端终端 / 菜单栏起的），请到桌面端停止")
+)
+
+// stop 停一个工作台：只停自己起的（整组），外部实例如实回报。
+func (m *appManager) stop(spec appSpec) (AppItem, error) {
+	m.mu.Lock()
+	run := m.runs[spec.ID]
+	m.mu.Unlock()
+	if run == nil || !agent.PIDAlive(run.PID) {
+		if _, ok := m.locate(spec, true); ok {
+			return AppItem{}, errAppExternal
+		}
+		m.mu.Lock()
+		delete(m.runs, spec.ID)
+		m.mu.Unlock()
+		m.saveRuns()
+		return m.info(spec, true), nil // 没在跑 → 幂等成功
+	}
+	pid := run.PID
+	// 杀整组：unix kill(-pid) 带走 node 起的全部子进程；Windows taskkill /T /F。
+	_ = agent.KillPID(pid, true)
+	// 等它真的下去，否则手机点完「停止」立刻重画还会看到「运行中」。
+	for i := 0; i < 40; i++ {
+		if !agent.PIDAlive(pid) {
+			break
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	m.mu.Lock()
+	if r := m.runs[spec.ID]; r != nil && r.PID == pid {
+		delete(m.runs, spec.ID)
+	}
+	m.mu.Unlock()
+	m.saveRuns()
+	m.probeRunning(run.Port, true)
+	return m.info(spec, true), nil
+}
+
+/* appErr 本页的错误响应：中文**不转义**（\u77ed\u89c6\u9891 这种前端一旦当纯文本显示就是乱码样）。
+ *
+ * 为什么不改全局 writeErr：别的接口的错误体是给程序读的，escaped 也一样合法；
+ * 这一页的错误会原样显示给用户（起不来的 stderr 尾巴、一句人话），所以单独一份。 */
+func appErr(w http.ResponseWriter, code int, msg string) {
+	var buf bytes.Buffer
+	enc := json.NewEncoder(&buf)
+	enc.SetEscapeHTML(false)
+	_ = enc.Encode(map[string]any{"error": msg})
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(code)
+	_, _ = w.Write(buf.Bytes())
+}
+
+/* ─────────────── 反代 ─────────────── */
+
+// workbenchPrefix 手机可用的工作台入口前缀：/workbench/{id}/。
+const workbenchPrefix = "/workbench/"
+
+/* workbenchCookie 记住「这个浏览器的手机界面当前在看哪个工作台」，给页面里的根相对
+ * '/api/…' 兜底用（见 workbenchFor）。HttpOnly：只是一条给服务端看的标记，脚本不用读。 */
+const workbenchCookie = "magic_wb"
+
+// workbenchTarget 解析 /workbench/{id} 或 /workbench/{id}/{sub}。
+func workbenchTarget(p string) (id, sub string, ok bool) {
+	if !strings.HasPrefix(p, workbenchPrefix) {
+		return "", "", false
+	}
+	rest := strings.TrimPrefix(p, workbenchPrefix)
+	id, sub = rest, ""
+	if i := strings.IndexByte(rest, '/'); i >= 0 {
+		id, sub = rest[:i], rest[i:]
+	}
+	if id == "" || strings.Contains(sub, "..") {
+		return "", "", false
+	}
+	return id, sub, true
+}
+
+// newWorkbenchProxy 建一个指向 127.0.0.1:<port> 的反代。
+func newWorkbenchProxy(spec appSpec, port int) *httputil.ReverseProxy {
+	host := net.JoinHostPort("127.0.0.1", strconv.Itoa(port))
+	return &httputil.ReverseProxy{
+		Director: func(req *http.Request) {
+			req.URL.Scheme = "http"
+			req.URL.Host = host
+			req.Header.Set("X-Forwarded-Prefix", workbookBase(spec.ID))
+		},
+		FlushInterval: 60 * time.Millisecond, // 工作台有长轮询 / 流式输出，别攒着
+		ErrorHandler: func(w http.ResponseWriter, req *http.Request, err error) {
+			appErr(w, http.StatusBadGateway, spec.Name+" 工作台没有响应："+err.Error())
+		},
+	}
+}
+
+// handleWorkbench /workbench/{id}/{...} → 工作台。
+//
+// 第一个请求（/workbench/{id}/，手机内置浏览器打开的就是它）先探活：
+// 没在跑就回一句人话；在跑就 302 到 "/"，让工作台**在根路径下**跑 ——
+// 页面里的 '/api/…' 于是打回本服务，再由 handleStatic 按 Referer 认出来转发。
+// 其余子路径（/workbench/{id}/xxx）照常反代，给不依赖根路径的地址用。
+func (s *Service) handleWorkbench(w http.ResponseWriter, r *http.Request) {
+	id, sub, ok := workbenchTarget(r.URL.Path)
+	if !ok {
+		appErr(w, http.StatusNotFound, "用法：/workbench/{id}/")
+		return
+	}
+	spec, found := findApp(id)
+	if !found {
+		appErr(w, http.StatusNotFound, "没有这个应用："+id)
+		return
+	}
+	mgr := s.appMgr()
+	port, running := mgr.locate(spec, true)
+	if !running {
+		appErr(w, http.StatusServiceUnavailable, spec.Name+" 没有在运行。先到「发现 → 应用」点启动。")
+		return
+	}
+	if sub == "" || sub == "/" {
+		/* 跳到 "/" 让工作台在根路径下跑，并带一个 via=<id> 标记：
+		   前端内置浏览器看到的地址就变成 "/"（应用页不再把它当站点重载）；
+		   点「刷新」时再带回这里（先探活、再跳），工作台退出了会得到一句人话而不是白屏。
+		   也正因为带了这个标记，前端的「关闭浏览器」不会被当成「离开站点」而反复重开。 */
+		/* 同时种 cookie：页面里根相对的 '/api/…' 可能既没 Referer 也没 via（见 workbenchFor）。
+		   Path=/ + SameSite=Lax：只影响根路径下的请求，不外泄到别的站点。 */
+		http.SetCookie(w, &http.Cookie{
+			Name:     workbenchCookie,
+			Value:    spec.ID,
+			Path:     "/",
+			SameSite: http.SameSiteLaxMode,
+			HttpOnly: true,
+		})
+		target := "/?via=" + url.QueryEscape(spec.ID)
+		if q := r.URL.RawQuery; q != "" {
+			target += "&" + q
+		}
+		http.Redirect(w, r, target, http.StatusFound)
+		return
+	}
+	s.serveWorkbench(w, r, spec, port, sub)
+}
+
+// r2WithPath 复制请求并改写路径（反代 Director 之后还会再次改写，这里只负责把
+// /workbench/{id}/xxx 换成 /xxx，保留 query）。
+func r2WithPath(r *http.Request, path, orig string) *http.Request {
+	if path == orig {
+		return r
+	}
+	c := r.Clone(r.Context())
+	u := *r.URL
+	u.Path = path
+	u.RawPath = ""
+	c.URL = &u
+	return c
+}
+
+// workbenchFor 判定「这次根路径请求是不是某个运行中的工作台发起的」，是则返回它与端口。
+//
+// 判据是 **Referer**：工作台页面（以及它里边的 fetch）一定带着页面自己的地址
+// http(s)://<手机入口>/workbench/{id}/…。要求 Referer 的宿主与本次请求一致 ——
+// 别的站点伪造一个 Referer 也只会拿到「桌面端 127.0.0.1 上的那个工作台」，
+// 那本来就是这台机器的东西，不扩大攻击面。
+func (s *Service) workbenchFor(r *http.Request) (appSpec, int, bool) {
+	/* 两条认法，缺一不可：
+	   1. Referer 的路径是 /workbench/{id}/…（页面加深、工作台内部跳转都带着它）；
+	   2. 或者地址上带 ?via={id} —— 入口 302 过来的第一跳。
+	   ⚠️ 只靠 1 不够：移动端内置浏览器的 iframe 历史上带 referrerpolicy="no-referrer"，
+	      浏览器一个头都不发，服务端认不出这是工作台，结果把客户的界面（或 401）丢给页面。
+	      via 是服务端自己拼的标记，浏览器也留得住（站内跳转不丢），比裸 Referer 可靠。 */
+	var id string
+	if ref := strings.TrimSpace(r.Header.Get("Referer")); ref != "" {
+		if u, err := url.Parse(ref); err == nil && strings.EqualFold(u.Host, r.Host) {
+			if v, _, ok := workbenchTarget(u.Path); ok {
+				id = v
+			}
+		}
+	}
+	if id == "" {
+		via := strings.TrimSpace(r.URL.Query().Get("via"))
+		if via == "" {
+			/* 页面里的 '/api/…' 是 XHR / fetch：地址上没 via、Referer 也可能被浏览器抹掉。
+			   入口那一跳给浏览器种了 cookie（同源、根路径、只放应用 id），这里认它。 */
+			if ck, err := r.Cookie(workbenchCookie); err == nil {
+				via = strings.TrimSpace(ck.Value)
+			}
+		}
+		if via != "" {
+			if spec, found := findApp(via); found {
+				if port, running := s.appMgr().locate(spec, false); running {
+					return spec, port, true
+				}
+			}
+			return appSpec{}, 0, false
+		}
+	}
+	if id == "" {
+		return appSpec{}, 0, false
+	}
+	spec, found := findApp(id)
+	if !found {
+		return appSpec{}, 0, false
+	}
+	port, running := s.appMgr().locate(spec, false)
+	if !running {
+		return appSpec{}, 0, false
+	}
+	return spec, port, true
+}
+
+// serveWorkbench 把根路径请求转给工作台（handleStatic 命中时调用）。
+// path 为空 = 沿用请求自己的路径（页面里的 '/api/…' 原样交给工作台）。
+func (s *Service) serveWorkbench(w http.ResponseWriter, r *http.Request, spec appSpec, port int, path string) {
+	if path == "" {
+		newWorkbenchProxy(spec, port).ServeHTTP(w, r)
+		return
+	}
+	newWorkbenchProxy(spec, port).ServeHTTP(w, r2WithPath(r, path, r.URL.Path))
+}
+
+/* ─────────────── HTTP 入口 ─────────────── */
+
+// handleApps GET /desk/apps：应用清单 + 状态。
+func (s *Service) handleApps(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		appErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	specs, notes := appSpecs()
+	mgr := s.appMgr()
+	items := make([]AppItem, 0, len(specs))
+	for _, spec := range specs {
+		items = append(items, mgr.info(spec, false))
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"apps": items, "notes": notes})
+}
+
+// handleAppAction POST /desk/apps/{id}/{start|stop}
+//
+// 回 SSE（与插件安装同一口径）：启动要等端口应答（几秒），输出逐行回来，
+// 手机上看得见在动；`event: end` 带完整的最新状态与 ok/error。
+func (s *Service) handleAppAction(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		appErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	rest := strings.TrimPrefix(r.URL.Path, "/desk/apps/")
+	parts := strings.Split(strings.Trim(rest, "/"), "/")
+	if len(parts) != 2 {
+		appErr(w, http.StatusNotFound, "用法：POST /desk/apps/{id}/{start|stop}")
+		return
+	}
+	spec, ok := findApp(parts[0])
+	if !ok {
+		appErr(w, http.StatusNotFound, "没有这个应用："+parts[0])
+		return
+	}
+	action := parts[1]
+	if action != "start" && action != "stop" {
+		appErr(w, http.StatusNotFound, "动作只有 start / stop")
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("X-Accel-Buffering", "no")
+	flusher, _ := w.(http.Flusher)
+	send := func(event string, payload any) {
+		b, _ := json.Marshal(payload)
+		if event != "" {
+			fmt.Fprintf(w, "event: %s\n", event)
+		}
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		if flusher != nil {
+			flusher.Flush()
+		}
+	}
+
+	send("open", map[string]any{"id": spec.ID, "action": action})
+
+	/* 与 /desk/ask、插件安装同一口径：客户端断连不是「取消」。
+	   起工作台起一半被手机锁屏杀掉，端口上可能已经有人在应答，状态就会两头说不清。 */
+	mgr := s.appMgr()
+	var (
+		item AppItem
+		err  error
+	)
+	if action == "start" {
+		item, err = mgr.start(spec)
+	} else {
+		item, err = mgr.stop(spec)
+	}
+	if err != nil {
+		code := http.StatusInternalServerError
+		if errors.Is(err, errAppStarting) || errors.Is(err, errAppExternal) {
+			code = http.StatusConflict
+		}
+		send("end", map[string]any{"ok": false, "code": code, "error": err.Error(), "app": mgr.info(spec, true)})
+		return
+	}
+	send("end", map[string]any{"ok": true, "code": 0, "app": item})
+}