KB-1037
S178 Cong 2 GD1 Final Report
9 min read Revision 1
larkcong2s178rest-apiread-matrix
S178 Cong 2 GD1 — Final Report
S178 | 2026-04-11 | Lark Bitable REST API READ toolkit Base chinh: 88 "Phai cu" (YSIkb8PxOaNaozs2vwalOOcagkf)
TL;DR (10 dong)
- 46 endpoint Lark Bitable v1 public REST — 4 nguon dong thuan (Docs EN/CN, SDK Go/Python).
- 15 READ / 31 WRITE. GD1 verify 15/15 READ = 100% PASS.
- 5 phat hien trai docs: App Get (3 bonus field), Form Get (2 bonus), Form Fields (rich_description), Role List (278KB permission matrix), Member List (2 bonus).
- 2 undocumented: Role page_size max=30, Record List 12x cham hon Search.
- 1 confirm: Workflow List public = shallow (3 field). Cong 4 bat buoc cho full automation logic.
- Cong 2 co gia tri doc quyen: role permission matrix, form question tree, member user_id — Cong 4 CHUA phu.
- Cong 4 co 7 loai exclusive: automation full, syncTableIds, formula code, trash, ordering, change stream, record perm.
- Toolkit Python production-ready:
tools/lark_probe/— 645 LOC, 12 probe functions, dump_base() orchestrator. - Demo dump Base 88: 567 API calls, 256s, 10.7 MB JSON (80 tables, 3674 fields, 1791 records capped 50/table, 288 views, 6 forms, 183 workflows, 12 roles).
- Bottleneck: Table "Ke hoach cong viec" co ~424K records — Phase 4 can sampling/incremental strategy.
Roadmap 6 buoc — Vi tri hien tai
| Buoc | Muc tieu | Trang thai |
|---|---|---|
| 1 | Ve ro so do (hieu Lark van hanh) | Done (S176/S177 mechanisms.md) |
| 2 | Xay du tool dump | 50% — Cong 2 xong (S178). Cong 4 toolkit chua build. |
| 3 | Lay du thong tin, dung lai mo hinh | Chua |
| 4 | Xay tool CRUD | Chua |
| 5 | Sua chua Lark | Chua |
| 6 | Chuyen toan bo ve PG | Chua |
Ket qua 15/15 READ
| # | Endpoint | Status | Bat ngo |
|---|---|---|---|
| 1 | App Get | PASS | 3 field bonus (advance_version, formula_type, app_token) |
| 5 | Table List | PASS | — |
| 11 | Field List | PASS | — |
| 15 | Record List (deprecated) | PASS | 12x slower than Search |
| 16 | Record Get | PASS | — |
| 17 | Record Search | PASS | — |
| 18 | Record BatchGet | PASS | CN-only docs, works fine |
| 25 | View List | PASS | — |
| 26 | View Get | PASS | hidden_fields lo 54 field IDs |
| 30 | Form Get | PASS | shared_limit, submit_limit_once bonus |
| 31 | Form Field List | PASS | rich_description — question tree exposed |
| 34 | Dashboard List | PASS | Empty (Base 88 has 0 dashboards) |
| 36 | Workflow List | PASS | Shallow confirmed: {id, title, status} only |
| 38 | Role List | PASS | 278KB! table_roles[] = full perm matrix |
| 42 | Member List | PASS | user_id, member_en_name bonus |
Matrix 3 Cong
| Thong tin | C1 MCP | C2 REST | C4 Internal | Chinh | Ghi chu |
|---|---|---|---|---|---|
| App meta | N | 7 field | 34 keys (clientvars) | C2 basic, C4 extended | |
| Table list | Y | 80 tables | clientvars.blocks | C2 (headless) | |
| Field schema | Y | 87 fields | fieldMap | C2 (headless) | |
| Records | Y (search) | 500/page | 3000/call | C2 (production) | C4 higher limit |
| Views | N | list + detail | 37 views full | C4 richer, C2 baseline | |
| Forms | N | meta + questions | Chua test | C2 ONLY | |
| Dashboards | N | endpoint works | N/A | C2 | |
| Workflows (shallow) | N | 3 field | FULL logic | C4 for logic | C2 for id/status |
| Automation full | N | N | draft.steps[] | C4 ONLY | |
| Roles + perms | N | 278KB matrix | baseRoleMap partial | C2 | C2 richer than C4! |
| Members | N | full detail | N | C2 ONLY | |
| Sync Table IDs | N | N (heuristic) | syncTableIds | C4 ONLY | |
| Formula code | N | N | formulaInfo | C4 ONLY | |
| Trash tables | N | N | trashBlockMap | C4 ONLY | |
| Record ordering | N | N | viewRankMap | C4 ONLY | |
| Change stream | N | N | cs + latestCSRev | C4 ONLY |
Phase 4 Dump Estimate (dieu chinh sau P5)
| Cong | Operation | Calls/Base | x 18 Base | Total |
|---|---|---|---|---|
| C2 | Schema (app+tables+fields+views+view detail) | ~170 | 18 | ~3,060 |
| C2 | Records (search, 500/page) | varies | 18 | TBD (424K records bottleneck) |
| C2 | Forms + dashboards + workflows | ~10 | 18 | ~180 |
| C2 | Roles + members | ~17 | 18 | ~306 |
| C4 | clientvars (per table) | ~50 | 18 | ~900 |
| C4 | automation/list | 1 | 18 | 18 |
Schema-only (no records): ~3,546 calls = ~3 phut. With records (capped 50/table): ~5,600 calls = ~4.7 phut (P5 actual: 567 calls, 256s for 1 Base). With records (unlimited): TBD — "Ke hoach cong viec" alone = 848 pages = ~14 phut. Need incremental/delta strategy.
Bottleneck strategy cho Phase 4
- Option A: Cap max_records (50-500), dump schema + sample. Fast.
- Option B: Incremental — dump record_ids first (lightweight), then fetch full records in batches overnight.
- Option C: Use Cong 4 records endpoint (3000/call) for large tables — 3x fewer calls.
- Recommendation: A for first pass (mo hinh), B+C for production.
Toolkit Module Structure
tools/lark_probe/ 645 LOC Python + 264 LOC docs
__init__.py (13) exports LarkClient, dump_base
client.py (137) LarkClient: GSM auth, reactive retry, rate limit
probe.py (288) 12 probe_*() functions, auto-pagination, max_records
dump.py (152) dump_base() orchestrator
demo_dump_base88.py (55) demo script, env DUMP_MAX_RECORDS
README.md (70) usage docs
lark-rest-read-matrix.md P6 final matrix
Quickstart:
from tools.lark_probe import LarkClient, dump_base
client = LarkClient()
result = dump_base(client, "YSIkb8PxOaNaozs2vwalOOcagkf", max_records_per_table=50)
DE XUAT PATCH MECHANISMS.MD (KHONG tu patch — Desktop review)
Patch 1: Section 11 GPT matrix — 15 row tu ⏳ sang ✅
Chuyen tat ca READ endpoint tu "⏳" sang "✅ S178 verified" voi ghi chu cu the:
- App Get: 7 field (3 bonus)
- Records: 4 endpoint all verified
- Views: list + detail verified, property = {filter_info, hidden_fields, hierarchy_config}
- Forms: 2 endpoint verified, question tree exposed
- Dashboard: endpoint works, Base 88 empty
- Workflow: shallow confirmed (3 field)
- Roles: RICH — table_roles[] 278KB permission matrix, page_size max=30
- Members: full detail + user_id bonus
Patch 2: Section 5 matrix — 6 row cap nhat
Chuyen 6 row "⚠️ lark-mcp chua load tool" sang "✅ Cong 2 verified S178": Views, App meta, Roles & Permissions, Dashboards, Forms metadata, Workflow list.
Patch 3: Section moi "10ter. Cong 2 verified S178"
Them section moi gom:
- Auth model (tenant_access_token, GSM, reactive retry)
- 15 READ endpoint summary table
- 3 gia tri doc quyen Cong 2 (role perm, form questions, member user_id)
- 2 undocumented quirks (page_size=30, Record List 12x slow)
Patch 4: Section 10bis — Append so sanh Cong 2 vs Cong 4
- Cong 2 phu 15/15 READ, headless cron-ready
- Cong 4 vuot Cong 2 o 7 loai exclusive
- Cong 2 vuot Cong 4 o 3 loai exclusive
- Phase 4 dung CA HAI
Chuan bi GD2: 31 WRITE Endpoints
| Nhom | Count | Canh bao |
|---|---|---|
| App (create/update/copy) | 3 | Copy = tao Base moi. Test tren sandbox. |
| Table (CRUD + batch) | 5 | Delete = mat data. Sandbox bat buoc. |
| Field (CRUD) | 3 | Update field type co the mat data. |
| Record (CRUD + batch) | 6 | batch_create up to 500, batch_update up to 1000 |
| View (CRUD) | 3 | Nhe, an toan test |
| Form (update) | 2 | Nhe |
| Dashboard (copy) | 1 | Nhe |
| Workflow (enable/disable) | 1 | NGUY HIEM: disable workflow on production = dung automation |
| Role (CRUD) | 3 | Anh huong permission |
| Member (CRUD + batch) | 4 | Anh huong access |
BAT BUOC: Tao Base sandbox rieng cho GD2. KHONG test WRITE tren Base 88/6.5 production.
Bai hoc cho phien sau
- Role List trai docs nhieu nhat — docs noi "role_id, role_name" nhung thuc te tra 278KB permission matrix. Luon test thuc te, khong tin docs.
- page_size undocumented limits — Role max=30, docs im lang. Can test moi endpoint voi page_size lon de phat hien.
- Record List deprecated dung ly — 12x cham. Luon dung Search.
- 424K records bottleneck — Bảng lon can strategy rieng (incremental, delta, Cong 4 3000/call).
- API tra null thay [] — Role members API tra null cho empty list. Pattern:
data.get(key) or []. - Toolkit hoat dong tot — 567 calls, 0 error (sau fix null), 10.7 MB output. Production-ready.