Chuyển tới nội dung chính

Thiết lập Feishu / Lark

Đại lý Hermes tích hợp với Feishu và Lark dưới dạng bot đầy đủ tính năng. Sau khi kết nối, bạn có thể trò chuyện với tổng đài viên bằng tin nhắn trực tiếp hoặc trò chuyện nhóm, nhận kết quả công việc định kỳ trong cuộc trò chuyện tại nhà và gửi văn bản, hình ảnh, âm thanh và tệp đính kèm thông qua luồng cổng thông thường.

Việc tích hợp hỗ trợ cả hai chế độ kết nối:​

websocket — được khuyến nghị; Hermes mở kết nối gửi đi và bạn không cần điểm cuối webhook công khai​

webhook — hữu ích khi bạn muốn Feishu/Lark đẩy các sự kiện vào cổng của bạn qua HTTP

Cách Hermes cư xử​

Bối cảnhHành vi
Tin nhắn trực tiếpHermes trả lời mọi tin nhắn.
Trò chuyện nhómHermes chỉ phản hồi khi bot được @đề cập trong cuộc trò chuyện.
Trò chuyện nhóm được chia sẻTheo mặc định, lịch sử phiên được tách riêng cho mỗi người dùng trong cuộc trò chuyện được chia sẻ.

Hành vi trò chuyện chia sẻ này được kiểm soát bởi `config.yaml

:

group_sessions_per_user: true

`
``Chỉ đặt thành 
`false
` nếu bạn rõ ràng muốn một cuộc trò chuyện được chia sẻ cho mỗi cuộc trò chuyện.

## Bước 1: Tạo ứng dụng Feishu/Lark

### Khuyến nghị: Quét để tạo (một lệnh)

`bash
Hermes gateway setup

`
``Chọn **Feishu / Lark** và quét mã QR bằng ứng dụng di động Feishu hoặc Lark của bạn. Hermes sẽ tự động tạo một ứng dụng bot với các quyền chính xác và lưu thông tin xác thực.

### Phương án thay thế: Thiết lập thủ công

Nếu tính năng quét để tạo không khả dụng, trình hướng dẫn sẽ quay lại chế độ nhập thủ công:
1. Mở bảng điều khiển dành cho nhà phát triển Feishu hoặc Lark:

   - Feishu: [https://open.Feishu.cn/](https://open.Feishu.cn/)
   - Sơn ca: [https://open.larksuite.com/](https://open.larksuite.com/)
2. Tạo một ứng dụng mới.
3. Trong **Thông tin xác thực & Thông tin cơ bản**, sao chép **ID ứng dụng** và **Bí mật ứng dụng**.
4. Kích hoạt khả năng **Bot** cho ứng dụng.
5. Chạy 
`Hermes gateway setup

, chọn **Feishu / Lark** và nhập thông tin xác thực khi được nhắc.

:::warning
Giữ Bí mật ứng dụng ở chế độ riêng tư. Bất cứ ai có nó đều có thể mạo danh ứng dụng của bạn.
:::

## Bước 2: Chọn Chế độ kết nối

### Khuyến nghị: Chế độ WebSocket

Sử dụng chế độ WebSocket khi Hermes chạy trên máy tính xách tay, máy trạm hoặc máy chủ riêng của bạn. Không có URL công khai được yêu cầu. SDK Lark chính thức mở và duy trì kết nối WebSocket gửi đi liên tục bằng tính năng kết nối lại tự động.

``` bash
Feishu_CONNECTION_MODE=websocket

`
``**Yêu cầu:** Phải cài đặt gói Python 
`websockets

. SDK xử lý vòng đời kết nối, nhịp tim và tự động kết nối lại trong nội bộ.

**Cách hoạt động:** Bộ điều hợp chạy ứng dụng khách WebSocket của Lark SDK trong luồng thực thi nền. Các sự kiện gửi đến (tin nhắn, phản ứng, hành động thẻ) được gửi đến vòng lặp asyncio chính. Khi ngắt kết nối, SDK sẽ cố gắng tự động kết nối lại.

### Tùy chọn: Chế độ Webhook

Chỉ sử dụng chế độ webhook khi bạn đã chạy Hermes sau điểm cuối HTTP có thể truy cập.

`bash
Feishu_CONNECTION_MODE=webhook

`
``Ở chế độ webhook, Hermes khởi động máy chủ HTTP (thông qua 
`aiohttp

) và phục vụ điểm cuối Feishu tại:

`text
/Feishu/webhook

`
``**Yêu cầu:** Phải cài đặt gói Python 
`aiohttp

.

Bạn có thể tùy chỉnh địa chỉ và đường dẫn liên kết của máy chủ webhook:

`bash
Feishu_WEBHOOK_HOST=127.0.0.1   # default: 127.0.0.1
Feishu_WEBHOOK_PORT=8765         # default: 8765
Feishu_WEBHOOK_PATH=/Feishu/webhook  # default: /Feishu/webhook

`
``Khi Feishu gửi thử thách xác minh URL (
`type: url_verification

), webhook sẽ tự động phản hồi để bạn có thể hoàn tất thiết lập đăng ký trong bảng điều khiển dành cho nhà phát triển Feishu. Phản hồi thử thách được kiểm soát trên 
`Feishu_VERIFICATION_TOKEN
` khi được đặt — các yêu cầu thử thách có mã thông báo bị thiếu hoặc không khớp sẽ bị từ chối nên điều khiển từ xa không được xác thực không thể chứng minh khả năng kiểm soát điểm cuối bằng cách lặp lại dữ liệu thử thách do kẻ tấn công kiểm soát.

## Bước 3: Cấu hình Hermes

### Tùy chọn A: Thiết lập tương tác

`bash
Hermes gateway setup

`
``Chọn **Feishu / Lark** và điền vào lời nhắc.

### Tùy chọn B: Cấu hình thủ công

Thêm phần sau vào 

~/.Hermes/.env

:

`bash
Feishu_APP_ID=CLI_xxx
Feishu_APP_SECRET=secret_xxx
Feishu_DOMAIN=Feishu
Feishu_CONNECTION_MODE=websocket

# Optional but strongly recommended
Feishu_ALLOWED_USERS=ou_xxx,ou_yyy
Feishu_HOME_CHANNEL=oc_xxx

`
```Feishu_DOMAIN
` chấp nhận:
- 
`Feishu
` cho Feishu Trung Quốc

- 
`lark
` dành cho Lark quốc tế

## Bước 4: Khởi động Gateway

``` bash
Hermes gateway

`
``Sau đó nhắn tin cho bot từ Feishu/Lark để xác nhận rằng kết nối đang hoạt động.

## Trò chuyện tại nhà

Sử dụng 

/set-home
` trong cuộc trò chuyện Feishu/Lark để đánh dấu kênh này là kênh chính để biết kết quả công việc định kỳ và thông báo đa nền tảng.

Bạn cũng có thể cấu hình sẵn nó:

`bash
Feishu_HOME_CHANNEL=oc_xxx

`

## Bảo mật

### Danh sách cho phép người dùng

Để sử dụng trong sản xuất, hãy đặt danh sách cho phép các ID mở Feishu:

`bash
Feishu_ALLOWED_USERS=ou_xxx,ou_yyy

`
``Nếu bạn để trống danh sách cho phép thì bất kỳ ai có thể tiếp cận bot đều có thể sử dụng bot đó. Trong cuộc trò chuyện nhóm, danh sách cho phép được kiểm tra dựa trên open_id của người gửi trước khi xử lý tin nhắn.### Khóa mã hóa Webhook

Khi chạy ở chế độ webhook, hãy đặt khóa mã hóa để bật xác minh chữ ký của tải trọng webhook gửi đến:

`bash
Feishu_ENCRYPT_KEY=your-encrypt-key

`
``Bạn có thể tìm thấy khóa này trong phần **Đăng ký sự kiện** trong cấu hình ứng dụng Feishu của bạn. Khi được đặt, bộ điều hợp sẽ xác minh mọi yêu cầu webhook bằng thuật toán chữ ký:

`
SHA256(timestamp + nonce + encrypt_key + body)

`
``Hàm băm được tính toán được so sánh với tiêu đề 
`x-lark-signature
` bằng cách sử dụng so sánh an toàn về thời gian. Yêu cầu có chữ ký không hợp lệ hoặc thiếu chữ ký sẽ bị từ chối bằng HTTP 401.

:::tip
Ở chế độ WebSocket, việc xác minh chữ ký được chính SDK xử lý, vì vậy 
`Feishu_ENCRYPT_KEY
` là tùy chọn. Ở chế độ webhook, nó được khuyến khích sử dụng cho sản xuất.

:::

### Mã thông báo xác minh

Một lớp xác thực bổ sung kiểm tra trường 
`token
` bên trong tải trọng webhook:

``` bash
Feishu_VERIFICATION_TOKEN=your-verification-token

`
``Mã thông báo này cũng được tìm thấy trong phần **Đăng ký sự kiện** trong ứng dụng Feishu của bạn. Khi được đặt, mọi tải trọng webhook gửi đến phải chứa 
`token
` phù hợp trong đối tượng 
`header

. Mã thông báo không khớp sẽ bị từ chối bằng HTTP 401.

Cả 
`Feishu_ENCRYPT_KEY
` và 
`Feishu_VERIFICATION_TOKEN
` đều có thể được sử dụng cùng nhau để phòng thủ theo chiều sâu.

## Chính sách tin nhắn của nhóm

Biến môi trường 
`Feishu_GROUP_POLICY
` kiểm soát xem Hermes có phản hồi như thế nào trong các cuộc trò chuyện nhóm hay không và như thế nào:

`bash
Feishu_GROUP_POLICY=allowlist   # default

`

| Giá trị | Hành vi |
|-------|----------|
| 
`open
` | Hermes phản hồi các @đề cập từ bất kỳ người dùng nào trong bất kỳ nhóm nào. |
| 
`allowlist
` | Hermes chỉ phản hồi các @đề cập từ người dùng được liệt kê trong 
`Feishu_ALLOWED_USERS

. |
| 
`disabled
` | Hermes hoàn toàn bỏ qua tất cả các tin nhắn nhóm. |

Trong tất cả các chế độ, bot phải được đề cập rõ ràng bằng @ (hoặc @all) trong nhóm trước khi tin nhắn được xử lý. Tin nhắn trực tiếp luôn bỏ qua cổng này.

Đặt 
`Feishu_REQUIRE_MENTION=false
` để cho phép Hermes đọc tất cả lưu lượng truy cập của nhóm mà không yêu cầu @mention:

`bash
Feishu_REQUIRE_MENTION=false

`
``Để kiểm soát mỗi cuộc trò chuyện, hãy đặt 
`require_mention
` trên mục nhập 
`group_rules
` — xem [Per-Group Access Control](#per-group-access-control) bên dưới.

### Nhận dạng Bot

Hermes tự động phát hiện 
`open_id
` của bot và hiển thị tên khi khởi động. Bạn chỉ cần đặt những cài đặt này theo cách thủ công khi tính năng tự động phát hiện không thể tiếp cận API Feishu hoặc khi ứng dụng của bạn sử dụng ID người dùng trong phạm vi đối tượng thuê:

`bash
Feishu_BOT_OPEN_ID=ou_xxx     # only when auto-detection fails
Feishu_BOT_USER_ID=xxx        # required if your app uses sender_id_type=user_id
Feishu_BOT_NAME=MyBot         # only when auto-detection fails

`

## Nhắn tin từ Bot đến Bot

Theo mặc định, Hermes bỏ qua tin nhắn được gửi bởi các bot khác. Kích hoạt tính năng nhắn tin từ bot đến bot khi bạn muốn Hermes tham gia điều phối A2A hoặc nhận thông báo từ các bot khác trong cùng nhóm.

`bash
Feishu_ALLOW_BOTS=mentions   # default: none

`

| Giá trị | Hành vi |
|-------|----------|
| 
`none
` | Bỏ qua tất cả tin nhắn từ các bot khác (mặc định). |
| 
`mentions
` | Chỉ chấp nhận khi bot ngang hàng @đề cập đến Hermes. |
| 
`all
` | Chấp nhận mọi tin nhắn bot ngang hàng. |

Cũng có thể định cấu hình là 
`Feishu.allow_bots
` trong 
`config.yaml
` (env thắng khi cả hai được đặt).

Không cần thêm các bot ngang hàng vào 
`Feishu_ALLOWED_USERS
` — danh sách cho phép đó chỉ áp dụng cho người gửi.

Cấp phạm vi 
`application:bot.basic_info:read
` để hiển thị tên bot ngang hàng; không có nó, các bot ngang hàng vẫn định tuyến chính xác nhưng xuất hiện dưới dạng 
`open_id

.

## Hành động thẻ tương tác

Khi người dùng nhấp vào nút hoặc tương tác với các thẻ tương tác do bot gửi, bộ điều hợp sẽ định tuyến những thẻ này dưới dạng sự kiện lệnh 

/card
` tổng hợp:
- Nút bấm trở thành: 

/card button \{"key": "value", ...}

`
- Tải trọng 
`value
` của hành động từ định nghĩa thẻ được đưa vào dưới dạng JSON.
- Các hành động thẻ được loại bỏ trùng lặp với thời hạn 15 phút để ngăn chặn việc xử lý trùng lặp.

Lời nhắc cập nhật dựa trên cổng sử dụng thẻ Feishu 
`Yes
` / 
`No
` gốc thay vì quay lại trả lời bằng văn bản thuần túy. Khi 
`Hermes update --gateway
` cần xác nhận, bộ điều hợp sẽ ghi lại câu trả lời đã chọn trong tệp 

.update_response
` của Hermes và thay thế thẻ nội tuyến bằng trạng thái đã giải quyết.

Các sự kiện hành động thẻ được gửi đi bằng 
`MessageType.COMMAND

, do đó chúng chảy qua quy trình xử lý lệnh thông thường.

Đây cũng là cách **phê duyệt lệnh** hoạt động — khi tác nhân cần chạy một lệnh nguy hiểm, nó sẽ gửi một thẻ tương tác với các nút Cho phép một lần / Phiên / Luôn / Từ chối. Người dùng nhấp vào nút và lệnh gọi lại hành động thẻ sẽ gửi lại quyết định phê duyệt cho tổng đài viên.

### Cấu hình ứng dụng Feishu bắt buộcThẻ tương tác yêu cầu **ba** bước cấu hình trong Bảng điều khiển dành cho nhà phát triển Feishu. Thiếu bất kỳ mục nào trong số chúng sẽ gây ra lỗi **200340** khi người dùng nhấp vào nút thẻ.
1. **Đăng ký sự kiện hành động thẻ:**
   Trong **Đăng ký sự kiện**, thêm 
`card.action.trigger
` vào các sự kiện đã đăng ký của bạn.
2. **Kích hoạt tính năng Thẻ tương tác:**
   Trong **Tính năng ứng dụng > Bot**, đảm bảo bật nút chuyển đổi **Thẻ tương tác**. Điều này cho Feishu biết rằng ứng dụng của bạn có thể nhận được lệnh gọi lại hành động thẻ.
3. **Định cấu hình URL yêu cầu thẻ (chỉ ở chế độ webhook):**
   Trong **Tính năng ứng dụng > Bot > URL yêu cầu thẻ tin nhắn**, hãy đặt URL về cùng điểm cuối với webhook sự kiện của bạn (ví dụ: 
`https://your-server:8765/Feishu/webhook

). Trong chế độ WebSocket, việc này được SDK xử lý tự động.

:::warning
Nếu không có cả ba bước, Feishu sẽ *gửi* thẻ tương tác thành công (chỉ gửi yêu cầu quyền 
`im:message:send

), nhưng việc nhấp vào bất kỳ nút nào sẽ trả về lỗi 200340. Thẻ có vẻ hoạt động — lỗi chỉ xuất hiện khi người dùng tương tác với nó.
:::

## Nhận xét tài liệu Trả lời thông minh

Ngoài trò chuyện, bộ điều hợp còn có thể trả lời các đề cập 

@
` còn lại trên **tài liệu Feishu/Lark**. Khi người dùng nhận xét về một tài liệu (lựa chọn văn bản cục bộ hoặc nhận xét toàn bộ tài liệu) và @-đề cập đến bot, Hermes sẽ đọc tài liệu đó cùng với chuỗi nhận xét xung quanh và đăng nội dung trả lời LLM trên chuỗi đó.

Được hỗ trợ bởi sự kiện 
`drive.notice.comment_add_v1

, trình xử lý:
- Tìm nạp song song nội dung tài liệu và dòng thời gian nhận xét (20 tin nhắn cho các chuỗi toàn bộ tài liệu, 12 cho các chuỗi chọn cục bộ).
- Chạy tác nhân với bộ công cụ 
`Feishu_doc

 + 
`Feishu_drive
` trong phạm vi phiên nhận xét duy nhất đó.
- Chunks trả lời ở 4000 ký tự và đăng lại dưới dạng câu trả lời theo chuỗi.
- Lưu các phiên trên mỗi tài liệu vào bộ nhớ đệm trong 1 giờ với giới hạn 50 tin nhắn để các nhận xét tiếp theo trên cùng một tài liệu sẽ giữ nguyên ngữ cảnh.

### Kiểm soát truy cập 3 tầng

Các câu trả lời nhận xét về tài liệu **chỉ được cấp rõ ràng** — không có chế độ cho phép tất cả ngầm định. Quyền được giải quyết theo thứ tự sau (trận đầu tiên thắng, trên mỗi trường):
1. **Tài liệu chính xác** — quy tắc nằm trong phạm vi mã thông báo tài liệu cụ thể.
2. **Ký tự đại diện** — quy tắc khớp với mẫu tài liệu.
3. **Cấp cao nhất** — quy tắc mặc định cho không gian làm việc.

Hai chính sách có sẵn cho mỗi quy tắc:
- **
`allowlist

** — danh sách tĩnh người dùng/người thuê.
- **
`pairing

** — danh sách tĩnh ∪ cửa hàng được phê duyệt trong thời gian chạy. Hữu ích cho các đợt triển khai trong đó người kiểm duyệt có thể cấp quyền truy cập trực tiếp.

Các quy tắc tồn tại trong 

~/.Hermes/Feishu_comment_rules.JSON
` (cấp ghép nối trong 

~/.Hermes/Feishu_comment_pairing.JSON

) với tính năng tải lại nóng được lưu vào bộ nhớ đệm mtime — các chỉnh sửa sẽ có hiệu lực trong sự kiện nhận xét tiếp theo mà không cần khởi động lại cổng.

CLI:

``` bash

# Inspect current rules and pairing state
Python -m gateway.platforms.Feishu_comment_rules status

# Simulate an access check for a specific doc + user
Python -m gateway.platforms.Feishu_comment_rules check <fileType:fileToken <user_open_id

# Manage pairing grants at runtime
Python -m gateway.platforms.Feishu_comment_rules pairing list
Python -m gateway.platforms.Feishu_comment_rules pairing add <user_open_id
Python -m gateway.platforms.Feishu_comment_rules pairing remove <user_open_id

`

### Cấu hình ứng dụng Feishu bắt buộc

Ngoài các quyền trò chuyện/thẻ đã được cấp, hãy thêm sự kiện nhận xét trên Drive:
- Đăng ký 
`drive.notice.comment_add_v1
` trong **Đăng ký sự kiện**.
- Cấp các phạm vi 
`docs:doc:readonly
` và 
`drive:drive:readonly
` để người xử lý có thể đọc nội dung tài liệu.

## Hỗ trợ truyền thông

### Trong nước (đang nhận)

Bộ điều hợp nhận và lưu trữ các loại phương tiện sau từ người dùng:

| Loại | Tiện ích mở rộng | Nó được xử lý như thế nào |
|------|-------------|-------------------|
| **Hình ảnh** | .jpg, .jpeg, .png, .gif, .webp, .bmp | Được tải xuống qua API Feishu và được lưu vào bộ nhớ đệm cục bộ |
| **Âm thanh** | .ogg, .mp3, .wav, .m4a, .aac, .flac, .opus, .webm | Đã tải xuống và lưu vào bộ nhớ đệm; các tập tin văn bản nhỏ được tự động giải nén |
| **Video** | .mp4, .mov, .avi, .mkv, .webm, .m4v, .3gp | Đã tải xuống và lưu vào bộ nhớ đệm dưới dạng tài liệu |
| **Tệp** | .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, v.v. | Đã tải xuống và lưu vào bộ nhớ đệm dưới dạng tài liệu |

Phương tiện từ các tin nhắn văn bản đa dạng thức (bài đăng), bao gồm hình ảnh nội tuyến và tệp đính kèm, cũng được trích xuất và lưu vào bộ nhớ đệm.

Đối với các tài liệu dạng văn bản nhỏ (.txt, .md), nội dung tệp sẽ tự động được đưa vào văn bản tin nhắn để tổng đài viên có thể đọc trực tiếp mà không cần đến công cụ.

### Gửi đi (gửi)| Phương pháp | Nó gửi gì |
|--------|--------------|
| 
`send
` | Tin nhắn văn bản hoặc bài viết phong phú (được tự động phát hiện dựa trên nội dung đánh dấu) |
| 
`send_image
` / 
`send_image_file
` | Tải hình ảnh lên Feishu, sau đó gửi dưới dạng bong bóng hình ảnh gốc (có chú thích tùy chọn) |
| 
`send_document
` | Tải tệp lên API Feishu, sau đó gửi dưới dạng tệp đính kèm |
| 
`send_voice
` | Tải tệp âm thanh lên dưới dạng tệp đính kèm tệp Feishu |
| 
`send_video
` | Tải video lên và gửi dưới dạng tin nhắn đa phương tiện gốc |
| 
`send_animation
` | GIF bị hạ cấp thành tệp đính kèm (Feishu không có bong bóng GIF gốc) |

Định tuyến tải lên tệp được tự động dựa trên tiện ích mở rộng:
- 

.ogg

, 

.opus
` → được tải lên dưới dạng âm thanh 
`opus

- 

.mp4

, 

.mov

, 

.avi

, 

.m4v
` → được tải lên dưới dạng phương tiện 
`mp4

- 

.pdf

, 

.doc(x)

, 

.xls(x)

, 

.ppt(x)
` → được tải lên cùng với loại tài liệu của chúng
- Mọi thứ khác → được tải lên dưới dạng tệp luồng chung

## Hiển thị Markdown và đăng dự phòng

Khi văn bản gửi đi chứa định dạng đánh dấu (tiêu đề, in đậm, danh sách, khối mã, liên kết, v.v.), bộ điều hợp sẽ tự động gửi nó dưới dạng tin nhắn Feishu **post** với thẻ 
`md
` được nhúng thay vì dưới dạng văn bản thuần túy. Điều này cho phép hiển thị phong phú trong ứng dụng khách Feishu.

Nếu API Feishu từ chối tải trọng bài đăng (ví dụ: do cấu trúc đánh dấu không được hỗ trợ), bộ điều hợp sẽ tự động quay trở lại gửi dưới dạng văn bản thuần túy bị loại bỏ đánh dấu. Dự phòng hai giai đoạn này đảm bảo tin nhắn luôn được gửi.

Tin nhắn văn bản thuần túy (không phát hiện thấy đánh dấu) được gửi dưới dạng loại tin nhắn 
``` text
` đơn giản.

## Đang xử lý các phản ứng trạng thái

Trong khi tác nhân đang làm việc, bot hiển thị phản ứng 
`Typing
` trên tin nhắn của bạn. Nó sẽ bị xóa khi có phản hồi hoặc được thay thế bằng 
`CrossMark
` nếu quá trình xử lý không thành công.

Đặt 
`Feishu_REACTIONS=false
` để tắt.

## Bảo vệ chống cháy nổ và phân khối

Bộ điều hợp bao gồm việc gỡ lỗi cho các loạt tin nhắn nhanh chóng để tránh làm quá tải tác nhân:

### Sắp xếp văn bản

Khi người dùng gửi nhiều tin nhắn văn bản liên tiếp, chúng sẽ được hợp nhất thành một sự kiện duy nhất trước khi được gửi đi:

| Cài đặt | Env Var | Mặc định |
|----------|----------|---------|
| Thời kỳ yên tĩnh |

Hermes_Feishu_TEXT_BATCH_DELAY_SECONDS
` | 0,6 giây |
| Số tin nhắn tối đa mỗi đợt |

Hermes_Feishu_TEXT_BATCH_MAX_MESSAGES
` | 8 |
| Ký tự tối đa mỗi đợt |

Hermes_Feishu_TEXT_BATCH_MAX_CHARS
` | 4000 |

### Phương tiện truyền thông hàng loạt

Nhiều tệp đính kèm phương tiện được gửi liên tiếp nhanh chóng (ví dụ: kéo một số hình ảnh) sẽ được hợp nhất thành một sự kiện duy nhất:

| Cài đặt | Env Var | Mặc định |
|----------|----------|---------|
| Thời kỳ yên tĩnh |

Hermes_Feishu_MEDIA_BATCH_DELAY_SECONDS
` | 0,8 giây |

### Tuần tự hóa mỗi cuộc trò chuyện

Các tin nhắn trong cùng một cuộc trò chuyện được xử lý tuần tự (mỗi lần một tin nhắn) để duy trì sự mạch lạc trong cuộc trò chuyện. Mỗi cuộc trò chuyện có khóa riêng nên tin nhắn trong các cuộc trò chuyện khác nhau sẽ được xử lý đồng thời.

## Giới hạn tốc độ (Chế độ Webhook)

Ở chế độ webhook, bộ điều hợp thực thi giới hạn tốc độ trên mỗi IP để bảo vệ khỏi lạm dụng:
- **Cửa sổ:** Cửa sổ trượt 60 giây

- **Giới hạn:** 120 yêu cầu trên mỗi cửa sổ trên mỗi bộ ba (app_id, path, IP)
- **Giới hạn theo dõi:** Đã theo dõi tối đa 4096 khóa duy nhất (ngăn chặn sự tăng trưởng bộ nhớ không giới hạn)

Yêu cầu vượt quá giới hạn sẽ nhận được HTTP 429 (Quá nhiều yêu cầu).

### Theo dõi sự bất thường của Webhook

Bộ điều hợp theo dõi các phản hồi lỗi liên tiếp trên mỗi địa chỉ IP. Sau 25 lỗi liên tiếp từ cùng một IP trong khoảng thời gian 6 giờ, một cảnh báo sẽ được ghi lại. Điều này giúp phát hiện các máy khách bị định cấu hình sai hoặc các nỗ lực thăm dò.

Các biện pháp bảo vệ webhook bổ sung:
- **Giới hạn kích thước cơ thể:** tối đa 1 MB
- **Thời gian chờ đọc nội dung:** 30 giây
- **Thực thi loại nội dung:** Chỉ chấp nhận 
`application/JSON

## Điều chỉnh WebSocket

Khi sử dụng chế độ 
`websocket

, bạn có thể tùy chỉnh hành vi kết nối lại và ping:

``` yaml
platforms:
  Feishu:
    extra:
      ws_reconnect_interval: 120   # Seconds between reconnect attempts (default: 120)
      ws_ping_interval: 30         # Seconds between WebSocket pings (optional; SDK default if unset)

`

| Cài đặt | Phím cấu hình | Mặc định | Mô tả |
|----------|-------------|---------|-------------|
| Khoảng thời gian kết nối lại |

ws_reconnect_interval
` | 120s | Phải đợi bao lâu giữa các lần kết nối lại |
| Khoảng thời gian Ping |

ws_ping_interval
` | _(SDK mặc định)_ | Tần suất ping liên tục của WebSocket |

## Kiểm soát truy cập theo nhóm

Ngoài 
`Feishu_GROUP_POLICY
` toàn cầu, bạn có thể đặt các quy tắc chi tiết cho mỗi cuộc trò chuyện nhóm bằng 
`group_rules
` trong config.yaml:

`YAML
platforms:
  Feishu:
    extra:
      default_group_policy: "open"     # Default for groups not in group_rules
      admins:                          # Users who can manage bot settings

        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_group_chat_id_2":
          policy: "admin_only"
        "oc_group_chat_id_3":
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"
        "oc_free_chat":
          policy: "open"
          require_mention: false       # overrides Feishu_REQUIRE_MENTION for this chat

`

| Chính sách | Mô tả |
|--------|-------------|
| 
`open
` | Bất kỳ ai trong nhóm đều có thể sử dụng bot |
| 
`allowlist
` | Chỉ người dùng trong 
`allowlist
` của nhóm mới có thể sử dụng bot |
| 
`blacklist
` | Mọi người ngoại trừ người dùng trong 
`blacklist
` của nhóm đều có thể sử dụng bot |
| 
`admin_only
` | Chỉ người dùng trong danh sách 
`admins
` toàn cầu mới có thể sử dụng bot trong nhóm này |
| 
`disabled
` | Bot bỏ qua tất cả tin nhắn trong nhóm này |

Đặt 
`require_mention: false
` trên mục nhập 
`group_rules
` để bỏ qua yêu cầu @-đề cập cho cuộc trò chuyện cụ thể đó. Khi bị bỏ qua, cuộc trò chuyện sẽ kế thừa giá trị 
`Feishu_REQUIRE_MENTION
` toàn cầu.

Các nhóm không được liệt kê trong 
`group_rules
` sẽ quay trở lại 
`default_group_policy
` (mặc định là giá trị 
`Feishu_GROUP_POLICY

).

## Chống trùng lặp

Tin nhắn gửi đến sẽ được loại bỏ trùng lặp bằng cách sử dụng ID tin nhắn có TTL 24 giờ. Trạng thái loại trừ được duy trì trong suốt quá trình khởi động lại 

~/.Hermes/Feishu_seen_message_ids.JSON

.

| Cài đặt | Env Var | Mặc định |
|----------|----------|---------|
| Kích thước bộ đệm |

Hermes_Feishu_DEDUP_CACHE_SIZE
` | 2048 mục |

## Tất cả các biến môi trường

| Biến | Bắt buộc | Mặc định | Mô tả |
|----------|----------|---------|-------------|
| 
`Feishu_APP_ID
` | ✅ | — | ID ứng dụng Feishu/Lark |
| 
`Feishu_APP_SECRET
` | ✅ | — | Bí mật ứng dụng Feishu/Lark |
| 
`Feishu_DOMAIN
` | — |

Feishu
` | 
`Feishu
` (Trung Quốc) hoặc 
`lark
` (quốc tế) |
| 
`Feishu_CONNECTION_MODE
` | — |

websocket
` | 
`websocket
` hoặc 
`webhook
` |
| 
`Feishu_ALLOWED_USERS
` | — | _(trống)_ | Danh sách open_id được phân tách bằng dấu phẩy dành cho danh sách cho phép người dùng |
| 
`Feishu_ALLOW_BOTS
` | — |

none
` | Chấp nhận tin nhắn từ các bot khác: 
`none

, 
`mentions
` hoặc 
`all
` |
| 
`Feishu_REQUIRE_MENTION
` | — |

true
` | Liệu tin nhắn nhóm có phải @mention bot |
| 
`Feishu_HOME_CHANNEL
` | — | — | ID trò chuyện cho đầu ra cron/thông báo |
| 
`Feishu_ENCRYPT_KEY
` | — | _(trống)_ | Khóa mã hóa để xác minh chữ ký webhook |
| 
`Feishu_VERIFICATION_TOKEN
` | — | _(trống)_ | Mã thông báo xác minh cho xác thực tải trọng webhook |
| 
`Feishu_GROUP_POLICY
` | — |

allowlist
` | Chính sách tin nhắn nhóm: 
`open

, 
`allowlist

, 
`disabled
` |
| 
`Feishu_BOT_OPEN_ID
` | — | _(trống)_ | open_id của Bot (để phát hiện @mention) |
| 
`Feishu_BOT_USER_ID
` | — | _(trống)_ | user_id của Bot (để phát hiện @mention) |
| 
`Feishu_BOT_NAME
` | — | _(trống)_ | Tên hiển thị của Bot (để phát hiện @mention) |
| 
`Feishu_WEBHOOK_HOST
` | — |

127.0.0.1
` | Địa chỉ liên kết máy chủ Webhook |
| 
`Feishu_WEBHOOK_PORT
` | — |

8765
` | Cổng máy chủ Webhook |
| 
`Feishu_WEBHOOK_PATH
` | — |

/Feishu/webhook
` | Đường dẫn điểm cuối Webhook |
| 
`Hermes_Feishu_DEDUP_CACHE_SIZE
` | — |

2048
` | ID tin nhắn được loại bỏ tối đa để theo dõi |
| 
`Hermes_Feishu_TEXT_BATCH_DELAY_SECONDS
` | — |

0.6
` | Văn bản bùng nổ gỡ lỗi thời kỳ yên tĩnh |
| 
`Hermes_Feishu_TEXT_BATCH_MAX_MESSAGES
` | — |

8
` | Số tin nhắn tối đa được hợp nhất trên mỗi lô văn bản |
| 
`Hermes_Feishu_TEXT_BATCH_MAX_CHARS
` | — |

4000
` | Số ký tự tối đa được hợp nhất trên mỗi lô văn bản |
| 
`Hermes_Feishu_MEDIA_BATCH_DELAY_SECONDS
` | — |

0.8
` | Truyền thông bùng nổ thời kỳ im lặng |

Cài đặt WebSocket và ACL theo nhóm được định cấu hình qua 
`config.yaml
` trong 
`platforms.Feishu.extra
` (xem [WebSocket Tuning](#websocket-tuning) và [Per-Group Access Control](#per-group-access-control) ở trên).

## Khắc phục sự cố| Vấn đề | Sửa chữa |
|----------|------|
| 
`lark-oAPI not installed
` | Cài đặt SDK: 
`pip install lark-oAPI
` |
| 
`websockets not installed; websocket mode unavailable
` | Cài đặt ổ cắm web: 
`pip install websockets
` |
| 
`aiohttp not installed; webhook mode unavailable
` | Cài đặt aiohttp: 
`pip install aiohttp
` |
| 
`Feishu_APP_ID or Feishu_APP_SECRET not set
` | Đặt cả hai biến env hoặc định cấu hình qua 
`Hermes gateway setup
` |
| 
`Another local Hermes gateway is already using this Feishu app_id
` | Tại một thời điểm, chỉ một phiên bản Hermes có thể sử dụng cùng một app_id. Dừng cổng khác trước. |
| Bot không phản hồi theo nhóm | Đảm bảo bot được @đề cập, kiểm tra 
`Feishu_GROUP_POLICY
` và xác minh người gửi có trong 
`Feishu_ALLOWED_USERS
` nếu chính sách là 
`allowlist
` |
| 
`Webhook rejected: invalid verification token
` | Đảm bảo 
`Feishu_VERIFICATION_TOKEN
` khớp với mã thông báo trong cấu hình Đăng ký sự kiện của ứng dụng Feishu của bạn |
| 
`Webhook rejected: invalid signature
` | Đảm bảo 
`Feishu_ENCRYPT_KEY
` khớp với khóa mã hóa trong cấu hình ứng dụng Feishu của bạn |
| Đăng tin nhắn hiển thị dưới dạng văn bản thuần túy | API Feishu từ chối tải trọng bài đăng; đây là hành vi dự phòng bình thường. Kiểm tra nhật ký để biết chi tiết. |
| Bot không nhận được hình ảnh/tập tin | Cấp phạm vi quyền 
`im:message
` và 
`im:resource
` cho ứng dụng Feishu của bạn |
| Nhận dạng bot không được tự động phát hiện | Thông thường, sự cố mạng tạm thời xảy ra với điểm cuối thông tin bot của Feishu. Đặt 
`Feishu_BOT_OPEN_ID
` và 
`Feishu_BOT_NAME
` theo cách thủ công như một giải pháp thay thế. |
| Tin nhắn bot ngang hàng vẫn bị bỏ qua sau khi bật 
`Feishu_ALLOW_BOTS
` | Hermes chưa thể tự nhận dạng - đặt 
`Feishu_BOT_OPEN_ID
` (và 
`Feishu_BOT_USER_ID
` nếu ứng dụng của bạn sử dụng 
`sender_id_type=user_id

). |
| Các bot ngang hàng hiển thị dưới dạng 
`ou_xxxxxx
` thay vì theo tên | Cấp phạm vi 
`application:bot.basic_info:read

. |
| Lỗi 200340 khi nhấp vào nút phê duyệt | Bật khả năng **Thẻ tương tác** và định cấu hình **URL yêu cầu thẻ** trong Bảng điều khiển dành cho nhà phát triển Feishu. Xem [Required Feishu App Configuration](#required-Feishu-app-configuration) ở trên. |
| 
`Webhook rate limit exceeded
` | Hơn 120 yêu cầu/phút từ cùng một IP. Đây thường là một cấu hình sai hoặc một vòng lặp. |

## Bộ công cụ

Feishu / Lark sử dụng cài đặt sẵn nền tảng 
`Hermes-Feishu

, bao gồm các công cụ cốt lõi giống như Telegram và các nền tảng nhắn tin dựa trên cổng khác.