菜单
Dùng khi người dùng yêu cầu làm việc với dữ liệu, sản phẩm, bảng giá, hóa đơn, đơn hàng, khách hàng, nhà cung cấp, danh mục, tồn kho, kiểm kho, thu chi, công nợ, báo cáo doanh thu, import, export, bảo trì reverse API, hoặc cập nhật KiotViet.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Dùng khi người dùng yêu cầu tải, lấy, cập nhật, đồng bộ dữ liệu KiotViet khách hàng, sản phẩm, bảng giá, hóa đơn, hoặc dữ liệu nền để làm hóa đơn.
Dùng khi người dùng yêu cầu import, upload, thêm mới, cập nhật, hoặc kiểm tra sản phẩm KiotViet từ Excel, CSV, template, hoặc danh sách hàng hóa.
Dùng khi người dùng yêu cầu import, cập nhật, đồng bộ, điều chỉnh, so sánh, hoặc kiểm tra bảng giá KiotViet từ file.
Dùng khi cần client reverse API KiotViet, token, gian hàng, chi nhánh, sản phẩm, khách hàng, bảng giá, hóa đơn, đơn hàng, tồn kho, công nợ, báo cáo, nhà cung cấp, danh mục, job import, hoặc script API.
Dùng khi cần tổ chức output KiotViet thư mục data, raw export, dữ liệu xử lý, file import, báo cáo, backup, hoặc manifest.
Dùng khi người dùng yêu cầu làm hóa đơn KiotViet, tạo đơn hàng, tạo file import hóa đơn, hoặc đối chiếu khách hàng và sản phẩm để bán hàng.
| name | kiotviet-orchestrator |
| description | Dùng khi người dùng yêu cầu làm việc với dữ liệu, sản phẩm, bảng giá, hóa đơn, đơn hàng, khách hàng, nhà cung cấp, danh mục, tồn kho, kiểm kho, thu chi, công nợ, báo cáo doanh thu, import, export, bảo trì reverse API, hoặc cập nhật KiotViet. |
Điều phối đúng skill KiotViet theo yêu cầu người dùng.
Mặc định dùng reverse API qua kiotviet-client. Không dùng Public API Business.
| Nhu cầu | Skill |
|---|---|
| Kiểm tra phiên, gọi API, CRUD, tồn kho, thu chi, báo cáo | kiotviet-client |
| Tổ chức output | kiotviet-data-manager |
| Tải dữ liệu khách hàng, sản phẩm, bảng giá, hóa đơn, đơn hàng | download-du-lieu-kiotviet |
| Import hoặc cập nhật sản phẩm từ Excel | import-san-pham |
| Cập nhật bảng giá | import-update-bang-gia |
| Làm hóa đơn hoặc file import hóa đơn | lamhoadon |
| Tạo hoá đơn random hàng loạt | nhathoadon |
| Endpoint lỗi do KiotViet đổi giao diện | reverse-engineering-api |
| Tình huống | Agent |
|---|---|
| Vận hành dữ liệu, tạo file, lập báo cáo | kiotviet-data-operator |
| Kiểm tra import, update, payload trước khi ghi | kiotviet-import-qa |
| Endpoint lỗi, cần phân tích HAR hoặc vá client | kiotviet-api-maintainer |
Orchestrator gọi agent theo rủi ro. Việc đọc dữ liệu đơn giản có thể chạy trực tiếp bằng skill.
Trước thao tác ghi, luôn có kiotviet-import-qa kiểm tra báo cáo hoặc payload.
download-du-lieu-kiotviet.import-san-pham.import-update-bang-gia.nhathoadon.lamhoadon.reverse-engineering-api, rồi cập nhật kiotviet-client.kiotviet-import-qa kiểm tra trước khi hỏi xác nhận.Trước thao tác ghi:
ensure_session.py.check_session.py.manifest.json trong data/reports/YYYYMMDD_HHMMSS/.data/reports/YYYYMMDD_HHMMSS/.qa_report.json trong data/reports/YYYYMMDD_HHMMSS/.kiotviet_write_gate.validate_apply_gate trước khi apply.qa_report.confirmation_text.confirmed=True.verify_summary.json.Không có qa_report.json thì không apply.
Nếu qa_report.blockers không rỗng thì không apply.
Nếu câu xác nhận không khớp qa_report.confirmation_text thì không apply.
Thao tác ghi gồm:
Trước mọi thao tác ghi lên KiotViet, phải báo rõ:
qa_report.json.Không gọi API ghi nếu user chỉ nói chung chung.
Không nói thao tác đã xong nếu chưa có bằng chứng đọc lại từ KiotViet.
Câu xác nhận phải nhắc lại đúng tác động.
Ví dụ:
Xác nhận apply: sẽ cập nhật 12 sản phẩm, tạo mới 3 sản phẩm trong bảng giá Giá Bán Buôn, theo report data/reports/<run_id>/report.md.
qa_report.jsonFile qa_report.json phải có tối thiểu:
{
"run_id": "YYYYMMDD_HHMMSS",
"operation": "create_pricebook",
"mode": "apply",
"target": {},
"planned_counts": {"affected_records": 0},
"endpoints": {"write": [], "verify": []},
"blockers": [],
"warnings": [],
"apply_allowed": true,
"confirmation_text": "Xác nhận apply: ...",
"verify_plan": {"expected_records": 0}
}
planned_counts.affected_records phải khớp verify_plan.expected_records.
endpoints.write và endpoints.verify không được rỗng.
| Chế độ | Ý nghĩa |
|---|---|
| dry run | kiểm tra, tạo file, tạo báo cáo, không ghi KiotViet |
| apply | ghi KiotViet sau xác nhận |
| repair | dùng HAR để sửa endpoint |
Nếu người dùng không nói rõ, mặc định là dry run.
Sau mọi thao tác ghi, orchestrator phải chạy hậu kiểm.
Luồng hậu kiểm:
data/reports/YYYYMMDD_HHMMSS/.data/reports/YYYYMMDD_HHMMSS/.Với import sản phẩm, dùng:
~/.venv/claude/bin/python .agents/skills/import-san-pham/scripts/product_import_audit.py verify \
--file data/import_ready/YYYYMMDD_HHMMSS/import_san_pham.xlsx \
--products-json data/raw/YYYYMMDD_HHMMSS/products.json \
--report-dir data/reports/YYYYMMDD_HHMMSS
Báo cáo cuối phải có:
Trước khi chạy, kiểm tra:
.env hoặc biến môi trường KiotViet đã có chưa.templates/ chưa.| Lỗi | Cách xử lý |
|---|---|
| token hết hạn | yêu cầu người dùng lấy token mới |
| thiếu env | báo đúng biến thiếu |
| endpoint đổi | dùng reverse-engineering-api với HAR mới |
| dữ liệu không chắc | hỏi người dùng chọn |
| preview lỗi | dừng, lưu lỗi vào data/import_errors/ |
| thiếu QA report | dừng, tạo lại dry run và QA |
| verify lệch | dừng, lưu verify_summary.json, báo mã lệch |
Luồng thường:
download-du-lieu-kiotviet.data/raw/<run_id>.Luồng lỗi:
check_session.py trả 401.