Kiến trúc openclaw-lark: thẻ tương tác và streaming cho Agent

Tóm tắt nhanh
openclaw-lark là plugin kênh chính thức kết nối Lark và Feishu với hệ sinh thái OpenClaw, gắn kết năng lực suy luận tự hành của AI agent vào không gian cộng tác doanh nghiệp. Được phát triển trên nền tảng Node.js và TypeScript, plugin tích hợp khả năng định tuyến sự kiện hai chiều, xuất văn bản streaming và quản trị thẻ trạng thái tương tác. Thay vì chỉ gửi tin nhắn tĩnh sau khi xử lý xong, openclaw-lark hỗ trợ các thẻ tin nhắn streaming tùy chọn chuyển đổi qua các trạng thái đang suy nghĩ, streaming và hoàn tất. Bộ lọc chính sách áp dụng danh sách cho phép và yêu cầu nhắc tên, thu hẹp phạm vi kích hoạt và giảm thiểu rủi ro prompt injection trong môi trường doanh nghiệp.

Môi trường chat nhóm doanh nghiệp đòi hỏi tương tác tức thời khi triển khai các AI coding agent và workflow agent tự hành. Webhook thông thường chỉ trả về các khối văn bản tĩnh sau khi toàn bộ chu kỳ thực thi của agent hoàn tất. Khi các tác vụ phức tạp kéo dài thời gian chạy – chẳng hạn rà soát nhánh git, chạy migration dữ liệu hay tổng hợp biên bản cuộc họp- giao diện im lặng khiến người dùng dễ gửi trùng lệnh hoặc từ bỏ phiên làm việc.

Bên cạnh đó, việc gửi nội dung văn bản không có cấu trúc vào nhóm chat tiềm ẩn nhiều rủi ro an ninh. Trong các kênh dùng chung, người dùng chưa xác minh có thể thử tấn công prompt injection bằng cách gắn thẻ agent kèm chỉ dẫn độc hại. Tin nhắn và tài liệu từ bên thứ ba là dữ liệu không tin cậy; các cổng kiểm soát giúp giảm lượt kích hoạt trái phép nhưng không bảo đảm nội dung vượt qua cổng hoàn toàn không chứa chỉ dẫn gây hại.

openclaw-lark giải quyết khoảng trống này bằng tầng giao tiếp tương tác có trạng thái. Bằng cách nối trực tiếp bus sự kiện của OpenClaw với Lark Open Platform, plugin kết xuất tiến trình suy luận và áp dụng chính sách kiểm soát truy cập mà không để lộ secret ra tiến trình host.

Mã nguồn dự án được phát hành theo giấy phép MIT tại LICENSE L1-L21.

Vòng đời thẻ tin nhắn tương tác và cơ chế phản hồi streaming

Cơ chế giao diện cốt lõi của openclaw-lark là vòng đời thẻ tin nhắn tương tác. Ngay khi sự kiện gửi đến kích hoạt agent, plugin sẽ chiếm chỗ luồng hội thoại bằng một thẻ tin nhắn phản hồi.

Theo quy định tại package.json L30-L56, gói phần mềm yêu cầu môi trường node >= 22 và kết nối các thư viện chuyên dụng:

• @larksuiteoapi/node-sdk (^1.64.0): Bộ SDK Node.js chính thức cho Lark Open Platform.
• @sinclair/typebox (0.34.49): Kiểm thực schema runtime cho các hợp đồng sự kiện.
• zod (^4.3.6): Xác thực tham số và biến môi trường.
• openclaw (>=2026.5.4): Thư viện ngang hàng cung cấp động cơ sự kiện agent cốt lõi.

[Người dùng Lark/Feishu] ──(Tin nhắn/@Bot)──► [Cổng openclaw-lark]
                                                           │
                       1. Xác thực quyền hạn & chính sách──│
                       2. Nạp ngữ cảnh kênh hội thoại──────│ 
                       3. Gửi thẻ "Đang suy nghĩ..."───────│ 
                                                           │
                                                           ▼
[LLM Agent sinh nội dung] ◄──(Phát sự kiện)────── [Lõi OpenClaw]
          │
          ├── (Luồng token xuất ra)
          ▼
[Bộ đệm điều tiết luồng] ──(Gọi API cập nhật)──► [Thẻ hiển thị streaming]
                                                           │
                                (Điều phối hành động thẻ)──│
                                                           ▼
                                       [Nút bấm tương tác trên thẻ]
                                            ("Lựa chọn thao tác")
                                                           │
                                                           ▼
                                            [Thẻ trạng thái hoàn tất]

Plugin hỗ trợ cả phản hồi tĩnh và thẻ streaming. Streaming là tính năng tùy chọn; khi bật streaming: true và đặt replyMode: "auto", tin nhắn trực tiếp (DM) sẽ stream liên tục trong khi nhóm chat mặc định dùng thẻ tĩnh. Theo src/card/reply-dispatcher.ts L50-L61, luồng điều phối trải qua 3 giai đoạn:

1. Trạng thái suy nghĩ: Khi nhận webhook, plugin gửi ngay thẻ chiếm chỗ kèm biểu tượng xử lý, báo hiệu agent đã nhận công việc.
2. Trạng thái streaming: Khi mô hình sinh token, openclaw-lark gom nội dung vào bộ đệm và cập nhật thẻ theo khoảng thời gian điều tiết tại src/card/reply-dispatcher-types.ts L107-L113 và src/card/streaming-card-controller.ts L1070-L1073 (100 ms cho streaming CardKit và 1.500 ms cho cập nhật patch). Cơ chế này giúp giảm tần suất gọi API; việc cập nhật vẫn có thể chạm trần tần suất nếu lưu lượng cụm quá lớn.
3. Trạng thái hoàn tất: Khi xử lý xong, thẻ chuyển sang giao diện nội dung cuối cùng. Các nút bấm tương tác trên thẻ điều phối lượt bấm của người dùng quay trở lại bộ điều phối sự kiện của OpenClaw để kích hoạt các trình xử lý callback đã đăng ký.

Về mặt vận hành, thư viện @larksuiteoapi/node-sdk cung cấp client giao vận HTTP và WebSocket (Lark.Client và Lark.WSClient). Plugin kiểm tra danh tính bot, định tuyến sự kiện card action qua EventDispatcher và điều phối vòng đời WebSocket trong kiến trúc kênh của OpenClaw.

Cấu hình kênh và kiểm soát chính sách bảo mật nhóm

Triển khai các agent tự hành vào hệ thống doanh nghiệp đòi hỏi ranh giới phân quyền rõ rệt. Một con bot có quyền truy cập lịch công tác hay tài liệu dự án không được phép nhận lệnh từ những thành viên chưa được xác minh trong nhóm chat.

Gói phần mềm khai báo bộ mô tả openclaw-lark với bí danh kênh lark. Tại runtime, src/channel/plugin.ts L63-L79 và src/core/config-schema.ts L160-L207 gán cấu hình thực thi trực tiếp dưới tiền tố channels.feishu:

{
  "channels": {
    "feishu": {
      "appId": "cli_a1b2c3d4e5f6",
      "appSecret": "YOUR_LARK_APP_SECRET",
      "domain": "feishu",
      "connectionMode": "websocket",
      "streaming": true,
      "replyMode": "auto",
      "dmPolicy": "allowlist",
      "allowFrom": ["ou_1234567890abcdef"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["ou_1234567890abcdef"],
      "requireMention": true,
      "allowBots": "mentions",
      "groups": {
        "oc_9876543210fedcba": {
          "requireMention": true,
          "allowBots": false
        }
      }
    }
  }
}

Kiến trúc an ninh phân định luồng xử lý qua các tầng:

• Chính sách tin nhắn trực tiếp: Giới hạn quyền trò chuyện cho danh sách mã nhân viên chỉ định, ngăn người lạ trong tenant sử dụng tài nguyên.
• Kiểm soát nhóm chat: Theo src/messaging/inbound/gate.ts L354-L413, groupAllowFrom lọc mã người gửi, trong khi groups cấu hình quy tắc cho từng phòng chat. Plugin yêu cầu gắn thẻ @Bot để kích hoạt; tin nhắn không gắn thẻ vẫn có thể lưu lại dưới dạng historyEntry để duy trì mạch hội thoại. Tài liệu upstream khuyến nghị cẩn trọng khi đưa bot vào nhóm chat công cộng.
• Chính sách vòng lặp bot: Việc xử lý sự kiện bot gửi đến được quản lý qua allowBots và quy tắc nhắc tên trong gate.ts, triệt tiêu self-echo khi danh tính bot đã xác lập đồng thời đánh giá tin nhắn từ bot khác để tránh vòng lặp vô tận.
• Chỉ dẫn hệ thống tùy biến: Chỉ dẫn hệ thống định hình phong cách giao tiếp của agent, nhưng chính sách cho phép hoặc từ chối công cụ mới là tầng quyết định quyền hạn thực thi.
• Đích phân giải secret: Tại secret-contract-api.ts L59-L78, plugin đăng ký đích secret cho cơ chế phân giải của OpenClaw. Host phân giải thông tin xác thực và truyền cho SDK lúc runtime.

Hợp đồng 39 công cụ doanh nghiệp và hướng dẫn triển khai

openclaw-lark biến OpenClaw thành một thành viên tích cực có khả năng thao tác trên không gian làm việc Lark.

Theo danh sách đăng ký trong openclaw.plugin.json L15-L54, plugin cung cấp 39 công cụ có định kiểu cụ thể:

• Quản trị cơ sở dữ liệu Bitable: feishu_bitable_app_table, feishu_bitable_app_table_record và feishu_bitable_app_table_view.
• Quản lý lịch và sự kiện: feishu_calendar_calendar, feishu_calendar_event và feishu_calendar_freebusy.
• Soạn thảo tài liệu cộng tác: feishu_create_doc, feishu_fetch_doc, feishu_update_doc và feishu_doc_media.
• Kho tri thức Wiki và bình luận tài liệu: feishu_wiki_space, feishu_wiki_space_node và feishu_doc_comments.
• Giao việc và phản hồi từ người dùng: feishu_task_task, feishu_task_subtask và feishu_ask_user_question.

Đối với các nhóm kỹ thuật duy trì tài liệu sống, các công cụ wiki và bình luận tài liệu cho phép agent đọc bản ghi quyết định kiến trúc, phản hồi trực tiếp các nhận xét đánh giá mã nguồn trong tài liệu đặc tả, và tổ chức không gian dự án theo thứ bậc một cách tự động.

Công cụ feishu_ask_user_question được định nghĩa tại src/tools/ask-user-question.ts L955-L988. Khi agent cần làm rõ yêu cầu, nó phát một thẻ khảo sát kèm các lựa chọn bấm sẵn và lập tức trả về trạng thái pending; phản hồi của người dùng được chuyển đến bất đồng bộ qua sự kiện callback tiếp theo:

{
  "questions": [
    {
      "question": "Which deployment environment should this release target?",
      "header": "Deploy",
      "options": [
        { "label": "Staging", "description": "Validate before production" },
        { "label": "Canary", "description": "Roll out to a limited production cohort" }
      ],
      "multiSelect": false
    }
  ]
}

Việc cài đặt plugin vào OpenClaw thực hiện qua các lệnh tiêu chuẩn:

# Kiểm tra phiên bản Node.js phù hợp (yêu cầu Node 22+)
node --version

# Cài đặt plugin kênh Lark chính thức vào OpenClaw
openclaw plugins install @larksuite/openclaw-lark

# Kiểm tra danh sách kênh đã được đăng ký thành công
openclaw channels list

Kỹ sư phát triển có thể kiểm tra tính toàn vẹn của mã nguồn trong bản checkout bằng cách chạy bộ test qua lệnh vitest run (hoặc pnpm test), kèm kiểm tra định dạng qua pnpm lint. Các kiểm thử tự động này bảo đảm quy tắc serialize thẻ tin nhắn, phân tích schema và kiểm soát phân quyền kênh luôn hoạt động nhất quán trên các môi trường Node được hỗ trợ.