magic-agent 1.0.2 → 1.0.46

package/internal/client/daemon_test.go

@@ -0,0 +1,212 @@
+package client
+
+// daemon_test.go - 后台常驻的状态文件与探活口径。
+//
+// 这里**不启动真的 serve 进程**（那需要 core 与整套 UI，属于真机验收的事），
+// 只钉住三件容易悄悄错掉的事：
+//  1) 状态文件是 0600（里面有令牌，权限就是门锁）；
+//  2) 令牌跨重启稳定（手机里存的是它，换了等于配对作废）；
+//  3) status 的判据是「进程在 **且** 健康检查答得上」，不是只看 pid。
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+func TestDaemonStateFileIsPrivate(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "client.json")
+	st := &DaemonState{PID: 1, Port: 1234, Token: "0123456789abcdef0123456789abcdef", StatePath: p}
+	if err := writeDaemonState(p, st); err != nil {
+		t.Fatalf("writeDaemonState: %v", err)
+	}
+	info, err := os.Stat(p)
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if perm := info.Mode().Perm(); perm != 0o600 {
+		t.Errorf("状态文件权限 = %o，want 600（里面有令牌，权限是唯一门锁）", perm)
+	}
+	got, err := ReadDaemonState(p)
+	if err != nil {
+		t.Fatalf("ReadDaemonState: %v", err)
+	}
+	if got == nil || got.Token != st.Token {
+		t.Fatalf("读回来对不上：%+v", got)
+	}
+	if got.StatePath != p {
+		t.Errorf("StatePath = %q，want %q", got.StatePath, p)
+	}
+}
+
+func TestReadDaemonStateMissingIsNil(t *testing.T) {
+	got, err := ReadDaemonState(filepath.Join(t.TempDir(), "nope.json"))
+	if err != nil {
+		t.Fatalf("不存在应当不算错误：%v", err)
+	}
+	if got != nil {
+		t.Errorf("got %+v，want nil", got)
+	}
+}
+
+// 令牌必须跨 start 稳定：手机里存的就是它。
+func TestResolveTokenIsStable(t *testing.T) {
+	dir := t.TempDir()
+	statePath := filepath.Join(dir, "client.json")
+
+	first := resolveToken(statePath, "")
+	if len(first) < MinLanTokenLen {
+		t.Fatalf("生成的令牌长度 %d < %d", len(first), MinLanTokenLen)
+	}
+	second := resolveToken(statePath, "")
+	if first != second {
+		t.Errorf("两次取到的令牌不同（%q vs %q）：手机配对会作废", first, second)
+	}
+
+	info, err := os.Stat(TokenPath(statePath))
+	if err != nil {
+		t.Fatalf("令牌文件没落盘：%v", err)
+	}
+	if perm := info.Mode().Perm(); perm != 0o600 {
+		t.Errorf("令牌文件权限 = %o，want 600", perm)
+	}
+
+	// 显式给了就用显式的（临时换令牌的排障路径），但**不改**已存的那份。
+	if got := resolveToken(statePath, "explicit-token-000000000000"); got != "explicit-token-000000000000" {
+		t.Errorf("显式令牌没被采用：%q", got)
+	}
+	if again := resolveToken(statePath, ""); again != first {
+		t.Errorf("显式令牌把存的那份覆盖了：%q，want %q", again, first)
+	}
+}
+
+// 存的令牌坏掉（太短 / 空）时应当重新生成，而不是拿个弱令牌去 --lan。
+func TestResolveTokenRejectsShortStored(t *testing.T) {
+	dir := t.TempDir()
+	statePath := filepath.Join(dir, "client.json")
+	if err := os.WriteFile(TokenPath(statePath), []byte("abc\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got := resolveToken(statePath, "")
+	if len(got) < MinLanTokenLen {
+		t.Errorf("存着的短令牌被直接采用了：%q", got)
+	}
+}
+
+func TestWriteReadyFileRoundTrip(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "sub", "ready.json")
+	if got, err := readReadyFile(p); err != nil || got != nil {
+		t.Fatalf("不存在时应返回 (nil,nil)，got %+v err %v", got, err)
+	}
+	info := ReadyInfo{Port: 50022, URL: "http://127.0.0.1:50022/?token=x", Lan: true,
+		LanAddrs: []string{"http://192.168.1.5:50022/?token=x"}}
+	if err := WriteReadyFile(p, info); err != nil {
+		t.Fatalf("WriteReadyFile: %v", err)
+	}
+	got, err := readReadyFile(p)
+	if err != nil {
+		t.Fatalf("readReadyFile: %v", err)
+	}
+	if got == nil || got.Port != 50022 || got.PID == 0 {
+		t.Fatalf("读回来不对：%+v", got)
+	}
+	if len(got.LanAddrs) != 1 || !strings.Contains(got.LanAddrs[0], "192.168.1.5") {
+		t.Errorf("lanAddrs 丢了：%v", got.LanAddrs)
+	}
+}
+
+// status 的判据：pid 活着但服务答不上来 → **不算 running**。
+// 只看 pid 会把「契约不匹配后卡住」的服务报成可用，用户照它去连必然失败。
+func TestStatusRequiresHealthyService(t *testing.T) {
+	dir := t.TempDir()
+	statePath := filepath.Join(dir, "client.json")
+
+	// 拿一个真的在监听、但**_不是_**我们的服务：能连上、答的不是 health JSON。
+	other := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte("<html>not magic</html>"))
+	}))
+	defer other.Close()
+	port := portOf(t, other.URL)
+
+	st := &DaemonState{PID: os.Getpid(), Port: port, Token: "x", StatePath: statePath}
+	if err := writeDaemonState(statePath, st); err != nil {
+		t.Fatal(err)
+	}
+	got, err := StatusDaemon(statePath)
+	if err != nil {
+		t.Fatalf("StatusDaemon: %v", err)
+	}
+	if got.Running {
+		t.Errorf("不是本服务也报 running：判据不能只看 pid / 端口通")
+	}
+	if got.Note == "" {
+		t.Errorf("不算 running 时必须给出原因，否则排障无从下手")
+	}
+}
+
+// 没有状态文件时 status 也是一条明确的回答，不是错误。
+func TestStatusWithoutStateFile(t *testing.T) {
+	got, err := StatusDaemon(filepath.Join(t.TempDir(), "none.json"))
+	if err != nil {
+		t.Fatalf("StatusDaemon: %v", err)
+	}
+	if got.Running || got.State != nil {
+		t.Errorf("got %+v，want 未运行", got)
+	}
+	if got.Note == "" {
+		t.Errorf("未运行也要说明原因")
+	}
+}
+
+// 没有状态文件时 stop 是幂等的空操作。
+func TestStopWithoutStateIsNoop(t *testing.T) {
+	stopped, st, err := StopDaemon(StopOptions{StatePath: filepath.Join(t.TempDir(), "none.json")})
+	if err != nil {
+		t.Fatalf("StopDaemon: %v", err)
+	}
+	if stopped || st != nil {
+		t.Errorf("stopped=%v st=%+v，want false/nil", stopped, st)
+	}
+}
+
+// 进程已不在时 stop 要清掉陈旧状态，否则 status 会一直报「进程已不在」。
+func TestStopClearsStaleState(t *testing.T) {
+	dir := t.TempDir()
+	statePath := filepath.Join(dir, "client.json")
+	// pid 1 在容器里可能真实存在；用一个几乎不可能存在的 pid（bool 判活对无效 pid 返回 false）。
+	st := &DaemonState{PID: 1 << 22, Port: 1, Token: "x", StatePath: statePath}
+	if err := writeDaemonState(statePath, st); err != nil {
+		t.Fatal(err)
+	}
+	stopped, got, err := StopDaemon(StopOptions{StatePath: statePath})
+	if err != nil {
+		t.Fatalf("StopDaemon: %v", err)
+	}
+	if stopped {
+		t.Errorf("进程本来就不在，不该报「这次停了它」")
+	}
+	if got == nil {
+		t.Fatalf("应当回一条陈旧状态，便于 CLI 说清楚")
+	}
+	if _, err := os.Stat(statePath); !os.IsNotExist(err) {
+		t.Errorf("陈旧状态文件没被清掉（err=%v）", err)
+	}
+}
+
+func portOf(t *testing.T, rawURL string) int {
+	t.Helper()
+	i := strings.LastIndex(rawURL, ":")
+	if i < 0 {
+		t.Fatalf("URL 没有端口：%s", rawURL)
+	}
+	p, err := strconv.Atoi(rawURL[i+1:])
+	if err != nil {
+		t.Fatalf("端口解析失败 %s：%v", rawURL, err)
+	}
+	return p
+}

package/internal/client/detach_unix.go

@@ -0,0 +1,19 @@
+//go:build !windows
+
+package client
+
+// detach_unix.go - 让后台 serve 与启动它的终端彻底分手。
+//
+// 为什么要 setsid：不脱离会话的话，关掉终端（SIGHUP）或用户 Ctrl-C 会把服务一起带走 ——
+// 而 `start` 的全部意义就是「关掉窗口它还在」。stdin 已经在调用方置空（see StartDaemon），
+// 这里只处理会话与进程组。
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+// detach 让子进程进入新会话（= 脱离控制终端）。
+func detach(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+}

package/internal/client/detach_windows.go

@@ -0,0 +1,27 @@
+//go:build windows
+
+package client
+
+// detach_windows.go - Windows 上没有 setsid，用 CREATE_NEW_PROCESS_GROUP +
+// DETACHED_PROCESS 达到同样效果：新进程组、不附着到父控制台。
+//
+// 为什么不用 windows service：那需要管理员权限与额外安装步骤，而这里只需要
+// 「关掉命令行窗口后还能连」。DETACHED_PROCESS 已经够。
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+const (
+	createNewProcessGroup = 0x00000200
+	detachedProcess       = 0x00000008
+)
+
+// detach 让子进程脱离父控制台并自成进程组。
+func detach(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{
+		CreationFlags: createNewProcessGroup | detachedProcess,
+		HideWindow:    true,
+	}
+}

package/internal/client/pair.go

@@ -117,7 +117,7 @@ func (s *Service) handlePairPage(w http.ResponseWriter, r *http.Request) {
 	page := `<!doctype html>
 <html lang="zh-CN"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1">
-<title>掌天瓶 · 配对</title>
+<title>magic-agent · 配对</title>
 <style>
  body{margin:0;background:#0A0A0B;color:#FAFAFA;padding:30px 24px 44px;
       font:15px/1.65 -apple-system,BlinkMacSystemFont,"PingFang SC","Noto Sans CJK SC",sans-serif}
@@ -130,8 +130,8 @@ func (s *Service) handlePairPage(w http.ResponseWriter, r *http.Request) {
  ol{color:#8A8A8F;font-size:13px;padding-left:20px;margin:22px 0 0}
  li{margin:5px 0}
 </style></head><body>
- <h1>掌天瓶 · 配对</h1>
- <p class="sub">用手机上的掌天瓶 App 扫下面这张码。手机要和这台电脑在同一个网络里。</p>
+ <h1>magic-agent · 配对</h1>
+ <p class="sub">用手机上的 magic-agent 扫下面这张码。手机要和这台电脑在同一个网络里。</p>
  <div class="qr"><img src="/pair/qr.png?token=__TOKENRAW__" alt="配对二维码"></div>
  <div class="row"><div class="k">桌面地址</div><div class="v">__ADDR__</div></div>
  <div class="row"><div class="k">令牌</div><div class="v">__TOKEN__</div></div>

package/internal/client/plugins.go

@@ -0,0 +1,376 @@
+package client
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+/* 插件目录：magic-* 工程各自的 CLI（magic-shorts / magic-video）。
+ *
+ * 为什么放在插件（magic-client）这一侧而不是 core：这些 CLI 不是引擎，core 对它们一无所知
+ *（`--engines` 里没有它们，也不该有）；它们是**另一个工程**的入口，只在「发现」页被介绍、
+ * 安装、升级，并被当作谈资丢进对话里让 Agent 去调。放进 core 会污染引擎注册表，
+ * 也会让「装不装插件时 core 行为一致」那条边界断言失效。
+ *
+ * ── 纪律 ──
+ *  1) 命令**只来自下面这张表**（argv 数组，不过 shell）—— 接口不接受客户端传来的命令，
+ *     唯一的外部输入是插件 id 与 action，找不到就 404。否则这个接口等于一个任意命令执行器。
+ *  2) 不假装成功：探测不到就报 installed=false + 说明；安装失败把 stderr 原样流回去。
+ *  3) 不自动装依赖：步骤是固定的、可见的，用户点「安装」才跑，跑完把每行输出给到手机。
+ */
+
+// pluginStep 安装/升级里的一条命令。Optional 的失败不中止后续步骤（例如本地有未提交改动时的 git pull）。
+type pluginStep struct {
+	Args     []string
+	Optional bool
+	SkipNote string // Optional 步骤跳过时展示的原因
+}
+
+func (p pluginStep) Command() string { return strings.Join(p.Args, " ") }
+
+// pluginSpec 插件目录里的一项（服务端固定表，不接受客户端输入）。
+type pluginSpec struct {
+	ID           string
+	Name         string
+	CLI          string
+	Tagline      string
+	Description  string
+	Requirements string
+	Homepage     string
+	// Repo 源码目录（绝对路径；可能不存在 —— 那样只剩 npm 这条安装路径）。
+	Repo     string
+	Install  []pluginStep
+	Upgrade  []pluginStep
+	Examples []string
+	// UsePrompt 是「让它干活」时预填到输入框里的话（用户补参数即可发送）。
+	UsePrompt string
+}
+
+func pluginSpecs() []pluginSpec {
+	home, _ := os.UserHomeDir()
+	shortsRepo := filepath.Join(home, ".openclaw", "workspace", "magic-shorts")
+	videoRepo := filepath.Join(home, ".openclaw", "workspace", "magic-video")
+	// 允许用环境变量指向别处的源码（与 core 的 MAGIC_AGENT_*_BIN 同一套思路）。
+	if v := strings.TrimSpace(os.Getenv("MAGIC_CLIENT_SHORTS_DIR")); v != "" {
+		shortsRepo = v
+	}
+	if v := strings.TrimSpace(os.Getenv("MAGIC_CLIENT_VIDEO_DIR")); v != "" {
+		videoRepo = v
+	}
+	return []pluginSpec{
+		{
+			ID:      "magic-shorts",
+			Name:    "magic-shorts",
+			CLI:     "magic-shorts",
+			Tagline: "知识短视频一条龙：选题 → 脚本 → 配音 → 素材 → 设计 → 成片",
+			Description: "把一句话主题做成可直接发布的横版/竖版短视频：先扫爆款定选题，再成稿、评审、分段配音、" +
+				"按设计规范合成成片。工程自带工作台（magic-shorts serve，端口 8899）与 macOS 菜单栏 App；" +
+				"数据落在 ~/.magic-shorts/。",
+			Requirements: "Node ≥18、Python ≥3.10（skillflow 依赖 click）",
+			Homepage:     "https://github.com/javacn/magic-shorts",
+			Repo:         shortsRepo,
+			Install: []pluginStep{
+				{Args: []string{"npm", "install", "-g", shortsRepo}},
+				{Args: []string{"python3", "-m", "pip", "install", "-e", shortsRepo}},
+			},
+			Upgrade: []pluginStep{
+				{Args: []string{"git", "-C", shortsRepo, "pull", "--ff-only"}, Optional: true,
+					SkipNote: "本地有未提交改动或拉取失败 —— 跳过更新源码，按当前源码重装"},
+				{Args: []string{"npm", "install", "-g", shortsRepo}},
+				{Args: []string{"python3", "-m", "pip", "install", "-e", shortsRepo}},
+			},
+			Examples: []string{
+				"magic-shorts make -p demo -n \"讲清波浪理论的核心铁律，面向散户\"",
+				"magic-shorts video -p demo --seg 2      # 只重生成第 2 段",
+				"magic-shorts serve                      # 工作台（http://127.0.0.1:8899）",
+			},
+			UsePrompt: "用 magic-shorts 做一条知识短视频。\n主题：\n目标时长：60 秒（竖版）\n受众：\n要求：先给我选题与大纲，确认后再跑后续阶段。",
+		},
+		{
+			ID:      "magic-video",
+			Name:    "magic-video",
+			CLI:     "magic-video",
+			Tagline: "短剧剧本 / 小说 / 视频分镜：三域一体的内容生产 CLI",
+			Description: "一个入口管三条内容线：novel（长篇/短篇小说）、script（180–210 秒一集的短剧剧本）、" +
+				"video（分镜与媒体）。另有 workbench 本地工作台、doctor 健康检查与 cost 用量统计；" +
+				"数据落在 ~/.magic-video/。",
+			Requirements: "Node ≥18（npm 包内自带二进制，无需 Go 环境）",
+			Homepage:     "https://github.com/javacn/magic-video",
+			Repo:         videoRepo,
+			Install: []pluginStep{
+				{Args: []string{"npm", "install", "-g", "@magicstock/magic-cli"}},
+			},
+			Upgrade: []pluginStep{
+				{Args: []string{"npm", "install", "-g", "@magicstock/magic-cli@latest"}},
+			},
+			Examples: []string{
+				"magic-video doctor                              # 13 项健康检查",
+				"magic-video script episode generate --project X --episode episode_001",
+				"magic-video workbench                           # 本地工作台",
+			},
+			UsePrompt: "用 magic-video 写一集短剧。\n题材：\n主角：\n时长：180–210 秒\n要求：先给三幕大纲与分集钩子，确认后再写成稿。",
+		},
+	}
+}
+
+func findPlugin(id string) (pluginSpec, bool) {
+	id = strings.TrimSpace(strings.ToLower(id))
+	for _, p := range pluginSpecs() {
+		if p.ID == id {
+			return p, true
+		}
+	}
+	return pluginSpec{}, false
+}
+
+// pluginInfo GET /desk/plugins 的一项（客户端只读，不做第二次推断）。
+type pluginInfo struct {
+	ID           string   `json:"id"`
+	Name         string   `json:"name"`
+	CLI          string   `json:"cli"`
+	Tagline      string   `json:"tagline"`
+	Description  string   `json:"description"`
+	Requirements string   `json:"requirements,omitempty"`
+	Homepage     string   `json:"homepage,omitempty"`
+	Installed    bool     `json:"installed"`
+	Version      string   `json:"version,omitempty"`
+	Bin          string   `json:"bin,omitempty"`
+	SourcePath   string   `json:"sourcePath,omitempty"`
+	SourceExists bool     `json:"sourceExists"`
+	Install      string   `json:"install"`
+	Upgrade      string   `json:"upgrade"`
+	Examples     []string `json:"examples"`
+	UsePrompt    string   `json:"usePrompt"`
+	// Note 讲清「为什么是现在这个状态」，客户端原样显示，不自己编。
+	Note string `json:"note,omitempty"`
+}
+
+func pluginInfoOf(p pluginSpec) pluginInfo {
+	info := pluginInfo{
+		ID: p.ID, Name: p.Name, CLI: p.CLI,
+		Tagline: p.Tagline, Description: p.Description, Requirements: p.Requirements,
+		Homepage: p.Homepage, Examples: p.Examples, UsePrompt: p.UsePrompt,
+		Install: pluginCommands(p.Install), Upgrade: pluginCommands(p.Upgrade),
+	}
+	if st, err := os.Stat(p.Repo); err == nil && st.IsDir() {
+		info.SourceExists = true
+		info.SourcePath = p.Repo
+	}
+	if bin, err := exec.LookPath(p.CLI); err == nil {
+		info.Installed = true
+		info.Bin = bin
+		info.Version = versionNearBin(bin)
+	}
+	switch {
+	case info.Installed && info.Version != "":
+		info.Note = "已安装，命令在 PATH 上"
+	case info.Installed:
+		info.Note = "已安装，但读不到版本号（该 CLI 没有 --version）"
+	case info.SourceExists:
+		info.Note = "未安装：源码在 " + p.Repo + "，可直接安装"
+	default:
+		info.Note = "未安装：PATH 上没有 " + p.CLI
+	}
+	return info
+}
+
+func pluginCommands(steps []pluginStep) string {
+	parts := make([]string, 0, len(steps))
+	for _, s := range steps {
+		parts = append(parts, s.Command())
+	}
+	return strings.Join(parts, " && ")
+}
+
+/* versionNearBin 顺着可执行文件找回它所属 npm 包的 package.json。
+ * 刻意不跑 `--version`：magic-video 不认这个 flag（会 exit 2），跑一次还会拖慢列表。 */
+func versionNearBin(bin string) string {
+	p := bin
+	if real, err := filepath.EvalSymlinks(bin); err == nil {
+		p = real
+	}
+	dir := filepath.Dir(p)
+	for i := 0; i < 4; i++ {
+		if v := packageVersion(filepath.Join(dir, "package.json")); v != "" {
+			return v
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			break
+		}
+		dir = parent
+	}
+	return ""
+}
+
+func packageVersion(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	var pkg struct {
+		Name    string `json:"name"`
+		Version string `json:"version"`
+	}
+	if err := json.Unmarshal(b, &pkg); err != nil {
+		return ""
+	}
+	if pkg.Version == "" {
+		return ""
+	}
+	return pkg.Version
+}
+
+// handlePlugins GET /desk/plugins：插件目录 + 本机安装状态。
+func (s *Service) handlePlugins(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	specs := pluginSpecs()
+	items := make([]pluginInfo, 0, len(specs))
+	for _, p := range specs {
+		items = append(items, pluginInfoOf(p))
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"plugins": items})
+}
+
+/* handlePluginAction POST /desk/plugins/{id}/{install|upgrade}
+ *
+ * 回 SSE：`event: open`（这次要跑哪几条命令）→ 每条命令一行 `event: step`，
+ * 输出逐行 `event: line` → `event: end`（ok / code / 刷新后的版本）。
+ * 用 SSE 而不是等一个 JSON：npm 装一个包几秒到几十秒，手机上必须看得见在动。 */
+func (s *Service) handlePluginAction(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	rest := strings.TrimPrefix(r.URL.Path, "/desk/plugins/")
+	parts := strings.Split(strings.Trim(rest, "/"), "/")
+	if len(parts) != 2 {
+		writeErr(w, http.StatusNotFound, "用法：POST /desk/plugins/{id}/{install|upgrade}")
+		return
+	}
+	spec, ok := findPlugin(parts[0])
+	if !ok {
+		writeErr(w, http.StatusNotFound, "没有这个插件："+parts[0])
+		return
+	}
+	var steps []pluginStep
+	switch parts[1] {
+	case "install":
+		steps = spec.Install
+	case "upgrade":
+		steps = spec.Upgrade
+	default:
+		writeErr(w, http.StatusNotFound, "动作只有 install / upgrade")
+		return
+	}
+	if len(steps) == 0 {
+		writeErr(w, http.StatusBadRequest, "这个插件没有配置安装命令")
+		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()
+		}
+	}
+
+	cmds := make([]string, 0, len(steps))
+	for _, st := range steps {
+		cmds = append(cmds, st.Command())
+	}
+	send("open", map[string]any{"id": spec.ID, "action": parts[1], "commands": cmds})
+
+	/* 与 /desk/ask 同一口径：客户端断连不是「取消安装」。
+	   装到一半被手机锁屏杀掉会更糟（半个包装在盘上），所以跑完再说。 */
+	ctx := context.WithoutCancel(r.Context())
+	failed := ""
+	failCode := 0
+	for i, st := range steps {
+		send("step", map[string]any{"index": i, "command": st.Command()})
+		code, err := runPluginStep(ctx, st, func(line string) {
+			send("line", map[string]any{"index": i, "line": line})
+		})
+		if err != nil || code != 0 {
+			if st.Optional {
+				send("line", map[string]any{"index": i, "line": "↷ " + st.SkipNote})
+				continue
+			}
+			if err != nil {
+				failed = err.Error()
+			} else {
+				failed = fmt.Sprintf("%s 退出码 %d", st.Command(), code)
+			}
+			failCode = code
+			break
+		}
+	}
+
+	info := pluginInfoOf(spec) // 跑完重新探一次：成功与否都让界面拿到最新状态
+	if failed != "" {
+		send("end", map[string]any{"ok": false, "code": failCode, "error": failed, "plugin": info})
+		return
+	}
+	send("end", map[string]any{"ok": true, "code": 0, "plugin": info})
+}
+
+// runPluginStep 跑一条命令并把 stdout+stderr 按行回调（顺序即实际发生顺序）。
+func runPluginStep(ctx context.Context, st pluginStep, onLine func(string)) (int, error) {
+	if len(st.Args) == 0 {
+		return 0, errors.New("空命令")
+	}
+	cmd := exec.CommandContext(ctx, st.Args[0], st.Args[1:]...)
+	pr, pw, err := os.Pipe()
+	if err != nil {
+		return 1, err
+	}
+	cmd.Stdout = pw
+	cmd.Stderr = pw
+	if err := cmd.Start(); err != nil {
+		pw.Close()
+		pr.Close()
+		return 1, fmt.Errorf("启动 %s 失败：%w（该命令不在 PATH 上？）", st.Args[0], err)
+	}
+	pw.Close()
+
+	done := make(chan struct{})
+	go func() {
+		sc := bufio.NewScanner(pr)
+		sc.Buffer(make([]byte, 0, 64<<10), 1<<20)
+		for sc.Scan() {
+			onLine(sc.Text())
+		}
+		close(done)
+	}()
+	err = cmd.Wait()
+	<-done
+	pr.Close()
+
+	code := 0
+	if cmd.ProcessState != nil {
+		code = cmd.ProcessState.ExitCode()
+	}
+	if err != nil && code == 0 {
+		code = 1
+	}
+	return code, nil
+}