Hướng dẫn cài đặt & sử dụng Celia Solution Advisor cho Claude

Bộ này gồm 2 thành phần cài vào Claude Code (CLI hoặc extension VSCode):

Thành phần	File trong zip	Cài vào	Dùng để
Skill `celia-advisor`	`skills/celia-advisor/SKILL.md`	`~/.claude/skills/`	Gõ `/celia-advisor` kèm yêu cầu nghiệp vụ — Claude phân tích catalog, đề xuất bộ rule/model, duyệt xong tự init project
Agent `celia-solution-advisor`	`agents/celia-solution-advisor.md`	`~/.claude/agents/`	Subagent chuyên trách — Claude tự gọi khi thấy yêu cầu chọn rule/tư vấn giải pháp, hoặc anh chỉ định đích danh

Cả hai dùng chung một quy trình; skill để gọi chủ động, agent để Claude tự điều phối. Cài cả hai.

1. Yêu cầu trước khi cài

Claude Code đã đăng nhập — một trong hai: - CLI: claude chạy được trong terminal (claude --version) - VSCode: extension "Claude Code" đã cài và đăng nhập (extension đọc chung thư mục ~/.claude/ với CLI — cài một lần dùng cả hai)
Truy cập catalog — một trong hai (khuyến nghị có cả hai): - Marketplace đang chạy và truy cập được (mặc định http://localhost:9095; môi trường server thì hỏi DevOps URL nội bộ) - Checkout celia-core trên máy: git clone https://dev.azure.com/Rainscales/CoreTechnical/_git/celia-core
Python 3.11+ (bước init project chạy python -m celia.cli): - macOS: brew install python@3.11 · Windows: cài từ python.org - Lưu ý: python hệ thống macOS là 3.9 — KHÔNG dùng được (thiếu tomllib)

2. Cài đặt

Bước 2.1 — Tải bundle

Vào marketplace → trang AI Advisor → nút "Tải bộ skill + agent cho Claude", hoặc:

curl -sL http://localhost:9095/advisor/bundle.zip -o celia-advisor-bundle.zip

Bước 2.2 — Giải nén vào thư mục Claude

macOS / Linux / WSL:

mkdir -p ~/.claude/skills ~/.claude/agents
unzip -o celia-advisor-bundle.zip -d /tmp/celia-advisor
cp -r /tmp/celia-advisor/skills/celia-advisor ~/.claude/skills/
cp /tmp/celia-advisor/agents/celia-solution-advisor.md ~/.claude/agents/

Windows (PowerShell):

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills", "$env:USERPROFILE\.claude\agents" | Out-Null
Expand-Archive celia-advisor-bundle.zip -DestinationPath "$env:TEMP\celia-advisor" -Force
Copy-Item -Recurse -Force "$env:TEMP\celia-advisor\skills\celia-advisor" "$env:USERPROFILE\.claude\skills\"
Copy-Item -Force "$env:TEMP\celia-advisor\agents\celia-solution-advisor.md" "$env:USERPROFILE\.claude\agents\"

Cài theo project thay vì toàn máy? Copy vào .claude/skills/ và .claude/agents/ ngay trong thư mục repo của dự án — chỉ session mở trong repo đó thấy skill/agent, và commit được để cả team dùng chung.

Bước 2.3 — Khai báo biến môi trường

Thêm vào ~/.zshrc / ~/.bashrc (macOS/Linux) hoặc Environment Variables (Windows):

export CELIA_MARKETPLACE_URL="http://localhost:9095"          # đổi theo URL nội bộ nếu có
export CELIA_CORE="$HOME/Workspace/CELIA/celia-core"          # đường dẫn checkout celia-core

Không set cũng chạy được nếu marketplace ở đúng localhost:9095; nhưng bước init project bắt buộc cần CELIA_CORE (hoặc đã pip install celia từ Azure Artifacts feed).

Bước 2.4 — Kiểm tra cài đặt

Mở phiên Claude Code MỚI (CLI: chạy lại claude; VSCode: Reload Window) — skill/agent chỉ nạp lúc khởi động phiên.
Gõ / → thấy celia-advisor trong danh sách skill.
Gõ thử: liệt kê các agent đang có → thấy celia-solution-advisor.

3. Cách sử dụng

Cách 1 — Gọi skill trực tiếp (khuyến nghị)

/celia-advisor Nhà máy có 12 camera khu kho. Cần cảnh báo khi xe nâng di chuyển mà càng đang
nâng hàng trên cao, và khi công nhân đứng yên bất thường quá 2 phút trong khu vực nguy hiểm.

Flow chuẩn sẽ diễn ra:

Claude tải catalog (marketplace hoặc checkout) — không bao giờ bịa rule/model ngoài catalog
Trả về: đánh giá + bảng rule khớp (fit high/partial + lý do + tham số phải chỉnh) + model cần deploy + phần còn thiếu (nếu có) + tên project gợi ý
Hỏi anh duyệt (và xác nhận tên project)
Duyệt xong → chạy celia new → add rule/model → validate → lock, báo lại kết quả validate (các field phải đo per-camera như zones/calibration là việc khảo sát site, không phải lỗi)
Nếu có gap "rule mới" → tự tải scaffold chuẩn từ marketplace kèm NEXT_STEPS.md để mở PR

Cách 2 — Giao cho agent

Dùng agent celia-solution-advisor: phân tích yêu cầu sau và đề xuất bộ rule/model...

Hoặc để Claude tự gọi — agent được đánh dấu "use proactively" khi gặp yêu cầu chọn rule/tư vấn giải pháp Celia.

Ví dụ kết quả mong đợi

Yêu cầu	Kết quả advisor
Xe nâng chạy khi nâng hàng cao + người đứng yên 2 phút	MHE10 (high) + HM07 (high, `limit_time: 120`) + model `yolov8m-warehouse`; init được ngay
Giáo viên rời lớp để trẻ một mình	CNT10 (high) + detector `karter-child-adult`; init được ngay
Nhân viên không đeo găng tay	PPE01 chỉ có helmet/áo phản quang → gap `train_model` (thêm attribute găng tay vào PPE SGIE); KHÔNG init vội
Người qua chốt không thổi cồn	OTH02 (high về logic) nhưng zoo CHƯA có detector `alcohol_tool` → gap `new_model`, validate sẽ chặn đúng

4. Xử lý sự cố

Triệu chứng	Nguyên nhân & cách xử lý
Gõ `/` không thấy `celia-advisor`	Sai đường dẫn (phải là `~/.claude/skills/celia-advisor/SKILL.md`) hoặc chưa mở phiên mới — CLI thoát chạy lại, VSCode Reload Window
Agent không xuất hiện	File phải nằm TRỰC TIẾP trong `~/.claude/agents/` (không bọc thêm thư mục con)
"catalog không tải được"	Marketplace chưa chạy / sai `CELIA_MARKETPLACE_URL`; kiểm tra `curl $CELIA_MARKETPLACE_URL/healthz`; hoặc set `CELIA_CORE` để đọc trực tiếp checkout
`ModuleNotFoundError: celia` khi init	Chưa set `CELIA_CORE` (advisor cần `PYTHONPATH` trỏ vào checkout) hoặc chưa `pip install celia`
Python báo `No module named 'tomllib'`	Đang dùng Python < 3.11 — cài python3.11 và bảo Claude dùng đúng binary
validate báo `requires class 'alcohol_tool'...`	Gap thật của model zoo (chưa có detector đó) — advisor phải báo cáo đây là hạng mục cần train/thêm model, không phải lỗi cài đặt
validate báo `config incomplete — must be set per-camera`	Bình thường: field đó (zones, `image_points`/`real_points`, `intersection`…) phải đo tại site rồi điền vào config từng camera

5. Cập nhật & gỡ bỏ

Cập nhật: tải bundle mới và copy đè (so version trong file VERSION của zip).
Gỡ: xoá ~/.claude/skills/celia-advisor/ và ~/.claude/agents/celia-solution-advisor.md, mở phiên mới.

6. Ghi chú

Advisor CHỈ chạy trong Claude Code — trang /advisor trên marketplace là nơi tải bundle và xem hướng dẫn này, không có bản phân tích trên web. Lợi thế của việc chạy trong Claude Code: advisor có tool thật — tự chạy celia validate/lock và đọc lỗi thật, tự tải scaffold, đọc được repo dự án của anh/chị, và hội thoại nhiều vòng để làm rõ yêu cầu.

Cài đặt & sử dụng trong Claude Code