@yufengtadian/freedom-cli 1.12.18 → 1.13.1

package/templates/go/pkg/freedom/backend_proc.go

@@ -3,6 +3,7 @@ package freedom
 import (
 	"bufio"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -27,16 +28,46 @@ import (
 // 壳启动后端进程时注入环境变量：FREEDOM_BACKEND=1、FREEDOM_IPC=stdio，
 // 后端可据此判断自己运行在 Freedom 壳内。
 type ProcBackend struct {
+	command []string // 启动 argv，重启策略据此重建子进程
+	dir     string   // 子进程工作目录（SetDir）；空则继承壳进程当前目录
 	cmd     *exec.Cmd
 	stdin   io.WriteCloser
 	mu      sync.Mutex
+	writeMu sync.Mutex // 串行化 stdin 写入；与 mu 分离，避免大消息阻塞写管道时与 readLoop/Close 形成环形死锁
 	pending map[int64]chan procResp
 	nextID  int64
 	closed  bool
 	onEvent func(event string, data interface{})
 	timeout time.Duration
+	maxLine int // 单条 stdout 行（一次响应）上限字节；超限即那条响应过大，不得中断整个通道
+
+	// —— W4 崩溃自愈（对标 Tauri shell spawn 的失败处理 / sidecar 重启）——
+	rp        RestartPolicy   // 重启策略（零值=不重启，保持旧行为）
+	gen       int             // 每次拉起递增；readLoop 据此识别"自己那一期"，过期实例不触发重启
+	pdone     chan struct{}   // 当前这期进程 Wait 完成后由 readLoop 关闭（Close 等它，不再自己 Wait，避免双重 Wait）
+	attempts  int             // 连续崩溃重启计数
+	startedAt time.Time       // 本期进程启动时刻（存活够久则重置 attempts）
+}
+
+// RestartPolicy 是后端进程崩溃后的自动重启策略（经 SetRestartPolicy 启用）。
+// 非零退出/被信号杀视为崩溃；退出码 0 视为后端主动结束，不重启。
+type RestartPolicy struct {
+	// MaxRetries 是"连续崩溃"允许的最大重启次数；0 表示禁用重启。
+	MaxRetries int
+	// Backoff 是首次重启前的等待时间，其后按 2 倍指数退避，封顶 30s。
+	// <=0 时取默认 250ms。
+	Backoff time.Duration
+	// ResetAfter 是进程存活超过该时长后清零连续崩溃计数（默认 60s），
+	// 让"运行几小时后崩一次"不被历史崩溃拖入重启耗尽。
+	ResetAfter time.Duration
 }
 
+const (
+	defaultRestartBackoff    = 250 * time.Millisecond
+	defaultRestartResetAfter = 60 * time.Second
+	maxRestartBackoff        = 30 * time.Second
+)
+
 // procResp 是一次调用在壳侧的等待结果。
 type procResp struct {
 	result json.RawMessage
@@ -61,31 +92,64 @@ func NewProcBackend(command ...string) *ProcBackend {
 	if len(command) == 0 {
 		panic("freedom: NewProcBackend requires at least one command argument")
 	}
-	cmd := exec.Command(command[0], command[1:]...)
-	hideWindow(cmd) // Windows 下隐藏后端的 cmd 黑窗（跨平台空实现）
 	return &ProcBackend{
-		cmd:     cmd,
+		command: command,
 		pending: map[int64]chan procResp{},
 		timeout: 60 * time.Second,
+		maxLine: 16 * 1024 * 1024, // 默认单条响应上限 16MB（见 SetMaxLine）
 	}
 }
 
-// SetDir 设置后端进程的工作目录。
-// 相对路径参数（如 "backend/main.mjs"）将相对该目录解析。
-// 通用壳在加载 resources/config.json 时自动设为 resources 目录。
+// SetDir 设置后端子进程的工作目录（链式返回自身）。通用壳用它把后端 CWD 定到
+// resources/，使 config.json 里的相对路径参数按 resources/ 解析。
 func (p *ProcBackend) SetDir(dir string) *ProcBackend {
-	if dir != "" {
-		p.cmd.Dir = dir
+	p.dir = dir
+	return p
+}
+
+// SetRestartPolicy 启用后端进程崩溃自动重启（默认关闭）。
+// 崩溃时向壳广播事件 "backend.crashed" {code, attempt, restarting}，
+// 重启成功拉起后广播 "backend.restarted" {attempt}。
+func (p *ProcBackend) SetRestartPolicy(rp RestartPolicy) *ProcBackend {
+	if rp.Backoff <= 0 {
+		rp.Backoff = defaultRestartBackoff
+	}
+	if rp.ResetAfter <= 0 {
+		rp.ResetAfter = defaultRestartResetAfter
 	}
+	p.mu.Lock()
+	p.rp = rp
+	p.mu.Unlock()
 	return p
 }
 
 // SetTimeout 设置单次调用的最大等待时间（默认 60s）。<=0 表示不超时。
 func (p *ProcBackend) SetTimeout(d time.Duration) *ProcBackend {
+	p.mu.Lock()
 	p.timeout = d
+	p.mu.Unlock()
 	return p
 }
 
+// SetMaxLine 设置单条后端响应（stdout 行）的字节上限（默认 16MB）。
+// 超过上限的单条响应会被判为"行过大"：仅该条调用收到错误，随后继续读取后续行，
+// 不会像旧实现那样把 bufio.ErrTooLong 误判为"进程退出"而打崩整个 IPC 通道。
+func (p *ProcBackend) SetMaxLine(n int) *ProcBackend {
+	if n > 0 {
+		p.mu.Lock()
+		p.maxLine = n
+		p.mu.Unlock()
+	}
+	return p
+}
+
+// getMaxLine 读取行上限配置（readLoop 每行读取，与 SetMaxLine 并发）。
+func (p *ProcBackend) getMaxLine() int {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.maxLine
+}
+
 // OnEvent 注册后端进程推送事件时的回调（由框架在 Run 时注入）。
 func (p *ProcBackend) OnEvent(fn func(event string, data interface{})) {
 	p.mu.Lock()
@@ -98,26 +162,42 @@ func (p *ProcBackend) start() error {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 	if p.closed {
-		return fmt.Errorf("freedom: proc backend is closed")
+		// closed 后再 start 会拉起一个永远无人 Wait/Kill 的孤儿子进程，必须拒绝。
+		return fmt.Errorf("freedom: proc backend already closed")
 	}
 	if p.stdin != nil {
 		return nil // 已启动
 	}
-	p.cmd.Env = append(os.Environ(), "FREEDOM_BACKEND=1", "FREEDOM_IPC=stdio")
-	p.cmd.Stderr = os.Stderr // 后端 stderr 日志原样转发
-	stdin, err := p.cmd.StdinPipe()
+	return p.launchLocked()
+}
+
+// launchLocked 按 command 重建子进程并启动 readLoop。崩溃重启与首次启动共用。
+// 调用方须持有 p.mu。
+func (p *ProcBackend) launchLocked() error {
+	cmd := exec.Command(p.command[0], p.command[1:]...)
+	if p.dir != "" {
+		cmd.Dir = p.dir // 相对路径参数（backend/main.mjs）据此目录解析
+	}
+	hideWindow(cmd) // Windows 下隐藏后端进程的 cmd 黑窗（跨平台空实现）
+	cmd.Env = append(os.Environ(), "FREEDOM_BACKEND=1", "FREEDOM_IPC=stdio")
+	cmd.Stderr = os.Stderr // 后端 stderr 日志原样转发
+	stdin, err := cmd.StdinPipe()
 	if err != nil {
 		return fmt.Errorf("freedom: proc backend stdin pipe: %w", err)
 	}
-	stdout, err := p.cmd.StdoutPipe()
+	stdout, err := cmd.StdoutPipe()
 	if err != nil {
 		return fmt.Errorf("freedom: proc backend stdout pipe: %w", err)
 	}
-	if err := p.cmd.Start(); err != nil {
-		return fmt.Errorf("freedom: proc backend start %q: %w", p.cmd.Path, err)
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("freedom: proc backend start %q: %w", cmd.Path, err)
 	}
+	p.cmd = cmd
 	p.stdin = stdin
-	go p.readLoop(stdout)
+	p.gen++
+	p.pdone = make(chan struct{})
+	p.startedAt = time.Now()
+	go p.readLoop(p.gen, stdout, cmd, p.pdone)
 	return nil
 }
 
@@ -137,23 +217,33 @@ func (p *ProcBackend) Handle(method string, params []json.RawMessage) (interface
 	id := p.nextID
 	ch := make(chan procResp, 1)
 	p.pending[id] = ch
-	w := p.stdin // 锁内取引用，锁外写，避免持锁阻塞（后端不消费 stdin 时 Write 可能挂起）
-	p.mu.Unlock()
-
 	msg := procMessage{ID: id, Method: method, Params: paramsJSON}
 	line, _ := json.Marshal(msg)
-	if _, err := w.Write(append(line, '\n')); err != nil {
+	stdin := p.stdin
+	timeout := p.timeout // 在锁内快照，SetTimeout 并发改值不影响本次调用
+	p.mu.Unlock()
+
+	// 写管道不持 mu：大消息阻塞在 Write 时，readLoop/Close 仍可拿锁推进，
+	// 超时唤醒路径也不会被卡死（写失败由下方 cancel 兜底唤醒）。
+	p.writeMu.Lock()
+	_, err = stdin.Write(append(line, '\n'))
+	p.writeMu.Unlock()
+
+	if err != nil {
 		p.cancel(id, fmt.Errorf("freedom: proc backend write: %w", err))
 		return nil, err
 	}
 
 	var resp procResp
-	if p.timeout > 0 {
+	if timeout > 0 {
+		// NewTimer 便于超时后 Stop 释放；time.After 的 timer 会滞留到期才回收。
+		timer := time.NewTimer(timeout)
+		defer timer.Stop()
 		select {
 		case resp = <-ch:
-		case <-time.After(p.timeout):
-			p.cancel(id, fmt.Errorf("freedom: proc backend: method %q timed out after %s", method, p.timeout))
-			return nil, fmt.Errorf("freedom: proc backend: method %q timed out after %s", method, p.timeout)
+		case <-timer.C:
+			p.cancel(id, fmt.Errorf("freedom: proc backend: method %q timed out after %s", method, timeout))
+			return nil, fmt.Errorf("freedom: proc backend: method %q timed out after %s", method, timeout)
 		}
 	} else {
 		resp = <-ch
@@ -182,22 +272,31 @@ func (p *ProcBackend) cancel(id int64, err error) {
 }
 
 // readLoop 持续读取后端 stdout，解析协议消息并分发。
-func (p *ProcBackend) readLoop(stdout io.Reader) {
-	sc := bufio.NewScanner(stdout)
-	sc.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
-	for sc.Scan() {
-		var msg procMessage
-		if err := json.Unmarshal(sc.Bytes(), &msg); err != nil {
-			fmt.Fprintf(os.Stderr, "freedom: proc backend: bad message: %v\n", err)
-			continue
+//
+// 行切分用受限读取 readLimitedLine（而非 ReadBytes/Scanner）：
+// ReadBytes 对无换行的巨量输出会不设上限地攒进内存；Scanner 超限后永久罢工。
+// 某条响应超限时仅丢弃该条并留痕，随后继续读后续行，
+// 绝不因单条大消息而中断整个 IPC 通道。
+func (p *ProcBackend) readLoop(gen int, stdout io.Reader, cmd *exec.Cmd, done chan struct{}) {
+	rd := bufio.NewReaderSize(stdout, 64*1024)
+	for {
+		limit := p.getMaxLine()
+		line, dropped, readErr := readLimitedLine(rd, limit)
+		if dropped {
+			fmt.Fprintf(os.Stderr, "freedom: proc backend: line too large (> maxLine %d), dropped\n", limit)
+		} else if len(line) > 0 {
+			p.dispatchLine(line)
 		}
-		if msg.Event != "" {
-			p.dispatchEvent(msg.Event, msg.Data)
-			continue
+		if readErr != nil {
+			if readErr == io.EOF {
+				// 正常结束：后端进程关闭了 stdout。
+			} else {
+				fmt.Fprintf(os.Stderr, "freedom: proc backend: read stdout: %v\n", readErr)
+			}
+			break
 		}
-		p.finish(msg)
 	}
-	// 后端进程已退出：唤醒所有仍等待中的调用。
+	// 后端进程已退出（或 stdout 不可读）：唤醒所有仍等待中的调用。
 	err := fmt.Errorf("freedom: proc backend exited unexpectedly")
 	p.mu.Lock()
 	for id, ch := range p.pending {
@@ -205,6 +304,140 @@ func (p *ProcBackend) readLoop(stdout io.Reader) {
 		ch <- procResp{err: err}
 	}
 	p.mu.Unlock()
+
+	if cmd == nil {
+		// 无真实子进程（协议层单测直接注入坏 reader）：唤醒 pending 即使命完成。
+		return
+	}
+	waitErr := cmd.Wait() // stdout 已 EOF，Wait 安全（见 os/exec StdoutPipe 约定）
+	if done != nil {
+		close(done) // 通知 Close()：本期进程已回收
+	}
+
+	p.mu.Lock()
+	if p.closed || p.gen != gen {
+		// 已 Close 或这是被重启淘汰的过期实例：不做崩溃处理。
+		p.mu.Unlock()
+		return
+	}
+	p.stdin = nil
+	p.cmd = nil
+	if p.rp.MaxRetries <= 0 {
+		p.mu.Unlock()
+		return
+	}
+	if waitErr == nil {
+		// 退出码 0：后端主动正常结束，不算崩溃、不重启（防退出型后端被无限拉起）。
+		p.mu.Unlock()
+		p.notifyFrontend("backend.exited", map[string]interface{}{"code": 0})
+		return
+	}
+	if time.Since(p.startedAt) >= p.rp.ResetAfter {
+		p.attempts = 0
+	}
+	p.attempts++
+	attempt := p.attempts
+	maxR := p.rp.MaxRetries
+	backoff := p.rp.Backoff << (attempt - 1)
+	if backoff > maxRestartBackoff || backoff <= 0 {
+		backoff = maxRestartBackoff
+	}
+	restarting := attempt <= maxR
+	p.mu.Unlock()
+
+	exitCode := -1
+	var ee *exec.ExitError
+	if errors.As(waitErr, &ee) {
+		exitCode = ee.ExitCode()
+	}
+	p.notifyFrontend("backend.crashed", map[string]interface{}{
+		"code": exitCode, "attempt": attempt, "restarting": restarting,
+	})
+	if !restarting {
+		return
+	}
+	time.AfterFunc(backoff, func() {
+		p.mu.Lock()
+		if p.closed || p.stdin != nil {
+			p.mu.Unlock()
+			return
+		}
+		launchErr := p.launchLocked()
+		p.mu.Unlock()
+		if launchErr != nil {
+			fmt.Fprintf(os.Stderr, "freedom: proc backend restart failed: %v\n", launchErr)
+			p.notifyFrontend("backend.crashed", map[string]interface{}{
+				"code": exitCode, "attempt": attempt, "restarting": false, "error": launchErr.Error(),
+			})
+			return
+		}
+		p.notifyFrontend("backend.restarted", map[string]interface{}{"attempt": attempt})
+	})
+}
+
+// notifyFrontend 经 onEvent 回调把框架级事件（backend.crashed 等）转发给壳（App.Emit）。
+func (p *ProcBackend) notifyFrontend(event string, data interface{}) {
+	p.mu.Lock()
+	fn := p.onEvent
+	p.mu.Unlock()
+	if fn != nil {
+		fn(event, data)
+	}
+}
+
+// readLimitedLine 读取一行（'\n' 结尾、返回时去掉换行）。
+// limit>0 时最多保留 limit 字节：超长行整体丢弃（dropped=true），
+// 内存占用有界——后端失控狂吐无换行数据时不会拖垮壳。
+// 返回的 err 为底层读取错误（行尾EOF时携带最后一行残余）。
+func readLimitedLine(rd *bufio.Reader, limit int) (line []byte, dropped bool, err error) {
+	var buf []byte
+	for {
+		chunk, e := rd.ReadSlice('\n')
+		if !dropped {
+			if limit > 0 && len(buf)+len(chunk) > limit {
+				dropped = true
+				buf = nil // 超限时不再保留内容，只消费到行尾
+			} else {
+				buf = append(buf, chunk...) // ReadSlice 的切片下次读会失效，必须复制
+			}
+		}
+		if e == nil {
+			break // 完整行到手
+		}
+		if e == bufio.ErrBufferFull {
+			continue // 行还没读完
+		}
+		err = e
+		break
+	}
+	if dropped {
+		return nil, true, err
+	}
+	if n := len(buf); n > 0 && buf[n-1] == '\n' {
+		buf = buf[:n-1]
+	}
+	return buf, false, err
+}
+
+// dispatchLine 处理一条（已去换行的）stdout 行。
+// 行字节上限由 readLimitedLine 在读侧守卫：超限行整体丢弃并留痕，
+// 后续行照常处理——单条大消息不会级联打崩其它在途调用。
+// 注意：超限行若恰好是某次调用的响应，该调用由 Handle 侧超时兜底。
+func (p *ProcBackend) dispatchLine(line []byte) {
+	// 空行：协议无意义，跳过。
+	if len(line) == 0 {
+		return
+	}
+	var msg procMessage
+	if err := json.Unmarshal(line, &msg); err != nil {
+		fmt.Fprintf(os.Stderr, "freedom: proc backend: bad message: %v\n", err)
+		return
+	}
+	if msg.Event != "" {
+		p.dispatchEvent(msg.Event, msg.Data)
+		return
+	}
+	p.finish(msg)
 }
 
 func (p *ProcBackend) finish(msg procMessage) {
@@ -225,22 +458,21 @@ func (p *ProcBackend) finish(msg procMessage) {
 func (p *ProcBackend) dispatchEvent(event string, dataJSON json.RawMessage) {
 	var data interface{}
 	if len(dataJSON) > 0 {
-		_ = json.Unmarshal(dataJSON, &data)
+		if err := json.Unmarshal(dataJSON, &data); err != nil {
+			// 非 JSON 事件负载降级为原始字符串，保留信息而非静默丢弃。
+			data = string(dataJSON)
+		}
 	}
 	p.mu.Lock()
 	fn := p.onEvent
 	p.mu.Unlock()
 	if fn != nil {
-		// 事件回调在 readLoop goroutine 执行；内部若 panic（如推送期间窗口已销毁）
-		// 一旦外泄到 readLoop 会崩掉整个壳进程，此处统一兜底。
-		func() {
-			defer func() { _ = recover() }()
-			fn(event, data)
-		}()
+		fn(event, data)
 	}
 }
 
 // Close 终止后端进程。先关闭 stdin 通知其优雅退出，超时则强杀。线程安全。
+// 进程回收（Wait）统一由 readLoop 负责，Close 只等它的 done 信号，避免双重 Wait。
 func (p *ProcBackend) Close() error {
 	p.mu.Lock()
 	if p.closed {
@@ -249,24 +481,30 @@ func (p *ProcBackend) Close() error {
 	}
 	p.closed = true
 	cmd := p.cmd
-	if p.stdin != nil {
-		_ = p.stdin.Close() // stdin EOF，后端可自行退出
+	stdin := p.stdin
+	done := p.pdone
+	if stdin != nil {
+		if err := stdin.Close(); err != nil && !errors.Is(err, os.ErrClosed) {
+			fmt.Fprintf(os.Stderr, "freedom: close backend stdin: %v\n", err)
+		}
 	}
 	p.mu.Unlock()
 
-	done := make(chan struct{})
-	go func() { _ = cmd.Wait(); close(done) }()
+	if done == nil {
+		return nil // 从未成功启动过，没有子进程需要回收
+	}
 	select {
 	case <-done:
 	case <-time.After(3 * time.Second):
-		if cmd.Process != nil {
-			_ = cmd.Process.Kill()
-			// M2：Kill 后进程仍可能不退出（僵死/句柄被占用/权限拒绝），
-			// 再等一小段，仍不退则放弃等待，避免 Close 永久阻塞壳退出。
+		if cmd != nil && cmd.Process != nil {
+			if err := cmd.Process.Kill(); err != nil && !errors.Is(err, os.ErrProcessDone) {
+				fmt.Fprintf(os.Stderr, "freedom: backend kill: %v\n", err)
+			}
+			// Kill 也可能失败（权限等），等待必须有上限，否则 Close 永久阻塞。
 			select {
 			case <-done:
 			case <-time.After(time.Second):
-				fmt.Fprintf(os.Stderr, "freedom: proc backend: process did not exit after kill\n")
+				fmt.Fprintf(os.Stderr, "freedom: backend: process did not exit after kill\n")
 			}
 		}
 	}

package/templates/go/pkg/freedom/bridge.go

@@ -109,7 +109,7 @@ func collectResults(res []reflect.Value) (interface{}, error) {
 		return nil, nil
 	case 1:
 		if res[0].Type().Implements(errorType) {
-			if !res[0].IsNil() {
+			if !isNilValue(res[0]) {
 				return nil, res[0].Interface().(error)
 			}
 			return nil, nil
@@ -119,7 +119,7 @@ func collectResults(res []reflect.Value) (interface{}, error) {
 		if !res[1].Type().Implements(errorType) {
 			return nil, fmt.Errorf("freedom: second return value must be error")
 		}
-		if !res[1].IsNil() {
+		if !isNilValue(res[1]) {
 			return res[0].Interface(), res[1].Interface().(error)
 		}
 		return res[0].Interface(), nil
@@ -127,3 +127,14 @@ func collectResults(res []reflect.Value) (interface{}, error) {
 		return nil, fmt.Errorf("freedom: function may return at most a value and an error")
 	}
 }
+
+// isNilValue 判空。绑定函数可返回实现了 error 接口的值类型
+// （如带 Error() 方法的 struct），对这类 Kind 调 reflect.Value.IsNil 会 panic。
+func isNilValue(v reflect.Value) bool {
+	switch v.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface,
+		reflect.Map, reflect.Ptr, reflect.Slice, reflect.UnsafePointer:
+		return v.IsNil()
+	}
+	return false
+}

package/templates/go/pkg/freedom/capability.go

@@ -0,0 +1,77 @@
+package freedom
+
+// M3 声明式能力模型（对标 Tauri capabilities）：对前端 sys/tray/window 三桥的
+// 可调用面做白/黑名单收口。语义：
+//   - Config.Capabilities == nil（默认）：全开，兼容既有应用。
+//   - Deny 命中 → 拒绝（优先于 Allow）。
+//   - Allow 非空且无一命中 → 拒绝。
+// 模式用 path.Match 语法（* / ?；"*" 全放开）；模式非法按不命中处理。
+// 判定发生在派发进平台层之前，拒绝路径零副作用；错误串统一以
+// "freedom: capability denied" 开头供前端识别。
+
+import (
+	"fmt"
+	"path"
+)
+
+// Capabilities 是前端桥接面的声明式收口配置。
+type Capabilities struct {
+	// Allow 非空时为白名单：仅命中项可调用。
+	Allow []string
+	// Deny 黑名单：命中即拒绝，优先于 Allow。
+	Deny []string
+}
+
+// capCheck 按全名判定一次调用是否放行。三桥的名字域：
+// sys 用方法原名（"clipboard.read"、"dialog.open"…），tray 用 "tray.*"/"menu.*"，
+// window 动作经 capCheckWindow 补 "window." 前缀——与 sys 里的 window.monitors /
+// window.backdrop 等同名前缀方法共享名字域，"window.*" 一条即可整族收口。
+func (a *App) capCheck(full string) error {
+	c := a.cfg.Capabilities
+	if c == nil {
+		return nil
+	}
+	for _, p := range c.Deny {
+		if matchCap(p, full) {
+			return capDenied(full)
+		}
+	}
+	if len(c.Allow) == 0 {
+		return nil
+	}
+	for _, p := range c.Allow {
+		if matchCap(p, full) {
+			return nil
+		}
+	}
+	return capDenied(full)
+}
+
+// capCheckWindow 判定窗口桥动作（action 补 window. 前缀后进名字域）。
+func (a *App) capCheckWindow(action string) error {
+	return a.capCheck("window." + action)
+}
+
+func matchCap(pattern, name string) bool {
+	ok, err := path.Match(pattern, name)
+	return err == nil && ok
+}
+
+func capDenied(name string) error {
+	return fmt.Errorf("freedom: capability denied: %q", name)
+}
+
+// sysCapGated / trayGated 是 __freedom_sys / __freedom_tray 的带闸绑定入口。
+func (a *App) sysCapGated(method, paramsJSON string) (interface{}, error) {
+	if err := a.capCheck(method); err != nil {
+		return nil, err
+	}
+	return a.sysCapCall(method, paramsJSON)
+}
+
+func (a *App) trayGated(method, paramsJSON string) (interface{}, error) {
+	if err := a.capCheck(method); err != nil {
+		return nil, err
+	}
+	return a.trayCall(method, paramsJSON)
+}

package/templates/go/pkg/freedom/center_other.go

@@ -5,3 +5,6 @@ package freedom
 // applyCenter 在 macOS / Linux 下保持空实现：窗口初始位置由窗口管理器决定，
 // 如需精确居中可在目标平台扩展（macOS 用 NSWindow center，Linux 用 Gtk 定位）。
 func (a *App) applyCenter() {}
+
+// centerHWND 非 Windows 平台空实现（M2 次级窗口居中，与 applyCenter 同语义）。
+func (a *App) centerHWND(hwnd uintptr) {}