feat(notify): 企业微信+飞书群机器人渠道——补齐国内三巨头（钉钉/企业微信/飞书），飞书支持官方加签

Author: cuihairu

internal/api/sitesettings/handler.go

@@ -166,7 +166,8 @@ func validateValue(key string, raw json.RawMessage) error {
 			return fmt.Errorf("%s 需要是 http(s) URL", key)
 		}
 	}
-	if key == settings.KeyNotifyDingtalkURL || key == settings.KeyNotifyWebhookURL {
+	if key == settings.KeyNotifyDingtalkURL || key == settings.KeyNotifyWebhookURL ||
+		key == settings.KeyNotifyWecomURL || key == settings.KeyNotifyFeishuURL {
 		if v != "" && !isHTTPLikeURL(v) {
 			return fmt.Errorf("%s 需要是 http(s) URL", key)
 		}

internal/platform/approvals/notification.go

@@ -45,6 +45,8 @@ const (
 	ChannelDingTalk  NotificationChannel = "dingtalk"
 	ChannelWeChat    NotificationChannel = "wechat"
 	ChannelSlack     NotificationChannel = "slack"
+	ChannelWecom     NotificationChannel = "wecom"
+	ChannelFeishu    NotificationChannel = "feishu"
 	ChannelInApp     NotificationChannel = "in_app"
 )
 
@@ -828,3 +830,96 @@ func validateEmailAddress(addr string) (string, error) {
 	}
 	return parsed.Address, nil
 }
+
+// WecomSender sends 企业微信群机器人 notifications.
+//
+// webhookURL 为群机器人 webhook（https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…）。
+// 企业微信机器人无加签机制，key 由 URL 携带。URL 为空时视为未配置，Send 直接 no-op。
+type WecomSender struct {
+	webhookURL string
+
+	// postJSON 与 DingTalkSender 同款测试注入口。
+	postJSON func(ctx context.Context, url string, payload []byte) error
+}
+
+// NewWecomSender creates a new 企业微信 sender.
+func NewWecomSender(webhookURL string) *WecomSender {
+	return &WecomSender{webhookURL: webhookURL}
+}
+
+// Send posts a markdown message to the group bot.
+func (w *WecomSender) Send(ctx context.Context, recipient string, event NotificationEvent) error {
+	if w.webhookURL == "" {
+		return nil
+	}
+	payload := map[string]interface{}{
+		"msgtype": "markdown",
+		"markdown": map[string]string{
+			"content": fmt.Sprintf("### %s\n\n%s", event.Title, event.Message),
+		},
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return err
+	}
+	postJSON := w.postJSON
+	if postJSON == nil {
+		postJSON = defaultPostJSON
+	}
+	return postJSON(ctx, w.webhookURL, body)
+}
+
+// Channel returns the channel type.
+func (w *WecomSender) Channel() NotificationChannel {
+	return ChannelWecom
+}
+
+// FeishuSender sends 飞书群机器人 notifications.
+//
+// webhookURL 为自定义机器人 webhook（https://open.feishu.cn/open-apis/bot/v2/hook/…）。
+// secret 为可选的加签密钥：官方校验方式为 sign = base64(hmac_sha256(key=timestamp+"\n"+secret, data=""))，
+// payload 顶层附带 timestamp（秒）与 sign。
+type FeishuSender struct {
+	webhookURL string
+	secret     string
+
+	postJSON func(ctx context.Context, url string, payload []byte) error
+}
+
+// NewFeishuSender creates a new 飞书 sender.
+func NewFeishuSender(webhookURL, secret string) *FeishuSender {
+	return &FeishuSender{webhookURL: webhookURL, secret: secret}
+}
+
+// Send posts a text message to the group bot.
+func (f *FeishuSender) Send(ctx context.Context, recipient string, event NotificationEvent) error {
+	if f.webhookURL == "" {
+		return nil
+	}
+	payload := map[string]interface{}{
+		"msg_type": "text",
+		"content": map[string]string{
+			"text": fmt.Sprintf("%s\n%s", event.Title, event.Message),
+		},
+	}
+	if f.secret != "" {
+		ts := time.Now().Unix()
+		mac := hmac.New(sha256.New, []byte(fmt.Sprintf("%d\n%s", ts, f.secret)))
+		payload["timestamp"] = fmt.Sprintf("%d", ts)
+		payload["sign"] = base64.StdEncoding.EncodeToString(mac.Sum(nil))
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return err
+	}
+	postJSON := f.postJSON
+	if postJSON == nil {
+		postJSON = defaultPostJSON
+	}
+	return postJSON(ctx, f.webhookURL, body)
+}
+
+// Channel returns the channel type.
+func (f *FeishuSender) Channel() NotificationChannel {
+	return ChannelFeishu
+}

internal/platform/approvals/notification_extra_test.go

@@ -2,6 +2,10 @@ package approvals
 
 import (
 	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
 	"errors"
 	"io"
 	"net/http"
@@ -372,3 +376,68 @@ func TestEmailSender_SendRejectsInjectedRecipient(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "invalid email recipient")
 }
+
+// 企业微信：markdown 载荷、无加签、URL 原样。
+func TestWecomSender_Payload(t *testing.T) {
+	var gotURL string
+	var gotBody []byte
+	w := NewWecomSender("https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=k1")
+	w.postJSON = func(ctx context.Context, url string, payload []byte) error {
+		gotURL, gotBody = url, payload
+		return nil
+	}
+	require.NoError(t, w.Send(context.Background(), "", NotificationEvent{
+		Title: "审批待办", Message: "订单退款需要审批",
+	}))
+	assert.Equal(t, "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=k1", gotURL)
+	assert.Contains(t, string(gotBody), `"msgtype":"markdown"`)
+	assert.Contains(t, string(gotBody), "审批待办")
+	assert.Equal(t, ChannelWecom, w.Channel())
+
+	// 未配置 URL：no-op
+	idle := NewWecomSender("")
+	assert.NoError(t, idle.Send(context.Background(), "", NotificationEvent{Title: "x"}))
+}
+
+// 飞书：text 载荷 + 加签（timestamp/sign 顶层字段，签名可复现校验）。
+func TestFeishuSender_PayloadAndSign(t *testing.T) {
+	var gotURL string
+	var gotBody []byte
+	f := NewFeishuSender("https://open.feishu.cn/open-apis/bot/v2/hook/h1", "sec-1")
+	f.postJSON = func(ctx context.Context, url string, payload []byte) error {
+		gotURL, gotBody = url, payload
+		return nil
+	}
+	require.NoError(t, f.Send(context.Background(), "", NotificationEvent{
+		Title: "告警", Message: "agent 离线",
+	}))
+	assert.Equal(t, "https://open.feishu.cn/open-apis/bot/v2/hook/h1", gotURL)
+
+	var payload map[string]interface{}
+	require.NoError(t, json.Unmarshal(gotBody, &payload))
+	assert.Equal(t, "text", payload["msg_type"])
+	content := payload["content"].(map[string]interface{})
+	assert.Contains(t, content["text"], "告警")
+	assert.Contains(t, content["text"], "agent 离线")
+
+	// 加签可复现：timestamp + sign 与本地 HMAC 结果一致
+	ts, ok := payload["timestamp"].(string)
+	require.True(t, ok)
+	sign, ok := payload["sign"].(string)
+	require.True(t, ok)
+	mac := hmac.New(sha256.New, []byte(ts+"\nsec-1"))
+	expect := base64.StdEncoding.EncodeToString(mac.Sum(nil))
+	assert.Equal(t, expect, sign)
+	assert.Equal(t, ChannelFeishu, f.Channel())
+
+	// 无密钥：不携带 timestamp/sign
+	noSign := NewFeishuSender("https://open.feishu.cn/hook/h2", "")
+	noSign.postJSON = func(ctx context.Context, url string, payload []byte) error {
+		var p map[string]interface{}
+		require.NoError(t, json.Unmarshal(payload, &p))
+		assert.NotContains(t, p, "sign")
+		assert.NotContains(t, p, "timestamp")
+		return nil
+	}
+	require.NoError(t, noSign.Send(context.Background(), "", NotificationEvent{Title: "x"}))
+}

internal/platform/settings/layered.go

@@ -58,6 +58,9 @@ const (
 	KeyNotifyDingtalkSecret = "notification.dingtalkSecret" // string
 	KeyNotifyWebhookURL     = "notification.webhookUrl"     // string
 	KeyNotifyWebhookSecret  = "notification.webhookSecret"  // string
+	KeyNotifyWecomURL       = "notification.wecomUrl"       // string
+	KeyNotifyFeishuURL      = "notification.feishuUrl"      // string
+	KeyNotifyFeishuSecret   = "notification.feishuSecret"   // string
 	KeyNotifyInAppEnabled   = "notification.inAppEnabled"   // bool
 
 	// 登录方式（外部身份源，L3 运行时配置——Harbor 模式：yaml 仅作
@@ -93,6 +96,7 @@ var ValidKeys = map[string]struct{}{
 	KeyNotifySMTPUser: {}, KeyNotifySMTPPassword: {}, KeyNotifySMTPFrom: {},
 	KeyNotifyDingtalkURL: {}, KeyNotifyDingtalkSecret: {},
 	KeyNotifyWebhookURL: {}, KeyNotifyWebhookSecret: {}, KeyNotifyInAppEnabled: {},
+	KeyNotifyWecomURL: {}, KeyNotifyFeishuURL: {}, KeyNotifyFeishuSecret: {},
 
 	KeyAuthLdapEnabled: {}, KeyAuthLdapAddr: {}, KeyAuthLdapBaseDn: {},
 	KeyAuthLdapBindDn: {}, KeyAuthLdapBindPassword: {}, KeyAuthLdapUserFilter: {},
@@ -406,6 +410,10 @@ type NotificationSnapshot struct {
 	WebhookURL           string            `json:"webhookUrl"`
 	WebhookSecretSet     bool              `json:"webhookSecretSet"`
 	WebhookSecretMasked  string            `json:"webhookSecretMasked,omitempty"`
+	WecomURL             string            `json:"wecomUrl"`
+	FeishuURL            string            `json:"feishuUrl"`
+	FeishuSecretSet      bool              `json:"feishuSecretSet"`
+	FeishuSecretMasked   string            `json:"feishuSecretMasked,omitempty"`
 	InAppEnabled         bool              `json:"inAppEnabled"`
 	Sources              map[string]string `json:"sources"`
 }
@@ -420,6 +428,8 @@ func (l *Layered) NotificationSnapshot() NotificationSnapshot {
 		SMTPFrom:     stringOrEmpty(l.GetString(context.Background(), KeyNotifySMTPFrom)),
 		DingtalkURL:  stringOrEmpty(l.GetString(context.Background(), KeyNotifyDingtalkURL)),
 		WebhookURL:   stringOrEmpty(l.GetString(context.Background(), KeyNotifyWebhookURL)),
+		WecomURL:     stringOrEmpty(l.GetString(context.Background(), KeyNotifyWecomURL)),
+		FeishuURL:    stringOrEmpty(l.GetString(context.Background(), KeyNotifyFeishuURL)),
 		InAppEnabled: l.GetBool(KeyNotifyInAppEnabled, true),
 		Sources:      map[string]string{},
 	}
@@ -437,6 +447,7 @@ func (l *Layered) NotificationSnapshot() NotificationSnapshot {
 	snap.SMTPPasswordSet, snap.SMTPPasswordMasked = mask(KeyNotifySMTPPassword)
 	snap.DingtalkSecretSet, snap.DingtalkSecretMasked = mask(KeyNotifyDingtalkSecret)
 	snap.WebhookSecretSet, snap.WebhookSecretMasked = mask(KeyNotifyWebhookSecret)
+	snap.FeishuSecretSet, snap.FeishuSecretMasked = mask(KeyNotifyFeishuSecret)
 	return snap
 }
 
@@ -468,6 +479,9 @@ type NotifyChannelsResolved struct {
 	DingtalkSecret string
 	WebhookURL     string
 	WebhookSecret  string
+	WecomURL       string
+	FeishuURL      string
+	FeishuSecret   string
 	InAppEnabled   bool
 	EmailEnabled   bool
 }
@@ -479,6 +493,9 @@ func (l *Layered) NotifyChannels() NotifyChannelsResolved {
 		DingtalkSecret: stringOrEmpty(l.GetString(context.Background(), KeyNotifyDingtalkSecret)),
 		WebhookURL:     stringOrEmpty(l.GetString(context.Background(), KeyNotifyWebhookURL)),
 		WebhookSecret:  stringOrEmpty(l.GetString(context.Background(), KeyNotifyWebhookSecret)),
+		WecomURL:       stringOrEmpty(l.GetString(context.Background(), KeyNotifyWecomURL)),
+		FeishuURL:      stringOrEmpty(l.GetString(context.Background(), KeyNotifyFeishuURL)),
+		FeishuSecret:   stringOrEmpty(l.GetString(context.Background(), KeyNotifyFeishuSecret)),
 		InAppEnabled:   l.GetBool(KeyNotifyInAppEnabled, true),
 		EmailEnabled:   l.GetBool(KeyNotifyEmailEnabled, false),
 	}

internal/service/notify/notify_extra_test.go

@@ -9,6 +9,8 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"sync"
+
+	gsqlite "github.com/glebarez/sqlite"
 	"testing"
 
 	"github.com/cuihairu/croupier/internal/model"
@@ -155,3 +157,44 @@ func TestDispatch_OnlyLayeredNoMessageModel(t *testing.T) {
 		svc.Dispatch(context.Background(), notifyservice.Event{Title: "t", Recipients: []string{"a"}})
 	})
 }
+
+// 企业微信/飞书渠道接线：配置 URL 后 dispatchExternal 投递两渠道。
+func TestDispatchExternal_WecomAndFeishu(t *testing.T) {
+	var wecomBody, feishuBody []byte
+	wecomSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		wecomBody, _ = io.ReadAll(r.Body)
+		w.WriteHeader(200)
+	}))
+	defer wecomSrv.Close()
+	feishuSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		feishuBody, _ = io.ReadAll(r.Body)
+		w.WriteHeader(200)
+	}))
+	defer feishuSrv.Close()
+
+	settings.ResetForTest()
+	db, err := gorm.Open(gsqlite.Open(t.TempDir()+"/notify-wf.db"), &gorm.Config{})
+	require.NoError(t, err)
+	require.NoError(t, model.AutoMigrate(db))
+	settingStore := model.NewPlatformSettingModel(db)
+	layered := settings.InitLayered(context.Background(), &settings.ConfigInput{}, settingStore)
+	setStr := func(key, val string) {
+		require.NoError(t, settingStore.Set(context.Background(), key, json.RawMessage(`"`+val+`"`), "test"))
+		layered.Reload(context.Background(), settingStore)
+	}
+	setStr("notification.wecomUrl", wecomSrv.URL)
+	setStr("notification.feishuUrl", feishuSrv.URL)
+	setStr("notification.feishuSecret", "s")
+
+	svc := notifyservice.New(layered, nil)
+	svc.Dispatch(context.Background(), notifyservice.Event{
+		Type: "approval_required", Title: "T", Message: "M",
+	})
+
+	require.NotEmpty(t, wecomBody, "wecom 应收到投递")
+	assert.Contains(t, string(wecomBody), `"msgtype":"markdown"`)
+	assert.Contains(t, string(wecomBody), "T")
+
+	require.NotEmpty(t, feishuBody, "feishu 应收到投递")
+	assert.Contains(t, string(feishuBody), `"msg_type":"text"`)
+}

internal/service/notify/service.go

@@ -3,6 +3,8 @@
 // 渠道矩阵（docs/architecture/config-layering.md notification.*）：
 //   - 站内信（默认开启）：写 messages 表 + SSE 推送，复用 message 模块
 //   - 钉钉群机器人：notification.dingtalkUrl/Secret 配置后启用
+//   - 企业微信群机器人：notification.wecomUrl 配置后启用（无加签，key 在 URL）
+//   - 飞书群机器人：notification.feishuUrl/Secret 配置后启用（加签可选）
 //   - 通用 webhook：notification.webhookUrl/Secret 配置后启用
 //   - 邮件：notification.emailEnabled + smtp.* 配置后启用
 //
@@ -105,6 +107,18 @@ func (s *Service) dispatchExternal(ctx context.Context, ev Event) {
 			slog.WarnContext(ctx, "notify: dingtalk send failed", "error", err)
 		}
 	}
+	if ch.WecomURL != "" {
+		sender := approvals.NewWecomSender(ch.WecomURL)
+		if err := sender.Send(ctx, "", approvalEvent); err != nil {
+			slog.WarnContext(ctx, "notify: wecom send failed", "error", err)
+		}
+	}
+	if ch.FeishuURL != "" {
+		sender := approvals.NewFeishuSender(ch.FeishuURL, ch.FeishuSecret)
+		if err := sender.Send(ctx, "", approvalEvent); err != nil {
+			slog.WarnContext(ctx, "notify: feishu send failed", "error", err)
+		}
+	}
 	if ch.WebhookURL != "" {
 		sender := approvals.NewWebhookSender(ch.WebhookURL, ch.WebhookSecret, "croupier")
 		if err := sender.Send(ctx, joinRecipients(ev.Recipients), approvalEvent); err != nil {

sdks/cpp/include/croupier/sdk/protocol.h

@@ -42,6 +42,10 @@ constexpr uint32_t MSG_HEARTBEAT_RESPONSE = 0x010104;
 constexpr uint32_t MSG_REGISTER_CAPABILITIES_REQ = 0x010105;
 constexpr uint32_t MSG_REGISTER_CAPABILITIES_RESP = 0x010106;
 
+// F：文件下发原语（hotpatch P1 传输层）
+constexpr uint32_t MSG_PROVIDER_FILE_PUSH_REQ = 0x050109;
+constexpr uint32_t MSG_PROVIDER_FILE_PUSH_RESP = 0x05010A;
+
 // ClientService (0x02xx)
 constexpr uint32_t MSG_REGISTER_CLIENT_REQUEST = 0x020101;
 constexpr uint32_t MSG_REGISTER_CLIENT_RESPONSE = 0x020102;

sdks/cpp/vcpkg.json

@@ -17,6 +17,9 @@
     },
     {
       "name": "zlib"
+    },
+    {
+      "name": "openssl"
     }
   ],
   "overrides": [

sdks/java/src/main/java/io/github/cuihairu/croupier/sdk/ClientConfig.java

@@ -53,6 +53,7 @@ public class ClientConfig {
     private boolean enableFileTransfer = false;  // Enable file transfer functionality (default: false)
     private boolean validateInputPayloads = false; // F：provider 侧入站校验（按函数声明 input schema），默认关闭
     private int maxFileSize = 10485760;         // Max file size in bytes (default: 10MB)
+    private String fileStagingDir = "./croupier-staging"; // F：下发文件仅落盘至此（不自动应用）
 
     // ========== Logging Configuration ==========
     private boolean disableLogging = false;  // Disable all logging
@@ -135,6 +136,9 @@ public ClientConfig(String gameId, String serviceId) {
     public int getMaxFileSize() { return maxFileSize; }
     public void setMaxFileSize(int maxFileSize) { this.maxFileSize = maxFileSize; }
 
+    public String getFileStagingDir() { return fileStagingDir; }
+    public void setFileStagingDir(String fileStagingDir) { this.fileStagingDir = fileStagingDir; }
+
     public boolean isDisableLogging() { return disableLogging; }
     public void setDisableLogging(boolean disableLogging) { this.disableLogging = disableLogging; }