Lark — Tài liệu tập trung (Index)

Đọc file này TRƯỚC khi tương tác với bất kỳ Lark Base nào. Mọi agent (Claude Desktop, Claude Code, Codex, Gemini, cron, CI) phải hiểu kiến trúc ở đây để không đi đường tắt, không tạo credential riêng, không gọi HTTP tự phát.

1. NGUYÊN TẮC VÀNG

Một Bot duy nhất, một credential duy nhất, một cửa duy nhất.

        ┌─────────────────────────────────────────────┐
        │  Mọi agent (Desktop, CLI, Codex, Gemini...) │
        └──────────────────┬──────────────────────────┘
                           │
                           │ đều đi qua
                           ▼
        ┌─────────────────────────────────────────────┐
        │  Bot "For Gem" (cli_a785d634437a502f)       │  ← danh tính DUY NHẤT
        │  Credential: GSM LARK_APP_ID / LARK_APP_SECRET│  ← chìa khoá DUY NHẤT
        └──────────────────┬──────────────────────────┘
                           │ HTTPS
                           ▼
                   Lark Open API (cloud)
                           │
                           ▼
              18 Base trong folder "Dữ liệu Phái cử"

Hệ quả:

Muốn cấm agent nào đó → revoke ở Lark Developer Console, TẤT CẢ mất quyền cùng lúc (an toàn)
Lark version history log mọi thay đổi dưới tên "For Gem" → dễ audit
Không agent nào có "cửa sau", không agent nào hardcode app_token
Thêm Base mới → phải add "For Gem" vào Base đó mới dùng được (qua Lark web UI: ... → Xem thêm → Thêm ứng dụng)

2. HẠ TẦNG KẾT NỐI

2.1 Bot identity

Tên app: For Gem
App ID: cli_a785d634437a502f
Loại: Custom app (Lark Developer Console)
Phạm vi: đã add vào 18 Base trong folder "Dữ liệu Phái cử"
Chủ sở hữu folder: Nghiem Nguyen Quang

2.2 Credential — SSOT là GSM

Project: github-chatgpt-ggcloud
Secrets: LARK_APP_ID, LARK_APP_SECRET
Truy cập: gcloud secrets versions access latest --secret=LARK_APP_ID --project=github-chatgpt-ggcloud
CẤM: ghi credential vào .env, file config, code, log, chat
CẤM: tạo Bot thứ 2 trên Lark. Mọi agent chung 1 Bot

2.3 Domain

Base URL: https://open.larksuite.com (Lark Global, KHÔNG phải Feishu open.feishu.cn — khác domain, khác cluster)
Token endpoint: /open-apis/auth/v3/tenant_access_token/internal
Token TTL: ~7200s (2h), phải cache + refresh khi còn <300s

3. 2 ĐƯỜNG TRUY CẬP (song song, cùng đích)

Tất cả cùng đi qua For Gem + GSM credential, chỉ khác cách gọi:

3.1 Đường MCP — cho Claude Desktop (interactive)

Package: @larksuiteoapi/lark-mcp (chính chủ ByteDance)
Cấu hình: trên máy Huyên, Claude Desktop claude_desktop_config.json
Dùng cho: em (Claude Desktop) query ad-hoc khi bàn việc với anh
Tool prefix: lark-mcp:bitable_v1_*
Ưu: gọi ngay trong phiên chat, có autocomplete tool
Nhược: overhead MCP, không stable cho batch dài, mỗi client phải config riêng

3.2 Đường CLI — cho mọi agent trên VPS (batch, production) ← MẶC ĐỊNH từ S176

Binary: /usr/local/bin/lark-tool (symlink tới /opt/incomex/lark-client/cli/lark_tool.py)
Thư viện: /opt/incomex/lark-client/lark_client/ (Python package)
Dùng cho: Claude Code, Codex, Gemini, cron, CI, bất kỳ script nào trên VPS
Ví dụ: LARK_AGENT=claude-code lark-tool schema dump --all
Ưu: Ổn định, audit log tập trung, rate limit global, không cần MCP
Yêu cầu: mỗi client set LARK_AGENT=<tên> để audit nhận diện

Quy tắc chọn đường:

Interactive, query 1 bảng, bàn việc với Huyên → MCP (Desktop em)
Batch, script, cron, dump, trace, anomaly scan → CLI lark-tool
CẤM script Python trực tiếp import requests gọi Lark API — phải import lark_client hoặc gọi CLI

4. PATTERN LOT (Lark Operation Template)

Lấy ý tưởng từ DOT Directus, nhưng cho Lark. Mọi tương tác Lark phải tuân:

Thành phần	Yêu cầu
Input	app_token (từ Registry), table_id, params (không hardcode)
Auth	Token từ GSM qua `LarkCore` — không đọc GSM trực tiếp trong script nghiệp vụ
Endpoint whitelist	Chỉ gọi endpoint có trong `config/allowed_endpoints.yaml`. Muốn thêm = PR + review
Rate limit	Global file lock `/var/lock/lark-api.lock`, 10 req/s
Retry	3 lần exponential backoff cho 429/503/network
Audit	Mọi call log JSONL vào `/var/log/lark-ops/YYYYMMDD.jsonl`
Idempotent	Read: rerun cho kết quả giống. Write: client_token UUID
Verify	`fields_fetched == total`, checksum cross-ref
Rollback	Read: không cần. Write: backup record cũ + lệnh undo tự sinh
Agent identity	`$LARK_AGENT` env var → fallback: `$USER@$HOSTNAME` → parent proc → `unknown-$PID`

5. READ vs WRITE — PHÂN TẦNG NGHIÊM NGẶT

5.1 Read (S176 — đang triển khai)

Mọi agent gọi tự do qua CLI: lark-tool schema dump, lark-tool records sample, lark-tool audit tail
Module lark_client.reader chỉ có 3 method: list_tables, list_fields, search_records
Không có create/update/delete methods trong Phase 1

5.2 Write (S177 — mission riêng, chưa làm)

Module lark_client.writer (chưa tồn tại ở Phase 1)
5 lớp bảo vệ bắt buộc:
1. --dry-run phải chạy thành công trước
2. Approval ID trong config/write-approvals.yaml, có scope + reason + expiry
3. Backup record cũ vào /var/log/lark-ops/writes/
4. Idempotency key (client_token UUID)
5. Rollback command tự sinh, in ra stdout cuối lệnh
Write endpoints ban đầu RỖNG trong whitelist. Mỗi endpoint mới = 1 PR review
Không có UI approval lúc này — sẽ thiết kế ở S177

6. REGISTRY SSOT — 18 BASE

File: /opt/incomex/lark-client/config/bases.yaml (sau khi S176 Phase 1 chạy xong) Nguồn dữ liệu: knowledge/dev/lark/lark-base-registry.md

Nguyên tắc §0-AU:

CẤM hardcode app_token trong bất kỳ file .py/.sh/.ts/.vue nào
Chỉ được xuất hiện ở bases.yaml (SSOT) và tests/*.py (test exception)
Pre-check grep trước mỗi commit

7. CÁC TÀI LIỆU TRONG FOLDER NÀY

File	Mô tả	Khi nào đọc
`README.md`	File này — index, nguyên tắc, kiến trúc	LUÔN đọc trước tiên
`lark-base-registry.md`	Registry 18 Base + app_token + số bảng	Cần biết Base nào có sẵn
`lark-base-88-phai-cu-blueprint.md`	Blueprint Base 88 — 80 bảng 15 nhóm, quy ước, thuật ngữ	Hiểu phân loại bảng Base 88
`lark-base-88-data-flow.md`	Luồng dữ liệu Base 88 từ schema thật (3 bảng core)	Trace workflow giao việc, link fields
`lark-client-architecture.md`	[S176 Phase 1 sẽ tạo] — kiến trúc Python library + CLI	Khi viết script Lark mới
`snapshots/YYYY-MM-DD/`	[S176 Phase 3 sẽ tạo] — summary dump định kỳ	Tra cứu state Lark tại 1 thời điểm

8. TRẠNG THÁI HIỆN TẠI (2026-04-10)

Đã có

Bot "For Gem" tạo và add vào 18 Base
GSM credential
MCP lark-mcp cấu hình trên Claude Desktop
Schema 3 bảng core Base 88 (Đơn hàng 234, TTS 233, Nghiệp đoàn 87 fields) — Phase A
Registry 18 Base (markdown)
Blueprint Base 88 (80 bảng 15 nhóm)
Data flow Base 88 (3 luồng chính)
IAM unblock — grant secretmanager.secretAccessor cho cursor-ci-builder (S176, 2026-04-11)
lark_client Python library v1.0.0 — core + reader + registry + audit + exceptions (S176 Phase 1, 19/19 test PASS)
lark-tool CLI — registry/schema list/dump/summarize/audit (S176 Phase 2, 8/8 VERIFY PASS)

Đang triển khai (S176)

Phase 3 — Dump thật 18 Base + summary KB snapshots/2026-04-11/ (ĐANG CHẠY)

Chưa làm (backlog)

77 bảng còn lại trong Base 88 chưa đọc fields (sẽ xong ở Phase 3)
17 Base còn lại chưa khảo sát (sẽ xong ở Phase 3)
Lần 2 — dump records selective (master tables full, transaction sample)
S177 — Write guard module + CLI write commands + approval UI
Automation rules (API không hỗ trợ, phải screenshot web UI)
Map field Lark → schema PG cho migration sau này

9. ĐIỂM CẦN NHỚ (cho mọi agent đọc file này)

1 Bot, 1 chìa khoá, 1 cửa. Không agent nào tự tạo Bot riêng, không ai đọc GSM ngoài LarkCore, không script nào gọi HTTP trực tiếp
Read qua CLI lark-tool, write qua S177 (chưa có)
Không hardcode app_token ở bất kỳ đâu trừ bases.yaml và tests/
LARK_AGENT env var bắt buộc khi chạy CLI batch — để audit log nhận diện
Lark version history lọc theo "For Gem" = lớp audit thứ 2, độc lập VPS log
Lark Base render canvas — JS DOM query cho header/cell không hoạt động
Thao tác field phải dùng field_id, không dùng tên (tên có thể trùng)
Không được sửa TTN tiến cử trong TTS (schema ghi rõ)
Base URL là open.larksuite.com (KHÔNG phải open.feishu.cn)
Lark đang chạy production — 0 rủi ro là ưu tiên cao nhất, mọi operation read-only cho đến khi S177

10. GHI CHÚ CẬP NHẬT FILE NÀY

Bất kỳ agent nào (em, Claude Code, Codex, Gemini) khi phát hiện thông tin mới về kiến trúc, quy tắc, hoặc thay đổi hạ tầng Lark đều PHẢI cập nhật file này ngay. Cụ thể:

Thêm Bot mới (nếu có) → section 2.1
Thêm/đổi credential → section 2.2
Thêm tool/method mới → section 3
Thêm rule LOT mới → section 4
Thêm endpoint whitelist mới → ghi chú ở section 4 + 5
Thêm file tài liệu mới → section 7
Cập nhật trạng thái milestone → section 8
Phát hiện "không được làm" mới → section 9

File này là contract chung cho mọi agent làm việc với Lark. Giữ ngắn gọn, rõ ràng, không để outdated.

Tạo: 2026-04-10 | Revision 2: thêm kiến trúc 2 đường (MCP + CLI), pattern LOT, read/write phân tầng, checklist cập nhật