magic-agent 2.4.3 → 2.6.3

package/internal/client/feishu_test.go

@@ -0,0 +1,649 @@
+package client
+
+/* 飞书推送的单测：**完全不碰外网**，用 httptest 冒充 open.feishu.cn 的两个接口。
+ *
+ * 钉住的几件事（每条都对应一个真出过 / 很会出的坑）：
+ *   ① 状态接口**永不回显 app_secret**（它落在一个手机能访问的接口上）。
+ *   ② 绑定码：6 位、一次性、过期作废、错码拒绝。
+ *   ③ 推送幂等：同一 ask_id 连调两次只发一条（手机多端轮询会重入）。
+ *   ④ 发送失败要重试；最终失败**不吞**，且幂等键释放（下一轮还能推）。
+ *   ⑤ 租户令牌缓存：两次推送只换一次令牌。
+ */
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// fakeFeishu 冒充飞书开放平台。
+type fakeFeishu struct {
+	mu          sync.Mutex
+	tokenHits   int
+	sent        []map[string]any
+	webhookSent []map[string]any
+	failNext    int  // 接下来 N 次发消息回失败（模拟网络抖动 / 频控）
+	badToken    bool // 令牌接口回凭据错误（测 config 校验）
+}
+
+func newFakeFeishu(t *testing.T) (*fakeFeishu, *httptest.Server) {
+	f := &fakeFeishu{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		switch r.URL.Path {
+		case "/open-apis/auth/v3/tenant_access_token/internal":
+			f.tokenHits++
+			if f.badToken {
+				_ = json.NewEncoder(w).Encode(map[string]any{"code": 10003, "msg": "app_secret invalid"})
+				return
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{"code": 0, "msg": "ok", "tenant_access_token": "t-test-token", "expire": 7200})
+		case "/desk/health":
+			// 验链接用：只有真指向本服务的入口才 200 + ok。测试里把假服务器当入口。
+			if r.Header.Get("X-Magic-Token") != "" {
+				_, _ = io.WriteString(w, `{"ok":true}`)
+			} else {
+				w.WriteHeader(http.StatusUnauthorized)
+				_, _ = io.WriteString(w, `{"error":"缺少令牌"}`)
+			}
+		case "/open-apis/bot/v2/hook/fake-token", "/open-apis/bot/v2/hook/x":
+			body, _ := io.ReadAll(r.Body)
+			var m map[string]any
+			_ = json.Unmarshal(body, &m)
+			f.webhookSent = append(f.webhookSent, m)
+			_, _ = io.WriteString(w, `{"code":0,"msg":"success","data":{}}`)
+		case "/open-apis/im/v1/messages":
+			if got := r.Header.Get("Authorization"); got != "Bearer t-test-token" {
+				w.WriteHeader(http.StatusUnauthorized)
+				_, _ = io.WriteString(w, `{"code":99991663,"msg":"invalid token"}`)
+				return
+			}
+			if f.failNext > 0 {
+				f.failNext--
+				w.WriteHeader(http.StatusTooManyRequests)
+				_, _ = io.WriteString(w, `{"code":99991400,"msg":"rate limited"}`)
+				return
+			}
+			body, _ := io.ReadAll(r.Body)
+			var m map[string]any
+			_ = json.Unmarshal(body, &m)
+			m["__receive_id_type"] = r.URL.Query().Get("receive_id_type")
+			f.sent = append(f.sent, m)
+			_, _ = io.WriteString(w, `{"code":0,"msg":"success","data":{"message_id":"om_1"}}`)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	t.Cleanup(srv.Close)
+	return f, srv
+}
+
+// newFeishuNotifier 一个把状态文件落在 t.TempDir、对接到假飞书的推送器。
+func newFeishuNotifier(t *testing.T, base string) *feishuNotifier {
+	t.Helper()
+	return &feishuNotifier{
+		path:    filepath.Join(t.TempDir(), "feishu-notify.json"),
+		sent:    map[string]time.Time{},
+		client:  &http.Client{Timeout: 5 * time.Second},
+		baseURL: base,
+	}
+}
+
+// newFeishuService 一个只带飞书推送器的 Service（不跑 New()，也就不需要 core 二进制）。
+func newFeishuService(t *testing.T, base string) (*Service, *feishuNotifier) {
+	t.Helper()
+	n := newFeishuNotifier(t, base)
+	return &Service{feishuN: n, feishuOnce: sync.Once{}}, n
+}
+
+func doJSON(t *testing.T, s *Service, method, path string, body any) (int, map[string]any) {
+	t.Helper()
+	var rd io.Reader
+	if body != nil {
+		b, _ := json.Marshal(body)
+		rd = strings.NewReader(string(b))
+	}
+	req := httptest.NewRequest(method, path, rd)
+	rec := httptest.NewRecorder()
+	s.handleFeishu(rec, req)
+	var out map[string]any
+	_ = json.Unmarshal(rec.Body.Bytes(), &out)
+	return rec.Code, out
+}
+
+func seedState(t *testing.T, n *feishuNotifier, st feishuState) {
+	t.Helper()
+	if err := n.save(st); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestFeishuStatusNeverLeaksSecret(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{
+		AppID: "cli_abc", AppSecret: "super-secret-value",
+		OpenID: "ou_1234567890abcdef", Enabled: true, BoundAt: time.Now(),
+	})
+	code, out := doJSON(t, s, "GET", "/desk/feishu", nil)
+	if code != http.StatusOK {
+		t.Fatalf("status = %d", code)
+	}
+	raw, _ := json.Marshal(out)
+	if strings.Contains(string(raw), "super-secret-value") {
+		t.Fatalf("状态接口回显了 app_secret：%s", raw)
+	}
+	if out["configured"] != true || out["bound"] != true || out["enabled"] != true {
+		t.Fatalf("状态不对：%v", out)
+	}
+	if tail := out["open_id_tail"]; tail != "abcdef" {
+		t.Fatalf("open_id_tail = %v，只该给末 6 位", tail)
+	}
+}
+
+func TestFeishuBindCodeLifecycle(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec"})
+
+	// 没申请绑定码就绑：拒绝，且说清楚下一步。
+	if code, out := doJSON(t, s, "POST", "/desk/feishu/bind", map[string]string{"code": "123456", "open_id": "ou_x"}); code != http.StatusBadRequest {
+		t.Fatalf("无码绑定应 400，得到 %d %v", code, out)
+	}
+	code, out := doJSON(t, s, "POST", "/desk/feishu/code", nil)
+	if code != http.StatusOK {
+		t.Fatalf("申请绑定码失败：%d %v", code, out)
+	}
+	bc, _ := out["code"].(string)
+	if len(bc) != 6 || strings.Trim(bc, "0123456789") != "" {
+		t.Fatalf("绑定码应为 6 位数字，得到 %q", bc)
+	}
+	// 绑一次成功（并自动推一条「绑定成功」）。
+	code, out = doJSON(t, s, "POST", "/desk/feishu/bind", map[string]string{"code": bc, "open_id": "ou_7d8a6e6df7621556ce0d21922b676706"})
+	if code != http.StatusOK || out["enabled"] != true {
+		t.Fatalf("绑定失败：%d %v", code, out)
+	}
+	// 同一码再用一次：作废。
+	if code, _ := doJSON(t, s, "POST", "/desk/feishu/bind", map[string]string{"code": bc, "open_id": "ou_aaaaaaaabbbbbbbbccccccccdddddddd"}); code != http.StatusBadRequest {
+		t.Fatalf("绑定码应当一次性，重复使用得到了 %d", code)
+	}
+	st, err := n.load()
+	if err != nil || st.ReceiveID != "ou_7d8a6e6df7621556ce0d21922b676706" || st.ReceiveType != "open_id" || !st.Enabled || st.Code != "" {
+		t.Fatalf("落盘状态不对：%+v err=%v", st, err)
+	}
+	// 权限：状态文件 0600（里面有 secret）。
+	fi, err := os.Stat(n.path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fi.Mode().Perm()&0o077 != 0 {
+		t.Fatalf("状态文件权限过宽：%v", fi.Mode().Perm())
+	}
+}
+
+func TestFeishuBindCodeExpired(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec", Code: "654321", CodeAt: time.Now().Add(-feishuCodeTTL - time.Minute)})
+	code, out := doJSON(t, s, "POST", "/desk/feishu/bind", map[string]string{"code": "654321", "open_id": "ou_7d8a6e6df7621556ce0d21922b676706"})
+	if code != http.StatusBadRequest || !strings.Contains(string(mustJSON(out)), "过期") {
+		t.Fatalf("过期绑定码应 400 并说明过期：%d %v", code, out)
+	}
+}
+
+func TestFeishuPushIdempotentAndTokenCached(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec", OpenID: "ou_me", Enabled: true})
+
+	code, out := doJSON(t, s, "POST", "/desk/feishu/push", map[string]any{"event": "result", "ask_id": "ask-1", "title": "重构登录"})
+	if code != http.StatusOK || out["ok"] != true {
+		t.Fatalf("推送失败：%d %v", code, out)
+	}
+	code, out = doJSON(t, s, "POST", "/desk/feishu/push", map[string]any{"event": "result", "ask_id": "ask-1", "title": "重构登录"})
+	if code != http.StatusOK || out["dupe"] != true {
+		t.Fatalf("同一 ask_id 应判定为重复：%d %v", code, out)
+	}
+	// 另一个事件（待确认）是另一条通知，不该被 result 的去重吃掉。
+	if _, out = doJSON(t, s, "POST", "/desk/feishu/push", map[string]any{"event": "confirm", "ask_id": "ask-1", "title": "重构登录"}); out["ok"] != true || out["dupe"] != nil {
+		t.Fatalf("confirm 应独立推送：%v", out)
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.sent) != 2 {
+		t.Fatalf("应发出 2 条（result + confirm），实际 %d", len(f.sent))
+	}
+	if f.tokenHits != 1 {
+		t.Fatalf("租户令牌应只换一次（缓存），实际 %d 次", f.tokenHits)
+	}
+	if f.sent[0]["receive_id"] != "ou_me" || f.sent[0]["msg_type"] != "interactive" {
+		t.Fatalf("消息体不对：%v", f.sent[0])
+	}
+	if c, _ := f.sent[0]["content"].(string); !strings.Contains(c, "重构登录") || !strings.Contains(c, "任务完成") {
+		t.Fatalf("卡片里缺标题：%s", c)
+	}
+}
+
+func TestFeishuPushRetriesThenReleasesKey(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec", OpenID: "ou_me", Enabled: true})
+
+	// 前 3 次都失败 → 这一次推送彻底失败（3 次尝试全用掉）。
+	f.failNext = feishuSendAttempts
+	code, out := doJSON(t, s, "POST", "/desk/feishu/push", map[string]any{"event": "result", "ask_id": "ask-2", "title": "x"})
+	if code != http.StatusBadGateway {
+		t.Fatalf("最终失败应回 502，得到 %d %v", code, out)
+	}
+	// 键必须释放：网络恢复后同一 ask_id 还能再推（否则「失败一次就永远不推」）。
+	if code, out := doJSON(t, s, "POST", "/desk/feishu/push", map[string]any{"event": "result", "ask_id": "ask-2", "title": "x"}); code != http.StatusOK || out["ok"] != true {
+		t.Fatalf("失败后重推应成功：%d %v", code, out)
+	}
+	// 最近记录里要能看到那次失败（排障用）。
+	st, _ := n.load()
+	if len(st.Recent) == 0 || st.Recent[len(st.Recent)-1].OK != true {
+		t.Fatalf("推送记录不对：%+v", st.Recent)
+	}
+	found := false
+	for _, r := range st.Recent {
+		if !r.OK && r.Attempt == feishuSendAttempts {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("失败记录没落盘：%+v", st.Recent)
+	}
+}
+
+func TestFeishuPushDisabledIsNotAnError(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec", OpenID: "ou_me", Enabled: false})
+	code, out := doJSON(t, s, "POST", "/desk/feishu/push", map[string]any{"event": "result", "ask_id": "a"})
+	if code != http.StatusOK || out["disabled"] != true {
+		t.Fatalf("关闭推送时应 200 + disabled（不是报错）：%d %v", code, out)
+	}
+}
+
+func TestFeishuConfigValidatesBeforeSaving(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+
+	// 错 secret：先验再存，一个字都不写。
+	f.badToken = true
+	if code, out := doJSON(t, s, "POST", "/desk/feishu/config", map[string]string{"app_id": "cli_x", "app_secret": "bad"}); code != http.StatusBadRequest {
+		t.Fatalf("错凭据应 400：%d %v", code, out)
+	}
+	if st, _ := n.load(); st.AppID != "" || st.AppSecret != "" {
+		t.Fatalf("校验失败不应落盘：%+v", st)
+	}
+	f.badToken = false
+	if code, out := doJSON(t, s, "POST", "/desk/feishu/config", map[string]string{"app_id": "cli_x", "app_secret": "good"}); code != http.StatusOK || out["configured"] != true {
+		t.Fatalf("正确凭据应保存：%d %v", code, out)
+	}
+	// 形如 cli_ 的校验。
+	if code, _ := doJSON(t, s, "POST", "/desk/feishu/config", map[string]string{"app_id": "abc", "app_secret": "s"}); code != http.StatusBadRequest {
+		t.Fatalf("非 cli_ 前缀应 400，得到 %d", code)
+	}
+}
+
+func TestFeishuUnknownAction(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{})
+	if code, _ := doJSON(t, s, "POST", "/desk/feishu/nope", nil); code != http.StatusNotFound {
+		t.Fatalf("未知动作应 404，得到 %d", code)
+	}
+	// 动作类接口只认 POST：GET /desk/feishu/code 不该顺手发码。
+	if code, _ := doJSON(t, s, "GET", "/desk/feishu/code", nil); code != http.StatusMethodNotAllowed {
+		t.Fatalf("GET 动作接口应 405，得到 %d", code)
+	}
+}
+
+func TestFeishuUnknownEventRejected(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec", OpenID: "ou_me", Enabled: true})
+	code, out := doJSON(t, s, "POST", "/desk/feishu/push", map[string]any{"event": "whatever", "ask_id": "a"})
+	if code != http.StatusBadGateway || !strings.Contains(string(mustJSON(out)), "未知的推送事件") {
+		t.Fatalf("未知事件应报错：%d %v", code, out)
+	}
+}
+
+/*
+2026-10-26 用户实测报障：「填了 ou_me 也绑上了，然后一条都推不出去」。
+
+	两个问题各自一条用例钉住：① 占位符不能当 open_id 收下；② 用邮箱绑定时必须
+	按 receive_id_type=email 发（飞书的 open_id 是应用维度的，跨应用抄一个必然失败）。
+*/
+func TestFeishuBindRejectsPlaceholderOpenID(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec"})
+	_, out := doJSON(t, s, "POST", "/desk/feishu/code", nil)
+	code := out["code"].(string)
+
+	status, out := doJSON(t, s, "POST", "/desk/feishu/bind", map[string]string{"code": code, "open_id": "ou_me"})
+	if status != http.StatusBadRequest {
+		t.Fatalf("占位符 open_id 应 400，得到 %d %v", status, out)
+	}
+	msg, _ := out["error"].(string)
+	if !strings.Contains(msg, "不完整") || !strings.Contains(msg, "邮箱") {
+		t.Fatalf("错误提示应说清「不完整」并建议填邮箱：%q", msg)
+	}
+	st, err := n.load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if st.ReceiveID != "" || st.Enabled {
+		t.Fatalf("被拒的绑定不许落盘：%+v", st)
+	}
+}
+
+func TestFeishuBindByEmailSendsToEmail(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec"})
+	_, out := doJSON(t, s, "POST", "/desk/feishu/code", nil)
+	code := out["code"].(string)
+
+	status, out := doJSON(t, s, "POST", "/desk/feishu/bind",
+		map[string]string{"code": code, "to": "someone@company.com"})
+	if status != http.StatusOK {
+		t.Fatalf("邮箱绑定应成功：%d %v", status, out)
+	}
+	if out["to_type"] != "email" {
+		t.Fatalf("to_type 应为 email：%v", out)
+	}
+	f.mu.Lock()
+	if len(f.sent) == 0 {
+		f.mu.Unlock()
+		t.Fatal("绑定成功后应立刻推一条确认卡片")
+	}
+	got := f.sent[0]
+	f.mu.Unlock()
+	if got["receive_id"] != "someone@company.com" || got["__receive_id_type"] != "email" {
+		t.Fatalf("应按邮箱发：%v", got)
+	}
+
+	st, err := n.load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if st.ReceiveID != "someone@company.com" || st.ReceiveType != "email" || !st.Enabled || st.Code != "" {
+		t.Fatalf("状态不对：%+v", st)
+	}
+
+	// 状态接口给的是**打过码**的收件人
+	_, stOut := doJSON(t, s, "GET", "/desk/feishu", nil)
+	if stOut["bound_to"] != "s***@company.com" || stOut["bound_type"] != "email" {
+		t.Fatalf("状态里的收件人应打码：%v", stOut)
+	}
+}
+
+func TestFeishuLegacyOpenIDStateStillPushes(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	// 老状态文件：只有 open_id，没有 receive_id/type
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec", OpenID: "ou_1234567890abcdef", Enabled: true})
+	if code, out := doJSON(t, s, "POST", "/desk/feishu/push",
+		map[string]string{"event": "result", "ask_id": "a1", "title": "老状态"}); code != http.StatusOK {
+		t.Fatalf("老状态文件必须照旧能推：%d %v", code, out)
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.sent) != 1 || f.sent[0]["__receive_id_type"] != "open_id" || f.sent[0]["receive_id"] != "ou_1234567890abcdef" {
+		t.Fatalf("应回落成 open_id 发送：%v", f.sent)
+	}
+}
+
+/* ── 群自定义机器人（2026-10-26 用户：「为什么需要邮箱啊」）── */
+
+// 签名算法钉住：以 `timestamp + "\n" + secret` 为密钥对**空串**做 HMAC-SHA256 再 base64。
+// 这里用固定输入算一遍，防止以后有人改成「对 body 签名」（那是另一套协议，飞书不认）。
+func TestFeishuWebhookSignMatchesFeishuSpec(t *testing.T) {
+	// 独立算一遍，不看被测函数的中间量。
+	mac := hmac.New(sha256.New, []byte("1599360473\nmy-secret"))
+	mac.Write(nil)
+	want := base64.StdEncoding.EncodeToString(mac.Sum(nil))
+	if got := feishuWebhookSign("1599360473", "my-secret"); got != want {
+		t.Fatalf("签名不符：got %s want %s", got, want)
+	}
+	// 换个 secret 必须变（防止「忘了用 secret」这种恒等错误）
+	if feishuWebhookSign("1599360473", "other") == want {
+		t.Fatal("secret 没参与签名")
+	}
+}
+
+func TestFeishuWebhookRejectsNonBotURL(t *testing.T) {
+	_, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{})
+	for _, bad := range []string{
+		"https://example.com/hook/abc",           // 不是飞书
+		"https://open.feishu.cn/open-apis/im/v1", // 飞书，但不是自定义机器人
+		"",                                       // 空
+		strings.TrimRight(srv.URL, "/") + "/wrong", // 测试替身也不许乱指
+	} {
+		if code, _ := doJSON(t, s, "POST", "/desk/feishu/webhook", map[string]string{"webhook": bad}); code != http.StatusBadRequest {
+			t.Fatalf("%q 应被拒，得到 %d", bad, code)
+		}
+	}
+	st, _ := n.load()
+	if st.Webhook != "" {
+		t.Fatalf("被拒的地址不许落盘：%+v", st)
+	}
+}
+
+func TestFeishuWebhookBindSendsCardWithLinkAndStatus(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	s.opts.Token = "tok-abc"
+	s.opts.Lan = false
+	seedState(t, n, feishuState{})
+
+	// 真地址形状（假服务器只按 path 匹配，所以这里换成它自己的地址 + 同一段 path）
+	hook := srv.URL + "/open-apis/bot/v2/hook/fake-token"
+	code, out := doJSON(t, s, "POST", "/desk/feishu/webhook", map[string]string{
+		"webhook": hook, "webhook_secret": "my-secret", "url": srv.URL,
+	})
+	if code != http.StatusOK {
+		t.Fatalf("绑定应成功：%d %v", code, out)
+	}
+	if out["mode"] != "webhook" || out["bound"] != true || out["configured"] != true {
+		t.Fatalf("状态不对：%v", out)
+	}
+
+	f.mu.Lock()
+	sent := append([]map[string]any(nil), f.webhookSent...)
+	f.mu.Unlock()
+	if len(sent) != 1 {
+		t.Fatalf("绑定应立刻发一条测试卡片，实际 %d", len(sent))
+	}
+	got := sent[0]
+	if got["timestamp"] == nil || got["sign"] == nil {
+		t.Fatalf("配了签名密钥就必须带 timestamp + sign：%v", got)
+	}
+	card, _ := got["card"].(map[string]any)
+	if card == nil {
+		t.Fatalf("webhook 的卡片应放在 card 字段里：%v", got)
+	}
+	raw, _ := json.Marshal(card)
+	if !strings.Contains(string(raw), "tok-abc") {
+		t.Fatalf("卡片里应带上「打开」链接（含令牌）：%s", raw)
+	}
+
+	// 之后 push 走同一条通道，且同一 ask_id 只推一次
+	if code, out := doJSON(t, s, "POST", "/desk/feishu/push",
+		map[string]string{"event": "result", "ask_id": "a1", "title": "跑完了", "url": srv.URL}); code != http.StatusOK {
+		t.Fatalf("webhook 推送应成功：%d %v", code, out)
+	}
+	_, out = doJSON(t, s, "POST", "/desk/feishu/push", map[string]string{"event": "result", "ask_id": "a1"})
+	if out["dupe"] != true {
+		t.Fatalf("第二次应判重：%v", out)
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.webhookSent) != 2 {
+		t.Fatalf("绑定 1 条 + 推送 1 条 = 2，实际 %d", len(f.webhookSent))
+	}
+}
+
+func TestFeishuWebhookTestMessageCarriesAddress(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	s.opts.Token = "tok-xyz"
+	seedState(t, n, feishuState{Webhook: srv.URL + "/open-apis/bot/v2/hook/x", Enabled: true})
+	if code, out := doJSON(t, s, "POST", "/desk/feishu/test", map[string]string{"url": srv.URL}); code != http.StatusOK {
+		t.Fatalf("测试消息应成功：%d %v", code, out)
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	raw, _ := json.Marshal(f.webhookSent[len(f.webhookSent)-1])
+	if !strings.Contains(string(raw), srv.URL) || !strings.Contains(string(raw), "tok-xyz") {
+		t.Fatalf("测试消息应带上当前入口地址：%s", raw)
+	}
+}
+
+/*
+2026-10-26 用户定调：「改为直接绑定会话 id 即可」—— oc_ 开头的群/单聊，
+
+	推送时 receive_id_type 必须是 chat_id（不是 open_id，也不是 email）。
+*/
+func TestFeishuBindByChatIDSendsToChat(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	seedState(t, n, feishuState{AppID: "cli_abc", AppSecret: "sec"})
+	_, out := doJSON(t, s, "POST", "/desk/feishu/code", nil)
+	code := out["code"].(string)
+
+	const chat = "oc_a90ab20986ffccf22b95939a1a8ce2a4"
+	status, out := doJSON(t, s, "POST", "/desk/feishu/bind", map[string]string{"code": code, "to": chat})
+	if status != http.StatusOK {
+		t.Fatalf("会话 id 绑定应成功：%d %v", status, out)
+	}
+	if out["to_type"] != "chat_id" {
+		t.Fatalf("to_type 应为 chat_id：%v", out)
+	}
+	f.mu.Lock()
+	got := f.sent[0]
+	f.mu.Unlock()
+	if got["receive_id"] != chat || got["__receive_id_type"] != "chat_id" {
+		t.Fatalf("应按 chat_id 发：%v", got)
+	}
+	// 状态里只留末 6 位，别把整串会话 id 甩给页面
+	_, stOut := doJSON(t, s, "GET", "/desk/feishu", nil)
+	if stOut["bound_to"] != "…8ce2a4" || stOut["bound_type"] != "chat_id" {
+		t.Fatalf("状态里的会话 id 应打码：%v", stOut)
+	}
+}
+
+/*
+2026-10-26 用户实测：「发送的消息中的访问连接地址不对 无法访问」。
+
+	根因是缓存里的公网域名属于**上一轮隧道**（cloudflared 重启就换域名，老域名 TCP 都不通）。
+	所以：只有回打 /desk/health 通了才写进卡片；全都不通就不放链接。
+*/
+func TestFeishuLinkOnlyUsesReachableAddress(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	s.opts.Token = "tok-live"
+
+	// 缓存里躺着一个死域名（.invalid 立即解析失败），手机报的入口是通的。
+	s.pubMu.Lock()
+	s.pubURL = "https://stale-tunnel.invalid"
+	s.pubExp = time.Now().Add(time.Hour)
+	s.pubLoaded = true
+	s.pubMu.Unlock()
+	link := s.feishuLink(context.Background(), srv.URL)
+	if !strings.HasPrefix(link, srv.URL) || !strings.Contains(link, "tok-live") {
+		t.Fatalf("应跳过死域名、用手机报的入口：%q", link)
+	}
+
+	// 全都不通 → 空串（卡片不带按钮），而不是发一个打不开的门。
+	s.pubMu.Lock()
+	s.pubURL = ""
+	s.pubMu.Unlock()
+	if got := s.feishuLink(context.Background(), "http://10.255.255.1:9"); got != "" {
+		t.Fatalf("没有可用地址时应返回空：%q", got)
+	}
+
+	// 走一遍真实发送：带链接时卡片里有 action 按钮，无链接时没有。
+	f.mu.Lock()
+	f.webhookSent = nil
+	f.mu.Unlock()
+	seedState(t, n, feishuState{Webhook: srv.URL + "/open-apis/bot/v2/hook/x", Enabled: true})
+	if code, _ := doJSON(t, s, "POST", "/desk/feishu/test", map[string]string{"url": srv.URL}); code != http.StatusOK {
+		t.Fatalf("测试消息应成功")
+	}
+	f.mu.Lock()
+	raw, _ := json.Marshal(f.webhookSent[len(f.webhookSent)-1])
+	f.mu.Unlock()
+	if !strings.Contains(string(raw), "动作") && !strings.Contains(string(raw), "action") {
+		t.Fatalf("通了就应该带按钮：%s", raw)
+	}
+}
+
+/* ── 启动通知（2026-10-26 用户：「重新启动后如果绑定了飞书 触发一下发送访问地址」）── */
+
+// 绑了飞书 + 有可用入口 → 启动后推一条带地址的卡片。
+func TestFeishuStartupPushesAccessAddress(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	s.opts.Token = "tok-start"
+	seedState(t, n, feishuState{Webhook: srv.URL + "/open-apis/bot/v2/hook/x", Enabled: true})
+
+	// 只试一次：用例不该为了等隧道真睡一分半。
+	oldDelays := feishuStartupDelays
+	feishuStartupDelays = []time.Duration{0}
+	t.Cleanup(func() { feishuStartupDelays = oldDelays })
+
+	s.NotifyStartup(srv.URL + "/?token=tok-start")
+
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.webhookSent) != 1 {
+		t.Fatalf("启动后应推一条，实际 %d", len(f.webhookSent))
+	}
+	raw, _ := json.Marshal(f.webhookSent[0])
+	if !strings.Contains(string(raw), "tok-start") || !strings.Contains(string(raw), "地址") {
+		t.Fatalf("卡片里应带上当前访问地址（含令牌）：%s", raw)
+	}
+}
+
+// 没绑定 / 关了推送 → 启动时一个请求都不发（启动不该产生出站流量）。
+func TestFeishuStartupSilentWhenUnboundOrDisabled(t *testing.T) {
+	f, srv := newFakeFeishu(t)
+	s, n := newFeishuService(t, srv.URL)
+	s.opts.Token = "tok-start"
+
+	oldDelays := feishuStartupDelays
+	feishuStartupDelays = []time.Duration{0}
+	t.Cleanup(func() { feishuStartupDelays = oldDelays })
+
+	// 还没绑定
+	seedState(t, n, feishuState{})
+	s.NotifyStartup(srv.URL + "/?token=tok-start")
+
+	// 绑了但用户关掉了
+	seedState(t, n, feishuState{Webhook: srv.URL + "/open-apis/bot/v2/hook/x", Enabled: false})
+	s.NotifyStartup(srv.URL + "/?token=tok-start")
+
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.webhookSent) != 0 || f.tokenHits != 0 {
+		t.Fatalf("没绑定 / 关了推送时不应有出站请求：webhook=%d token=%d", len(f.webhookSent), f.tokenHits)
+	}
+}