feat(feishu): harden ingress relay and decisions

Author: xiaojilele-glitch

README.md

@@ -130,12 +130,40 @@ export default defineConfig({
     messageFormat: 'text',
     appId: process.env.FEISHU_APP_ID,
     appSecret: process.env.FEISHU_APP_SECRET,
+    webhookVerificationToken: process.env.FEISHU_WEBHOOK_VERIFICATION_TOKEN,
+    webhookEncryptKey: process.env.FEISHU_WEBHOOK_ENCRYPT_KEY,
+    webhookMaxSkewSeconds: 300,
+    webhookDedupTtlSeconds: 600,
+    relaySecret: process.env.OPENCLAW_RELAY_SECRET,
+    relayMaxSkewSeconds: 300,
+    relayNonceTtlSeconds: 600,
+    deliveryMaxRetries: 2,
+    deliveryRetryBaseMs: 300,
+    deliveryRetryMaxMs: 5000,
     baseTaskUrl: process.env.OPENCLAW_FEISHU_PROGRESS_BASE_TASK_URL ?? 'http://127.0.0.1:8765',
     progressThrottlePercent: 15,
   },
 });
 ```
 
+如果配置了 `feishu.relaySecret`，OpenClaw 调用 `/api/feishu/relay` 与 `/api/feishu/relay/event` 时必须附带：
+
+- `x-openclaw-timestamp`
+- `x-openclaw-nonce`
+- `x-openclaw-signature`
+
+签名内容为 `METHOD + path + timestamp + nonce + stable JSON body` 的 HMAC-SHA256。
+
+如果配置了 `feishu.webhookEncryptKey`，飞书事件订阅调用 `/api/feishu/webhook` 时会校验：
+
+- `x-lark-request-timestamp`
+- `x-lark-request-nonce`
+- `x-lark-signature`
+
+如果同时配置了 `feishu.webhookVerificationToken`，还会校验回调体中的 token。事件去重状态会持久化到 `.opencroc/feishu-webhook-dedup.json`，这样服务重启后 TTL 内的重复投递仍会被拦截。
+
+出站发消息与卡片更新默认会对 `429/5xx/网络错误` 做有限次指数退避重试，可用 `deliveryMaxRetries`、`deliveryRetryBaseMs`、`deliveryRetryMaxMs` 调整。
+
 启动服务：
 
 开发态直启：

docs/roadmap.md

@@ -31,9 +31,9 @@
 - 已完成：Topic 基座（strict-by-thread）：为每个 Feishu/OpenClaw 对话线程生成确定性的 `topicId`，并禁止跨 `topicId` 的自动关联，避免“莫名其妙把两件事混在一起”
 - 已完成：详情页增强：在 `/tasks/:id` 详情中展示该话题的机器人 roster 与话题任务串（基于 `topicId` / 星球关系）
 - 已完成：手动关联作为补充：支持手动把不同话题的任务用星球关系关联（等价 topic merge 的最小形态）
-- 进行中：`/api/feishu/webhook` 的安全校验与幂等去重“可持久”：当前已有进程内去重，重启后 TTL 持久去重与完整安全校验尚未闭环
-- 未开始：`/api/feishu/relay` 与 `/api/feishu/relay/event` 增加最小鉴权（共享密钥/HMAC），并有回放保护（timestamp/nonce）
-- 未开始：出站投递稳态：对 429/5xx/网络抖动的重试退避策略明确，可配置，且不会造成无限重试与消息风暴
+- 已完成：`/api/feishu/webhook` 的安全校验与幂等去重“可持久”：支持 verification token / signature 校验，且重启后 TTL 内仍可持续去重
+- 已完成：`/api/feishu/relay` 与 `/api/feishu/relay/event` 增加最小鉴权（共享密钥/HMAC），并有回放保护（timestamp/nonce）
+- 已完成：出站投递稳态：对 429/5xx/网络抖动的重试退避策略明确，可配置，且不会造成无限重试与消息风暴
 
 交付（主线 B：OpenCroc scan/pipeline）
 
@@ -42,7 +42,7 @@
 
 Sprint 1 DoD（验收）
 
-- 未开始：针对 webhook/relay 鉴权与去重的单测覆盖完成，并在 CI 里跑
+- 已完成：针对 webhook/relay 鉴权与去重的单测覆盖完成，并在 CI 里跑
 - 进行中：本地 smoke：能在飞书看到 ACK -> 多次 progress -> done/failed（主链路已具备，含重试场景的闭环未完成）
 - 进行中：文档：新增/更新“鉴权配置与部署注意事项”小节（已有 Troubleshooting / systemd 基础，未形成鉴权专节）
 
@@ -53,7 +53,7 @@ Sprint 1 DoD（验收）
 交付（主线 A：飞书卡片交互）
 
 - 进行中：`waiting` 状态生成带按钮的卡片（例如：继续执行/停止/只生成报告/仅 scan），并支持回调；当前已有 waiting 卡片骨架，缺少决策按钮回调
-- 未开始：增加决策提交接口（例如：`POST /api/tasks/:id/decision`），支持 option id 与可选 free text
+- 已完成：增加决策提交接口（例如：`POST /api/tasks/:id/decision`），支持 option id 与可选 free text
 - 进行中：卡片 `card-live` 原地更新：基础更新能力已存在，但尚未接入完整决策流
 - 未开始：Topic 决策门禁：机器人自动产出“会影响外部/会写入产物/会修改代码”的内容时，必须先进入 `waiting`，由你在飞书卡片里确认
 
@@ -65,7 +65,7 @@ Sprint 1 DoD（验收）
 Sprint 2 DoD（验收）
 
 - 未开始：一条完整流程：飞书触发 -> 进入 waiting -> 点按钮 -> 任务继续 -> 最终在飞书收到完成摘要 + 任务链接
-- 未开始：决策回调与任务状态变更有单测（含重复点击/重复回调幂等）
+- 进行中：决策回调与任务状态变更有单测（决策提交与状态恢复测试已补，重复点击/重复回调幂等仍待完成）
 
 ## Sprint 3（2026-04-20 ~ 2026-05-03）：可观测性与生产部署一键化（进行中）
 

docs/troubleshooting.md

@@ -16,18 +16,25 @@
 - 确认飞书应用权限与范围：机器人是否有发消息权限，是否能在目标群/私聊中发言。
 - 确认 `OPENCLAW_FEISHU_PROGRESS_BASE_TASK_URL` 可被飞书用户访问，否则卡片/文本里的“任务详情链接”会打不开。
 - 如果使用 `messageFormat: 'card-live'`：需要能成功拿到 `message_id` 并允许 PATCH 更新；否则会退化为多条消息。
-- 如果出现 429：属于飞书限流，需要降低更新频率或启用退避重试策略。
+- 如果出现 429：当前版本会做有限次退避重试；如果仍失败，需要降低更新频率，或调大 `deliveryRetryBaseMs` / `deliveryRetryMaxMs`。
 
 ## Webhook 收不到或验签失败
 
 - 确认飞书事件订阅 URL 指向 `/api/feishu/webhook`，并能通过公网访问。
 - 首次校验会发送 `url_verification`，服务需要正确回传 challenge。
-- 若启用了验签/加密：确保配置的 token/key 与飞书后台一致。
+- 若启用了 `feishu.webhookVerificationToken`：确保它和飞书事件订阅后台的 verification token 一致。
+- 若启用了 `feishu.webhookEncryptKey`：确认飞书请求里带有 `x-lark-request-timestamp`、`x-lark-request-nonce`、`x-lark-signature`，并且 encrypt key 与后台一致。
+- 如果报时间戳过期：检查服务器时钟偏差，或适当调大 `webhookMaxSkewSeconds`。
+- 如果怀疑重复事件没有挡住：检查 `.opencroc/feishu-webhook-dedup.json` 是否可写，服务重启后去重状态会从这里恢复。
 
 ## relay 进度能进来但飞书不更新
 
+- 如果启用了 `feishu.relaySecret`：确认 OpenClaw 已发送 `x-openclaw-timestamp`、`x-openclaw-nonce`、`x-openclaw-signature` 三个请求头。
+- 确认 OpenClaw 与本服务机器时钟偏差不要超过 `relayMaxSkewSeconds`，否则会被当成过期请求拦截。
+- 如果出现 409：通常是相同 `timestamp + nonce` 被重复发送，属于回放保护命中。
 - 检查 `/api/feishu/relay/event` 是否成功返回（是否被鉴权拦截、是否 4xx/5xx）。
 - 检查任务是否已 bind 到飞书（`chatId` 是否正确；是否记录了 `messageId` 用于 live update）。
+- 如果飞书 API 偶发 429/5xx 或网络错误：确认 `deliveryMaxRetries`、`deliveryRetryBaseMs`、`deliveryRetryMaxMs` 是否配置合理。
 - 如果 OpenClaw 负责最终答案：确保 relay start 时设置 `finalAnswerSource=openclaw`，避免重复发送最终摘要。
 
 ## Studio 页面没数据

src/server/croc-office.ts

@@ -3,7 +3,7 @@ import type { OpenCrocConfig, PipelineRunResult, GeneratedTestFile, ExecutionMet
 import type { BackendStatus, ExecutionQualityGateResult, ExecutionRunMode, AuthStatus } from '../execution/types.js';
 import type { ScanResult } from '../graph/types.js';
 import type { SummonPlan } from '../agents/task-router.js';
-import { TaskStore, type TaskDecisionPrompt, type TaskRecord } from './task-store.js';
+import { TaskStore, type TaskDecisionPrompt, type TaskDecisionSubmission, type TaskRecord } from './task-store.js';
 import type { FeishuProgressBridge, FeishuTaskTarget } from './feishu-bridge.js';
 import { buildProjectChatAnswer, collectProjectChatSnapshot } from './chat-analysis.js';
 
@@ -269,6 +269,12 @@ export class CrocOffice {
     return task;
   }
 
+  async submitTaskDecision(taskId: string, submission: TaskDecisionSubmission, waitForDelivery = false): Promise<TaskRecord | undefined> {
+    const task = this.taskStore.resolveWaiting(taskId, submission);
+    await this.emitTaskUpdate(task, waitForDelivery);
+    return task;
+  }
+
   getAgents(): CrocAgent[] {
     return this.agents;
   }

src/server/feishu-bridge.ts

@@ -4,6 +4,16 @@ export interface FeishuBridgeConfig {
   enabled?: boolean;
   baseTaskUrl?: string;
   progressThrottlePercent?: number;
+  relaySecret?: string;
+  relayMaxSkewSeconds?: number;
+  relayNonceTtlSeconds?: number;
+  webhookVerificationToken?: string;
+  webhookEncryptKey?: string;
+  webhookMaxSkewSeconds?: number;
+  webhookDedupTtlSeconds?: number;
+  deliveryMaxRetries?: number;
+  deliveryRetryBaseMs?: number;
+  deliveryRetryMaxMs?: number;
   appId?: string;
   appSecret?: string;
   tenantAccessToken?: string;

src/server/feishu-delivery.test.ts

@@ -157,4 +157,112 @@ describe('FeishuApiDelivery', () => {
     expect(String(secondInit.body)).toContain('"root_id":"om_root_1"');
     expect(String(secondInit.body)).toContain('"reply_to_message_id":"om_ack_1"');
   });
+
+  it('retries message delivery on 429 and succeeds without infinite retry', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        headers: new Headers({ 'retry-after': '0' }),
+        text: async () => 'rate limited',
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ code: 0, msg: 'ok', data: { message_id: 'om_retry_1' } }),
+      });
+    global.fetch = fetchMock as typeof fetch;
+    const delivery = new FeishuApiDelivery({
+      enabled: true,
+      mode: 'live',
+      tenantAccessToken: 'tenant_token_xxx',
+      deliveryMaxRetries: 2,
+      deliveryRetryBaseMs: 0,
+      deliveryRetryMaxMs: 0,
+    });
+
+    const receipt = await delivery.send(sampleMessage);
+
+    expect(receipt).toEqual({ messageId: 'om_retry_1', rootId: undefined, threadId: undefined });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('retries message delivery on network failure and succeeds', async () => {
+    const fetchMock = vi.fn()
+      .mockRejectedValueOnce(new Error('network down'))
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ code: 0, msg: 'ok', data: { message_id: 'om_retry_network' } }),
+      });
+    global.fetch = fetchMock as typeof fetch;
+    const delivery = new FeishuApiDelivery({
+      enabled: true,
+      mode: 'live',
+      tenantAccessToken: 'tenant_token_xxx',
+      deliveryMaxRetries: 2,
+      deliveryRetryBaseMs: 0,
+      deliveryRetryMaxMs: 0,
+    });
+
+    const receipt = await delivery.send(sampleMessage);
+
+    expect(receipt).toEqual({ messageId: 'om_retry_network', rootId: undefined, threadId: undefined });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not retry non-retryable 4xx delivery errors', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 400,
+      statusText: 'Bad Request',
+      headers: new Headers(),
+      text: async () => 'invalid payload',
+    });
+    global.fetch = fetchMock as typeof fetch;
+    const delivery = new FeishuApiDelivery({
+      enabled: true,
+      mode: 'live',
+      tenantAccessToken: 'tenant_token_xxx',
+      deliveryMaxRetries: 3,
+      deliveryRetryBaseMs: 0,
+      deliveryRetryMaxMs: 0,
+    });
+
+    await expect(delivery.send(sampleMessage)).rejects.toThrow('Failed to send Feishu message: 400 Bad Request - invalid payload');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries tenant token fetch on 5xx before sending', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 502,
+        statusText: 'Bad Gateway',
+        headers: new Headers(),
+        text: async () => 'upstream error',
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ code: 0, msg: 'ok', tenant_access_token: 'tenant_token_retry', expire: 7200 }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ code: 0, msg: 'ok', data: { message_id: 'om_retry_token' } }),
+      });
+    global.fetch = fetchMock as typeof fetch;
+    const delivery = new FeishuApiDelivery({
+      enabled: true,
+      mode: 'live',
+      appId: 'cli_xxx',
+      appSecret: 'sec_xxx',
+      deliveryMaxRetries: 2,
+      deliveryRetryBaseMs: 0,
+      deliveryRetryMaxMs: 0,
+    });
+
+    const receipt = await delivery.send(sampleMessage);
+
+    expect(receipt).toEqual({ messageId: 'om_retry_token', rootId: undefined, threadId: undefined });
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
 });

src/server/feishu-delivery.ts

@@ -80,6 +80,21 @@ function resolveMessagePayload(message: FeishuOutboundMessage): { msgType: 'text
   };
 }
 
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+function parseRetryAfter(value: string | null): number | null {
+  if (!value) return null;
+  const seconds = Number.parseInt(value, 10);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const until = Date.parse(value);
+  if (Number.isFinite(until)) {
+    return Math.max(0, until - Date.now());
+  }
+  return null;
+}
+
 export class FeishuApiDelivery implements FeishuBridgeDelivery {
   private readonly config: FeishuBridgeConfig;
   private tokenCache: TokenCache | null = null;
@@ -92,6 +107,48 @@ export class FeishuApiDelivery implements FeishuBridgeDelivery {
     return this.config.enabled !== false && this.config.mode === 'live';
   }
 
+  private retryLimit(): number {
+    return Math.max(0, this.config.deliveryMaxRetries ?? 2);
+  }
+
+  private retryBaseMs(): number {
+    return Math.max(0, this.config.deliveryRetryBaseMs ?? 300);
+  }
+
+  private retryMaxMs(): number {
+    return Math.max(this.retryBaseMs(), this.config.deliveryRetryMaxMs ?? 5_000);
+  }
+
+  private async sleep(ms: number): Promise<void> {
+    if (ms <= 0) return;
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  private computeRetryDelay(attempt: number, retryAfterHeader: string | null): number {
+    const hinted = parseRetryAfter(retryAfterHeader);
+    if (hinted !== null) return Math.min(hinted, this.retryMaxMs());
+    const delay = this.retryBaseMs() * (2 ** attempt);
+    return Math.min(delay, this.retryMaxMs());
+  }
+
+  private async fetchWithRetry(input: string, init: RequestInit): Promise<Response> {
+    const maxRetries = this.retryLimit();
+
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        const response = await fetch(input, init);
+        if (response.ok || !isRetryableStatus(response.status) || attempt >= maxRetries) {
+          return response;
+        }
+
+        await this.sleep(this.computeRetryDelay(attempt, response.headers.get('retry-after')));
+      } catch (error) {
+        if (attempt >= maxRetries) throw error;
+        await this.sleep(this.computeRetryDelay(attempt, null));
+      }
+    }
+  }
+
   private async getTenantAccessToken(): Promise<string> {
     if (this.config.tenantAccessToken) return this.config.tenantAccessToken;
     if (this.tokenCache && this.tokenCache.expiresAt > Date.now() + 30_000) {
@@ -101,7 +158,7 @@ export class FeishuApiDelivery implements FeishuBridgeDelivery {
       throw new Error('Feishu live delivery requires tenantAccessToken or appId/appSecret');
     }
 
-    const response = await fetch(`${resolveApiBaseUrl(this.config)}/auth/v3/tenant_access_token/internal`, {
+    const response = await this.fetchWithRetry(`${resolveApiBaseUrl(this.config)}/auth/v3/tenant_access_token/internal`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json; charset=utf-8',
@@ -141,7 +198,7 @@ export class FeishuApiDelivery implements FeishuBridgeDelivery {
     const token = await this.getTenantAccessToken();
     const payload = resolveMessagePayload(message);
     const target = resolveReceiveTarget(message.target.chatId);
-    const response = await fetch(`${resolveApiBaseUrl(this.config)}/im/v1/messages?receive_id_type=${target.receiveIdType}`, {
+    const response = await this.fetchWithRetry(`${resolveApiBaseUrl(this.config)}/im/v1/messages?receive_id_type=${target.receiveIdType}`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json; charset=utf-8',
@@ -185,7 +242,7 @@ export class FeishuApiDelivery implements FeishuBridgeDelivery {
 
     const token = await this.getTenantAccessToken();
     const payload = resolveMessagePayload(message);
-    const response = await fetch(`${resolveApiBaseUrl(this.config)}/im/v1/messages/${encodeURIComponent(messageId)}`, {
+    const response = await this.fetchWithRetry(`${resolveApiBaseUrl(this.config)}/im/v1/messages/${encodeURIComponent(messageId)}`, {
       method: 'PATCH',
       headers: {
         'Content-Type': 'application/json; charset=utf-8',