magic-agent 2.4.2 → 2.6.0

package/internal/client/requirements.go

@@ -28,14 +28,17 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/darren/magic-agent/internal/agent"
+	"github.com/darren/magic-agent/internal/requirements"
 )
 
 // FeatureRequirements core 侧的能力位（与 internal/agent 的同名常量一致）。
@@ -45,6 +48,12 @@ import (
 // 「插件依赖哪些能力位」在 grep 时只有一处 —— 与 FeatureSessionTeam 的处理方式一致。
 const FeatureRequirements = "feature.requirements"
 
+// FeatureRequirementShots core 侧的能力位（与 internal/agent 的同名常量一致）。
+//
+// 与 FeatureRequirements 分开：core 可能支持需求聚合但还不支持截图 ——
+// 界面要能分别判断，别把「需求」页签整个藏掉。
+const FeatureRequirementShots = "feature.requirement.shots"
+
 // reqAutoDebounce 一轮收尾后等多久再归纳（期间再来一轮就顺延）。
 const reqAutoDebounce = 12 * time.Second
 
@@ -54,6 +63,12 @@ const reqAutoDebounce = 12 * time.Second
 // core 侧单次调用默认 4 分钟。给到 10 分钟覆盖「首次回填一大段历史」这种最慢的情况。
 const reqConsolidateTimeout = 10 * time.Minute
 
+// reqShotTimeout 追加截图的上限。
+//
+// 落盘本身是毫秒级的，但要先抢 core 的归纳锁（另一轮归纳在跑时要等）——
+// 给 30 秒足够，又不至于让界面一直转圈。
+const reqShotTimeout = 30 * time.Second
+
 // reqAutoOffEnv 关掉自动归纳的环境变量（排查 / 省额度用）。
 const reqAutoOffEnv = "MAGIC_CLIENT_NO_REQ_AUTO"
 
@@ -80,6 +95,25 @@ func (s *Service) handleRequirements(w http.ResponseWriter, r *http.Request) {
 	s.proxyCore(w, r, "--requirements", ws)
 }
 
+// handleRequirementsGraph GET /desk/requirements/graph?ws=<ws_id|目录>：
+// 会话↔需求关系图谱（nodes=会话/功能点，edges=关系）。纯读转发，同族范式。
+func (s *Service) handleRequirementsGraph(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	if !hasStr(s.contract.Features, FeatureRequirements) {
+		writeErr(w, http.StatusNotImplemented,
+			"当前 core 不支持需求聚合（缺少 "+FeatureRequirements+" 能力位，请升级 magic-agent）")
+		return
+	}
+	ws := strings.TrimSpace(r.URL.Query().Get("ws"))
+	if ws == "" {
+		ws = "all"
+	}
+	s.proxyCore(w, r, "--requirements-graph", ws)
+}
+
 // handleRequirementsConsolidate POST /desk/requirements/consolidate：
 // 立即归纳一轮（用户点「整理」）。
 //
@@ -149,6 +183,156 @@ func (s *Service) handleRequirementsConsolidate(w http.ResponseWriter, r *http.R
 	writeCoreJSON(w, out)
 }
 
+// handleRequirementsShots POST /desk/requirements/shots：
+// 给一个功能点追加一张「页面完成情况」截图。
+//
+// 请求体 = **PNG 原始字节**（不是 multipart）：这条通道只收图，形状越简单越不容易出错。
+// 参数走查询串：ws（工作区 id 或目录，空 = 当前目录）、module、name（功能点名）、caption。
+//
+// 为什么图片不直接落到需求目录、而要过 core：
+//
+//	需求文档是 core 的资产（~/.magic-agent/requirements/<wsid>/），它有自己的一套
+//	锁（与归纳共用）、路径归一（Windows 反斜杠）与文档段落格式。让 core 来写，
+//	客户端就只负责「拿到字节、传过去」—— 两边不会各写一套格式。
+func (s *Service) handleRequirementsShots(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	/* 能力位 gate：老 core 没有 --requirement-shot（exit 2）。先查能力位并**说清楚为什么** ——
+	   让用户看到「core 太旧，请升级」，比让它报一句 usage error 强得多。 */
+	if !hasStr(s.contract.Features, FeatureRequirementShots) {
+		writeErr(w, http.StatusNotImplemented,
+			"当前 core 不支持需求截图（缺少 "+FeatureRequirementShots+" 能力位，请升级 magic-agent）")
+		return
+	}
+	q := r.URL.Query()
+	name := strings.TrimSpace(q.Get("name"))
+	if name == "" {
+		writeErr(w, http.StatusBadRequest, "缺少 name（功能点名）")
+		return
+	}
+	module := strings.TrimSpace(q.Get("module"))
+	caption := strings.TrimSpace(q.Get("caption"))
+	ws := strings.TrimSpace(q.Get("ws"))
+	if ws == "" {
+		if wd, err := os.Getwd(); err == nil {
+			ws = wd
+		}
+	}
+	if ws == "" {
+		writeErr(w, http.StatusBadRequest, "ws 不能为空")
+		return
+	}
+	// 先收进内存再判大小。
+	//
+	// ⚠️ 不用 http.MaxBytesReader：它一超限就直接写 400（"request body too large"），
+	// 分不清「图片太大」和「请求体坏了」—— 用户看到的是一句看不懂的错。
+	// 这里自己读，超限的单独回 413。
+	body, err := io.ReadAll(io.LimitReader(r.Body, requirements.MaxShotBytes+1))
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "读取截图失败："+err.Error())
+		return
+	}
+	if len(body) == 0 {
+		writeErr(w, http.StatusBadRequest, "截图内容为空")
+		return
+	}
+	if len(body) > requirements.MaxShotBytes {
+		writeErr(w, http.StatusRequestEntityTooLarge,
+			fmt.Sprintf("截图过大（上限 %d 字节）", requirements.MaxShotBytes))
+		return
+	}
+	args := []string{"--requirement-shot", ws, "--requirement-name", name}
+	if module != "" {
+		args = append(args, "--requirement-module", module)
+	}
+	if caption != "" {
+		args = append(args, "--requirement-caption", caption)
+	}
+	out, err := s.runCoreTimedStdin(r.Context(), reqShotTimeout, bytes.NewReader(body), args...)
+	if err != nil {
+		code := http.StatusBadGateway
+		if isCoreTimeout(err) {
+			code = http.StatusGatewayTimeout
+		}
+		writeErr(w, code, fmt.Sprintf("%s --requirement-shot 失败：%v", s.opts.MagicAgent, err))
+		return
+	}
+	writeCoreJSON(w, out)
+}
+
+// handleRequirementShotRemote POST /desk/requirements/shot-remote：
+// 服务端 agent-browser 打开 url 截一张全页图，落到 /desk/uploads/ 并回图片地址。
+//
+// 2026-10-25 内置浏览器 MCP 改基 agent-browser 后，手机端的「截图」不再依赖
+// 页面内 relay 的 html2canvas（跨域污染 / iframe 抓不到 / 慢页超时），改由
+// 服务端真实 Chromium 截图。请求体 JSON：{"url":"…"}（必须 http/https）。
+// 响应：{ok, data:"/desk/uploads/…png"}（data 直接喂给标注浮层的 <img>）。
+//
+// 能力位与 /desk/requirements/shots 同一杆秤：缺 feature.requirement.shots 回 501；
+// 服务端没装 agent-browser 也回 501 + 安装提示。
+func (s *Service) handleRequirementShotRemote(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	if !hasStr(s.contract.Features, FeatureRequirementShots) {
+		writeErr(w, http.StatusNotImplemented,
+			"当前 core 不支持需求截图（缺少 "+FeatureRequirementShots+" 能力位，请升级 magic-agent）")
+		return
+	}
+	var req struct {
+		URL      string `json:"url"`
+		FullPage bool   `json:"full_page,omitempty"`
+	}
+	body, err := io.ReadAll(io.LimitReader(r.Body, 64<<10))
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "读取请求失败："+err.Error())
+		return
+	}
+	if err := json.Unmarshal(body, &req); err != nil {
+		writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON")
+		return
+	}
+	u := strings.TrimSpace(req.URL)
+	if !strings.HasPrefix(u, "http://") && !strings.HasPrefix(u, "https://") {
+		writeErr(w, http.StatusBadRequest, "url 必须是 http/https 地址")
+		return
+	}
+	if abBin() == "" {
+		writeErr(w, http.StatusNotImplemented,
+			"服务端未安装 agent-browser（npm install -g agent-browser && agent-browser install，或设 "+EnvAgentBrowserBin+"）")
+		return
+	}
+	// 截图落 uploads 目录（与 /desk/upload 同一个家，/desk/uploads/<name> 可回读）。
+	dir := filepath.Join(os.TempDir(), "magic-client-uploads")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		writeErr(w, http.StatusInternalServerError, "创建上传目录失败："+err.Error())
+		return
+	}
+	out := filepath.Join(dir, strconv.FormatInt(time.Now().UnixNano(), 10)+"-reqshot.png")
+	if err := abOpen(r.Context(), u); err != nil {
+		writeErr(w, http.StatusBadGateway, "agent-browser 打开页面失败："+err.Error())
+		return
+	}
+	if err := abShot(r.Context(), out, req.FullPage); err != nil {
+		_ = os.Remove(out)
+		writeErr(w, http.StatusBadGateway, "agent-browser 截图失败："+err.Error())
+		return
+	}
+	st, err := os.Stat(out)
+	if err != nil || st.Size() == 0 {
+		writeErr(w, http.StatusBadGateway, "截图文件没有生成")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"ok":   true,
+		"data": "/desk/uploads/" + url.PathEscape(filepath.Base(out)),
+		"size": st.Size(),
+	})
+}
+
 // consolidateArgs 组归纳命令。
 //
 // engine/model 来自客户端配置的默认引擎（手动「整理」）：传了就用它，core 不再自动换。
@@ -180,9 +364,19 @@ func consolidateArgs(ws, module string, force, all, auto bool, engine, model str
 
 // runCoreTimed 与 runCore 同形，但超时可调（归纳不是 45s 能跑完的）。
 func (s *Service) runCoreTimed(ctx context.Context, timeout time.Duration, args ...string) ([]byte, error) {
+	return s.runCoreTimedStdin(ctx, timeout, nil, args...)
+}
+
+// runCoreTimedStdin 与 runCoreTimed 同形，但把 stdin 接到子进程。
+//
+// 截图走这条路：PNG 几百 KB，放进 argv 会撞命令行长度上限、也会把二进制搅进进程列表。
+func (s *Service) runCoreTimedStdin(ctx context.Context, timeout time.Duration, stdin io.Reader, args ...string) ([]byte, error) {
 	ctx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	cmd := newCoreCmd(ctx, s.opts.MagicAgent, args...)
+	if stdin != nil {
+		cmd.Stdin = stdin
+	}
 	// 与 runCore 同一道保险：core 的后代进程握着管道时 Wait 不能永久挂住。
 	cmd.WaitDelay = 5 * time.Second
 	var stdout, stderr bytes.Buffer
@@ -327,3 +521,6 @@ func (s *Service) runAutoConsolidate(ws string) {
 
 // 编译期断言：能力位常量与 core 侧同值（改错一个字这里就编译不过）。
 var _ = func() bool { return agent.FeatureRequirements == FeatureRequirements }
+
+// 同上，截图能力位。
+var _ = func() bool { return agent.FeatureRequirementShots == FeatureRequirementShots }

package/internal/client/requirements_shots_test.go

@@ -0,0 +1,200 @@
+package client
+
+// requirements_shots_test.go - 「页面完成情况」截图端点的三条硬约束：
+//   · 老 core 缺能力位 → 501 且点名缺哪个位（不是 400/502 让人猜）；
+//   · PNG 走 **stdin** 传给 core（不进 argv：几百 KB 会撞命令行长度上限）；
+//   · 参数（ws / module / name / caption）原样透传。
+//
+// 假 core 用 .bat（Windows 上 exec 不了 shebang 脚本 —— 既有基线，见 jobs_test.go）。
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// shotCore 假 core：回契约、记下参数、并把从 stdin 收到的字节长度写进日志。
+//
+// ⚠️ Windows 上的两个坑（都只影响**测试桩**，真实 core 是 .exe，直接 exec 时
+// 中文参数与二进制 stdin 都是完好的 —— 实测 arg[2]="需求页" 字节 e9 9c 80…）：
+//   ① cmd.exe 按**控制台代码页**（936=GBK）传参，桩里要按同一编码解读；
+//   ② PNG 头里有 0x1A（EOF 字符），文本模式读 stdin 会**截断**（12 字节只读到 11）——
+//      必须用二进制模式读。
+//
+// 二进制读 stdin 的写法踩过坑：[Console]::OpenStandardInput() 返回的是 Stream，
+// **没有 ReadToEnd**（PowerShell 5.1 会报 method not found，$b 保持 null → 记成 0 字节）。
+// 正确写法是 CopyTo 到 MemoryStream 再看 Length。
+func shotCore(t *testing.T, features, logPath string) string {
+	t.Helper()
+	dir := t.TempDir()
+	if runtime.GOOS == "windows" {
+		// 读 stdin 的小脚本单独放一个 .ps1：批处理里的 -Command 引号嵌套太容易走样。
+		ps1 := filepath.Join(dir, "readstdin.ps1")
+		psBody := "$stdin = [Console]::OpenStandardInput()\n" +
+			"$ms = New-Object System.IO.MemoryStream\n" +
+			"$stdin.CopyTo($ms)\n" +
+			"[Console]::Out.Write('STDIN_BYTES=' + $ms.Length + \"`n\")\n"
+		if err := os.WriteFile(ps1, []byte(psBody), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		path := filepath.Join(dir, "magic-agent.bat")
+		lines := []string{
+			`@echo off`,
+			`set "A=%*"`,
+			`echo %A%>>"` + logPath + `"`,
+			`if "%A:--contract=%" == "%A%" goto other`,
+			`echo {"contractVersion":2,"features":[` + features + `],"engines":[]}`,
+			`exit /b 0`,
+			`:other`,
+			// 二进制读 stdin，记下字节数（追加进同一个日志）。
+			`powershell -NoProfile -ExecutionPolicy Bypass -File "` + ps1 + `">>"` + logPath + `"`,
+			`echo {"ok":true,"workspace":"ws-1","dir":"/x","file":"/x/f.md","path":"/x/1.png","shots":1}`,
+			`exit /b 0`,
+		}
+		// 批处理按代码页存（cmd.exe 按它解释脚本里的字节）。
+		body := strings.Join(lines, "\r\n") + "\r\n"
+		if err := os.WriteFile(path, encodeWindowsScript(body), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		return path
+	}
+	path := filepath.Join(dir, "magic-agent")
+	script := `#!/bin/sh
+echo "$*" >> ` + logPath + `
+case "$*" in
+  *--contract*)
+    echo '{"contractVersion":2,"features":[` + features + `],"engines":[]}'
+    exit 0
+    ;;
+esac
+# stdin 字节数（证明 PNG 走了 stdin）
+n=$(wc -c)
+echo "STDIN_BYTES=$n" >> ` + logPath + `
+echo '{"ok":true,"workspace":"ws-1","dir":"/x","file":"/x/f.md","path":"/x/1.png","shots":1}'
+exit 0
+`
+	if err := os.WriteFile(path, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// shotsService 造一个带截图能力位的测试服务。
+func shotsService(t *testing.T, logPath string) *Service {
+	t.Helper()
+	core := shotCore(t, `"feature.session.events","feature.session.control",`+
+		`"`+FeatureRequirements+`","`+FeatureRequirementShots+`"`, logPath)
+	return newTestService(t, core)
+}
+
+func TestRequirementShotsRouteNeedsFeature(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	core := shotCore(t, `"feature.session.events","feature.session.control"`, logPath)
+	svc := newTestService(t, core)
+
+	req := httptest.NewRequest(http.MethodPost, "/desk/requirements/shots?token=tok&name=需求页", bytes.NewReader([]byte("x")))
+	rec := httptest.NewRecorder()
+	svc.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusNotImplemented {
+		t.Fatalf("缺能力位应回 501，实际 %d: %s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), FeatureRequirementShots) {
+		t.Errorf("报错应点名缺哪个能力位，实际 %s", rec.Body.String())
+	}
+	for _, c := range readCalls(t, logPath) {
+		if strings.Contains(c, "--requirement-shot") {
+			t.Errorf("缺能力位时不该去调 core：%s", c)
+		}
+	}
+}
+
+func TestRequirementShotsRouteForwardsArgsAndStdin(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	svc := shotsService(t, logPath)
+
+	png := []byte{0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A, 0x01, 0x02, 0x03, 0x04}
+	url := "/desk/requirements/shots?token=tok&ws=ws-1&module=%E4%BB%BB%E5%8A%A1%E5%88%97%E8%A1%A8&name=%E9%9C%80%E6%B1%82%E9%A1%B5&caption=%E6%94%B9%E6%88%90%E5%8F%8C%E5%88%97"
+	req := httptest.NewRequest(http.MethodPost, url, bytes.NewReader(png))
+	rec := httptest.NewRecorder()
+	svc.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("截图应 200，实际 %d: %s", rec.Code, rec.Body.String())
+	}
+	// 响应是 core 的结构化结果。
+	if !strings.Contains(rec.Body.String(), `"ok":true`) {
+		t.Errorf("应原样回传 core 的结果，实际 %s", rec.Body.String())
+	}
+	var sawArgs bool
+	var sawStdin bool
+	for _, c := range readCalls(t, logPath) {
+		// ⚠️ Windows 上 cmd.exe 按控制台代码页传参 → 日志里是 GBK 字节。
+		// 按同一编码解读（真实 core 是 .exe，直接 exec 时参数是 UTF-8 —— 那是另一条路）。
+		decoded := decodeScriptBytes([]byte(c))
+		if strings.Contains(decoded, "--requirement-shot ws-1") &&
+			strings.Contains(decoded, "--requirement-name 需求页") &&
+			strings.Contains(decoded, "--requirement-module 任务列表") &&
+			strings.Contains(decoded, "--requirement-caption 改成双列") {
+			sawArgs = true
+		}
+		if strings.Contains(c, "STDIN_BYTES=") {
+			// PNG 字节数（12）应原样过 stdin。
+			if !strings.Contains(c, "STDIN_BYTES=12") {
+				t.Errorf("PNG 应原样走 stdin（12 字节），实际 %s", c)
+			}
+			sawStdin = true
+		}
+	}
+	if !sawArgs {
+		t.Errorf("参数应原样透传，实际 %v", readCalls(t, logPath))
+	}
+	if !sawStdin {
+		t.Errorf("PNG 应走 stdin 而不是 argv，实际 %v", readCalls(t, logPath))
+	}
+}
+
+func TestRequirementShotsRejectsBadInput(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	svc := shotsService(t, logPath)
+	cases := []struct {
+		name string
+		url  string
+		body []byte
+		code int
+	}{
+		{"缺 name", "/desk/requirements/shots?token=tok", []byte("x"), http.StatusBadRequest},
+		{"空 body", "/desk/requirements/shots?token=tok&name=x", nil, http.StatusBadRequest},
+		{"GET 不行", "/desk/requirements/shots?token=tok&name=x", nil, http.StatusMethodNotAllowed},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var req *http.Request
+			if c.code == http.StatusMethodNotAllowed {
+				req = httptest.NewRequest(http.MethodGet, c.url, nil)
+			} else {
+				req = httptest.NewRequest(http.MethodPost, c.url, bytes.NewReader(c.body))
+			}
+			rec := httptest.NewRecorder()
+			svc.Handler().ServeHTTP(rec, req)
+			if rec.Code != c.code {
+				t.Errorf("应回 %d，实际 %d: %s", c.code, rec.Code, rec.Body.String())
+			}
+		})
+	}
+}
+
+func TestRequirementShotsRejectsOversize(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	svc := shotsService(t, logPath)
+	big := make([]byte, 9<<20) // > 8MB 上限
+	req := httptest.NewRequest(http.MethodPost, "/desk/requirements/shots?token=tok&name=x", bytes.NewReader(big))
+	rec := httptest.NewRecorder()
+	svc.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Errorf("超限应回 413，实际 %d: %s", rec.Code, rec.Body.String())
+	}
+}

package/internal/client/restart.go

@@ -0,0 +1,134 @@
+package client
+
+/* restart.go - `POST /desk/restart`：让手机上「我的 → 重启服务」能重启桌面端客户端。
+ *
+ * ── 为什么不能在本进程里直接做 ──
+ * 重启 = 停掉自己再拉起自己。StopDaemon 会 TerminatePID 本进程，写在同一个进程里
+ * 等于「自杀到一半」：响应发不出去、后面的 start 也轮不到。
+ * 所以这里只做三件事：**先立标志、先答 200、再由进程内定时器拉起**一个脱离终端的
+ * `magic-client restart` 助手；助手停旧实例、按状态文件里的参数拉起新实例
+ * （见 daemon.go 的 RestartDaemon）。
+ *
+ * ── 为什么要「先标志、定时器后触发」（2026-10-25 用户定调）──
+ * 旧链路在 handler 里当场 spawn 带 `--delay 1s` 的助手，两个毛病：
+ *  ① 重复点击（双击 / 手机重试 / 两台设备同时点）各起一个助手，两个助手互相把对方
+ *     刚拉起的实例停掉 —— 端口抢占，手机 30 秒以上还「重启后连不上」；
+ *  ② 助手在 handler 里就起身，与「响应 flush 回手机」只隔一个 --delay，先后靠运气。
+ * 新链路：标志让重复点击变成一句「已在重启中」（幂等，不再排第二个定时器）；
+ * 定时器到点才拉助手，严格晚于 handler 返回 —— 响应一定先落地，服务才可能被杀。
+ * 标志同时经 /desk/health.restarting 带出去：手机探活看到它 = 旧实例认账、即将下线。
+ *
+ * ── 为什么先校验状态文件 ──
+ * 重启参数全来自 `~/.magic-client/client.json`。如果那个文件不存在（前台 serve 起的）
+ * 或指向的不是本进程（同机跑着两个实例），照着它重启会重启**别人**。两种都当场拒绝，
+ * 让手机看到能落地的一句话，而不是「点了没反应」。
+ */
+
+import (
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"sync"
+	"time"
+)
+
+// restartDelay 定时器等多久再拉助手：给这次 200 响应留落地时间。
+// 是 var 不是 const：测试里改小，不用真等一秒。
+var restartDelay = time.Second
+
+// restartPending 本进程是否已受理过一次重启（「标志」）。
+//
+// 为什么必须在服务端记：重复点击的对手不只是这一台手机 —— 手机重试、另一台设备
+// 同时点，都会各带一个 POST 过来。没有标志就会各排一个定时器、各起一个助手，
+// 两个助手互相把对方刚拉起的实例停掉（端口抢占，输家要等 ready 超时）。
+var (
+	restartMu      sync.Mutex
+	restartPending bool
+)
+
+// restartSpawner 定时器到点时真正干活的人：脱离终端拉一个 `magic-client restart`
+// 助手停旧起新。包级变量是为了测试能换成不碰真进程的假动作。
+var restartSpawner = spawnRestartHelper
+
+// restartRequested 本进程是否已受理过重启。/desk/health 带这个字段，
+// 手机据此把「旧实例认账」当成「它马上要下线」，不必等连接真的断。
+func restartRequested() bool {
+	restartMu.Lock()
+	defer restartMu.Unlock()
+	return restartPending
+}
+
+// handleRestart 重启后台实例（手机「我的」页那枚按钮）。
+func (s *Service) handleRestart(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	st, err := ReadDaemonState(DefaultStatePath())
+	if err != nil {
+		writeErr(w, http.StatusInternalServerError, "读实例状态失败："+err.Error())
+		return
+	}
+	if st == nil || st.PID != os.Getpid() {
+		writeErr(w, http.StatusConflict,
+			"当前实例不是后台启动的（没有指向本进程的状态文件），不能自重启："+
+				"请到桌面终端执行 magic-client restart")
+		return
+	}
+	exe, err := os.Executable()
+	if err != nil {
+		writeErr(w, http.StatusInternalServerError, "定位自身可执行文件失败："+err.Error())
+		return
+	}
+
+	/* 标志：本进程已受理过一次重启。重复点击（双击 / 手机重试 / 另一台设备同时点）
+	   直接答「已在重启中」—— 不再排第二个定时器、不再起第二个助手。 */
+	restartMu.Lock()
+	if restartPending {
+		restartMu.Unlock()
+		writeJSON(w, http.StatusOK, map[string]any{
+			"ok": true, "restarting": true, "already_pending": true, "pid": os.Getpid(),
+		})
+		return
+	}
+	restartPending = true
+	restartMu.Unlock()
+
+	// 先答，再让定时器触发：handler 返回后响应才真正落回手机，AfterFunc 在这一刻
+	// 之后才跑 —— 助手起身严格晚于响应落地，不存在「先把服务杀了、响应卡在缓冲区」。
+	writeJSON(w, http.StatusOK, map[string]any{
+		"ok":         true,
+		"restarting": true,
+		"pid":        os.Getpid(),
+	})
+	time.AfterFunc(restartDelay, func() { restartSpawner(exe, s.log) })
+	s.log.Printf("收到重启请求：%s 后由定时器拉起助手停旧起新（旧实例即将停止）", restartDelay)
+}
+
+// spawnRestartHelper 脱离终端拉一个 `magic-client restart` 助手：它停旧实例、按状态
+// 文件里的参数起新实例。不带 --delay —— 定时器已经等过 restartDelay 了。
+func spawnRestartHelper(exe string, lg *log.Logger) {
+	logPath := DefaultLogPath()
+	var logf *os.File
+	if logPath != "" {
+		logf, _ = os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
+	}
+	cmd := exec.Command(exe, "restart")
+	if logf != nil {
+		cmd.Stdout, cmd.Stderr = logf, logf
+	}
+	detach(cmd)
+	if err := cmd.Start(); err != nil {
+		if lg != nil {
+			lg.Printf("重启失败（spawn %s restart）：%v（手机侧可去桌面执行 magic-client restart）", exe, err)
+		}
+		_ = logf.Close()
+		return
+	}
+	// 子进程已拿到自己的句柄：父进程这份可以关了（它马上要被停）。
+	_ = logf.Close()
+	if lg != nil {
+		lg.Printf("重启助手已启动：%s restart（旧实例即将停止）", exe)
+	}
+}