@kesflow/kf 0.1.0 → 0.1.2

package/README.md

@@ -1,25 +1,106 @@
-# `@kesflow/kf`
+# `kf` — CLI nội bộ KesFlow
 
-CLI for KesFlow staff agents. Requires Node.js 22 or newer and a personal token from **Nội bộ → Kết nối của tôi**.
+`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.
+
+![kf hoạt động thế nào: bạn nói việc → agent chạy kf → server kiểm token, chạy đúng hàm như ops với vai của bạn, ghi nhật ký → kết quả về chat](docs/kf-hoat-dong.png)
+
+## 1. Cài đặt (một lần mỗi máy)
+
+Cần Node.js 22 trở lên.
 
 ```sh
 npm install -g @kesflow/kf
 ```
 
-Đăng nhập: bảo người dùng mở một terminal riêng và gõ `kf login`, rồi dán token vào ô ẩn (ô chat Claude Code với `!` không có terminal nên không dùng được). Agent không tự chạy `kf login`, không bao giờ hỏi hay nhận token trong chat. `kf logout` removes the local file; revoke the token on the ops page.
+Cài skill cho Claude Code (giúp agent dùng `kf` đúng cách):
+
+```sh
+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)
+
+![Đăng nhập một lần mỗi máy: tạo token trên ops → kf login trong terminal riêng → kf status → dùng trong Claude Code; không dán token vào chat](docs/dang-nhap-mot-lan.png)
+
+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õ:
+   ```sh
+   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)
+
+```sh
+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 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).
+
+## 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.
 
-Commands use the operation IDs from `GET /ops` exactly: `kf <op-id>`. Run `kf --help` for the live list, `kf schema <op-id>` for JSON Schema, or `kf <op-id> --help` for flags. The CLI keeps no persistent operations cache.
+## 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:
 
 ```sh
-kf status
-kf ops
-kf lms-buoi --lop-ma THUCLI
-kf lms-doi-ten --tep-id UUID --ten 'Tên mới'
-kf lms-ghi-recap --json '{"buoi_id":"UUID","recap_md":"# Buổi học","de_bai_md":null}'
-kf lms-dang-buoi --buoi-id UUID --gui-thu false --yes
-kf lms upload slide.html --buoi-id UUID
+npm install -g @kesflow/kf@latest
+cp "$(npm root -g)/@kesflow/kf/SKILL.md" ~/.claude/skills/kf-cli/SKILL.md
 ```
 
-Use `--dry-run` to validate an operation without writing and `--pretty` for indented JSON. High-risk operations require `--yes`. Normal output is one JSON line on stdout; errors are one JSON line on stderr. Exit codes: 0 success, 2 usage, 3 authentication or permission, 4 business error, 5 server or network.
+## 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
 
-Credentials are stored in `~/.config/kf/credentials.json` (directory mode 700, file mode 600). `KF_API_URL` is honoured by `kf login` and saved with the token. Changing it later requires another login. Plain HTTP is accepted only for localhost loopback tests.
+- 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).

package/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: kf-cli
+description: Thao tác nội bộ KesFlow qua CLI `kf` thay cho bấm màn ops — chốt buổi học LMS (gắn record từ Drive, tải slide, đổi tên/gỡ tệp, ghi recap/bài tập/chuẩn bị, đăng buổi), xem lớp và buổi mình phụ trách. Dùng khi nhân sự KesFlow nhờ "chốt buổi", "up slide/record lên LMS", "ghi recap", "đăng buổi", "đổi tên record", "xem buổi lớp TA05" hoặc nhắc tới `kf`. Không dùng cho việc ngoài danh sách `kf --help` (tiền, ghi danh, gửi mail tự do chưa có trong CLI).
+---
+
+# kf — CLI nội bộ KesFlow cho agent
+
+`kf` gọi Agent API của KesFlow **nhân danh người đang đăng nhập**; quyền do DB quyết định theo vai của người đó, y như màn ops.
+
+## Đăng nhập — người dùng tự làm, KHÔNG qua chat
+- Chưa đăng nhập (`kf status` thoát mã 3, `NOT_LOGGED_IN`) hoặc token hết hạn/thu hồi (401): bảo người dùng
+  1. vào ops → **Kết nối của tôi** → **Tạo token** (đặt tên máy);
+  2. **mở một terminal riêng** (ô chat Claude Code với `!` không có terminal nên không dùng được), gõ `kf login`, dán token vào ô ẩn.
+- **Không bao giờ** hỏi, nhận, đọc, in hay ghi token. Không tự chạy `kf login`. Không đọc `~/.config/kf/credentials.json`.
+
+## Cách dùng
+- Danh sách thao tác (lấy trực tiếp từ server, luôn đúng): `kf --help`. Tham số một thao tác: `kf <op> --help`, `kf schema <op>`.
+- Gọi: `kf <op> --<tham-so> <giá trị>` hoặc `kf <op> --json '{...}'`. Kết quả: một dòng JSON (`--pretty` để đọc).
+- Không chắc thì chạy thử trước: thêm `--dry-run` (chỉ kiểm, không ghi gì).
+- Tải tệp từ máy lên buổi học: `kf lms upload <tệp> --buoi-id <id> [--loai slide_pdf|slide_html|record|video_xem_truoc] [--ten ...]`.
+- Tìm `buoi-id`: `kf status` (lớp tôi phụ trách) → `kf lms-buoi --lop-ma <MÃ LỚP>`.
+
+## Thao tác rủi ro cao (`[high]`, cần `--yes`)
+- Ví dụ `lms-dang-buoi --gui-thu true` gửi thư cho **cả lớp thật**.
+- Chỉ thêm `--yes` **sau khi người dùng đồng ý rõ trong chat** với đúng nội dung: buổi nào, lớp nào, có gửi thư không. Không tự suy ra ý định gửi thư.
+- `--yes` không thay người duyệt; người dùng nên để Claude Code hỏi quyền trước lệnh `kf … --yes`.
+
+## Đọc kết quả
+| Mã thoát | Nghĩa | Làm gì |
+|---|---|---|
+| 0 | OK | báo kết quả |
+| 2 | Sai cách dùng / thiếu `--yes` / cấu hình | sửa lệnh; cấu hình lỗi → nhắc đăng nhập lại ở terminal riêng |
+| 3 | 401 (token) / 403 `khong_vai` (không có vai với lớp/buổi đó) | 401 → nhắc đăng nhập lại; 403 → báo người dùng không có quyền, không thử đường khác |
+| 4 | Lỗi nghiệp vụ (`LMS_*`, vd `LMS_DA_CO_RECORD`) | đọc mã, báo người dùng |
+| 5 | Mạng/server; `AGENT_TAT` = Agent API đang tắt | báo người dùng, không thử lại liên tục |
+
+`lms-dang-buoi` có thể trả `da_dang:false, thieu:["record"]`: buổi chưa có record sẵn sàng nên chưa đăng — không phải lỗi.

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "@kesflow/kf",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "KesFlow agent CLI",
   "type": "module",
-  "bin": { "kf": "./dist/cli.js" },
-  "files": ["dist", "README.md"],
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=22" },
+  "bin": {
+    "kf": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
     "prepack": "npm run build",