@vui-design/openclaw-plugin-feishu-progress 0.1.5

package/openclaw.plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "feishu-progress",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@vui-design/openclaw-plugin-feishu-progress",
+  "version": "0.1.5",
+  "description": "飞书任务进度卡片插件 — 在 AI 执行复杂多步骤任务时，实时更新飞书进度卡片",
+  "keywords": [
+    "openclaw-plugin",
+    "feishu",
+    "lark",
+    "progress"
+  ],
+  "license": "MIT",
+  "author": "vui-design",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src/",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "installDependencies": true,
+    "install": {
+      "npmSpec": "@vui-design/openclaw-plugin-feishu-progress",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.13"
+  }
+}

package/src/card-builder.ts

@@ -0,0 +1,58 @@
+import type { StepEntry } from './session-store.js';
+
+export interface CardInput {
+  stepIndex: number;
+  totalSteps: number;
+  done?: boolean;
+}
+
+export interface CardSession {
+  steps: StepEntry[];
+  startTime: number;
+}
+
+function formatElapsed(ms: number): string {
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+  return `${Math.floor(sec / 60)}m ${sec % 60}s`;
+}
+
+export function buildProgressCard(input: CardInput, session: CardSession): object {
+  const elapsed = formatElapsed(Date.now() - session.startTime);
+  const isDone = input.done === true;
+
+  const headerText = isDone
+    ? `任务完成  ·  用时 ${elapsed}`
+    : `正在执行任务  ·  已用时 ${elapsed}`;
+
+  const stepElements = session.steps.map((s) => {
+    const icon =
+      s.status === 'done' ? '✅' : s.status === 'active' ? '🔄' : '⬜';
+    return {
+      tag: 'div',
+      text: { tag: 'lark_md', content: `${icon}  ${s.label}` },
+    };
+  });
+
+  return {
+    config: { wide_screen_mode: true },
+    header: {
+      template: isDone ? 'green' : 'blue',
+      title: {
+        tag: 'plain_text',
+        content: '🤖 OpenClaw 任务进度',
+      },
+    },
+    elements: [
+      {
+        tag: 'div',
+        text: {
+          tag: 'lark_md',
+          content: `**${isDone ? '✅' : '⏳'} ${headerText}**`,
+        },
+      },
+      { tag: 'hr' },
+      ...stepElements,
+    ],
+  };
+}

package/src/feishu-client.ts

@@ -0,0 +1,82 @@
+export interface FeishuConfig {
+  appId: string;
+  appSecret: string;
+  domain?: 'feishu' | 'lark';
+}
+
+interface TokenCache {
+  token: string;
+  expiresAt: number;
+}
+
+export class FeishuClient {
+  private tokenCache: TokenCache | null = null;
+
+  constructor(private config: FeishuConfig) {}
+
+  private get baseUrl(): string {
+    return this.config.domain === 'lark'
+      ? 'https://open.larksuite.com'
+      : 'https://open.feishu.cn';
+  }
+
+  async getToken(): Promise<string> {
+    if (this.tokenCache && Date.now() < this.tokenCache.expiresAt) {
+      return this.tokenCache.token;
+    }
+    const res = await fetch(
+      `${this.baseUrl}/open-apis/auth/v3/tenant_access_token/internal`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          app_id: this.config.appId,
+          app_secret: this.config.appSecret,
+        }),
+      }
+    );
+    const data = (await res.json()) as { tenant_access_token: string; expire: number };
+    // 提前 5 分钟过期，避免边界问题
+    this.tokenCache = {
+      token: data.tenant_access_token,
+      expiresAt: Date.now() + (data.expire - 300) * 1000,
+    };
+    return this.tokenCache.token;
+  }
+
+  async sendCard(chatId: string, card: object): Promise<string> {
+    const token = await this.getToken();
+    const res = await fetch(
+      `${this.baseUrl}/open-apis/im/v1/messages?receive_id_type=chat_id`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          receive_id: chatId,
+          msg_type: 'interactive',
+          content: JSON.stringify(card),
+        }),
+      }
+    );
+    const data = (await res.json()) as { data: { message_id: string } };
+    return data.data.message_id;
+  }
+
+  async updateCard(messageId: string, card: object): Promise<void> {
+    const token = await this.getToken();
+    await fetch(`${this.baseUrl}/open-apis/im/v1/messages/${messageId}`, {
+      method: 'PATCH',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        msg_type: 'interactive',
+        content: JSON.stringify(card),
+      }),
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+import { FeishuClient } from './feishu-client.js';
+import { buildProgressCard } from './card-builder.js';
+import { sessionStore } from './session-store.js';
+import type { StepEntry } from './session-store.js';
+
+// ── 注入到系统提示的 Skill 说明 ──────────────────────────────────────────────
+const SKILL_PROMPT = `
+## 任务进度报告规范（report_progress 工具）
+
+当你需要执行包含 **3 个或以上独立工具调用** 的复杂任务时，必须遵守以下规范：
+
+1. **任务最开始**：调用 \`report_progress\`，提供完整的 \`allSteps\` 步骤列表、\`stepIndex: 1\`、当前步骤描述
+2. **每个主要步骤开始前**：调用 \`report_progress\` 更新 \`stepIndex\` 和 \`step\`
+3. **所有步骤完成后**：调用 \`report_progress\` 并设置 \`done: true\`
+
+规则：
+- \`allSteps\` 只在第一次调用时传入，后续调用省略
+- \`step\` 应简洁，10 字以内
+- 不要等待 \`report_progress\` 的返回结果影响主任务，它只是通知机制
+`.trim();
+
+// ── 插件定义 ─────────────────────────────────────────────────────────────────
+export default {
+  id: 'feishu-progress',
+
+  register(api: any) {
+    const cfg = api.config ?? {};
+    const client = new FeishuClient({
+      appId: cfg.appId,
+      appSecret: cfg.appSecret,
+      domain: cfg.domain ?? 'feishu',
+    });
+
+    // 将 Skill 说明注入系统提示（before_prompt_build 是稳定的生命周期钩子）
+    api.on('before_prompt_build', async (event: any) => {
+      event.appendSystemSection?.('feishu-progress-skill', SKILL_PROMPT);
+    });
+
+    // 注册 report_progress 工具
+    // 凭据未配置时跳过工具注册，避免运行时 crash
+    if (!cfg.appId || !cfg.appSecret) {
+      api.logger?.warn(
+        '[feishu-progress] appId / appSecret 未配置，进度卡片功能已禁用。\n' +
+        '请执行：\n' +
+        '  openclaw config set plugins.entries.openclaw-plugin-feishu-progress.config.appId     "cli_xxx"\n' +
+        '  openclaw config set plugins.entries.openclaw-plugin-feishu-progress.config.appSecret "xxx"\n' +
+        '然后重启 OpenClaw。'
+      );
+      return;
+    }
+
+    api.registerTool((ctx: any) => ({
+      name: 'report_progress',
+      description:
+        '向飞书发送或更新任务进度卡片。在每个关键步骤开始前调用，让用户实时了解任务进展。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          step: {
+            type: 'string',
+            description: '当前正在执行的步骤描述（简洁，10 字以内）',
+          },
+          stepIndex: {
+            type: 'number',
+            description: '当前第几步（从 1 开始）',
+          },
+          totalSteps: {
+            type: 'number',
+            description: '本次任务的总步骤数',
+          },
+          allSteps: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '所有步骤名称列表，仅首次调用时传入',
+          },
+          done: {
+            type: 'boolean',
+            description: '是否所有步骤已全部完成，完成时设为 true',
+          },
+        },
+        required: ['step', 'stepIndex', 'totalSteps'],
+      },
+
+      execute: async (input: {
+        step: string;
+        stepIndex: number;
+        totalSteps: number;
+        allSteps?: string[];
+        done?: boolean;
+      }) => {
+        // 优先取飞书 chat_id（兼容不同版本的 ctx 字段名）
+        const chatId: string | undefined =
+          ctx.channelMeta?.chatId ??
+          ctx.channelMeta?.chat_id ??
+          ctx.channelContext?.chatId ??
+          ctx.chatId;
+
+        if (!chatId) {
+          return { ok: false, reason: '无法获取飞书 chat_id，跳过进度更新' };
+        }
+
+        // minSteps 未达到时静默跳过
+        const minSteps: number = cfg.minSteps ?? 3;
+        if (input.totalSteps < minSteps) {
+          return { ok: true, skipped: true };
+        }
+
+        const sessionKey = `${chatId}:${ctx.sessionKey ?? ctx.runId ?? 'default'}`;
+        const existing = sessionStore.get(sessionKey);
+
+        // 构造步骤状态列表
+        let steps: StepEntry[];
+        if (!existing) {
+          // 首次调用：用 allSteps 或自动生成占位标签
+          const labels: string[] =
+            input.allSteps ??
+            Array.from({ length: input.totalSteps }, (_, i) =>
+              i + 1 === input.stepIndex ? input.step : `步骤 ${i + 1}`
+            );
+          steps = labels.map((label, i) => ({
+            label,
+            status:
+              i + 1 < input.stepIndex
+                ? 'done'
+                : i + 1 === input.stepIndex
+                  ? 'active'
+                  : 'pending',
+          }));
+        } else {
+          // 后续调用：更新已有步骤状态
+          steps = existing.steps.map((s, i) => ({
+            ...s,
+            status:
+              i + 1 < input.stepIndex
+                ? 'done'
+                : i + 1 === input.stepIndex && !input.done
+                  ? 'active'
+                  : 'pending',
+          }));
+        }
+
+        // done=true 时所有步骤标为 done
+        if (input.done) {
+          steps = steps.map((s) => ({ ...s, status: 'done' as const }));
+        }
+
+        const startTime = existing?.startTime ?? Date.now();
+        const card = buildProgressCard(
+          { stepIndex: input.stepIndex, totalSteps: input.totalSteps, done: input.done },
+          { steps, startTime }
+        );
+
+        try {
+          if (!existing) {
+            const msgId = await client.sendCard(chatId, card);
+            sessionStore.set(sessionKey, { msgId, chatId, startTime, steps });
+          } else {
+            await client.updateCard(existing.msgId, card);
+            sessionStore.set(sessionKey, { ...existing, steps });
+          }
+
+          // 任务完成后 30s 清理 session，避免内存泄漏
+          if (input.done) {
+            setTimeout(() => sessionStore.delete(sessionKey), 30_000);
+          }
+
+          return { ok: true };
+        } catch (err: any) {
+          return { ok: false, reason: err?.message ?? String(err) };
+        }
+      },
+    }));
+  },
+};

package/src/session-store.ts

@@ -0,0 +1,29 @@
+export interface StepEntry {
+  label: string;
+  status: 'done' | 'active' | 'pending';
+}
+
+export interface SessionEntry {
+  msgId: string;
+  chatId: string;
+  startTime: number;
+  steps: StepEntry[];
+}
+
+class SessionStore {
+  private store = new Map<string, SessionEntry>();
+
+  get(key: string): SessionEntry | undefined {
+    return this.store.get(key);
+  }
+
+  set(key: string, entry: SessionEntry): void {
+    this.store.set(key, entry);
+  }
+
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+}
+
+export const sessionStore = new SessionStore();