Bridge giữa agent và Lark
Trong phiên Hermes, Lark CLI nên được xem như tool bridge. Agent có thể đọc dữ liệu Lark để hiểu bối cảnh làm việc, sau đó đề xuất hoặc thực hiện hành động nếu người dùng xác nhận.
1. Lark CLI là gì trong ngữ cảnh Hermes
LarkSuite CLI là lớp thao tác dòng lệnh để Hermes và người dùng làm việc với Lark: kiểm tra auth, tìm người, gửi tin nhắn, quản lý task, đọc docs/wiki/drive và tạo cập nhật có kiểm soát.
Contact, IM, Task, Docs
Các nhóm lệnh thường xoay quanh danh bạ, chat, task, docs, wiki và drive. Mọi quyền phụ thuộc vào OAuth scope, workspace Lark và user đang login.
Read-first automation
Hermes có thể tăng tốc thao tác, nhưng không thay thế kiểm tra. Luôn đọc trạng thái hiện tại trước khi gửi tin, tạo task, cập nhật task hoặc chỉnh tài liệu.
2. Trạng thái đã cài/connect hiện tại
Kết quả hiện tại tại workspace này: lark-cli đã cài và dùng được. Phiên auth đã sẵn sàng cho cả bot identity và user identity, token còn valid, và nhiều OAuth scopes cần thiết đã có.
Checklist máy hiện tại
- ✓CLI: đã cài
lark-cli version 1.0.59. - ✓Bot identity: ready.
- ✓User identity: ready cho Hai Ninh Vu / Michael Aurora.
- ✓Open ID:
ou_22fd91bb15250a9e771b2654e62d1201. - ✓Token/scopes: token valid; nhiều scopes đã có cho contact, IM, task và các nhóm Lark liên quan.
Lệnh kiểm tra nên chạy
lark-cli --version
lark-cli auth status --json
lark-cli contact +search-user --query "Michael" --as user --json
lark-cli task +get-my-tasks --complete=false --as user --jsonDùng --as user cho thao tác cần quyền user Michael. Trước thao tác ghi, kiểm tra lại trạng thái bằng JSON để thấy identity, token và scopes thực tế.
3. Các nhóm lệnh hay dùng
Các command bên dưới dùng đúng binary và cú pháp hiện tại: lark-cli, resource như contact/task/im, action dạng +action-name, và flag --as user khi cần identity của Michael.
Auth status
Kiểm tra user, tenant/workspace, scope và expiry. Chạy đầu phiên và trước write action.
lark-cli auth status --jsonContact search
Tìm người nhận theo tên hoặc email trước khi gửi IM hoặc assign task. Tránh dùng ID đoán.
lark-cli contact +search-user --query "Michael" --as user --jsonIM send
Gửi tin nhắn sau khi xác nhận đúng open_id hoặc chat. Với nội dung nhạy cảm, đưa bản nháp để review trước.
lark-cli im +messages-send --receive-id-type open_id --receive-id ou_22fd91bb15250a9e771b2654e62d1201 --text "Nội dung đã được xác nhận" --as user --jsonTask list/search
Đọc danh sách và search trước. Khi tạo hoặc update bằng các action task khác, ghi rõ title, assignee, due date và mô tả.
lark-cli task +get-my-tasks --complete=false --as user --json
lark-cli task +search --query "keyword" --completed=false --as user --jsonDocs, Wiki, Drive
| Nhóm | Dùng để | Ghi chú cú pháp |
|---|---|---|
auth | Xác nhận identity, token và scopes hiện có. | lark-cli auth status --json |
contact | Tìm user theo query trước khi dùng open_id trong IM/task. | lark-cli contact +search-user --query "Michael" --as user --json |
update | Cập nhật CLI khi schema/action thay đổi. | lark-cli update |
4. Workflow an toàn
Chuẩn vận hành cho Hermes khi dùng Lark CLI trong AI Native Lab.
- 1Đọc trước ghi sau: dùng
lark-cli auth status --json,lark-cli contact +search-user,lark-cli task +get-my-tasksvàlark-cli task +searchđể xác nhận thực thể hiện tại. - 2Write action cần xác nhận: trước
lark-cli im +messages-sendhoặc action tạo/cập nhật task/docs, Hermes phải trình bày người nhận, nội dung, ID và tác động. - 3Không lộ secret: không paste app secret, refresh token, access token, cookie hoặc private key vào prompt, log, docs hay IM.
- 4Kiểm tra workspace/user: xác nhận tenant, user login và scope trước khi chạy lệnh có tác động tới team.
- 5Ghi audit ngắn: lưu command, timestamp, mục tiêu, kết quả và link Lark liên quan nếu task quan trọng.
5. Ví dụ lệnh copy được
Các ví dụ dùng placeholder, không chứa secret thật. Thay USER_ID, TASK_ID, DOC_ID, FOLDER_ID bằng giá trị đã kiểm tra.
Chuẩn bị phiên làm việc
lark-cli auth status --json
lark-cli contact +search-user --query "Michael" --as user --json
lark-cli task +get-my-tasks --complete=false --as user --jsonGửi update sau xác nhận
lark-cli im +messages-send --receive-id-type open_id --receive-id ou_22fd91bb15250a9e771b2654e62d1201 --text "Michael ơi, em đã kiểm tra xong checklist Hermes/Lark. Phần cần anh xác nhận là quyền task và docs." --as user --jsonTìm task follow-up
lark-cli task +search --query "Xác nhận scope Lark CLI" --completed=false --as user --jsonCập nhật CLI
lark-cli update
lark-cli --version
lark-cli auth status --json6. Troubleshooting
Các lỗi phổ biến khi dùng Lark CLI từ Hermes và cách xử lý nhanh.
Thiếu scope
Dấu hiệu: auth valid nhưng lệnh contact/task/IM báo forbidden hoặc missing permission.
lark-cli auth status --jsonAuth/login hết hạn
Dấu hiệu: token expired, invalid grant, yêu cầu re-consent hoặc không thấy user. Sau khi xử lý auth, kiểm tra lại bằng JSON.
lark-cli auth status --jsonCLI/tool chưa đúng version
Dấu hiệu: command cũ, schema mismatch, action không hỗ trợ hoặc tài liệu vẫn nhắc tới binary cũ.
lark-cli --version
lark-cli update
lark-cli auth status --jsonCần update
Dấu hiệu: thiếu nhóm task/docs mới, output JSON đổi schema hoặc CLI báo unsupported.
lark-cli update
lark-cli --version7. Quick start cho Michael
Luồng ngắn để Michael bắt đầu trong một phiên Hermes mới, không cần nhớ toàn bộ tài liệu.
- ✓Mở terminal tại workspace dự án và kiểm tra CLI:
lark-cli --versionphải trả vềlark-cli version 1.0.59. - ✓Kiểm tra auth:
lark-cli auth status --jsonđể xác nhận bot identity ready, user identity ready và token valid. - ✓Xác nhận đúng user Hai Ninh Vu / Michael Aurora với open_id
ou_22fd91bb15250a9e771b2654e62d1201. - ✓Chạy read command trước: tìm contact, list task, search task. Chỉ chạy send/create/update sau khi xác nhận nội dung.
- ✓Khi cần cập nhật CLI, dùng
lark-cli update.
lark-cli --version
lark-cli auth status --json
lark-cli contact +search-user --query "Michael" --as user --json
lark-cli task +get-my-tasks --complete=false --as user --json
lark-cli task +search --query "keyword" --completed=false --as user --json