# CHO CLAUDE ĐỌC: Bước 4. Cài Lark + trợ lý Lark

> Tài liệu này viết cho Claude Code của học viên. Người học chỉ cần dán câu lệnh bên dưới vào Claude, Claude đọc file này rồi làm.
> Thuộc hệ thống triển khai AI 20 bước của Trương Minh Kiên. Trang bước này: https://trienkhailark.truongminhkien.vn

## Việc cần làm

Claude điều khiển Lark của bạn: tạo Base Lead, sổ khách hàng mà mọi bước sau ghi vào.

Câu lệnh học viên dán vào Claude:

```
Tải gói https://trienkhailark.truongminhkien.vn/tro-ly-lark.zip, giải nén, đọc CHO-CLAUDE-DOC.md rồi cài lark-cli cho tôi, đăng nhập, tạo 1 Lark Base tên Lead có bảng cột Họ tên / Số điện thoại / Email / Nguồn / Ngày tạo
```

## Luật khi làm

1. Đọc hết file này, kể cả phần bẫy, trước khi chạy lệnh nào.
2. Việc cần mật khẩu, mã OTP, token hay thanh toán thì dừng lại để học viên tự làm, không nhập hộ.
3. Không xoá dữ liệu, bản ghi DNS hay file cũ của học viên. Chỉ thêm.
4. Khoá bí mật chỉ nằm trong `.env` (đã có trong `.gitignore`), không ghi vào mã, wiki hay kết quả.
5. Xong mỗi bước thì kiểm tra thật (chạy thử, đọc lại) rồi mới báo xong.
6. Gói này chạy trên máy của học viên, không phải máy người soạn. Mọi đường dẫn tính từ thư mục giải nén hoặc thư mục vault của học viên; hỏi học viên nếu cần. Skill nào nhắc tới file `output/...` hay trang `wiki/...` mà vault học viên chưa có thì đó chỉ là nguồn tham khảo của người soạn: bỏ qua, dùng nội dung ngay trong skill. Riêng `wiki/concepts/bo-mau-thuong-hieu.md`: nếu chưa có, chép từ `mau/bo-mau-thuong-hieu.md` trong gói rồi hỏi học viên để điền.

## Skill trong gói

- `lark`
- `lark-approval`
- `lark-apps`
- `lark-attendance`
- `lark-base`
- `lark-calendar`
- `lark-contact`
- `lark-doc`
- `lark-drive`
- `lark-event`
- `lark-im`
- `lark-mail`
- `lark-markdown`
- `lark-meeting` (thêm 19/10: tra biên bản, ghi chép, bản ghi cuộc họp Lark)
- `lark-minutes`
- `lark-note`
- `lark-okr`
- `lark-openapi-explorer`
- `lark-shared`
- `lark-sheets`
- `lark-skill-maker`
- `lark-slides`
- `lark-task`
- `lark-vc`
- `lark-vc-agent`
- `lark-whiteboard`
- `lark-wiki`
- `lark-workflow-meeting-summary`
- `lark-workflow-standup-report`

Cách cài skill: chép từng thư mục trong `.claude/skills/` của gói vào `.claude/skills/` của vault Obsidian (bước 1). Tên thư mục phải trùng tên skill, file chính tên `SKILL.md`.

## Cách cài đặt từng bước (làm theo thứ tự)

### CHO CLAUDE ĐỌC — cài lark-cli, kết nối Lark, tạo Base "Lead"

> Bạn là Claude Code trên máy một người mới. Người đó vừa dán: *"Đọc repo trên rồi cài lark-cli cho
> tôi, đăng nhập, tạo 1 Lark Base tên Lead…"*. Kết quả cuối: `lark-cli whoami` ra tên thật của họ,
> và một Base **Lead** có bảng `Lead` với cột Họ tên / Số điện thoại / Email / Nguồn / Ngày tạo,
> mở được trong ứng dụng Lark của họ. Tiếng Việt, mỗi lượt một việc.

## 0. Kiểm trước

| # | Cần | Lệnh kiểm | Thiếu thì |
|---|---|---|---|
| 1 | Node.js ≥ 18 | `node --version` | Cài từ https://nodejs.org (bản LTS), mở lại PowerShell |
| 2 | Tài khoản **Lark** (larksuite.com), đã đăng nhập trên trình duyệt | hỏi người dùng | Người dùng tự tạo tài khoản — Claude không tạo hộ |
| 3 | Chưa có `~/.lark-cli/config.json` | `Test-Path ~/.lark-cli/config.json` | **Nếu ĐÃ có** → tuyệt đối không chạy `config init` (bẫy 1). Dùng `lark-cli profile add` |

## 1. Cài lark-cli

```
npm install -g @larksuite/cli
lark-cli --version
```
Tên lệnh là **`lark-cli`**, không phải `lark`. Tài liệu API của 27 domain nằm sẵn trong CLI: `lark-cli skills list` · `lark-cli skills read lark-base`
(bản mới của CLI tự phát các skill `lark-*` vào `~/.claude/skills/` ở lần chạy đầu — kiểm bằng `ls ~/.claude/skills`).

Chép thư mục `.claude/skills/lark/` của repo này vào `~/.claude/skills/lark/` — đó là **la bàn
tiếng Việt** (định tuyến câu hỏi → lệnh, luật an toàn, sổ sự cố).

## 2. Tạo app Lark và nạp vào CLI — máy mới, chưa có hồ sơ

```
lark-cli config init --new --brand lark
```
Lệnh này **chặn cho tới khi người dùng làm xong trên trình duyệt**: nó in một link → đưa link cho
người dùng → họ đăng nhập Lark, bấm tạo app theo hướng dẫn trên trang → CLI tự nhận app_id/secret.
Chạy lệnh trong **cửa sổ có tiêu đề** (không ẩn) để người dùng thấy và tắt được. Nếu công cụ của bạn
chỉ trả kết quả cuối, chạy nền và đọc link từ tệp log.

`--brand lark` cho tài khoản larksuite.com (quốc tế). Tài khoản feishu.cn → `--brand feishu`.

**Không bao giờ nhận App Secret từ người dùng để tự gõ.** Nếu họ đã có app: `lark-cli profile add`
— CLI tự hỏi, che kín lúc gõ.

## 3. Đăng nhập danh tính người dùng

```
lark-cli auth login --domain base,docs,drive,task,calendar,im,mail,wiki,sheets --no-wait --json
```
Lấy `verification_url` + `device_code` từ kết quả. Dựng QR: `lark-cli auth qrcode --output ./qr.png "<verification_url>"`
(đường dẫn `--output` **phải tương đối**, trong thư mục hiện hành). Gửi người dùng **cả link lẫn QR**,
**kết thúc lượt**. Họ báo xong → `lark-cli auth login --device-code <device_code>`.

Kiểm: `lark-cli whoami` → `identity: user`, `onBehalfOf.userName` là tên họ. Chữ `needs_refresh`
**không phải lỗi** — CLI tự làm mới.

## 4. Tạo Base "Lead"

```
lark-cli base +base-create --as user --name "Lead" --table-name "Lead" --time-zone Asia/Ho_Chi_Minh --fields '[{"name":"Họ tên","type":"text"},{"name":"Số điện thoại","type":"text","style":{"type":"phone"}},{"name":"Email","type":"text","style":{"type":"email"}},{"name":"Nguồn","type":"select","options":[{"name":"Facebook"},{"name":"Zalo"},{"name":"Website"},{"name":"Giới thiệu"}]},{"name":"Ngày tạo","type":"created_at"}]'
```
Kiểu trường theo `lark-cli skills read lark-base/references/lark-base-field-json.md`: điện thoại và email là
`text` + `style.type`; ngày tạo là `created_at`. Trước khi chạy thật: `--dry-run` một lần. Trường nào bị từ chối →
đọc lại tệp tham chiếu đó, đừng bịa thuộc tính. **Tạo bằng `--as user`** để Base thuộc về người
dùng và hiện ngay trong Lark của họ (bẫy 4).

Kết quả trả `app_token` + `url`. Lưu hai thứ này vào `references/may-nay.md` của skill lark (bảng
"Base Lead") — các gói sau (trang thu, máy gửi thư, Zalo) đều cần.

## 5. Nghiệm thu

1. Người dùng mở link Base trên Lark → thấy bảng `Lead` với 5 cột.
2. Thêm thử một dòng: `lark-cli base +record-batch-create --as user --base-token <app_token> --table-id <table_id> --records '[{"fields":{"Họ tên":"Thử","Số điện thoại":"0900000000","Nguồn":"Website"}}]'` → `ok: true`, dòng hiện trên Lark. Xoá dòng thử sau đó.
3. `lark-cli auth status --json` → user `ready` hoặc `needs_refresh`, domain đã cấp gồm `base`.

## 6. Bẫy đã trả giá

| # | Bẫy | Cách tránh |
|---|---|---|
| 1 | **`config init` xoá sạch mọi hồ sơ đang có, kể cả khi thêm `--profile`** (đã mất hồ sơ hai lần trong một ngày) | Chỉ chạy trên máy chưa có `config.json`. Có rồi → `profile add` |
| 2 | `bot: ready` không có nghĩa khoá đúng — chỉ là có khoá được lưu | Kiểm bằng một lệnh thật |
| 3 | `missing_scope` thực ra là gọi `--as bot` cho shortcut *user-only* | Đọc `hint` trong lỗi; thử `--as user` trước khi xin thêm quyền |
| 4 | Tạo bằng `--as bot` → tài nguyên thuộc bot, người dùng không thấy | `--as user` cho mọi thứ họ cần sở hữu |
| 5 | Token đăng nhập từ công cụ của Claude (sandbox Windows) nằm ở lớp registry khác → **Task Scheduler / tiến trình nền dùng token cũ** | Việc chạy theo lịch: đăng nhập lại bằng một task tạm (`schtasks /Create /SC ONCE … /TR "cmd /c lark-cli auth login --domain base > _login.txt"`), lấy link trong `_login.txt` |
| 6 | Cập nhật bản ghi Base là `PUT` (thay cả bản ghi), không phải `PATCH` | Gửi đủ trường khi cập nhật |
| 7 | `auth login` không `--no-wait` chặn mãi trong công cụ không hiện tiến trình | Luôn `--no-wait --json` rồi `--device-code` ở lượt sau |
| 8 | `_notice` "có bản CLI mới" trong mọi kết quả | Không phải lỗi, không tự chạy `lark-cli update` |
| 9 | Kết quả có `ok:false` kèm `hint`/`suggestions` là tên cờ đúng | Đọc hint rồi sửa, không đoán lần hai |

## 7. Báo cáo cuối (khuôn)

```
✅ lark-cli <phiên bản> · hồ sơ <app_id> · đăng nhập: <tên người dùng>
📊 Base "Lead": <url> · app_token … · table_id …
🧪 Nghiệm thu: mở được / thêm dòng thử ok / quyền base ✔
➡️ Tiếp: các gói trang thu, máy gửi thư, Zalo sẽ dùng app_token này
```


## Hướng dẫn chi tiết và các bẫy đã gặp

(Bản đầy đủ có hình và nút bấm: https://trienkhailark.truongminhkien.vn)

Yêu cầu trước khi bắt đầu

- Đã hoàn thành [Bước 2: Cài Claude AI](https://trienkhaiclaude.truongminhkien.vn/)
- Có tài khoản Lark (đăng ký miễn phí tại [larksuite.com](https://www.larksuite.com) nếu chưa có)

## Các bước cài đặt

1

### Cài lark-cli

Mở Terminal/PowerShell, gõ:

npm install -g @larksuite/cli

Kiểm tra:

lark-cli --version

**Không cần "kết nối" lark-cli với Claude AI** — đăng nhập xong (Bước 2-3 dưới đây) là Claude AI tự dùng được ngay, vì nó chạy chung Terminal/máy với bạn (xem nguyên tắc ở [Bước 2](https://trienkhaiclaude.truongminhkien.vn/)).

2

### Cấu hình app lần đầu

lark-cli config init --new

Lệnh này in ra 1 đường link + mã QR — **mở link đó trên trình duyệt của chính bạn** để tạo app Lark gắn với tài khoản của bạn. Đừng đưa mật khẩu Lark cho ai/AI nào — chỉ cần mở link và làm theo trên chính trình duyệt bạn đang đăng nhập.

3

### Đăng nhập

lark-cli auth login --recommend

Lại hiện link — mở trên trình duyệt, xác nhận đăng nhập. Kiểm tra đã đăng nhập thành công:

lark-cli auth status

4

### Tạo bảng Lark Base dùng xuyên suốt hệ thống

Lark Base giống Excel/Airtable — mỗi bảng lưu 1 loại dữ liệu. Tạo ngay bảng chính này để các bước sau chỉ việc nối vào:

**Bảng Lead (khách để lại thông tin):** nói với Claude AI: *"Tạo cho tôi 1 Lark Base tên 'Lead - \[tên dự án của bạn\]', 1 bảng có cột Họ và tên / Số điện thoại / Email / Ngày tạo."* Dùng ở [Bước 11 (Lead Magnet)](https://trienkhaileadmagnet.truongminhkien.vn/) và mọi nơi thu thông tin khách sau này. Claude sẽ tự dùng lark-cli để tạo, trả về `app_token` và `table_id` — ghi lại đầy đủ, dùng ở mọi bước sau.

**Không cần tự tạo bảng "Lịch đăng bài" ở đây** — bảng đó (và 4 bảng khác) sẽ được workflow `init-tables` của repo thật tự động tạo ngay trong Base này ở [Bước 14 (Đăng Facebook tự động)](https://trienkhaifb.truongminhkien.vn/). Tự tạo tay trước ở đây sẽ ra 1 bảng thừa, không phải bảng mà script Bước 14 thực sự đọc/ghi.

## ⚠ Bẫy đã gặp thật + cách gỡ

0\. 🔴 Nghiêm trọng nhất — mời quyền cao nhất qua giao diện vẫn báo "you don't have permission" (91403)

Nếu Base được tạo bằng cách bấm icon chuyển đổi ứng dụng ngay trên giao diện Lark, Base đó tự động bị đưa vào không gian "Wiki" — khi đó mời app làm cộng tác viên qua nút "Chia sẻ" trên giao diện (dù chọn quyền cao nhất "Có thể quản lý", dù giao diện báo "Đã mời" thành công) vẫn KHÔNG được nhận diện đúng ở tầng API. Đã thử đủ cách qua giao diện (bật Bot, đổi quyền chia sẻ toàn tổ chức, xoá cache token lấy token mới, mời lại quyền cao nhất) — vẫn báo lỗi y hệt. Đây là lỗi/giới hạn thật ở tầng nền tảng, không phải do làm sai bước nào.

**Cách gỡ (đã xác nhận hết lỗi ngay từ lần thử đầu):** đừng tạo Base qua icon chuyển đổi ứng dụng trên giao diện — yêu cầu Claude AI tạo Base **thẳng qua dòng lệnh** (không qua Wiki), rồi cấp quyền ghi cũng qua dòng lệnh (không qua nút "Chia sẻ" trên giao diện). Nếu 1 Base đã lỡ tạo qua giao diện và dính lỗi này, cách nhanh nhất là tạo Base MỚI theo đúng cách trên, không cố sửa Base cũ.

1\. npm chặn cài đặt bằng "allow-scripts"

Sau `npm install -g @larksuite/cli`, npm chặn script cài đặt sau cùng, và `npm approve-scripts` báo "không có gì đang chờ" — không giải quyết được gì.

**Cách gỡ:** chạy thẳng script bị chặn:

node "\$(npm root -g)/@larksuite/cli/scripts/install.js"

2\. Lệnh đăng nhập bị timeout giữa chừng

Nếu chạy `config init`/`auth login` trong 1 giới hạn thời gian ngắn (ví dụ lệnh tự huỷ sau 20 giây), nó bị giết ngay khi vừa in ra link — **trước khi kịp mở trình duyệt bấm vào**.

**Cách gỡ:** luôn để lệnh này chạy không giới hạn thời gian / chạy nền, đợi vài phút cho tới khi tự xác nhận xong — đừng vội huỷ.

3\. Link đăng nhập hết hạn

Mã `user_code` trong link đăng nhập chỉ sống vài phút. Nếu bấm vào mà báo hết hạn/không hợp lệ, đừng cố lại link cũ.

**Cách gỡ:** chạy lại đúng lệnh ở Bước 2/3 để lấy link mới, bấm ngay trong vài phút.

4\. Bot báo lỗi "you don't have permission" (code 91403) khi ghi/xoá dữ liệu

App bot mặc định không đủ quyền ghi/xoá record trong Base, dù đã được thêm làm thành viên.

**Cách gỡ:** chạy lệnh với quyền người dùng thay vì bot (thêm cờ `--as user`), rồi làm theo link xác thực hiện ra để cấp quyền qua chính tài khoản của bạn.

5\. PowerShell làm hỏng dữ liệu JSON khi gửi lệnh

Trên Windows, nếu truyền thẳng 1 đoạn JSON vào lệnh (ví dụ `--json '{"a":"b"}'`), PowerShell tự ý bỏ dấu ngoặc kép, lệnh nhận sai dữ liệu, báo lỗi kiểu "invalid character".

**Cách gỡ:** ghi nội dung JSON ra 1 file riêng trước, rồi trỏ lệnh vào file đó (ví dụ `--json "@./du-lieu.json"`) thay vì gõ thẳng.

Bước tiếp theo

Đã có Lark, sang bước kế tiếp: cài GitHub — nơi lưu code và chạy tự động miễn phí, cần cho nhiều bước sau.

[Sang bước 5: Cài GitHub →](https://trienkhaigithub.truongminhkien.vn/)
<!-- them 19/10 -->
### Lark khoá gọi API cả tháng (lỗi 99991403)
Gói Lark miễn phí có hạn mức số lần gọi API mỗi tháng, **tính chung cả tài khoản**, không riêng từng app. Máy tự động gọi 5 phút một lần cộng một đợt chuyển dữ liệu lớn là hết; mọi app và cả Claude bị khoá tới đầu tháng sau, trang thu lead báo lỗi.
**Cách gỡ:** máy chạy theo giờ thay vì 5 phút; nhớ đệm mã đăng nhập, danh sách bảng và cột; chỉ đọc bảng khi có thay đổi; đếm lượt gọi theo tháng và tự bỏ việc phụ khi gần trần. Chuyển dữ liệu lớn thì chia ra nhiều ngày. Trang thu lead phải có chỗ cất tạm khi Lark không nhận (gói Bước 11).

### App có quyền sửa nhưng thấy 0 bảng
Base bật quyền nâng cao thì app chỉ được "Có thể sửa" vẫn không thấy bảng nào; lệnh đọc trả rỗng, không báo lỗi.
**Cách gỡ:** cấp app mức **Có thể quản lý** ở Base đó rồi đọc thử lại danh sách bảng.