magic-agent 2.4.3 → 2.6.3

package/internal/client/feishu.go

@@ -0,0 +1,1259 @@
+package client
+
+/* 飞书推送（2026-10-26 用户：「另增加飞书绑定支持登录后推送通知」）。
+ *
+ * 要解决的问题：手机端的系统通知只在 App 在前台轮询时才会响（见 index.html 的
+ * pollOnce）—— 锁屏 / 切到后台 / 离开 Wi-Fi 就什么都收不到。飞书推送把**桌面端**
+ * 变成推送源：桌面端在任务出结果、需要人确认的时候，用飞书机器人往用户自己的飞书
+ * 推一条卡片。用户在飞书里就能知道「哪条任务跑完了、问的什么、该去点什么」。
+ *
+ * 分两步，跟「登录」这件事对齐：
+ *   POST /desk/feishu/code      → 发一个 6 位绑定码（10 分钟有效），手机端显示出来；
+ *   POST /desk/feishu/bind      → {code, open_id} 绑定（手机端从绑定的飞书桌面端/应用里
+ *                                 取 open_id，见 index.html openFeishuBind）。
+ * 绑定成功后**只推给这个 open_id**，不是推给一个群 —— 推送是「我的通知」，不是广播。
+ *
+ * 凭据：飞书自建应用的 APP_ID / APP_SECRET 属于部署方的敏感信息，**不收进移动端**。
+ * 桌面端按以下顺序找：
+ *   ① 环境变量 MAGIC_FEISHU_APP_ID / MAGIC_FEISHU_APP_SECRET
+ *   ② ~/.magic-agent/feishu.json             （{"app_id":"…","app_secret":"…"}，0600）
+ *   ③ config.json 的 feishu.app_id / feishu.app_secret
+ *   ④ 本机已登录的 lark-cli（`lark-cli config show --json` 拿 appId）**不做**——
+ *      那是用户自己的开发者身份，借来发「任务完成」有冒用风险。
+ * 都没有时 GET /desk/feishu/status 回 configured=false，移动端把 App ID/Secret 的录入框
+ * 亮出来（POST /desk/feishu/config，只写本机 0600 文件，不回显 secret）。
+ *
+ * 推送事件（**幂等**）：手机端在 /desk/sessions 看到一轮结束 / 等待确认时调
+ * POST /desk/feishu/push {event, ask_id}。ask_id 是这一轮的稳定身份，重复调用只推一次
+ * （手机轮询会重入、多台手机各自轮询，不做去重就会刷屏）。服务端发送失败按退避重试
+ * （最多 3 次），最终失败只记在最近的推送记录里，**不吞掉**。
+ *
+ * 飞书接口：
+ *   POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
+ *   POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id
+ * 两者都用官方直连，不经过 /b/ 中转（这是服务端自己的出站请求）。
+ */
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"math/big"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	feishuCodeTTL        = 10 * time.Minute
+	feishuTokenAhead     = 2 * time.Minute // 租户令牌提前这么久换新
+	feishuSendAttempts   = 3
+	feishuRetryBackoff   = 800 * time.Millisecond
+	feishuRecentKeep     = 20
+	feishuHTTPTimeout    = 10 * time.Second
+	feishuMaxPushTextLen = 800
+)
+
+// 推送事件：result / confirm 与手机端 pollOnce 里的通知种类一一对应；
+// startup 是服务启动自己的通知（见 NotifyStartup），没有对应的手机端轮询种类。
+var feishuEvents = map[string]struct {
+	title string
+	tag   string
+}{
+	"result":  {"任务完成", "green"},
+	"confirm": {"任务待确认", "orange"},
+	"startup": {"服务已重启", "blue"},
+}
+
+// feishuState 落盘形状（~/.magic-agent/feishu-notify.json）。
+// 特意与 mobile-prefs.json 分开：那份是「设备偏好」，这份含凭据与个人 open_id，
+// 权限、备份范围都不一样。
+type feishuState struct {
+	AppID     string `json:"app_id,omitempty"`
+	AppSecret string `json:"app_secret,omitempty"`
+	/* 推给谁。2026-10-26 用户报「填了 ou_me 也能绑上、然后一条都推不出去」之后改的：
+	   open_id **是应用维度的**（同一个人在不同应用下 open_id 不同），而且飞书客户端
+	   根本不显示它 —— 让用户手抄 open_id 等于让他猜。所以绑定改成「邮箱也行」：
+	     ReceiveType = email    → 收件人是飞书账号邮箱（im/v1/messages 原生支持）
+	     ReceiveType = open_id  → 老路子，手里真有 open_id 的人照旧能用
+	     ReceiveType = chat_id  → 推到某个群（oc_ 开头）
+	   ReceiveID 为空时回落到 OpenID（老状态文件兼容，见 target()）。 */
+	/* 群自定义机器人 webhook（2026-10-26 用户：「为什么需要邮箱啊」）。
+	   这才是「把消息推到我的飞书」最省事的路：群里加一个「自定义机器人」拿一条地址，
+	   不用建应用、不用审批、不用知道 open_id / 邮箱 —— 收件人就是那个群。
+	   配了它就走它（优先级高于应用凭据）。 */
+	Webhook       string          `json:"webhook,omitempty"`
+	WebhookSecret string          `json:"webhook_secret,omitempty"`
+	ReceiveID     string          `json:"receive_id,omitempty"`
+	ReceiveType   string          `json:"receive_type,omitempty"`
+	OpenID        string          `json:"open_id,omitempty"`
+	BoundAt       time.Time       `json:"bound_at,omitempty"`
+	Enabled       bool            `json:"enabled"`
+	Code          string          `json:"code,omitempty"`
+	CodeAt        time.Time       `json:"code_at,omitempty"`
+	Recent        []feishuPushLog `json:"recent,omitempty"`
+}
+
+// target 推给谁 + 用哪种 id 解释它。老状态文件只有 open_id → 按 open_id 用。
+func (st feishuState) target() (string, string) {
+	if st.ReceiveID != "" {
+		t := st.ReceiveType
+		if t == "" {
+			t = "open_id"
+		}
+		return st.ReceiveID, t
+	}
+	if st.OpenID != "" {
+		return st.OpenID, "open_id"
+	}
+	return "", ""
+}
+
+// feishuPushLog 最近一次推送的结果（排障用：用户报「没收到」时看这里）。
+// Link 记下这条卡片实际发出去的地址 —— 「地址打不开」时第一件事就是看
+// 当时推的是公网还是局域网、是不是上一轮隧道的域名。
+type feishuPushLog struct {
+	At      time.Time `json:"at"`
+	Event   string    `json:"event"`
+	AskID   string    `json:"ask_id"`
+	Title   string    `json:"title"`
+	Link    string    `json:"link,omitempty"`
+	OK      bool      `json:"ok"`
+	Attempt int       `json:"attempt"`
+	Error   string    `json:"error,omitempty"`
+}
+
+// feishuNotifier 单例（进程内），由 Service.feishu() 惰性建。
+type feishuNotifier struct {
+	mu   sync.RWMutex
+	path string
+
+	token     string
+	tokenExp  time.Time
+	tokenBase string // 令牌对应的 app（换 app 就作废）
+
+	sent   map[string]time.Time // event|ask_id → 首次受理时间（幂等去重）
+	client *http.Client
+
+	baseURL string // 测试可改；空 = 官方
+}
+
+func feishuStatePath() string {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".magic-agent", "feishu-notify.json")
+}
+
+// Service.feishu 惰性建推送器（与其它 hub 一个套路：请求路径上不建）。
+func (s *Service) feishu() *feishuNotifier {
+	s.feishuOnce.Do(func() {
+		if s.feishuN == nil {
+			s.feishuN = &feishuNotifier{}
+		}
+		n := s.feishuN
+		if n.path == "" {
+			n.path = feishuStatePath()
+		}
+		if n.sent == nil {
+			n.sent = map[string]time.Time{}
+		}
+		if n.client == nil {
+			n.client = &http.Client{Timeout: feishuHTTPTimeout}
+		}
+	})
+	return s.feishuN
+}
+
+func (n *feishuNotifier) load() (feishuState, error) {
+	var st feishuState
+	if n.path == "" {
+		return st, errors.New("找不到用户目录")
+	}
+	b, err := os.ReadFile(n.path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return st, nil
+		}
+		return st, err
+	}
+	if len(bytes.TrimSpace(b)) == 0 {
+		return st, nil
+	}
+	if err := json.Unmarshal(b, &st); err != nil {
+		return feishuState{}, fmt.Errorf("飞书配置损坏（%s）：%v", n.path, err)
+	}
+	return st, nil
+}
+
+func (n *feishuNotifier) save(st feishuState) error {
+	if n.path == "" {
+		return errors.New("找不到用户目录")
+	}
+	if err := os.MkdirAll(filepath.Dir(n.path), 0o755); err != nil {
+		return err
+	}
+	b, err := json.MarshalIndent(st, "", "  ")
+	if err != nil {
+		return err
+	}
+	tmp := n.path + ".tmp"
+	// 0600：里面有 app_secret 与个人 open_id。
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, n.path)
+}
+
+/* 凭据判定。环境变量名与 internal/config 的 EnvFeishu* 保持一致；
+   这里只读不写（写由移动端的 /desk/feishu/config 负责，落本机 0600 文件）。 */
+
+func envCreds() (string, string) {
+	return strings.TrimSpace(os.Getenv("MAGIC_AGENT_FEISHU_APP_ID")),
+		strings.TrimSpace(os.Getenv("MAGIC_AGENT_FEISHU_APP_SECRET"))
+}
+
+// credsOf 判定凭据：本机文件 > 环境变量 > config.json（Options 传进来）。
+// 返回 (appID, appSecret, 来源说明)。来源只用于界面展示，secret 永远不回显。
+func (s *Service) credsOf(st feishuState) (string, string, string) {
+	if st.AppID != "" && st.AppSecret != "" {
+		return st.AppID, st.AppSecret, "本机配置"
+	}
+	if id, sec := envCreds(); id != "" && sec != "" {
+		return id, sec, "环境变量"
+	}
+	if s.opts.FeishuAppID != "" && s.opts.FeishuAppSecret != "" {
+		return s.opts.FeishuAppID, s.opts.FeishuAppSecret, "config.json"
+	}
+	return "", "", ""
+}
+
+/* ─────────────── 飞书 API ─────────────── */
+
+func (n *feishuNotifier) apiBase() string {
+	if n.baseURL != "" {
+		return strings.TrimRight(n.baseURL, "/")
+	}
+	return "https://open.feishu.cn"
+}
+
+func (n *feishuNotifier) post(ctx context.Context, path string, body any, bearer string) ([]byte, error) {
+	b, err := json.Marshal(body)
+	if err != nil {
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, n.apiBase()+path, bytes.NewReader(b))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json; charset=utf-8")
+	if bearer != "" {
+		req.Header.Set("Authorization", "Bearer "+bearer)
+	}
+	resp, err := n.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	out, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode >= 300 {
+		return out, fmt.Errorf("飞书接口 HTTP %d：%s", resp.StatusCode, feishuErrText(out))
+	}
+	return out, nil
+}
+
+// feishuErrText 把飞书统一的 {code,msg} 翻成人话，拿不到就截断原文。
+func feishuErrText(b []byte) string {
+	var v struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+	}
+	if json.Unmarshal(b, &v) == nil && (v.Msg != "" || v.Code != 0) {
+		return fmt.Sprintf("code=%d %s", v.Code, v.Msg)
+	}
+	s := strings.TrimSpace(string(b))
+	if len(s) > 200 {
+		s = s[:200] + "…"
+	}
+	if s == "" {
+		return "（空响应）"
+	}
+	return s
+}
+
+// tenantToken 拿（并缓存）租户令牌。app 变了立刻作废缓存 —— 换 app 还拿旧令牌
+// 会得到「机器人没被加入会话」这类莫名其妙的错误。
+func (n *feishuNotifier) tenantToken(ctx context.Context, appID, appSecret string) (string, error) {
+	// 读缓存走 RLock：推送是高频路径，不该每次都在写锁上排队。
+	n.mu.RLock()
+	if n.token != "" && n.tokenBase == appID && time.Now().Before(n.tokenExp) {
+		tk := n.token
+		n.mu.RUnlock()
+		return tk, nil
+	}
+	n.mu.RUnlock()
+
+	out, err := n.post(ctx, "/open-apis/auth/v3/tenant_access_token/internal",
+		map[string]string{"app_id": appID, "app_secret": appSecret}, "")
+	if err != nil {
+		return "", err
+	}
+	var v struct {
+		Code              int    `json:"code"`
+		Msg               string `json:"msg"`
+		TenantAccessToken string `json:"tenant_access_token"`
+		Expire            int    `json:"expire"`
+	}
+	if err := json.Unmarshal(out, &v); err != nil {
+		return "", fmt.Errorf("飞书令牌响应无法解析：%v", err)
+	}
+	if v.Code != 0 || v.TenantAccessToken == "" {
+		return "", fmt.Errorf("飞书拒绝换取令牌：code=%d %s", v.Code, v.Msg)
+	}
+	ttl := time.Duration(v.Expire) * time.Second
+	if ttl <= 0 {
+		ttl = time.Hour
+	}
+	if ttl > feishuTokenAhead {
+		ttl -= feishuTokenAhead
+	}
+	n.mu.Lock()
+	n.token, n.tokenBase, n.tokenExp = v.TenantAccessToken, appID, time.Now().Add(ttl)
+	n.mu.Unlock()
+	return v.TenantAccessToken, nil
+}
+
+// sendCard 发一条 interactive 卡片给 to（toType 决定 to 怎么解释：open_id / email / chat_id）。
+// 为什么用卡片而不是 text：卡片能带灰字脚注（时间）与标题色，
+// 通知列表里一眼能分辨「完成（绿）/ 待确认（橙）/ 测试（蓝）」。
+// feishuCard 组装卡片（应用 / 群机器人两条路共用同一张卡）。
+//
+// link 非空时加一个「打开」按钮（2026-10-26 用户：「发测试消息就是把当前公网地址发送过去」）——
+// 在飞书里点一下就回到 App，不用自己回忆地址、也不用手抄令牌。
+func feishuCard(title, color, body, link string) map[string]any {
+	var els []any
+	if body != "" {
+		els = append(els, map[string]any{"tag": "div", "text": map[string]any{"tag": "lark_md", "content": body}})
+	}
+	if link != "" {
+		els = append(els, map[string]any{
+			"tag": "action",
+			"actions": []any{map[string]any{
+				"tag":  "button",
+				"type": "primary",
+				"text": map[string]any{"tag": "plain_text", "content": "打开 Magic Agent"},
+				"url":  link,
+			}},
+		})
+	}
+	els = append(els, map[string]any{
+		"tag": "note",
+		"elements": []any{map[string]any{
+			"tag":     "plain_text",
+			"content": "Magic Agent · " + time.Now().Format("01-2 15:04") + " · 来自桌面端",
+		}},
+	})
+	return map[string]any{
+		"config": map[string]any{"wide_screen_mode": true},
+		"header": map[string]any{
+			"template": color,
+			"title":    map[string]any{"tag": "plain_text", "content": title},
+		},
+		"elements": els,
+	}
+}
+
+// sendCard 发一条 interactive 卡片给 to（toType 决定 to 怎么解释：open_id / email / chat_id）。
+// 为什么用卡片而不是 text：卡片能带灰字脚注（时间）与标题色，
+// 通知列表里一眼能分辨「完成（绿）/ 待确认（橙）/ 测试（蓝）」。
+func (n *feishuNotifier) sendCard(ctx context.Context, appID, appSecret, to, toType, title, color, body, link string) error {
+	tk, err := n.tenantToken(ctx, appID, appSecret)
+	if err != nil {
+		return err
+	}
+	// im/v1/messages 的 content 字段是**卡片 JSON 的字符串**（v1 结构：config + header + elements）。
+	payload := map[string]any{
+		"receive_id": to,
+		"msg_type":   "interactive",
+		"content":    mustJSON(feishuCard(title, color, body, link)),
+	}
+	if toType == "" {
+		toType = "open_id"
+	}
+	out, err := n.post(ctx, "/open-apis/im/v1/messages?receive_id_type="+toType, payload, tk)
+	if err != nil {
+		return err
+	}
+	var v struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+	}
+	if err := json.Unmarshal(out, &v); err != nil {
+		return fmt.Errorf("飞书发送响应无法解析：%v", err)
+	}
+	if v.Code != 0 {
+		// 令牌失效那几种码：作废缓存，下一次重新换。
+		switch v.Code {
+		case 99991663, 99991664, 99991668:
+			n.mu.Lock()
+			n.token = ""
+			n.mu.Unlock()
+		}
+		return fmt.Errorf("飞书拒绝发送：code=%d %s", v.Code, v.Msg)
+	}
+	return nil
+}
+
+/* ─────────────── 群自定义机器人（webhook） ─────────────── */
+
+// webhookOK 只认自定义机器人的地址：<官方域名>/open-apis/bot/v2/hook/<token>。
+// 其它地址（比如某个应用的回调）发过去只会得到一段不明所以的 404。
+//
+// ⚠️ 必须是 https + 官方域名：这条 URL 里的 token 就是发消息的凭证，允许随便是谁
+// （http、任意主机）都等于让人把「往哪发」指到别处去。单测里 n.baseURL 指向假服务器时
+// 只认那一个前缀 —— 测试替身不能顺手把生产校验放宽。
+func (n *feishuNotifier) webhookOK(u string) bool {
+	const path = "/open-apis/bot/v2/hook/"
+	if n.baseURL != "" {
+		return strings.HasPrefix(u, n.baseURL+path) && len(u) > len(n.baseURL+path)
+	}
+	return strings.HasPrefix(u, "https://open.feishu.cn"+path) ||
+		strings.HasPrefix(u, "https://open.larksuite.com"+path)
+}
+
+// feishuWebhookSign 飞书自定义机器人的「签名校验」：以 `timestamp + "\n" + secret` 为密钥，
+// 对**空字符串**做 HMAC-SHA256，再 base64。不是对请求体签名 —— 这里很容易写错。
+func feishuWebhookSign(timestamp, secret string) string {
+	mac := hmac.New(sha256.New, []byte(timestamp+"\n"+secret))
+	mac.Write(nil)
+	return base64.StdEncoding.EncodeToString(mac.Sum(nil))
+}
+
+// sendWebhook 往群机器人发一张卡片。收件人是那个群 —— 不需要 open_id / 邮箱。
+func (n *feishuNotifier) sendWebhook(ctx context.Context, hook, secret, title, color, body, link string) error {
+	payload := map[string]any{
+		"msg_type": "interactive",
+		"card":     feishuCard(title, color, body, link),
+	}
+	if secret != "" {
+		ts := strconv.FormatInt(time.Now().Unix(), 10)
+		payload["timestamp"] = ts
+		payload["sign"] = feishuWebhookSign(ts, secret)
+	}
+	b, err := json.Marshal(payload)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, hook, bytes.NewReader(b))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json; charset=utf-8")
+	resp, err := n.client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	out, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return err
+	}
+	if resp.StatusCode >= 300 {
+		return fmt.Errorf("飞书群机器人 HTTP %d：%s", resp.StatusCode, feishuErrText(out))
+	}
+	/* 响应有两种拼写：新版 {code,msg}，老版 {StatusCode,StatusMessage}。都要认，
+	   否则「发失败但返回 200」会被当成成功 —— 用户那边就是「一条都没收到」。 */
+	var v struct {
+		Code          *int   `json:"code"`
+		Msg           string `json:"msg"`
+		StatusCode    *int   `json:"StatusCode"`
+		StatusMessage string `json:"StatusMessage"`
+	}
+	if err := json.Unmarshal(out, &v); err != nil {
+		return fmt.Errorf("飞书群机器人响应无法解析：%v", err)
+	}
+	code, msg := 0, v.Msg
+	if v.Code != nil {
+		code = *v.Code
+	} else if v.StatusCode != nil {
+		code, msg = *v.StatusCode, v.StatusMessage
+	}
+	if code != 0 {
+		if code == 19021 {
+			msg = "签名校验失败（签名密钥填错了）"
+		}
+		return fmt.Errorf("飞书群机器人拒绝接收：code=%d %s", code, msg)
+	}
+	return nil
+}
+
+func mustJSON(v any) string {
+	b, _ := json.Marshal(v)
+	return string(b)
+}
+
+/* ─────────────── 绑定码 ─────────────── */
+
+// newBindCode 6 位数字（纯数字方便在手机上转述 / 粘贴）。crypto/rand，不用 math/rand。
+func newBindCode() (string, error) {
+	v, err := rand.Int(rand.Reader, big.NewInt(1000000))
+	if err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("%06d", v.Int64()), nil
+}
+
+/* ─────────────── 推送（幂等 + 退避重试） ─────────────── */
+
+// pushResult 一次推送调用的结果（HTTP 层用）。
+type pushResult struct {
+	OK       bool   `json:"ok"`
+	Dupe     bool   `json:"dupe,omitempty"`     // 这一轮已经推过（幂等命中）
+	Disabled bool   `json:"disabled,omitempty"` // 没开 / 没绑 / 没配，什么也没做
+	Reason   string `json:"reason,omitempty"`
+}
+
+// push 推一条。key 由 event + ask_id 组成（没有 ask_id 时退回标题），保证同一轮只推一次。
+//
+// 为什么幂等键在**服务端**而不是手机端：手机在多个 tab / 多台手机里各自轮询，
+// 每台都有自己的基线；靠客户端去重 = 换个手机就重推一遍。服务端记一份，
+// 谁先到谁推，后来的直接断定为 dupe。
+func (n *feishuNotifier) push(ctx context.Context, appID, appSecret string, st feishuState, event, askID, title, body, link string) pushResult {
+	ev, ok := feishuEvents[event]
+	if !ok {
+		return pushResult{Reason: "未知的推送事件：" + event}
+	}
+	/* 开关 / 绑定 / 凭据在**幂等判重之后**判：不推、也不占键。
+	   两条通道：配了群机器人 webhook 就走它（不需要知道收件人是谁），
+	   否则走「飞书应用 + 收件人」。 */
+	to, toType := st.target()
+	useHook := st.Webhook != ""
+	if !useHook && to == "" {
+		return pushResult{Disabled: true, Reason: "还没绑定飞书账号（群机器人地址或收件人都没有）"}
+	}
+	if !st.Enabled {
+		return pushResult{Disabled: true, Reason: "飞书推送已关闭"}
+	}
+	if !useHook && (appID == "" || appSecret == "") {
+		return pushResult{Disabled: true, Reason: "飞书应用凭据未配置"}
+	}
+	key := event + "|" + askID
+	if askID == "" {
+		key = event + "|" + title
+	}
+
+	n.mu.Lock()
+	if _, dup := n.sent[key]; dup {
+		n.mu.Unlock()
+		return pushResult{OK: true, Dupe: true}
+	}
+	// 先把键占上：两台手机几乎同时上报时，后到的那台也会看到 dupe。
+	// 发送失败时下面会**释放**键，否则「失败一次就永远不再推」。
+	n.sent[key] = time.Now()
+	n.mu.Unlock()
+
+	if len([]rune(body)) > feishuMaxPushTextLen {
+		r := []rune(body)
+		body = string(r[:feishuMaxPushTextLen]) + "…"
+	}
+	fullTitle := "【" + ev.title + "】" + title
+
+	var lastErr error
+	for attempt := 1; attempt <= feishuSendAttempts; attempt++ {
+		var err error
+		if useHook {
+			err = n.sendWebhook(ctx, st.Webhook, st.WebhookSecret, fullTitle, ev.tag, body, link)
+		} else {
+			err = n.sendCard(ctx, appID, appSecret, to, toType, fullTitle, ev.tag, body, link)
+		}
+		if err == nil {
+			n.logPush(feishuPushLog{At: time.Now(), Event: event, AskID: askID, Title: title, Link: link, OK: true, Attempt: attempt})
+			return pushResult{OK: true}
+		}
+		lastErr = err
+		if ctx.Err() != nil {
+			break
+		}
+		if attempt < feishuSendAttempts {
+			select {
+			case <-ctx.Done():
+			case <-time.After(feishuRetryBackoff * time.Duration(attempt)):
+			}
+		}
+	}
+	n.mu.Lock()
+	delete(n.sent, key)
+	n.mu.Unlock()
+	msg := ""
+	if lastErr != nil {
+		msg = lastErr.Error()
+	}
+	n.logPush(feishuPushLog{At: time.Now(), Event: event, AskID: askID, Title: title, Link: link, OK: false, Attempt: feishuSendAttempts, Error: msg})
+	return pushResult{Reason: msg}
+}
+
+// logPush 把最近一次结果追加到落盘状态（只留最后 feishuRecentKeep 条）。
+// 写失败无所谓 —— 这是排障记录，不能影响推送本身。
+func (n *feishuNotifier) logPush(l feishuPushLog) {
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	st, err := n.load()
+	if err != nil {
+		return
+	}
+	st.Recent = append(st.Recent, l)
+	if len(st.Recent) > feishuRecentKeep {
+		st.Recent = st.Recent[len(st.Recent)-feishuRecentKeep:]
+	}
+	_ = n.save(st)
+}
+
+/* ─────────────── 会话标题（推送正文用） ─────────────── */
+
+// feishuAskTitle 给一个 ask_id 找会话标题：先查作业队列，再查标题表。
+// 都没有时问句首行 / 「会话 <前缀>」兜底 —— 宁可不推，也不要推一条「任务完成：」的空卡片。
+func (s *Service) feishuAskTitle(askID, sessionID string) (title, workspace string) {
+	if s.jobs != nil && askID != "" {
+		if j := s.jobs.get(askID); j != nil {
+			sessionID = j.SessionID
+			workspace = j.Workspace
+			if j.Prompt != "" {
+				title = firstLine(j.Prompt)
+			}
+		}
+	}
+	if sessionID != "" {
+		if t := strings.TrimSpace(loadTitles()[sessionID]); t != "" {
+			title = t
+		} else if title == "" {
+			title = "会话 " + shortID(sessionID)
+		}
+	}
+	return title, workspace
+}
+
+func firstLine(s string) string {
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		s = s[:i]
+	}
+	r := []rune(strings.TrimSpace(s))
+	if len(r) > 40 {
+		r = append(r[:40], '…')
+	}
+	return string(r)
+}
+
+func shortID(id string) string {
+	if len(id) > 8 {
+		return id[:8]
+	}
+	return id
+}
+
+/* ─────────────── 启动通知 ─────────────── */
+
+/* 2026-10-26 用户：「重新启动后如果绑定了飞书 触发一下发送访问地址」。
+
+   重启是唯一「手机一定会失联」的时刻（换网 / 换端口 / 隧道换域名），而飞书是唯一
+   不依赖那条连接的通道 —— 服务起来后主动把**验证过能用**的入口推过去，用户不用回忆、
+   也不用在飞书上翻上次那张卡片。
+
+   两个约束：
+     · 没绑定 / 关了推送 → 一个请求都不发（启动不该产生任何出站流量）；
+     · 地址必须过 /desk/health（feishuLink 的口径）：客户端往往比隧道 / 网卡起得早，
+       所以按 feishuStartupDelays 退避重试；**公网优先**（最多等 90 秒），一直等不到
+       才用局域网入口兜底；两者都不通就不发 —— 一条「重启了」但没有地址的卡片没有用。 */
+
+// feishuStartupDelays 启动后**第几秒**去试一次公网地址（绝对时间，不是每次睡多久）。
+// 第一次立即试（只重启 magic-client 时隧道没断，落盘里就有域名）；之后按退避再试。
+//
+// 为什么最长等到 90 秒：重启掌天瓶时 cloudflared 跟着重起，quick tunnel 的新域名
+// 从「进程给了 hostname」到「公网真能解析、能回 /desk/health」实测要 90 秒上下
+// （2026-10-26 20:12 重启：cloudflared 14 秒起、域名 96 秒后才验通）。中途就退回局域网，
+// 等于把「不在同一个 Wi-Fi」的人送到打不开的地址上 —— 那正是用户报过的毛病。
+// 是 var 不是 const：测试里改短，不用真等一分半。
+var feishuStartupDelays = []time.Duration{
+	0, 5 * time.Second, 10 * time.Second, 15 * time.Second, 20 * time.Second,
+	30 * time.Second, 45 * time.Second, 60 * time.Second, 75 * time.Second, 90 * time.Second,
+}
+
+// NotifyStartup 服务启动后给已绑定的飞书推一条「当前访问地址」。
+//
+// lanEntry 是启动时已知的局域网入口（带令牌，由 cmd/magic-client 传入）：没有公网入口
+// 时用它兜底 —— 服务端算不出自己的监听地址，只有那一层知道。
+//
+// 由调用方 `go` 起来：里面会为了等隧道退避重试几十秒，不能挡住服务启动。
+func (s *Service) NotifyStartup(lanEntry string) {
+	n := s.feishu()
+	st, err := n.load()
+	if err != nil {
+		s.logf("飞书启动通知：读状态失败：%v", err)
+		return
+	}
+	to, _ := st.target()
+	if st.Webhook == "" && to == "" {
+		return // 没绑定
+	}
+	if !st.Enabled {
+		return // 绑了但用户关了推送
+	}
+	id, sec, _ := s.credsOf(st)
+	if st.Webhook == "" && (id == "" || sec == "") {
+		s.logf("飞书启动通知：已绑定但没有应用凭据，跳过")
+		return
+	}
+
+	var link string
+	start := time.Now()
+	for _, at := range feishuStartupDelays {
+		if wait := time.Until(start.Add(at)); wait > 0 {
+			time.Sleep(wait)
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+		link = s.feishuLink(ctx, "") // 公网优先：人可能不在同一个 Wi-Fi 里
+		cancel()
+		if link != "" {
+			break
+		}
+	}
+	if link == "" && strings.TrimSpace(lanEntry) != "" {
+		/* 一直没等到公网入口（没开公网 / 隧道根本起不来）才退回局域网 ——
+		   同 Wi-Fi 能打开，总比一条什么都没有的「重启了」强。 */
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		link = s.feishuLink(ctx, lanEntry)
+		cancel()
+	}
+	if link == "" {
+		s.logf("飞书启动通知：没有验证通过的可用地址，本次不发")
+		return
+	}
+
+	body := "桌面端已重新启动，当前访问地址：\n\n地址：" + link +
+		"\n（这个链接含访问令牌，别转发给别人）"
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	// key 带 pid + 时间：每次启动都是独立一条，不跟上一轮的去重键撞。
+	key := fmt.Sprintf("startup-%d-%d", os.Getpid(), time.Now().Unix())
+	res := n.push(ctx, id, sec, st, "startup", key, "当前访问地址", body, link)
+	if res.Disabled || !res.OK {
+		s.logf("飞书启动通知：%s", res.Reason)
+	}
+}
+
+/* ─────────────── HTTP 端点 ─────────────── */
+
+// handleFeishu 前缀路由：/desk/feishu 与 /desk/feishu/{action}。
+//
+//	GET  /desk/feishu          → 状态（不含 secret）
+//	POST /desk/feishu/code     → {code, expires_in}
+//	POST /desk/feishu/bind     → {code, open_id} 绑定并**自动开启**
+//	POST /desk/feishu/unbind   → 解绑（open_id 清空，enabled 置 false）
+//	POST /desk/feishu/enable   → {enabled}
+//	POST /desk/feishu/config   → {app_id, app_secret} 先验令牌，再落本机 0600
+//	POST /desk/feishu/test     → 立即发一条测试卡片
+//	POST /desk/feishu/push     → {event, ask_id, session_id?, title?, body?} 幂等推送
+func (s *Service) handleFeishu(w http.ResponseWriter, r *http.Request) {
+	action := strings.Trim(strings.TrimPrefix(r.URL.Path, "/desk/feishu"), "/")
+	n := s.feishu()
+	if action == "" {
+		if r.Method != http.MethodGet {
+			writeErr(w, http.StatusMethodNotAllowed, "只支持 GET")
+			return
+		}
+		s.feishuWriteStatus(w, n)
+		return
+	}
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "只支持 POST")
+		return
+	}
+	var req struct {
+		Code          string `json:"code"`
+		To            string `json:"to"`      // 邮箱 / open_id / chat_id，见 feishuDetectTarget
+		OpenID        string `json:"open_id"` // 老客户端
+		Enabled       *bool  `json:"enabled"`
+		Webhook       string `json:"webhook"`
+		WebhookSecret string `json:"webhook_secret"`
+		AppID         string `json:"app_id"`
+		AppSecret     string `json:"app_secret"`
+		Event         string `json:"event"`
+		AskID         string `json:"ask_id"`
+		SessionID     string `json:"session_id"`
+		URL           string `json:"url"` // 手机当前用的入口（拼卡片里那个「打开」按钮）
+		Title         string `json:"title"`
+		Body          string `json:"body"`
+	}
+	if r.ContentLength != 0 {
+		if err := json.NewDecoder(io.LimitReader(r.Body, 64<<10)).Decode(&req); err != nil && !errors.Is(err, io.EOF) {
+			writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON："+err.Error())
+			return
+		}
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 20*time.Second)
+	defer cancel()
+
+	switch action {
+	case "code":
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		code, err := newBindCode()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, "生成绑定码失败："+err.Error())
+			return
+		}
+		st.Code, st.CodeAt = code, time.Now()
+		if err := n.save(st); err != nil {
+			writeErr(w, http.StatusInternalServerError, "写入绑定码失败："+err.Error())
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]any{"code": code, "expires_in": int(feishuCodeTTL.Seconds())})
+
+	case "bind":
+		code := strings.TrimSpace(req.Code)
+		raw := strings.TrimSpace(req.To)
+		if raw == "" {
+			raw = strings.TrimSpace(req.OpenID) // 老客户端只发 open_id
+		}
+		to, toType, err := feishuDetectTarget(raw)
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		if st.Code == "" {
+			writeErr(w, http.StatusBadRequest, "还没有申请绑定码，请先点「获取绑定码」")
+			return
+		}
+		if time.Since(st.CodeAt) > feishuCodeTTL || st.CodeAt.After(time.Now()) {
+			writeErr(w, http.StatusBadRequest, "绑定码已过期，请重新获取")
+			return
+		}
+		// 先判过期再比码：过期的码填对了也该让它去重新申请，而不是说「不正确」。
+		if code != st.Code {
+			writeErr(w, http.StatusBadRequest, "绑定码不正确（6 位数字，10 分钟内有效）")
+			return
+		}
+		st.ReceiveID, st.ReceiveType, st.BoundAt = to, toType, time.Now()
+		st.OpenID = "" // 新模型只用 ReceiveID/ReceiveType，别再让两份不一致
+		st.Enabled = true
+		st.Code, st.CodeAt = "", time.Time{} // 一次性：用过即废
+		if err := n.save(st); err != nil {
+			writeErr(w, http.StatusInternalServerError, "写入绑定失败："+err.Error())
+			return
+		}
+		// 绑好立刻推一条：用户不用等下一次任务跑完才知道通没通。
+		id, sec, _ := s.credsOf(st)
+		var pushRes pushResult
+		if id != "" && sec != "" {
+			pushRes = n.push(ctx, id, sec, st, "result", "bind-"+to, "飞书绑定成功",
+				"之后任务完成 / 待确认会推到这里。在「我的 → 通知」里可以关掉。", s.feishuLink(ctx, req.URL))
+		}
+		out := map[string]any{"ok": true, "to": to, "to_type": toType, "enabled": true, "push": pushRes}
+		if id == "" || sec == "" {
+			out["notice"] = "已绑定，但飞书应用凭据未配置，还没法发消息 —— 在「我的 → 通知」里填 App ID / Secret"
+		}
+		writeJSON(w, http.StatusOK, out)
+
+	/* 群自定义机器人（2026-10-26）：用户要的是「把消息推到我的飞书」，不是「建一个应用」。
+	   填一条 webhook 地址就完事 —— 不用应用凭据、不用审批、不需要 open_id / 邮箱。
+	   落盘前**当场发一条测试卡片**：地址错了 / 签名错了现在就说，别等下一次任务跑完。 */
+	case "webhook":
+		hook := strings.TrimSpace(req.Webhook)
+		sec := strings.TrimSpace(req.WebhookSecret)
+		if !n.webhookOK(hook) {
+			writeErr(w, http.StatusBadRequest,
+				"这不像群机器人地址：应形如 https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx")
+			return
+		}
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		link := s.feishuLink(ctx, req.URL)
+		body := "绑定成功。之后任务跑完 / 等你确认时会推到这个群。"
+		if link != "" {
+			body += "\n\n地址：`" + link + "`\n（这个链接含访问令牌，别转发给别人）"
+		}
+		if err := n.sendWebhook(ctx, hook, sec, "【绑定】Magic Agent 飞书推送", "green", body, link); err != nil {
+			writeErr(w, http.StatusBadRequest, "测试发送失败："+err.Error())
+			return
+		}
+		st.Webhook, st.WebhookSecret = hook, sec
+		st.Enabled, st.BoundAt = true, time.Now()
+		if err := n.save(st); err != nil {
+			writeErr(w, http.StatusInternalServerError, "写入绑定失败："+err.Error())
+			return
+		}
+		n.mu.Lock()
+		n.sent = map[string]time.Time{}
+		n.mu.Unlock()
+		n.logPush(feishuPushLog{At: time.Now(), Event: "bind", Title: "群机器人绑定", OK: true, Attempt: 1})
+		s.feishuWriteStatus(w, n)
+
+	case "unbind":
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		st.ReceiveID, st.ReceiveType, st.OpenID = "", "", ""
+		st.Webhook, st.WebhookSecret = "", ""
+		st.BoundAt, st.Enabled = time.Time{}, false
+		if err := n.save(st); err != nil {
+			writeErr(w, http.StatusInternalServerError, "写入失败："+err.Error())
+			return
+		}
+		n.mu.Lock()
+		n.sent = map[string]time.Time{}
+		n.mu.Unlock()
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true})
+
+	case "enable":
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		if req.Enabled == nil {
+			writeErr(w, http.StatusBadRequest, "缺少 enabled")
+			return
+		}
+		if *req.Enabled && st.Webhook == "" && func() bool { t, _ := st.target(); return t == "" }() {
+			writeErr(w, http.StatusBadRequest, "还没绑定飞书账号")
+			return
+		}
+		st.Enabled = *req.Enabled
+		if err := n.save(st); err != nil {
+			writeErr(w, http.StatusInternalServerError, "写入失败："+err.Error())
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true, "enabled": st.Enabled})
+
+	case "config":
+		id := strings.TrimSpace(req.AppID)
+		sec := strings.TrimSpace(req.AppSecret)
+		if id == "" || sec == "" {
+			writeErr(w, http.StatusBadRequest, "App ID 与 App Secret 都要填")
+			return
+		}
+		if !strings.HasPrefix(id, "cli_") {
+			writeErr(w, http.StatusBadRequest, "App ID 形如 cli_xxxxxxxxxxxx")
+			return
+		}
+		/* 先验一次令牌再落盘：错的 secret 存进去只会变成「绑定成功、推送全失败」，
+		   用户在界面里看不出是哪一步坏了。验不过就当场报出来，一个字都不写。 */
+		if _, err := n.tenantToken(ctx, id, sec); err != nil {
+			writeErr(w, http.StatusBadRequest, "凭据校验失败："+err.Error())
+			return
+		}
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		st.AppID, st.AppSecret = id, sec
+		if err := n.save(st); err != nil {
+			writeErr(w, http.StatusInternalServerError, "写入失败："+err.Error())
+			return
+		}
+		s.feishuWriteStatus(w, n)
+
+	case "test":
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		to, toType := st.target()
+		link := s.feishuLink(ctx, req.URL)
+		body := "收到这条说明通道是通的。任务跑完 / 需要确认时会自动推。"
+		if link != "" {
+			body += "\n\n地址：`" + link + "`\n（这个链接含访问令牌，别转发给别人）"
+		}
+		if st.Webhook != "" {
+			if err := n.sendWebhook(ctx, st.Webhook, st.WebhookSecret, "【测试】Magic Agent 飞书推送", "blue", body, link); err != nil {
+				writeErr(w, http.StatusBadGateway, err.Error())
+				return
+			}
+			n.logPush(feishuPushLog{At: time.Now(), Event: "test", Title: "测试（群机器人）", OK: true, Attempt: 1})
+			writeJSON(w, http.StatusOK, map[string]any{"ok": true})
+			return
+		}
+		if to == "" {
+			writeErr(w, http.StatusBadRequest, "还没绑定飞书账号")
+			return
+		}
+		id, sec, _ := s.credsOf(st)
+		if id == "" || sec == "" {
+			writeErr(w, http.StatusBadRequest, "飞书应用凭据未配置")
+			return
+		}
+		if err := n.sendCard(ctx, id, sec, to, toType, "【测试】Magic Agent 飞书推送", "blue", body, link); err != nil {
+			writeErr(w, http.StatusBadGateway, err.Error())
+			return
+		}
+		n.logPush(feishuPushLog{At: time.Now(), Event: "test", Title: "测试", OK: true, Attempt: 1})
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true})
+
+	case "push":
+		st, err := n.load()
+		if err != nil {
+			writeErr(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		id, sec, _ := s.credsOf(st)
+		title, ws := req.Title, ""
+		if title == "" {
+			title, ws = s.feishuAskTitle(req.AskID, req.SessionID)
+		}
+		if title == "" {
+			title = "会话"
+		}
+		body := req.Body
+		if body == "" {
+			var lines []string
+			if ws != "" {
+				lines = append(lines, "工作空间：`"+filepath.Base(ws)+"`")
+			}
+			switch req.Event {
+			case "result":
+				lines = append(lines, "这条会话跑完了一轮，打开 App 看结果。")
+			case "confirm":
+				lines = append(lines, "这条会话在等你确认，打开 App 处理。")
+			}
+			body = strings.Join(lines, "\n")
+		}
+		link := s.feishuLink(ctx, req.URL)
+		if link != "" {
+			/* 纯文本地址，不用 markdown 的 [文字](url)：飞书取回的消息里把它摊成
+			   `[文字]($1)`，看着像坏链；裸链接反而会被自动识别成可点的。 */
+			body += "\n\n地址：" + link
+		}
+		res := n.push(ctx, id, sec, st, req.Event, req.AskID, title, body, link)
+		if res.Disabled {
+			// 没开 / 没配不是错误：手机端照样会发，服务端回 200 + disabled，免得日志里全是红字。
+			writeJSON(w, http.StatusOK, res)
+			return
+		}
+		if !res.OK {
+			writeErr(w, http.StatusBadGateway, "飞书推送失败："+res.Reason)
+			return
+		}
+		writeJSON(w, http.StatusOK, res)
+
+	default:
+		writeErr(w, http.StatusNotFound, "未知的飞书接口："+action)
+	}
+}
+
+// feishuDetectTarget 判断「推给谁」那串东西是什么，并挡掉明显填错的。
+//
+// 为什么允许邮箱（2026-10-26 用户实测反馈）：open_id **是应用维度的** —— 同一个人在
+// 不同飞书应用下 open_id 不同，而且飞书客户端任何界面都不显示它。让用户手抄 open_id
+// 等于让他猜：他填了 `ou_me`，旧代码照收，绑成功、推送全失败，界面上还显示「已绑定」。
+// 邮箱是用户真知道的东西，im/v1/messages 原生支持 receive_id_type=email。
+func feishuDetectTarget(raw string) (id, typ string, err error) {
+	v := strings.TrimSpace(raw)
+	switch {
+	case v == "":
+		return "", "", fmt.Errorf("请填你的飞书邮箱（推荐）或 open_id")
+	case strings.Contains(v, "@"):
+		// 邮箱：@ 前后都要有东西，且域名带点。不做完整 RFC 校验，挡的是「手滑」。
+		at := strings.LastIndexByte(v, '@')
+		if at <= 0 || at == len(v)-1 || !strings.Contains(v[at+1:], ".") || strings.ContainsAny(v, " \t") {
+			return "", "", fmt.Errorf("邮箱格式不对：%s", v)
+		}
+		return v, "email", nil
+	case strings.HasPrefix(v, "oc_"):
+		if len(v) < 10 {
+			return "", "", fmt.Errorf("chat_id 看起来不完整（正常是 oc_ 开头的一长串）")
+		}
+		return v, "chat_id", nil
+	case strings.HasPrefix(v, "ou_"):
+		/* 正常 open_id 是 ou_ + 32 位。当初就是这里太宽松：`ou_me` 这种占位符
+		   被当成合法 id 存了下来，之后每条推送都在飞书那边失败。 */
+		if len(v) < 20 {
+			return "", "", fmt.Errorf("open_id 看起来不完整（正常是 ou_ 开头 + 32 位）。建议改填飞书邮箱，不用找 open_id")
+		}
+		return v, "open_id", nil
+	}
+	return "", "", fmt.Errorf("认不出这是什么：请填飞书邮箱（如 you@company.com），或 ou_ 开头的 open_id，或 oc_ 开头的群 id")
+}
+
+// maskTarget 状态接口里显示的收件人：邮箱留首字母与域名，open_id / chat_id 留末 6 位。
+func maskTarget(to, typ string) string {
+	if typ == "email" {
+		at := strings.LastIndexByte(to, '@')
+		if at > 0 {
+			return string([]rune(to)[:1]) + "***" + to[at:]
+		}
+	}
+	return "…" + tail(to, 6)
+}
+
+// feishuLink 拼「在飞书里点一下就回到 App」的地址。
+//
+// 优先用桌面端已知的**公网**入口（隧道由壳托管，重启不变，人在外面也能开）；
+// 没有公网就用手机报上来的那个入口（它自己最清楚当前怎么连上的：局域网 / 隧道 / 域名）。
+// 都拿不到就返回空 —— 那张卡片只是没有按钮，其余照发，不能因此推不出去。
+//
+// ⚠️ 链接里带令牌：这条卡片等同把控制权交给能看见这个会话的人。
+// 所以正文里明写一句「别转发」，界面上也照实提示（见 index.html）。
+func (s *Service) feishuLink(ctx context.Context, fromClient string) string {
+	/* 2026-10-26 用户实测：「发送的消息中的访问连接地址不对 无法访问」。
+	   根因是**信了缓存**：实例里那个公网域名是上一轮隧道留下的，cloudflared 一重启就换域名，
+	   老域名 TCP 都不通；而真正活着的那条隧道域名当时就在 metrics 里躺着。
+	   所以这里不再「取一个像样的地址就发」，而是**逐个回打 /desk/health**，
+	   只发能通的那个；一个都不通就不放链接（宁可没有按钮，也不给人一个打不开的门）。 */
+	var cands []string
+	add := func(u string) {
+		u = strings.TrimRight(strings.TrimSpace(u), "/")
+		if u == "" {
+			return
+		}
+		for _, c := range cands {
+			if c == u {
+				return
+			}
+		}
+		cands = append(cands, u)
+	}
+	// ① 手机此刻在用的入口：它至少对这台手机是通的。
+	if strings.Contains(fromClient, "token=") {
+		// 手机报上来的已经是完整链接，直接用（不再拼 /m/）。
+		if healthOK(strings.SplitN(fromClient, "?", 2)[0], s.opts.Token, 2*time.Second) {
+			return fromClient
+		}
+	} else {
+		add(fromClient)
+	}
+	// ② 缓存里的公网域名 + 当前所有隧道域名（缓存可能是死的，隧道清单才是活的）。
+	add(s.publicURLOrEmpty())
+	for _, h := range quickTunnelHosts() {
+		add("https://" + h)
+	}
+	/* ③ 局域网不再单独兜底：手机在自己报的 fromClient 里已经带了它所在的网段，
+	   服务端不知道自己的监听地址（Options 没有这一项），瞎猜只会拼出打不开的地址。 */
+
+	/* 并发验（每个 4s 上限）：quick tunnel 首包要过 DNS + TLS + 边缘转发，实测冷启动
+	   一两秒很常见 —— 1.5s 会把**能用的**地址误判成死的（2026-10-26 实测：探针日志里
+	   「没有验证通过的可用地址」紧接着就是「公网入口：https://…」，只是验得太急）。
+	   并发是为了不让「任务完成」的推送为了拼一个按钮多等十几秒。 */
+	okIdx := make([]bool, len(cands))
+	var wg sync.WaitGroup
+	for i, base := range cands {
+		wg.Add(1)
+		go func(i int, base string) {
+			defer wg.Done()
+			okIdx[i] = healthOK(base, s.opts.Token, 4*time.Second)
+		}(i, base)
+	}
+	wg.Wait()
+	for i, base := range cands {
+		if !okIdx[i] {
+			continue
+		}
+		if ctx.Err() != nil {
+			return ""
+		}
+		/* 公网域名验通了就顺手纠正缓存：否则界面上还会一直显示那个死域名。 */
+		if strings.HasPrefix(base, "https://") && base != s.publicURLOrEmpty() {
+			if strings.Contains(base, ".trycloudflare.com") {
+				s.applyProbeResult(base)
+			}
+		}
+		if s.opts.Token == "" {
+			return base + "/m/"
+		}
+		return base + "/m/?token=" + s.opts.Token
+	}
+	if s.log != nil {
+		s.log.Printf("飞书卡片：没有验证通过的可用地址，本次不带链接")
+	}
+	return ""
+}
+
+// feishuWriteStatus 状态（**绝不回显 secret**）。Configured 只说明「能换到令牌」的前置条件在。
+func (s *Service) feishuWriteStatus(w http.ResponseWriter, n *feishuNotifier) {
+	out := map[string]any{
+		"configured": false,
+		"source":     "",
+		"app_id":     "",
+		"bound":      false,
+		"enabled":    false,
+		"recent":     []any{},
+	}
+	st, err := n.load()
+	if err != nil {
+		out["error"] = err.Error()
+		writeJSON(w, http.StatusOK, out)
+		return
+	}
+	id, sec, src := s.credsOf(st)
+	if id != "" && sec != "" {
+		out["configured"], out["source"] = true, src
+	}
+	if id != "" {
+		out["app_id"] = id
+	}
+	to, toType := st.target()
+	useHook := st.Webhook != ""
+	out["bound"] = useHook || to != ""
+	out["enabled"] = st.Enabled && (useHook || to != "")
+	switch {
+	case useHook:
+		out["mode"] = "webhook"
+		out["webhook_tail"] = tail(st.Webhook, 8)
+		out["configured"] = true
+		if out["source"] == "" {
+			out["source"] = "群机器人"
+		}
+	case to != "":
+		out["mode"] = "app"
+	}
+	out["bound_type"] = toType
+	if to != "" {
+		out["bound_to"] = maskTarget(to, toType)
+	}
+	if !st.BoundAt.IsZero() {
+		out["bound_at"] = st.BoundAt
+	}
+	if to != "" && toType == "open_id" {
+		out["open_id_tail"] = tail(to, 6) // 老字段，PC / 老手机还在读
+	}
+	if len(st.Recent) > 0 {
+		out["recent"] = st.Recent
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+func tail(s string, n int) string {
+	r := []rune(s)
+	if len(r) <= n {
+		return string(r)
+	}
+	return string(r[len(r)-n:])
+}