@nextclaw/channel-plugin-feishu 0.2.16 → 0.2.18

package/src/tool-scopes.ts

@@ -0,0 +1,102 @@
+export type ToolActionKey =
+  | "feishu_get_user.default"
+  | "feishu_search_user.default"
+  | "feishu_calendar_calendar.list"
+  | "feishu_calendar_calendar.get"
+  | "feishu_calendar_calendar.primary"
+  | "feishu_calendar_event.create"
+  | "feishu_calendar_event.list"
+  | "feishu_calendar_event.get"
+  | "feishu_calendar_event.patch"
+  | "feishu_calendar_event.delete"
+  | "feishu_calendar_event.instance_view"
+  | "feishu_calendar_event_attendee.create"
+  | "feishu_calendar_event_attendee.list"
+  | "feishu_calendar_freebusy.list"
+  | "feishu_task_task.create"
+  | "feishu_task_task.get"
+  | "feishu_task_task.list"
+  | "feishu_task_task.patch"
+  | "feishu_task_tasklist.create"
+  | "feishu_task_tasklist.get"
+  | "feishu_task_tasklist.list"
+  | "feishu_task_tasklist.tasks"
+  | "feishu_task_tasklist.patch"
+  | "feishu_task_tasklist.add_members"
+  | "feishu_task_comment.create"
+  | "feishu_task_comment.get"
+  | "feishu_task_comment.list"
+  | "feishu_task_subtask.create"
+  | "feishu_task_subtask.list"
+  | "feishu_sheet.info"
+  | "feishu_sheet.read"
+  | "feishu_sheet.write"
+  | "feishu_sheet.append"
+  | "feishu_sheet.find"
+  | "feishu_sheet.create"
+  | "feishu_sheet.export";
+
+export const TOOL_SCOPES: Record<ToolActionKey, string[]> = {
+  "feishu_get_user.default": ["contact:contact.base:readonly", "contact:user.base:readonly"],
+  "feishu_search_user.default": ["contact:user:search"],
+  "feishu_calendar_calendar.list": ["calendar:calendar:read"],
+  "feishu_calendar_calendar.get": ["calendar:calendar:read"],
+  "feishu_calendar_calendar.primary": ["calendar:calendar:read"],
+  "feishu_calendar_event.create": [
+    "calendar:calendar.event:create",
+    "calendar:calendar.event:update",
+  ],
+  "feishu_calendar_event.list": ["calendar:calendar.event:read"],
+  "feishu_calendar_event.get": ["calendar:calendar.event:read"],
+  "feishu_calendar_event.patch": ["calendar:calendar.event:update"],
+  "feishu_calendar_event.delete": ["calendar:calendar.event:delete"],
+  "feishu_calendar_event.instance_view": ["calendar:calendar.event:read"],
+  "feishu_calendar_event_attendee.create": ["calendar:calendar.event:update"],
+  "feishu_calendar_event_attendee.list": ["calendar:calendar.event:read"],
+  "feishu_calendar_freebusy.list": ["calendar:calendar.free_busy:read"],
+  "feishu_task_task.create": ["task:task:write", "task:task:writeonly"],
+  "feishu_task_task.get": ["task:task:read", "task:task:write"],
+  "feishu_task_task.list": ["task:task:read", "task:task:write"],
+  "feishu_task_task.patch": ["task:task:write", "task:task:writeonly"],
+  "feishu_task_tasklist.create": ["task:tasklist:write"],
+  "feishu_task_tasklist.get": ["task:tasklist:read", "task:tasklist:write"],
+  "feishu_task_tasklist.list": ["task:tasklist:read", "task:tasklist:write"],
+  "feishu_task_tasklist.tasks": ["task:tasklist:read", "task:tasklist:write"],
+  "feishu_task_tasklist.patch": ["task:tasklist:write"],
+  "feishu_task_tasklist.add_members": ["task:tasklist:write"],
+  "feishu_task_comment.create": ["task:comment:write"],
+  "feishu_task_comment.get": ["task:comment:read", "task:comment:write"],
+  "feishu_task_comment.list": ["task:comment:read", "task:comment:write"],
+  "feishu_task_subtask.create": ["task:task:write"],
+  "feishu_task_subtask.list": ["task:task:read", "task:task:write"],
+  "feishu_sheet.info": ["sheets:spreadsheet.meta:read", "sheets:spreadsheet:read"],
+  "feishu_sheet.read": ["sheets:spreadsheet.meta:read", "sheets:spreadsheet:read"],
+  "feishu_sheet.write": [
+    "sheets:spreadsheet.meta:read",
+    "sheets:spreadsheet:read",
+    "sheets:spreadsheet:create",
+    "sheets:spreadsheet:write_only",
+  ],
+  "feishu_sheet.append": [
+    "sheets:spreadsheet.meta:read",
+    "sheets:spreadsheet:read",
+    "sheets:spreadsheet:create",
+    "sheets:spreadsheet:write_only",
+  ],
+  "feishu_sheet.find": ["sheets:spreadsheet.meta:read", "sheets:spreadsheet:read"],
+  "feishu_sheet.create": [
+    "sheets:spreadsheet.meta:read",
+    "sheets:spreadsheet:read",
+    "sheets:spreadsheet:create",
+    "sheets:spreadsheet:write_only",
+  ],
+  "feishu_sheet.export": ["docs:document:export"],
+};
+
+export function getRequiredScopes(toolAction: ToolActionKey): string[] {
+  return TOOL_SCOPES[toolAction] ?? [];
+}
+
+export function getAllKnownScopes(): string[] {
+  return Array.from(new Set(Object.values(TOOL_SCOPES).flat())).sort();
+}

package/src/tools-config.test.ts

@@ -8,14 +8,33 @@ describe("feishu tools config", () => {
     expect(resolved.chat).toBe(true);
   });
 
+  it("enables newly synced user tools by default", () => {
+    const resolved = resolveToolsConfig(undefined);
+    expect(resolved.calendar).toBe(true);
+    expect(resolved.task).toBe(true);
+    expect(resolved.sheets).toBe(true);
+    expect(resolved.oauth).toBe(true);
+    expect(resolved.identity).toBe(true);
+  });
+
   it("accepts tools.chat in config schema", () => {
     const parsed = FeishuConfigSchema.parse({
       enabled: true,
       tools: {
         chat: false,
+        calendar: false,
+        task: false,
+        sheets: false,
+        oauth: false,
+        identity: false,
       },
     });
 
     expect(parsed.tools?.chat).toBe(false);
+    expect(parsed.tools?.calendar).toBe(false);
+    expect(parsed.tools?.task).toBe(false);
+    expect(parsed.tools?.sheets).toBe(false);
+    expect(parsed.tools?.oauth).toBe(false);
+    expect(parsed.tools?.identity).toBe(false);
   });
 });

package/src/tools-config.ts

@@ -12,6 +12,11 @@ export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
   drive: true,
   perm: false,
   scopes: true,
+  calendar: true,
+  task: true,
+  sheets: true,
+  oauth: true,
+  identity: true,
 };
 
 /**

package/src/types.ts

@@ -93,6 +93,11 @@ export type FeishuToolsConfig = {
   drive?: boolean;
   perm?: boolean;
   scopes?: boolean;
+  calendar?: boolean;
+  task?: boolean;
+  sheets?: boolean;
+  oauth?: boolean;
+  identity?: boolean;
 };
 
 export type DynamicAgentCreationConfig = {

package/src/uat-client.ts

@@ -0,0 +1,159 @@
+import { NeedAuthorizationError, REFRESH_TOKEN_RETRYABLE, TOKEN_RETRY_CODES } from "./auth-errors.js";
+import { resolveOAuthEndpoints } from "./device-flow.js";
+import { feishuFetch } from "./feishu-fetch.js";
+import {
+  getStoredToken,
+  removeStoredToken,
+  setStoredToken,
+  tokenStatus,
+  type StoredUAToken,
+} from "./token-store.js";
+import type { FeishuDomain } from "./types.js";
+
+export type UATCallOptions = {
+  userOpenId: string;
+  appId: string;
+  appSecret: string;
+  domain: FeishuDomain;
+};
+
+const refreshLocks = new Map<string, Promise<StoredUAToken | null>>();
+
+async function doRefreshToken(
+  opts: UATCallOptions,
+  stored: StoredUAToken,
+): Promise<StoredUAToken | null> {
+  if (Date.now() >= stored.refreshExpiresAt) {
+    await removeStoredToken(opts.appId, opts.userOpenId);
+    return null;
+  }
+
+  const endpoints = resolveOAuthEndpoints(opts.domain);
+  const requestBody = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: stored.refreshToken,
+    client_id: opts.appId,
+    client_secret: opts.appSecret,
+  }).toString();
+
+  const callEndpoint = async () => {
+    const response = await feishuFetch(endpoints.token, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: requestBody,
+    });
+    return (await response.json()) as Record<string, unknown>;
+  };
+
+  let data = await callEndpoint();
+  const code = typeof data.code === "number" ? data.code : undefined;
+  const error = typeof data.error === "string" ? data.error : undefined;
+
+  if ((code !== undefined && code !== 0) || error) {
+    if (code !== undefined && REFRESH_TOKEN_RETRYABLE.has(code)) {
+      data = await callEndpoint();
+      const retryCode = typeof data.code === "number" ? data.code : undefined;
+      const retryError = typeof data.error === "string" ? data.error : undefined;
+      if ((retryCode !== undefined && retryCode !== 0) || retryError) {
+        await removeStoredToken(opts.appId, opts.userOpenId);
+        return null;
+      }
+    } else {
+      await removeStoredToken(opts.appId, opts.userOpenId);
+      return null;
+    }
+  }
+
+  if (!data.access_token) {
+    throw new Error("Token refresh returned no access_token");
+  }
+
+  const now = Date.now();
+  const updated: StoredUAToken = {
+    userOpenId: stored.userOpenId,
+    appId: opts.appId,
+    accessToken: String(data.access_token),
+    refreshToken: String(data.refresh_token ?? stored.refreshToken),
+    expiresAt: now + Number(data.expires_in ?? 7200) * 1000,
+    refreshExpiresAt: data.refresh_token_expires_in
+      ? now + Number(data.refresh_token_expires_in) * 1000
+      : stored.refreshExpiresAt,
+    scope: String(data.scope ?? stored.scope),
+    grantedAt: stored.grantedAt,
+  };
+  await setStoredToken(updated);
+  return updated;
+}
+
+async function refreshWithLock(
+  opts: UATCallOptions,
+  stored: StoredUAToken,
+): Promise<StoredUAToken | null> {
+  const key = `${opts.appId}:${opts.userOpenId}`;
+  const existing = refreshLocks.get(key);
+  if (existing) {
+    await existing;
+    return getStoredToken(opts.appId, opts.userOpenId);
+  }
+
+  const promise = doRefreshToken(opts, stored);
+  refreshLocks.set(key, promise);
+  try {
+    return await promise;
+  } finally {
+    refreshLocks.delete(key);
+  }
+}
+
+export async function getValidAccessToken(opts: UATCallOptions): Promise<string> {
+  const stored = await getStoredToken(opts.appId, opts.userOpenId);
+  if (!stored) {
+    throw new NeedAuthorizationError(opts.userOpenId);
+  }
+
+  const status = tokenStatus(stored);
+  if (status === "valid") {
+    return stored.accessToken;
+  }
+  if (status === "needs_refresh") {
+    const refreshed = await refreshWithLock(opts, stored);
+    if (!refreshed) {
+      throw new NeedAuthorizationError(opts.userOpenId);
+    }
+    return refreshed.accessToken;
+  }
+
+  await removeStoredToken(opts.appId, opts.userOpenId);
+  throw new NeedAuthorizationError(opts.userOpenId);
+}
+
+export async function callWithUAT<T>(
+  opts: UATCallOptions,
+  apiCall: (accessToken: string) => Promise<T>,
+): Promise<T> {
+  const accessToken = await getValidAccessToken(opts);
+  try {
+    return await apiCall(accessToken);
+  } catch (error) {
+    const code =
+      (error as { code?: number; response?: { data?: { code?: number } } }).code ??
+      (error as { response?: { data?: { code?: number } } }).response?.data?.code;
+    if (!TOKEN_RETRY_CODES.has(Number(code))) {
+      throw error;
+    }
+
+    const stored = await getStoredToken(opts.appId, opts.userOpenId);
+    if (!stored) {
+      throw new NeedAuthorizationError(opts.userOpenId);
+    }
+    const refreshed = await refreshWithLock(opts, stored);
+    if (!refreshed) {
+      throw new NeedAuthorizationError(opts.userOpenId);
+    }
+    return apiCall(refreshed.accessToken);
+  }
+}
+
+export async function revokeUAT(appId: string, userOpenId: string): Promise<void> {
+  await removeStoredToken(appId, userOpenId);
+}

package/src/user-tool-client.ts

@@ -0,0 +1,224 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import { listEnabledFeishuAccounts, resolveFeishuAccount } from "./accounts.js";
+import { getAppGrantedScopes, invalidateAppScopeCache, missingScopes } from "./app-scope-checker.js";
+import {
+  AppScopeMissingError,
+  LARK_ERROR,
+  NeedAuthorizationError,
+  UserAuthRequiredError,
+  UserScopeInsufficientError,
+} from "./auth-errors.js";
+import { createFeishuClient } from "./client.js";
+import { getTicket } from "./lark-ticket.js";
+import { rawLarkRequest } from "./raw-request.js";
+import { getRequiredScopes, type ToolActionKey } from "./tool-scopes.js";
+import { callWithUAT } from "./uat-client.js";
+import { getStoredToken } from "./token-store.js";
+import type { ClawdbotConfig } from "./nextclaw-sdk/feishu.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+type LarkRequestOptions = ReturnType<typeof Lark.withUserAccessToken>;
+type InvokeFn<T> = (sdk: Lark.Client, opts?: LarkRequestOptions, uat?: string) => Promise<T>;
+
+function assertConfiguredAccount(account: ResolvedFeishuAccount): ResolvedFeishuAccount & {
+  appId: string;
+  appSecret: string;
+  configured: true;
+} {
+  if (!account.enabled) {
+    throw new Error(`Feishu account "${account.accountId}" is disabled.`);
+  }
+  if (!account.configured || !account.appId || !account.appSecret) {
+    throw new Error(`Feishu account "${account.accountId}" is not configured.`);
+  }
+  return account as ResolvedFeishuAccount & { appId: string; appSecret: string; configured: true };
+}
+
+function resolveConfiguredAccount(config: ClawdbotConfig, accountIndex = 0) {
+  const ticket = getTicket();
+  if (ticket?.accountId) {
+    return assertConfiguredAccount(resolveFeishuAccount({ cfg: config, accountId: ticket.accountId }));
+  }
+  const accounts = listEnabledFeishuAccounts(config);
+  if (accounts.length === 0) {
+    throw new Error("No enabled Feishu accounts configured.");
+  }
+  return assertConfiguredAccount(accounts[Math.min(accountIndex, accounts.length - 1)]);
+}
+
+export class UserToolClient {
+  readonly account: ReturnType<typeof assertConfiguredAccount>;
+  readonly senderOpenId?: string;
+  readonly sdk: Lark.Client;
+
+  constructor(
+    readonly config: ClawdbotConfig,
+    accountIndex = 0,
+  ) {
+    this.account = resolveConfiguredAccount(config, accountIndex);
+    this.senderOpenId = getTicket()?.senderOpenId;
+    this.sdk = createFeishuClient(this.account);
+  }
+
+  async invoke<T>(
+    toolAction: ToolActionKey,
+    fn: InvokeFn<T>,
+    options?: { as?: "user" | "tenant"; userOpenId?: string },
+  ): Promise<T> {
+    const requiredScopes = getRequiredScopes(toolAction);
+    const tokenType = options?.as ?? "user";
+    const appScopeVerified = await this.verifyAppScopes(requiredScopes, tokenType, toolAction);
+
+    if (tokenType === "tenant") {
+      try {
+        return await fn(this.sdk);
+      } catch (error) {
+        this.rethrowStructuredError(error, toolAction, requiredScopes);
+        throw error;
+      }
+    }
+
+    const userOpenId = options?.userOpenId ?? this.senderOpenId;
+    if (!userOpenId) {
+      throw new UserAuthRequiredError("unknown", {
+        apiName: toolAction,
+        scopes: requiredScopes,
+        appScopeVerified,
+        appId: this.account.appId,
+      });
+    }
+
+    const stored = await getStoredToken(this.account.appId, userOpenId);
+    if (!stored) {
+      throw new UserAuthRequiredError(userOpenId, {
+        apiName: toolAction,
+        scopes: requiredScopes,
+        appScopeVerified,
+        appId: this.account.appId,
+      });
+    }
+
+    if (appScopeVerified && stored.scope && requiredScopes.length > 0) {
+      const granted = new Set(stored.scope.split(/\s+/).filter(Boolean));
+      const missingUserScopes = requiredScopes.filter((scope) => !granted.has(scope));
+      if (missingUserScopes.length > 0) {
+        throw new UserAuthRequiredError(userOpenId, {
+          apiName: toolAction,
+          scopes: missingUserScopes,
+          appScopeVerified,
+          appId: this.account.appId,
+        });
+      }
+    }
+
+    try {
+      return await callWithUAT(
+        {
+          userOpenId,
+          appId: this.account.appId,
+          appSecret: this.account.appSecret,
+          domain: this.account.domain,
+        },
+        (accessToken) => fn(this.sdk, Lark.withUserAccessToken(accessToken), accessToken),
+      );
+    } catch (error) {
+      if (error instanceof NeedAuthorizationError) {
+        throw new UserAuthRequiredError(userOpenId, {
+          apiName: toolAction,
+          scopes: requiredScopes,
+          appScopeVerified,
+          appId: this.account.appId,
+        });
+      }
+      this.rethrowStructuredError(error, toolAction, requiredScopes, userOpenId);
+      throw error;
+    }
+  }
+
+  async invokeByPath<T = unknown>(
+    toolAction: ToolActionKey,
+    path: string,
+    options?: {
+      method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+      body?: unknown;
+      query?: Record<string, string>;
+      headers?: Record<string, string>;
+      as?: "user" | "tenant";
+      userOpenId?: string;
+    },
+  ): Promise<T> {
+    return this.invoke(
+      toolAction,
+      async (_sdk, _opts, uat) =>
+        rawLarkRequest<T>({
+          domain: this.account.domain,
+          path,
+          method: options?.method,
+          body: options?.body,
+          query: options?.query,
+          headers: options?.headers,
+          accessToken: uat,
+        }),
+      options,
+    );
+  }
+
+  private async verifyAppScopes(
+    requiredScopes: string[],
+    tokenType: "user" | "tenant",
+    toolAction: ToolActionKey,
+  ): Promise<boolean> {
+    if (requiredScopes.length === 0) {
+      return true;
+    }
+    const appGrantedScopes = await getAppGrantedScopes(this.sdk, this.account.appId, tokenType);
+    if (appGrantedScopes.length === 0) {
+      return false;
+    }
+    const missingAppScopes = missingScopes(
+      appGrantedScopes,
+      tokenType === "user"
+        ? [...new Set([...requiredScopes, "offline_access"])]
+        : requiredScopes,
+    );
+    if (missingAppScopes.length > 0) {
+      throw new AppScopeMissingError({
+        apiName: toolAction,
+        scopes: missingAppScopes,
+        appId: this.account.appId,
+      });
+    }
+    return true;
+  }
+
+  private rethrowStructuredError(
+    error: unknown,
+    toolAction: ToolActionKey,
+    requiredScopes: string[],
+    userOpenId?: string,
+  ): void {
+    const code =
+      (error as { code?: number; response?: { data?: { code?: number } } }).code ??
+      (error as { response?: { data?: { code?: number } } }).response?.data?.code;
+
+    if (code === LARK_ERROR.APP_SCOPE_MISSING) {
+      invalidateAppScopeCache(this.account.appId);
+      throw new AppScopeMissingError({
+        apiName: toolAction,
+        scopes: requiredScopes,
+        appId: this.account.appId,
+      });
+    }
+
+    if (code === LARK_ERROR.USER_SCOPE_INSUFFICIENT && userOpenId) {
+      throw new UserScopeInsufficientError(userOpenId, {
+        apiName: toolAction,
+        scopes: requiredScopes,
+      });
+    }
+  }
+}
+
+export function createUserToolClient(config: ClawdbotConfig, accountIndex = 0): UserToolClient {
+  return new UserToolClient(config, accountIndex);
+}

package/src/user-tool-helpers.ts

@@ -0,0 +1,157 @@
+import { Type, type SchemaOptions, type TSchema } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError } from "./auth-errors.js";
+import { openPlatformDomain } from "./domains.js";
+import { formatLarkError } from "./user-tool-result.js";
+import { getAllKnownScopes } from "./tool-scopes.js";
+import { createUserToolClient } from "./user-tool-client.js";
+import { jsonToolResult } from "./tool-result.js";
+
+export function json(data: unknown) {
+  return jsonToolResult(data);
+}
+
+export function createToolContext(api: OpenClawPluginApi, toolName: string, accountIndex = 0) {
+  const logPrefix = `${toolName}:`;
+  const log = {
+    info: (message: string) => api.logger.info?.(`${logPrefix} ${message}`),
+    warn: (message: string) => api.logger.warn?.(`${logPrefix} ${message}`),
+    error: (message: string) => api.logger.error?.(`${logPrefix} ${message}`),
+    debug: (message: string) => api.logger.debug?.(`${logPrefix} ${message}`),
+  };
+
+  return {
+    toolClient: () => createUserToolClient(api.config, accountIndex),
+    log,
+  };
+}
+
+export function registerTool(
+  api: OpenClawPluginApi,
+  tool: Parameters<OpenClawPluginApi["registerTool"]>[0],
+  opts?: Parameters<OpenClawPluginApi["registerTool"]>[1],
+) {
+  api.registerTool(tool, opts);
+}
+
+export function assertLarkOk(res: { code?: number; msg?: string }) {
+  if (!res.code || res.code === 0) {
+    return;
+  }
+  throw new Error(res.msg ?? `Feishu API error (code=${res.code})`);
+}
+
+export function StringEnum<T extends string>(values: readonly T[], options?: SchemaOptions): TSchema {
+  return Type.Union(values.map((value) => Type.Literal(value)), options);
+}
+
+export function parseTimeToTimestamp(input: string): string | null {
+  const date = parseDateLike(input);
+  return date ? Math.floor(date.getTime() / 1000).toString() : null;
+}
+
+export function parseTimeToTimestampMs(input: string): string | null {
+  const date = parseDateLike(input);
+  return date ? date.getTime().toString() : null;
+}
+
+export function parseTimeToRFC3339(input: string): string | null {
+  const trimmed = input.trim();
+  if (/[Zz]$|[+-]\d{2}:\d{2}$/.test(trimmed)) {
+    return new Date(trimmed).toString() === "Invalid Date" ? null : trimmed;
+  }
+  const normalized = trimmed.replace(" ", "T");
+  const match = normalized.match(
+    /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/,
+  );
+  if (!match) {
+    const date = new Date(trimmed);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+  }
+  const [, y, m, d, hh, mm, ss] = match;
+  return `${y}-${m}-${d}T${hh}:${mm}:${ss ?? "00"}+08:00`;
+}
+
+export function unixTimestampToISO8601(raw: string | number | undefined): string | null {
+  if (raw === undefined || raw === null || raw === "") {
+    return null;
+  }
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    return null;
+  }
+  const ms = value > 1_000_000_000_000 ? value : value * 1000;
+  return new Date(ms).toISOString();
+}
+
+function parseDateLike(input: string): Date | null {
+  const trimmed = input.trim();
+  if (/[Zz]$|[+-]\d{2}:\d{2}$/.test(trimmed)) {
+    const date = new Date(trimmed);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+
+  const normalized = trimmed.replace("T", " ");
+  const match = normalized.match(/^(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2})(?::(\d{2}))?$/);
+  if (!match) {
+    const date = new Date(trimmed);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+
+  const [, year, month, day, hour, minute, second] = match;
+  return new Date(
+    Date.UTC(
+      Number(year),
+      Number(month) - 1,
+      Number(day),
+      Number(hour) - 8,
+      Number(minute),
+      Number(second ?? "0"),
+    ),
+  );
+}
+
+export async function handleInvokeError(error: unknown, _api: OpenClawPluginApi) {
+  if (error instanceof AppScopeMissingError) {
+    return json({
+      error: "app_scope_missing",
+      message: error.message,
+      missing_scopes: error.missingScopes,
+      app_id: error.appId,
+      open_platform: openPlatformDomain("feishu"),
+    });
+  }
+
+  if (error instanceof UserAuthRequiredError) {
+    return json({
+      error: "need_user_authorization",
+      message: "当前用户尚未完成飞书 OAuth 授权，或授权范围不足。",
+      required_scopes: error.requiredScopes,
+      next_tool_call: {
+        tool: "feishu_oauth",
+        params: {
+          action: "authorize",
+          scope: error.requiredScopes.join(" "),
+        },
+      },
+      default_scope_suggestion: getAllKnownScopes().join(" "),
+    });
+  }
+
+  if (error instanceof UserScopeInsufficientError) {
+    return json({
+      error: "user_scope_insufficient",
+      message: "当前用户授权范围不足，请重新授权补齐缺失 scope。",
+      missing_scopes: error.missingScopes,
+      next_tool_call: {
+        tool: "feishu_oauth",
+        params: {
+          action: "authorize",
+          scope: error.missingScopes.join(" "),
+        },
+      },
+    });
+  }
+
+  return json({ error: formatLarkError(error) });
+}