kf — CLI nội bộ KesFlow

kf cho phép agent (Claude Code, Hermes, Codex) làm việc nội bộ KesFlow thay bạn, thay vì bạn bấm từng màn trên ops. Agent dùng đúng tài khoản ops của bạn: bạn được làm gì trên ops thì agent làm được đúng như vậy, không hơn. Mỗi thao tác qua agent đều được ghi nhật ký.

Hiện có nhóm LMS sau buổi học: xem lớp/buổi mình phụ trách, gắn record từ Google Drive, tải slide/record lên, đổi tên/gỡ tệp, ghi recap/bài tập/chuẩn bị, đăng buổi. Danh sách luôn cập nhật theo server — gõ kf --help để xem.

1. Cài đặt (một lần mỗi máy)

Cần Node.js 22 trở lên.

npm install -g @kesflow/kf

Cài skill cho Claude Code (giúp agent dùng kf đúng cách):

mkdir -p ~/.claude/skills/kf-cli && cp "$(npm root -g)/@kesflow/kf/SKILL.md" ~/.claude/skills/kf-cli/SKILL.md

Agent khác (Hermes, Codex…): nạp tệp SKILL.md ở $(npm root -g)/@kesflow/kf/SKILL.md theo cách agent đó nạp skill.

2. Đăng nhập (một lần mỗi máy)

1. Vào ops → Kết nối của tôi (/noi-bo/ket-noi) → đặt tên máy (vd "Laptop làm việc") → Tạo token → copy. Token chỉ hiện một lần.
2. Mở một terminal riêng (Terminal trên macOS/Linux, PowerShell trên Windows) và gõ:

   kf login

   Dán token vào ô ẩn (không hiện chữ) rồi Enter.
3. Kiểm tra: kf status hiện tên bạn và các lớp bạn phụ trách.

Không dán token vào ô chat của Claude Code hay bất kỳ agent nào, và không gõ ! kf login trong ô chat (lệnh ! không có terminal nên không nhập ẩn được). Agent sẽ chỉ nhắc bạn đăng nhập, không bao giờ hỏi token.

Token tự gia hạn khi còn dùng; bỏ không dùng 30 ngày thì hết hạn — khi đó tạo token mới và kf login lại. Đổi máy, mất máy hoặc nghi lộ: vào Kết nối của tôi → Thu hồi. kf logout chỉ xoá token trên máy, không thu hồi trên server.

3. Dùng với Claude Code

Sau khi đăng nhập, cứ nói việc cần làm, ví dụ:

• "Xem các buổi của lớp TA05."
• "Chốt buổi B03 lớp TA05: gắn record từ link Drive này, đổi tên thành 'Record Buổi 3 - …', ghi recap như sau …"
• "Tải file slide.html này lên buổi B03 lớp TA05."

Agent tự tìm thao tác phù hợp (kf --help), chạy thử khi cần (--dry-run), rồi làm.

4. Thao tác rủi ro cao

Các thao tác gắn nhãn [high] (vd đăng buổi có gửi thư cho học viên) cần thêm --yes. Agent chỉ được thêm --yes sau khi bạn đồng ý rõ trong chat với đúng nội dung: buổi nào, lớp nào, có gửi thư không. Đọc kỹ trước khi đồng ý — thư đã gửi thì không thu hồi được.

Khuyến nghị: để Claude Code hỏi quyền trước khi chạy lệnh shell (không bật chế độ bỏ qua quyền) khi làm việc với kf.

5. Dùng tay (tuỳ chọn)

kf --help                                   # danh sách thao tác hiện có
kf lms-buoi --lop-ma TA05                   # các buổi của lớp
kf lms-buoi-chi-tiet --buoi-id <id>         # tệp, recap, đề bài của buổi
kf lms-doi-ten --tep-id <id> --ten 'Tên mới'
kf lms upload slide.html --buoi-id <id>     # tải tệp lên (tự nhận loại theo đuôi tệp)
kf tn upload file.pdf --ma <SP>             # tải tệp tài nguyên lên sản phẩm
kf lms-ghi-recap --buoi-id <id> --recap-md '# Recap' --de-bai-md null --dry-run
kf <thao-tác> --help                        # tham số của một thao tác

Kết quả là một dòng JSON (--pretty để dễ đọc). kf tn upload gửi tới https://ops.kesflow.vn (không đổi KF_API_URL của các lệnh khác). Khi chạy môi trường thử hoặc cục bộ, đặt KF_NB_URL thành origin nội bộ tương ứng; chỉ localhost được dùng HTTP.

6. Lỗi thường gặp

| Mã thoát | Thông báo | Nghĩa / làm gì | |---|---|---| | 3 | NOT_LOGGED_IN, HTTP_401, "token hết hạn/đã thu hồi" | Tạo token mới trên ops, mở terminal riêng gõ kf login | | 3 | khong_vai (403) | Bạn không có vai với lớp/buổi đó — nhờ quản trị cấp vai trên ops | | 2 | "cần --yes", sai tham số, KF_API_URL khác nơi đã đăng nhập | Sửa lệnh; với địa chỉ API thì đăng nhập lại | | 4 | LMS_… (vd LMS_DA_CO_RECORD) | Lỗi nghiệp vụ — đọc mã, xử lý như trên ops | | 5 | AGENT_TAT | Agent API đang tạm tắt — báo quản trị, làm tay trên ops | | 5 | mạng / server | Thử lại sau; vẫn lỗi thì báo kỹ thuật |

lms-dang-buoi trả da_dang:false, thieu:["record"] nghĩa là buổi chưa có record sẵn sàng nên chưa đăng — không phải lỗi.

7. Cập nhật

Thao tác mới do server thêm sẽ tự hiện trong kf --help, không cần cập nhật. Chỉ khi được báo có bản CLI mới:

npm install -g @kesflow/kf@latest
cp "$(npm root -g)/@kesflow/kf/SKILL.md" ~/.claude/skills/kf-cli/SKILL.md

8. Bảo mật

• Token nằm ở ~/.config/kf/credentials.json (chỉ bạn đọc được) và gắn với địa chỉ API lúc đăng nhập.
• Không dùng kf trên máy dùng chung. Không chép tệp credentials sang máy khác — mỗi máy một token.

Cho người phát triển

• Mã nguồn: repo riêng tư kescyz/kf. TypeScript, không phụ thuộc runtime; lệnh dựng lúc chạy từ GET https://kesflow.vn/api/agent/v1/ops — CLI không chứa nghiệp vụ. Thêm thao tác = sửa registry ở repo website (tài liệu API sinh tự động: docs/api/agent-ops.md), không cần phát hành CLI.
• Phần chung (đọc đặc tả → dựng lệnh, đăng nhập, mã thoát) nằm ở src/api.ts, src/ops.ts, src/config.ts; phần riêng KesFlow ở src/kesflow.ts — nền để sau tách kes-api2cli.
• Sơ đồ trong README: nguồn sửa là docs/*.html (skill kf-create-diagram), docs/*.png là bản xuất để nhúng, docs/*.svg là bản vector.
• npm test (build + test), npm run typecheck, npm pack --dry-run (chỉ dist, README.md, SKILL.md, package.json).
• Phát hành: tăng version, rồi chủ tài khoản npm chạy npm publish --auth-type=web trong terminal riêng (xác nhận passkey).