magic-agent 2.4.2 → 2.6.0

package/internal/client/scripts.go

@@ -0,0 +1,1047 @@
+package client
+
+// scripts.go - 「发现 → 脚本」：用户登记脚本，服务端负责启停与日志。
+//
+// ## 这个功能是什么
+//
+// 手机端「发现」页多了一个「脚本」入口：用户登记若干脚本文件（路径 + 参数），
+// 就能在手机上**启动 / 停止**它们，并**实时看日志**。相当于一个极简的
+// 进程管理器，面向「这台桌面上要跑着的那些小服务 / 一次性任务」。
+//
+// ## 为什么放在插件（magic-client）这一侧而不是 core
+//
+// 与 plugins.go 的理由同源：脚本**不是引擎**。core 的 `--engines` 里没有它，
+// 也不该有 —— core 是「跑一轮 agent」的进程，跑完就退出，没有「常驻管着某个
+// 脚本」这个概念。只有常驻的插件知道「这个脚本现在还活着」。
+//
+// ## ── 纪律 ──
+//
+//  1) **客户端不能传任意命令行**。客户端只能登记「脚本文件路径 + 参数」，
+//     服务端按登记的 id 执行。命令**不过 shell**（.cmd/.bat/.ps1 由
+//     agent.WrapLaunch 包成 PowerShell 单引号字面量调用）。
+//     这条接口若接受客户端传来的命令串，就等于开了一个任意命令执行器。
+//  2) **只认脚本文件**，扩展名走白名单（见 scriptExtOK）。不是脚本的东西
+//     （.txt / 任意 exe）一律拒绝 —— 白名单比黑名单稳。
+//  3) **不假装成功**：脚本起不来就把 stderr 原样回给用户；日志区显示的是
+//     **真实输出**，不是「已启动」三个字。
+//  4) **状态如实**：服务重启后靠 pid 探活判断脚本是不是还活着，不靠猜。
+//
+// ## 存储
+//
+//	config.json   脚本定义（用户登记的清单）—— ~/.magic-agent/scripts/
+//	runs.json     运行态（pid / 状态 / 退出码 / 日志游标）—— 跨重启保留
+//	logs/<id>.log 每个脚本一份完整日志（环形缓冲之外的持久副本）
+//
+// 运行态落盘是必须的：服务重启后，脚本**进程还活着**（它是被 detach 出去的
+// 独立进程组），但服务端已经忘了它 —— 不落盘就会出现「明明在跑，界面说已停止」。
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+/* ─────────────── 数据形状 ─────────────── */
+
+// ScriptDef 一个已登记的脚本（用户配置，持久化）。
+type ScriptDef struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+	// Path 脚本文件绝对路径（服务端不做家目录限制 —— 令牌持有者本来就能让
+	// agent 跑任意命令，这里再限制只会让「脚本放在 D 盘」这种正当用法失败）。
+	Path string `json:"path"`
+	// Args 传给脚本的参数（不过 shell，逐个作为独立 argv 元素）。
+	Args []string `json:"args"`
+	// Cwd 工作目录；空 = 用脚本所在目录。
+	Cwd string `json:"cwd,omitempty"`
+	// Interpreter 解释器路径（空 = 直接跑脚本文件本身）。
+	//
+	// 为什么需要它：**白名单里没有 .exe**（可执行文件不是脚本），
+	// 所以 Python / Node 这类脚本在 Windows 上没法直接 exec ——
+	// 路径指向 .py 时 Windows 不会拿它当程序跑。
+	// 填了解释器就变成 `<解释器> <脚本路径> [参数…]`。
+	//
+	// ⚠️ 解释器本身**不受脚本白名单约束**（它是用户显式指定的可执行文件，
+	//    跟脚本路径是两层事）。但它必须是存在的文件。
+	Interpreter string `json:"interpreter,omitempty"`
+	// Env 追加的环境变量（"KEY=VALUE" 逐条）。
+	//
+	// 为什么需要它：Python 脚本 stdout 非 tty 时改用**块缓冲**（4~8KB），
+	// 日志会「跑完一大半才刷出来」—— 实时日志就废了。
+	// 要治它得设 PYTHONUNBUFFERED=1（还要 PYTHONIOENCODING=utf-8 治乱码）。
+	// 这些是脚本自己的运行环境，不该由服务端替用户猜。
+	Env []string `json:"env,omitempty"`
+	// Note 备注（界面上给用户自己看的）。
+	Note string `json:"note,omitempty"`
+}
+
+// ScriptState 运行态。
+type ScriptState struct {
+	// State: stopped | running | done | failed
+	State string `json:"state"`
+	PID   int    `json:"pid,omitempty"`
+	// ExitCode 脚本自己退出时的退出码（-1 = 还在跑 / 被强杀）。
+	ExitCode int `json:"exitCode"`
+	// StartedAt 起跑时刻（Unix 毫秒）；0 = 没跑过。
+	StartedAt int64 `json:"startedAt,omitempty"`
+	// EndedAt 结束时刻（Unix 毫秒）；0 = 还在跑。
+	EndedAt int64 `json:"endedAt,omitempty"`
+	// LogSeq 已经产生过多少行日志（客户端按它增量拉）。
+	LogSeq int `json:"logSeq"`
+	// Error 起跑失败时的原因（没起起来）。
+	Error string `json:"error,omitempty"`
+}
+
+// ScriptItem GET /desk/scripts 的一项：定义 + 运行态。
+type ScriptItem struct {
+	ScriptDef
+	State ScriptState `json:"state"`
+}
+
+// scriptConfig 落盘的脚本清单。
+type scriptConfig struct {
+	Scripts []ScriptDef `json:"scripts"`
+}
+
+/* ─────────────── 常量 ─────────────── */
+
+const (
+	// scriptLogRing 内存里保留的日志行数（每脚本）。
+	//
+	// 为什么要有环：脚本可能狂打日志（每秒几十行），全留在内存里会把这台
+	// 桌面吃干。完整副本在 logs/<id>.log —— 要看全部可以用
+	// GET /desk/path-read 读那个文件（它就是普通文本）。
+	scriptLogRing = 500
+	// scriptMaxNameLen 名称长度上限（防超长名撑爆界面）。
+	scriptMaxNameLen = 80
+	// scriptMaxArgs 参数个数上限。
+	scriptMaxArgs = 32
+	// scriptMaxArgLen 单个参数长度上限。
+	scriptMaxArgLen = 512
+	// scriptMaxEnv 环境变量条数上限。
+	scriptMaxEnv = 32
+)
+
+// scriptExtOK 允许的脚本扩展名白名单。
+//
+// 为什么是白名单：黑名单（"排除 .txt"）永远漏 —— .pyc / .so / .msi 都能被
+// 当脚本跑。白名单里这几类才是「人写的、拿来跑的」东西。
+//
+// .exe 特意**不在**白名单里：可执行文件不是「脚本」，而且允许它就等于允许
+// 跑任意二进制。
+var scriptExtOK = map[string]bool{
+	".sh":   true,
+	".bash": true,
+	".cmd":  true,
+	".bat":  true,
+	".ps1":  true,
+	".py":   true,
+	".js":   true,
+	".mjs":  true,
+}
+
+/* ─────────────── 管理器 ─────────────── */
+
+// scriptManager 脚本清单 + 运行态 + 日志的全部状态。
+type scriptManager struct {
+	dir string // ~/.magic-agent/scripts
+
+	mu    sync.Mutex
+	defs  map[string]*ScriptDef // id → 定义
+	order []string              // 定义顺序（登记先后）
+	runs  map[string]*scriptRun // id → 运行态与日志
+	seq   int                   // 生成 id 的序号
+	// starting 正在 spawn 的脚本 id（防并发重复启动，见 start）。
+	starting map[string]bool
+}
+
+// scriptRun 一个脚本的运行态 + 日志缓冲。
+type scriptRun struct {
+	state ScriptState
+	// lines 环形缓冲里的日志行（seq, text）。
+	lines []scriptLine
+	// nextSeq 下一行日志要用的 seq。
+	nextSeq int
+	// cmd 当前持有的进程（用于停止）；nil = 没在跑。
+	cmd *exec.Cmd
+	// cancel 当前这次运行的可取消 context。
+	cancel context.CancelFunc
+	// stopping 本次运行是**用户主动停的**（不是自己退的）。
+	//
+	// 为什么要有这个标记：被强杀的进程退出码非 0，若不区分就会显示成
+	// 「失败」—— 用户明明是自己点的停止，看到「失败」会以为脚本出错。
+	stopping bool
+}
+
+// scriptLine 一行日志。
+type scriptLine struct {
+	Seq  int    `json:"seq"`
+	Text string `json:"text"`
+}
+
+// envScriptsDir 覆盖脚本数据目录（测试用；生产走 ~/.magic-agent/scripts）。
+//
+// 与 jobs.go 的 MAGIC_CLIENT_JOBS_DIR 同一套思路：单测要能造一个干净的
+// 脚本目录，不许写进用户真实的 ~/.magic-agent/scripts。
+const envScriptsDir = "MAGIC_CLIENT_SCRIPTS_DIR"
+
+// newScriptManager 建管理器并读回落盘的清单与运行态。
+func newScriptManager(s *Service) *scriptManager {
+	m := &scriptManager{
+		defs:     map[string]*ScriptDef{},
+		runs:     map[string]*scriptRun{},
+		starting: map[string]bool{},
+	}
+	dir := strings.TrimSpace(os.Getenv(envScriptsDir))
+	if dir == "" {
+		home, err := os.UserHomeDir()
+		if err != nil || home == "" {
+			m.dir = ""
+			return m
+		}
+		dir = filepath.Join(home, ".magic-agent", "scripts")
+	}
+	m.dir = dir
+	if err := os.MkdirAll(filepath.Join(m.dir, "logs"), 0o700); err != nil {
+		// s.log 可能是 nil（单测里 &Service{} 直接构造）→ 不能直接调。
+		if s.log != nil {
+			s.log.Printf("脚本目录创建失败 %s（%v），脚本清单将不落盘", m.dir, err)
+		}
+		m.dir = ""
+		return m
+	}
+	m.load()
+	return m
+}
+
+// scriptMgr 取脚本管理器（**惰性建**）。
+//
+// 为什么不用 s.scripts 直接取：单测里 Service 是 &Service{} 直接构造的，
+// 没走 New() → 字段是 nil → handler 里解引用会 panic。
+// 惰性建同时解决了「New 早于配置目录可用」的次序问题。
+func (s *Service) scriptMgr() *scriptManager {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.scripts == nil {
+		s.scripts = newScriptManager(s)
+	}
+	return s.scripts
+}
+
+/* ─────────────── 持久化 ─────────────── */
+
+func (m *scriptManager) configPath() string {
+	if m.dir == "" {
+		return ""
+	}
+	return filepath.Join(m.dir, "config.json")
+}
+
+func (m *scriptManager) runsPath() string {
+	if m.dir == "" {
+		return ""
+	}
+	return filepath.Join(m.dir, "runs.json")
+}
+
+func (m *scriptManager) logPath(id string) string {
+	if m.dir == "" {
+		return ""
+	}
+	return filepath.Join(m.dir, "logs", id+".log")
+}
+
+// load 读回清单与运行态。
+//
+// 运行态里的 pid 要**探活**：服务重启后脚本进程可能还活着（它是独立进程组，
+// 不随服务端退出），也可能早就被系统收了 —— 不探活就会出现两种胡话：
+// 「明明在跑，界面说已停止」或「早就退了，界面还说在跑」。
+func (m *scriptManager) load() {
+	if p := m.configPath(); p != "" {
+		if b, err := os.ReadFile(p); err == nil && json.Valid(b) {
+			var cfg scriptConfig
+			if json.Unmarshal(b, &cfg) == nil {
+				for i := range cfg.Scripts {
+					def := cfg.Scripts[i]
+					if def.ID == "" {
+						continue
+					}
+					m.defs[def.ID] = &def
+					m.order = append(m.order, def.ID)
+				}
+			}
+		}
+	}
+	if p := m.runsPath(); p != "" {
+		if b, err := os.ReadFile(p); err == nil && json.Valid(b) {
+			var states map[string]ScriptState
+			if json.Unmarshal(b, &states) == nil {
+				for id, st := range states {
+					if _, ok := m.defs[id]; !ok {
+						continue // 定义被删了 → 运行态也作废
+					}
+					if st.State == "running" {
+						if st.PID > 0 && agent.PIDAlive(st.PID) {
+							// 还活着：状态照旧，但服务端已经管不到它的输出了
+							// （管道随旧进程一起没了）。日志从落盘文件补。
+							st.Error = "服务已重启，这个脚本仍在运行；日志从落盘文件读"
+						} else {
+							st.State = "stopped"
+							st.PID = 0
+							st.ExitCode = -1
+						}
+					}
+					m.runs[id] = &scriptRun{state: st, nextSeq: st.LogSeq}
+				}
+			}
+		}
+	}
+}
+
+// saveConfig 落盘脚本清单（原子写：先写临时文件再 rename）。
+func (m *scriptManager) saveConfig() {
+	p := m.configPath()
+	if p == "" {
+		return
+	}
+	cfg := scriptConfig{}
+	for _, id := range m.order {
+		if def, ok := m.defs[id]; ok {
+			cfg.Scripts = append(cfg.Scripts, *def)
+		}
+	}
+	b, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return
+	}
+	tmp := p + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, p)
+}
+
+// saveRuns 落盘运行态。
+func (m *scriptManager) saveRuns() {
+	p := m.runsPath()
+	if p == "" {
+		return
+	}
+	states := map[string]ScriptState{}
+	for id, r := range m.runs {
+		states[id] = r.state
+	}
+	b, err := json.MarshalIndent(states, "", "  ")
+	if err != nil {
+		return
+	}
+	tmp := p + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, p)
+}
+
+/* ─────────────── 清单操作 ─────────────── */
+
+// list 返回清单（定义 + 运行态），按登记顺序。
+func (m *scriptManager) list() []ScriptItem {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	items := make([]ScriptItem, 0, len(m.order))
+	for _, id := range m.order {
+		def, ok := m.defs[id]
+		if !ok {
+			continue
+		}
+		it := ScriptItem{ScriptDef: *def}
+		if r, ok := m.runs[id]; ok {
+			it.State = r.state
+		} else {
+			it.State = ScriptState{State: "stopped", ExitCode: -1}
+		}
+		items = append(items, it)
+	}
+	return items
+}
+
+// get 拿一个脚本条目。
+func (m *scriptManager) get(id string) (ScriptItem, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	def, ok := m.defs[id]
+	if !ok {
+		return ScriptItem{}, false
+	}
+	it := ScriptItem{ScriptDef: *def}
+	if r, ok := m.runs[id]; ok {
+		it.State = r.state
+	} else {
+		it.State = ScriptState{State: "stopped", ExitCode: -1}
+	}
+	return it, true
+}
+
+// add 登记一个新脚本。
+func (m *scriptManager) add(def ScriptDef) (ScriptItem, error) {
+	if err := validateScriptDef(&def); err != nil {
+		return ScriptItem{}, err
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.seq++
+	def.ID = fmt.Sprintf("script-%d-%d", time.Now().UnixNano()/1e6, m.seq)
+	if def.Name == "" {
+		def.Name = scriptBaseName(def.Path)
+	}
+	m.defs[def.ID] = &def
+	m.order = append(m.order, def.ID)
+	m.runs[def.ID] = &scriptRun{state: ScriptState{State: "stopped", ExitCode: -1}}
+	m.saveConfig()
+	return ScriptItem{ScriptDef: def, State: ScriptState{State: "stopped", ExitCode: -1}}, nil
+}
+
+// update 改一个脚本的定义（**不**动运行态）。
+func (m *scriptManager) update(id string, def ScriptDef) (ScriptItem, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	old, ok := m.defs[id]
+	if !ok {
+		return ScriptItem{}, os.ErrNotExist
+	}
+	if err := validateScriptDef(&def); err != nil {
+		return ScriptItem{}, err
+	}
+	def.ID = id
+	if def.Name == "" {
+		def.Name = old.Name
+	}
+	m.defs[id] = &def
+	m.saveConfig()
+	return ScriptItem{ScriptDef: def, State: m.stateLocked(id)}, nil
+}
+
+// remove 删一个脚本。运行中不给删 —— 先让用户停掉。
+func (m *scriptManager) remove(id string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if _, ok := m.defs[id]; !ok {
+		return os.ErrNotExist
+	}
+	if m.stateLocked(id).State == "running" {
+		return errScriptRunning
+	}
+	delete(m.defs, id)
+	delete(m.runs, id)
+	for i, x := range m.order {
+		if x == id {
+			m.order = append(m.order[:i], m.order[i+1:]...)
+			break
+		}
+	}
+	m.saveConfig()
+	m.saveRuns()
+	// 落盘日志也跟着删 —— 界面上写的是「配置与日志都会被删掉」，
+	// 留着文件就是话说了不算（用户删脚本是为了清掉不想留的东西）。
+	// 删不掉不算失败：脚本已经从清单里没了，日志只是残留文件。
+	if p := m.logPath(id); p != "" {
+		_ = os.Remove(p)
+	}
+	return nil
+}
+
+// errScriptRunning 运行中不能删/不能重复起。
+var errScriptRunning = errors.New("这个脚本正在运行，先停止它")
+
+// stateLocked 取运行态（调用方持锁）。
+func (m *scriptManager) stateLocked(id string) ScriptState {
+	if r, ok := m.runs[id]; ok {
+		return r.state
+	}
+	return ScriptState{State: "stopped", ExitCode: -1}
+}
+
+/* ─────────────── 校验 ─────────────── */
+
+// validateScriptDef 校验一个脚本定义。
+//
+// 关键：**路径必须是文件、扩展名在白名单内**。这两条是「客户端不能变成
+// 任意命令执行器」的落地点。
+func validateScriptDef(def *ScriptDef) error {
+	def.Name = strings.TrimSpace(def.Name)
+	def.Path = strings.TrimSpace(def.Path)
+	def.Cwd = strings.TrimSpace(def.Cwd)
+	def.Interpreter = strings.TrimSpace(def.Interpreter)
+	def.Note = strings.TrimSpace(def.Note)
+
+	if def.Name == "" {
+		return errors.New("脚本需要一个名字")
+	}
+	if len([]rune(def.Name)) > scriptMaxNameLen {
+		return fmt.Errorf("名字太长了（上限 %d 字）", scriptMaxNameLen)
+	}
+	if def.Path == "" {
+		return errors.New("脚本需要一个文件路径")
+	}
+	if !filepath.IsAbs(def.Path) {
+		return errors.New("脚本路径要用绝对路径")
+	}
+	ext := strings.ToLower(filepath.Ext(def.Path))
+	if !scriptExtOK[ext] {
+		return fmt.Errorf("不支持的脚本类型 %q（可用：%s）", ext, scriptExtStrings())
+	}
+	st, err := os.Stat(def.Path)
+	if err != nil {
+		return fmt.Errorf("找不到这个脚本文件：%s（%v）", def.Path, err)
+	}
+	if st.IsDir() {
+		return errors.New("这是一个目录，不是脚本文件")
+	}
+	if len(def.Args) > scriptMaxArgs {
+		return fmt.Errorf("参数太多（上限 %d 个）", scriptMaxArgs)
+	}
+	for i, a := range def.Args {
+		if len(a) > scriptMaxArgLen {
+			return fmt.Errorf("第 %d 个参数太长（上限 %d 字节）", i+1, scriptMaxArgLen)
+		}
+	}
+	// 解释器：必须存在且是文件（不校验白名单 —— 它是用户显式指定的可执行文件）。
+	if def.Interpreter != "" {
+		if !filepath.IsAbs(def.Interpreter) {
+			return errors.New("解释器路径要用绝对路径")
+		}
+		ist, err := os.Stat(def.Interpreter)
+		if err != nil {
+			return fmt.Errorf("找不到这个解释器：%s（%v）", def.Interpreter, err)
+		}
+		if ist.IsDir() {
+			return errors.New("解释器是一个目录，不是可执行文件")
+		}
+	}
+	// 环境变量：逐条 "KEY=VALUE"，KEY 要像个环境变量名。
+	if len(def.Env) > scriptMaxEnv {
+		return fmt.Errorf("环境变量太多（上限 %d 条）", scriptMaxEnv)
+	}
+	for i, e := range def.Env {
+		e = strings.TrimSpace(e)
+		if e == "" {
+			continue
+		}
+		k, _, ok := strings.Cut(e, "=")
+		if !ok || strings.TrimSpace(k) == "" {
+			return fmt.Errorf("第 %d 个环境变量不是 KEY=VALUE 的形式：%q", i+1, e)
+		}
+		if strings.ContainsAny(k, " \t\r\n") {
+			return fmt.Errorf("第 %d 个环境变量的名字里有空格：%q", i+1, e)
+		}
+	}
+	return nil
+}
+
+func scriptExtStrings() string {
+	exts := make([]string, 0, len(scriptExtOK))
+	for e := range scriptExtOK {
+		exts = append(exts, e)
+	}
+	// 固定顺序，别让界面上的列表每次刷新都变。
+	sort.Strings(exts)
+	return strings.Join(exts, " ")
+}
+
+// scriptBaseName 取脚本文件名（显示用）。
+//
+// ⚠️ 同时按 '/' 与 '\\' 切：桌面可能是 Windows，路径是 D:\workspace\x.cmd，
+// 只按 '/' 切会得到整条路径（记忆 project_client_path_handling）。
+func scriptBaseName(p string) string {
+	s := strings.ReplaceAll(p, "\\", "/")
+	s = strings.TrimRight(s, "/")
+	if i := strings.LastIndex(s, "/"); i >= 0 {
+		return s[i+1:]
+	}
+	return s
+}
+
+/* ─────────────── 启停 ─────────────── */
+
+// start 启动一个脚本。
+//
+// 流程：spawn 一个**独立进程组**的后台进程 → stdout/stderr 合流 → 逐行进
+// 环形缓冲与落盘文件 → 进程退出时收尾状态。
+//
+// 用独立进程组是为了「停止」能整组带走（unix kill(-pid) / Windows taskkill /T），
+// 不留孤儿 worker。
+func (m *scriptManager) start(id string) (ScriptItem, error) {
+	m.mu.Lock()
+	def, ok := m.defs[id]
+	if !ok {
+		m.mu.Unlock()
+		return ScriptItem{}, os.ErrNotExist
+	}
+	if m.stateLocked(id).State == "running" {
+		m.mu.Unlock()
+		return ScriptItem{}, errScriptRunning
+	}
+	/* 「正在起」也占坑：否则两次并发的 start 会**都**通过上面的检查、
+	   都 spawn 一个进程 —— 界面上一个脚本跑着两份，日志也串在一起。
+	   标记在 spawn **之前**落，失败时撤销。 */
+	if m.starting[id] {
+		m.mu.Unlock()
+		return ScriptItem{}, errScriptRunning
+	}
+	if m.starting == nil {
+		m.starting = map[string]bool{}
+	}
+	m.starting[id] = true
+	// 复制一份定义出来用：解锁后 m.defs 可能被并发改动。
+	cp := *def
+	cp.Args = append([]string(nil), def.Args...)
+	cp.Env = append([]string(nil), def.Env...)
+	m.mu.Unlock()
+
+	defer func() {
+		m.mu.Lock()
+		delete(m.starting, id)
+		m.mu.Unlock()
+	}()
+
+	// 两条路：
+	//   · 有解释器 → `<解释器> <脚本路径> [参数…]`（Python/Node 脚本走这条；
+	//     白名单里没有 .exe，Windows 上 .py 不能直接 exec）。
+	//   · 没解释器 → 直接跑脚本文件（.cmd/.bat/.ps1 在 Windows 上要包
+	//     PowerShell，否则参数会被 cmd.exe 拆坏）。
+	bin, args := cp.Path, cp.Args
+	if cp.Interpreter != "" {
+		bin = cp.Interpreter
+		args = append([]string{cp.Path}, cp.Args...)
+	} else {
+		bin, args = agent.WrapLaunch(cp.Path, cp.Args)
+	}
+
+	cwd := cp.Cwd
+	if cwd == "" {
+		cwd = filepath.Dir(cp.Path)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cmd := exec.CommandContext(ctx, bin, args...)
+	cmd.Dir = cwd
+	// 进程组：停止时整组杀。
+	agent.ConfigureProcGroup(cmd)
+	// 不分配控制台窗口：后台服务本身没有控制台，子进程每起一次都要新建
+	// conhost —— 实测多花 3.1 秒（见 internal/client/corecmd.go）。
+	noConsole(cmd)
+	// 环境：继承但剔除父会话专属项（SERVER__* / CODEBUDDY_* / CLAUDE_* 等），
+	// 再叠加脚本自己要的（PYTHONUNBUFFERED=1 之类）。
+	cmd.Env = agent.ChildEnvWith(cp.Env)
+
+	pr, pw, err := os.Pipe()
+	if err != nil {
+		cancel()
+		return ScriptItem{}, fmt.Errorf("建日志管道失败：%w", err)
+	}
+	cmd.Stdout = pw
+	cmd.Stderr = pw
+	if err := cmd.Start(); err != nil {
+		pw.Close()
+		pr.Close()
+		cancel()
+		return ScriptItem{}, fmt.Errorf("启动 %s 失败：%w", cp.Path, err)
+	}
+	pw.Close()
+	pid := cmd.Process.Pid
+
+	m.mu.Lock()
+	r, ok := m.runs[id]
+	if !ok {
+		m.mu.Unlock()
+		cancel()
+		_ = cmd.Process.Kill()
+		pr.Close()
+		return ScriptItem{}, os.ErrNotExist
+	}
+	r.cmd = cmd
+	r.cancel = cancel
+	r.stopping = false
+	/* 日志序号**跨重启单调递增**（不清零）。
+	   客户端拿着 after=<seq> 断线重连 —— 若序号清零，新行的 seq 会比上次
+	   拿到的 after 还小，客户端按 seq > after 过滤就会**一行都收不到**。
+	   同理不清空 lines：重启后往回翻还能看到上一轮的输出。 */
+	r.state = ScriptState{
+		State:     "running",
+		PID:       pid,
+		ExitCode:  -1,
+		StartedAt: time.Now().UnixMilli(),
+		LogSeq:    r.nextSeq,
+	}
+	m.saveRuns()
+	m.mu.Unlock()
+
+	// 逐行读日志（后台 goroutine，与 HTTP 请求无关 —— 脚本要能一直跑）。
+	go m.drain(id, pr, cmd)
+
+	item, _ := m.get(id)
+	return item, nil
+}
+
+// drain 逐行读脚本输出，喂给环形缓冲与落盘文件；进程退出时收尾。
+func (m *scriptManager) drain(id string, pr *os.File, cmd *exec.Cmd) {
+	defer pr.Close()
+
+	// 落盘文件：完整副本（环形缓冲只留最近几百行）。
+	//
+	// ⚠️ **追加**而不是覆盖：多次运行同一个脚本时，历史输出连成一份，
+	// 用户翻日志能看到「上次跑到哪」。覆盖的话第二次运行就把上次的抹了。
+	var logFile *os.File
+	if p := m.logPath(id); p != "" {
+		if f, err := os.OpenFile(p, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600); err == nil {
+			logFile = f
+			defer logFile.Close()
+		}
+	}
+
+	sc := bufio.NewScanner(pr)
+	sc.Buffer(make([]byte, 0, 64<<10), 1<<20)
+	for sc.Scan() {
+		/* ⚠️ 先按**原始字节**解，再入缓冲。
+		   Windows 上脚本输出的是控制台代码页字节（中文系统 = GBK），
+		   直接当 UTF-8 解会得到一堆乱码（见 scripts_decode_windows.go）。 */
+		line := decodeScriptBytes(sc.Bytes())
+		if logFile != nil {
+			fmt.Fprintln(logFile, line)
+		}
+		m.appendLine(id, line)
+	}
+	if err := sc.Err(); err != nil {
+		m.appendLine(id, "⚠ 读日志出错："+err.Error())
+	}
+
+	// 等进程真正退出，拿退出码。
+	//
+	// ⚠️ Wait 只能调一次 —— stop() 也会想等它退出，两处都 Wait 会 panic
+	//（"exec: Wait was already called"）。所以由**这里**独占地 Wait，
+	// stop() 只负责杀进程，然后等本 goroutine 通过 done 通知收尾。
+	err := cmd.Wait()
+	code := 0
+	if cmd.ProcessState != nil {
+		code = cmd.ProcessState.ExitCode()
+	}
+	if err != nil && code == 0 {
+		code = 1
+	}
+
+	m.mu.Lock()
+	r, ok := m.runs[id]
+	if !ok {
+		m.mu.Unlock()
+		return
+	}
+	// ⚠️ 只有**当前这次运行**退出才收尾 —— 用户可能已经停了它又重起了，
+	// 那时旧 goroutine 的 Wait 返回不该把新一次运行标成结束。
+	if r.cmd == cmd {
+		r.cmd = nil
+		r.cancel = nil
+		if r.state.State == "running" {
+			switch {
+			case r.stopping:
+				// 用户主动停的 → 不是失败。
+				r.state.State = "stopped"
+				r.state.ExitCode = -1
+			case code != 0:
+				r.state.State = "failed"
+				r.state.ExitCode = code
+			default:
+				r.state.State = "done"
+				r.state.ExitCode = code
+			}
+			r.state.EndedAt = time.Now().UnixMilli()
+		}
+		r.stopping = false
+	}
+	m.saveRuns()
+	m.mu.Unlock()
+}
+
+// appendLine 追加一行日志（进环形缓冲 + 更新游标）。
+func (m *scriptManager) appendLine(id, text string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	r, ok := m.runs[id]
+	if !ok {
+		return
+	}
+	r.nextSeq++
+	r.lines = append(r.lines, scriptLine{Seq: r.nextSeq, Text: text})
+	if len(r.lines) > scriptLogRing {
+		r.lines = r.lines[len(r.lines)-scriptLogRing:]
+	}
+	r.state.LogSeq = r.nextSeq
+}
+
+// stop 停止一个脚本（杀整个进程组）。
+func (m *scriptManager) stop(id string) (ScriptItem, error) {
+	m.mu.Lock()
+	r, ok := m.runs[id]
+	if !ok {
+		m.mu.Unlock()
+		return ScriptItem{}, os.ErrNotExist
+	}
+	if r.state.State != "running" || r.cmd == nil {
+		m.mu.Unlock()
+		item, _ := m.get(id) // 没在跑 → 不算错误（幂等）
+		return item, nil
+	}
+	pid := r.state.PID
+	cancel := r.cancel
+	// 标记「用户主动停的」—— drain 收尾时据此把状态记成 stopped 而不是 failed。
+	r.stopping = true
+	m.mu.Unlock()
+
+	// 杀整组：unix 上 kill(-pid, SIGKILL) 带走全部后代，Windows 上
+	// taskkill /T /F 带走整棵进程树。脚本 spawn 出来的 worker 不会变孤儿。
+	if err := agent.KillPID(pid, true); err != nil {
+		m.appendLine(id, "⚠ 停止失败："+err.Error())
+	}
+	if cancel != nil {
+		cancel()
+	}
+	/* 不在这里 Wait —— drain goroutine 才是这次运行的唯一 Wait 者
+	   （两处都 Wait 会 panic："exec: Wait was already called"）。
+	   等一小会儿让状态落定即可：杀完之后 drain 会很快收尾。
+	   状态落定前先返回也没关系 —— drain 会自己把 state 改掉。 */
+	for i := 0; i < 40; i++ {
+		item, _ := m.get(id)
+		if item.State.State != "running" {
+			return item, nil
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
+	item, _ := m.get(id)
+	return item, nil
+}
+
+/* ─────────────── 日志读取 ─────────────── */
+
+// logLines 取 after 之后的日志行。
+//
+// 客户端断线重连时带着 after=<seq> 回来 → 只补新行，不重发旧的。
+func (m *scriptManager) logLines(id string, after int) ([]scriptLine, ScriptState, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if _, ok := m.defs[id]; !ok {
+		return nil, ScriptState{}, false
+	}
+	r, ok := m.runs[id]
+	if !ok {
+		return nil, ScriptState{State: "stopped", ExitCode: -1}, true
+	}
+	out := make([]scriptLine, 0, len(r.lines))
+	for _, l := range r.lines {
+		if l.Seq > after {
+			out = append(out, l)
+		}
+	}
+	return out, r.state, true
+}
+
+/* ─────────────── HTTP ─────────────── */
+
+// handleScripts GET /desk/scripts（清单）/ POST /desk/scripts（新增）。
+func (s *Service) handleScripts(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		writeJSON(w, http.StatusOK, map[string]any{"scripts": s.scriptMgr().list()})
+
+	case http.MethodPost:
+		var def ScriptDef
+		if err := decodeJSONBody(r, &def); err != nil {
+			writeErr(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		item, err := s.scriptMgr().add(def)
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		writeJSON(w, http.StatusOK, item)
+
+	default:
+		writeErr(w, http.StatusMethodNotAllowed, "只支持 GET / POST")
+	}
+}
+
+// handleScriptSub /desk/scripts/{id}[/{action}]。
+//
+// 子动作：PUT（改定义）/ DELETE（删）/ start / stop / log。
+func (s *Service) handleScriptSub(w http.ResponseWriter, r *http.Request) {
+	rest := strings.TrimPrefix(r.URL.Path, "/desk/scripts/")
+	parts := strings.Split(strings.Trim(rest, "/"), "/")
+	if len(parts) == 0 || parts[0] == "" {
+		writeErr(w, http.StatusNotFound, "用法：/desk/scripts/{id}[/{start|stop|log}]")
+		return
+	}
+	id := parts[0]
+	action := ""
+	if len(parts) > 1 {
+		action = parts[1]
+	}
+
+	switch action {
+	case "":
+		switch r.Method {
+		case http.MethodPut:
+			var def ScriptDef
+			if err := decodeJSONBody(r, &def); err != nil {
+				writeErr(w, http.StatusBadRequest, err.Error())
+				return
+			}
+			item, err := s.scriptMgr().update(id, def)
+			if err != nil {
+				writeScriptErr(w, err)
+				return
+			}
+			writeJSON(w, http.StatusOK, item)
+		case http.MethodDelete:
+			if err := s.scriptMgr().remove(id); err != nil {
+				writeScriptErr(w, err)
+				return
+			}
+			writeJSON(w, http.StatusOK, map[string]any{"ok": true})
+		default:
+			writeErr(w, http.StatusMethodNotAllowed, "只支持 PUT / DELETE")
+		}
+
+	case "start":
+		if r.Method != http.MethodPost {
+			writeErr(w, http.StatusMethodNotAllowed, "POST only")
+			return
+		}
+		item, err := s.scriptMgr().start(id)
+		if err != nil {
+			writeScriptErr(w, err)
+			return
+		}
+		writeJSON(w, http.StatusOK, item)
+
+	case "stop":
+		if r.Method != http.MethodPost {
+			writeErr(w, http.StatusMethodNotAllowed, "POST only")
+			return
+		}
+		item, err := s.scriptMgr().stop(id)
+		if err != nil {
+			writeScriptErr(w, err)
+			return
+		}
+		writeJSON(w, http.StatusOK, item)
+
+	case "log":
+		if r.Method != http.MethodGet {
+			writeErr(w, http.StatusMethodNotAllowed, "GET only")
+			return
+		}
+		s.handleScriptLog(w, r, id)
+
+	default:
+		writeErr(w, http.StatusNotFound, "动作只有 start / stop / log")
+	}
+}
+
+// handleScriptLog GET /desk/scripts/{id}/log?after=<seq> → SSE。
+//
+// 事件：event: line（{seq,text}）逐行 / event: state（{state,exitCode}）收尾。
+// after=<seq> 只补之后的行（断线重连用）。
+func (s *Service) handleScriptLog(w http.ResponseWriter, r *http.Request, id string) {
+	after := 0
+	if v := strings.TrimSpace(r.URL.Query().Get("after")); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			after = n
+		}
+	}
+
+	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()
+		}
+	}
+
+	lines, state, ok := s.scriptMgr().logLines(id, after)
+	if !ok {
+		writeErr(w, http.StatusNotFound, "没有这个脚本："+id)
+		return
+	}
+	for _, l := range lines {
+		send("line", l)
+	}
+	send("state", state)
+
+	// 脚本还在跑 → 挂着等新行；跑完了 → 直接收尾（客户端拿到 state 就知道结束了）。
+	// 断连不是「停止脚本」：脚本归用户管，不归这条连接管。
+	for {
+		select {
+		case <-r.Context().Done():
+			return
+		case <-time.After(700 * time.Millisecond):
+		}
+		lines, state, ok := s.scriptMgr().logLines(id, after)
+		if !ok {
+			return
+		}
+		for _, l := range lines {
+			send("line", l)
+			after = l.Seq
+		}
+		if state.State != "running" {
+			send("state", state)
+			return
+		}
+	}
+}
+
+// writeScriptErr 把内部错误映射成合适的 HTTP 码。
+func writeScriptErr(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, os.ErrNotExist):
+		writeErr(w, http.StatusNotFound, err.Error())
+	case errors.Is(err, errScriptRunning):
+		writeErr(w, http.StatusConflict, err.Error())
+	default:
+		writeErr(w, http.StatusBadRequest, err.Error())
+	}
+}
+
+// decodeJSONBody 读一个 JSON 请求体（上限 64KB）。
+func decodeJSONBody(r *http.Request, v any) error {
+	b, err := io.ReadAll(io.LimitReader(r.Body, 1<<16))
+	if err != nil {
+		return fmt.Errorf("读请求体失败：%w", err)
+	}
+	if len(b) == 0 {
+		return errors.New("请求体是空的")
+	}
+	if err := json.Unmarshal(b, v); err != nil {
+		return fmt.Errorf("不是合法的 JSON：%w", err)
+	}
+	return nil
+}