Skip to main content
Trang này dành cho ai? Bạn chỉ cần đọc nếu muốn chạy lệnh tay trong terminal — ví dụ debug khi watcher không chạy, viết script tự động, hoặc tích hợp vào CI.Nếu bạn chỉ muốn tìm asset hay xem watcher có chạy không, dùng nút double-click trong setup/ thì gọn hơn:
  • setup/Search.command (Mac) / Search.bat (Win) — tìm asset bằng tiếng Việt.
  • setup/Status.command (Mac) / Status.bat (Win) — xem trạng thái watcher.
Xem Sử dụng cơ bản để biết thêm.

​
Tại sao cần CLI?

Module Asset Index gồm 6 file Python trong tools/asset_index/. Mỗi file phụ trách 1 việc và có thể chạy độc lập bằng lệnh python -m <tên_module>. Bảng dưới giúp bạn chọn đúng module cho công việc cần làm:
Bạn muốn…Dùng lệnh
Theo dõi raw_assets/ real-time, tự index file mới khi drop vàowatcher.py
Bắt buộc index lại 1 file (sau khi sửa nội dung hoặc fix bug)router.py
Tìm asset trong DB bằng truy vấn ngôn ngữ tự nhiênsearch.py
Cài / gỡ / khởi động lại service watcher chạy nềnservice.py
Chạy lại trình cài đặt từng bước (như setup/Install.command nhưng từ terminal)bootstrap.py
Xuất nội dung DB ra file JSON để share, backup, hoặc migrateexporter.py
Mọi lệnh dưới đây bắt đầu bằng .venv/bin/python — đó là Python riêng của repo (đã cài lúc setup). Nếu bạn lỡ gõ python -m ... (không có prefix .venv/bin/) máy có thể dùng Python hệ thống và thiếu thư viện → chạy fail.

​
watcher.py — theo dõi filesystem

Khi nào cần? Bình thường watcher tự chạy nền (cài bằng service.py install hoặc auto-installer). Bạn chỉ cần chạy tay khi muốn debug — ví dụ thấy watcher không phát hiện file mới và muốn xem log trực tiếp. 
.venv/bin/python -m tools.asset_index.watcher [OPTIONS]
CờVai trò
--scan-on-startKhởi động xong, quét toàn bộ folder để index những file đã drop từ trước (chứ không chỉ file mới drop sau này)
--include-jobsWatch thêm jobs/*/input/raw_assets/ (mặc định chỉ watch raw_assets/ ở root)
--watch <path>Thêm path tuỳ ý vào danh sách watch (cờ này có thể lặp nhiều lần)
--pollingĐổi cơ chế theo dõi sang kiểm tra theo nhịp (mỗi vài giây quét lại) — dùng khi chạy trên ổ mạng (NFS) hoặc trong sandbox không hỗ trợ FSEvents/inotify
--debounce <sec>Override khoảng chờ trước khi xử lý file mới (mặc định 1.5s trên Mac, 2.5s trên Win). Tăng lên nếu file copy chậm (ổ mạng, file lớn)
Ví dụ — debug-mode quét lại toàn bộ folder, watch luôn cả jobs/, debounce 2 giây: 
.venv/bin/python -m tools.asset_index.watcher \
  --scan-on-start \
  --include-jobs \
  --debounce 2.0

​
router.py — index 1 file cụ thể

Khi nào cần? Khi watcher đã index 1 file nhưng kết quả không đúng (vd. AI mô tả sai nội dung), hoặc khi bạn sửa file gốc và muốn re-index. Router là cách bypass watcher để xử lý ngay 1 file duy nhất. 
.venv/bin/python -m tools.asset_index.router <PATH> [OPTIONS]
CờVai trò
--forceRe-index dù DB đã có “vân tay” (hash) khớp với file. Mặc định router skip file đã index để tiết kiệm chi phí AI
--db <path>Trỏ đến file DB khác (mặc định .asset_index/index.db)
--env <path>Trỏ đến file .env khác (mặc định .env ở root repo)
Ví dụ — bắt buộc index lại 1 ảnh ngay cả khi nó đã có trong DB: 
.venv/bin/python -m tools.asset_index.router \
  raw_assets/images/test.jpg \
  --force
Output là JSON, ví dụ: 
{
  "status": "ok",
  "file_path": "raw_assets/images/test.jpg",
  "media_type": "image",
  "id": "a1b2c3...",
  "summary": "Phong cảnh núi mùa thu...",
  "embed_model": "text-embedding-3-small"
}
status có 3 giá trị có thể gặp:
  • ok — vừa index thành công.
  • skipped — file đã có trong DB và --force không bật → bỏ qua.
  • failed — có lỗi → xem field error để biết chi tiết.

​
search.py — tìm asset bằng ngôn ngữ tự nhiên

Khi nào cần? Để gõ tìm asset từ terminal (gõ python -m ... "phong cảnh núi" thay vì mở Search.command). Hữu ích khi bạn viết script tự động hoặc muốn output JSON. 
.venv/bin/python -m tools.asset_index.search "<query>" [OPTIONS]
CờVai trò
--top NSố kết quả tối đa (mặc định 5)
--media TYPEChỉ tìm 1 loại: image / video / audio
--source SOURCEChỉ tìm trong raw_assets (pool chung) hoặc jobs (asset của 1 job)
--job JOB_IDLọc theo 1 job cụ thể (dùng kèm --source jobs)
--jsonTrả output JSON thay vì human-readable (để pipe vào script khác)
Ví dụ — tìm 10 ảnh khớp ngữ nghĩa “phong cảnh núi tuyết”, trả JSON: 
.venv/bin/python -m tools.asset_index.search \
  "phong cảnh núi tuyết" \
  --top 10 \
  --media image \
  --json

​
service.py — quản lý service watcher chạy nền

Khi nào cần? Để cài/gỡ/khởi động lại watcher như một dịch vụ hệ thống. Auto-installer đã làm install cho bạn rồi; chỉ cần đụng tay khi muốn gỡ, dừng tạm, hoặc debug trạng thái. 
.venv/bin/python -m tools.asset_index.service <CMD>
LệnhHành động
installĐăng ký watcher với hệ điều hành để tự khởi động cùng máy: launchd plist trên macOS, Task Scheduler entry trên Windows, in hướng dẫn systemd trên Linux
uninstallGỡ đăng ký + dừng watcher
statusIn trạng thái: đang chạy hay không, PID là bao nhiêu, lỗi gần nhất
startKhởi động watcher (sau khi đã install)
stopDừng watcher tạm thời (đăng ký vẫn còn — máy reboot là chạy lại)

​
bootstrap.py — trình setup tự động

Khi nào cần? bootstrap.py chính là phần lõi của setup/Install.command. Bạn chạy thẳng module này khi:
  • Đang chạy CI và không có double-click GUI để bấm.
  • Muốn cài lại từng phần (chỉ deps, không cần đăng ký service…).
.venv/bin/python -m tools.asset_index.bootstrap [OPTIONS]
CờVai trò
--non-interactiveKhông hỏi gì — nếu thiếu key hay deps thì fail luôn (cho CI)
--skip-serviceCài deps + tạo DB nhưng không đăng ký watcher với OS
--skip-installBỏ qua pip install (cho trường hợp .venv đã có sẵn deps)

​
exporter.py — export DB ra JSON

Khi nào cần? Khi muốn xem nội dung DB không qua SQLite, share index cho người khác, hoặc backup trước khi xoá .asset_index/. 
.venv/bin/python -m tools.asset_index.exporter --output assets.json
Lệnh này xuất toàn bộ bảng assets ra JSON (không kèm vector embedding để file nhẹ). Dùng cho debug, migration, hoặc share index.

​
Bước tiếp theo

File runtime

Hiểu cấu trúc .asset_index/ (DB SQLite, log, state.json).