10 KiB
Dùng CASAN local để làm dự án — hướng dẫn từng bước
Tài liệu này dành cho môi trường local hiện tại: macOS chạy Control Panel và model local, Docker chạy hạ tầng, máy Linux thanhnv@192.168.1.5 là tài nguyên mở rộng khi cần. Production là một giai đoạn riêng.
1. Hiểu CASAN trong một phút
CASAN không phải là một model AI mới. CASAN là lớp điều phối và kiểm soát nằm giữa người dùng, model và công cụ.
flowchart LR
U["Mục tiêu / câu hỏi"] --> H1["H1 Context"]
H1 --> H2["H2 Local worker / tools"]
H2 --> H3["H3 Cloud review / eval"]
H3 --> H4["H4 Security"]
H4 --> H5["H5 Governance + audit"]
H5 --> H6["H6 Runtime + cost"]
H6 --> H7["H7 Governed outcome"]
H2 -. private first pass .-> L["Ollama local"]
H3 -. independent review .-> C["Codex / Claude / cloud API"]
Control Panel hiện có bốn bề mặt chính:
| Màn hình | Dùng khi nào | Có ghi/sửa source code không? |
|---|---|---|
| Ask CASAN | Hỏi tài liệu, kiến trúc, bằng chứng, trạng thái hệ thống | Không; read-only |
| Goal orchestrator | Đưa một mục tiêu để local worker và cloud reviewer cùng lập lời giải | Không; tạo kết quả và audit, chưa tự sửa workspace |
| Run observability | Xem một input đã đi qua H1–H7 và dừng/cảnh báo ở đâu | Không |
| Settings / Approvals | Quản trị cấu hình và quyết định có kiểm soát | Chỉ các action đã đăng ký và đủ quyền |
Điểm quan trọng: bạn có thể dùng ba luồng trên hoàn toàn trong trình duyệt, không cần mở Codex, VS Code hay Claude Code. Tuy nhiên, phiên bản hiện tại chưa có “workspace executor” được cấp quyền tự tạo/sửa source code từ Goal orchestrator. Kết quả của Goal orchestrator là kế hoạch/lời giải đã được hai model kiểm tra. Bước ghi code vẫn phải đi qua một action có approval hoặc một coding agent bên ngoài.
2. Chuẩn bị một lần
Kiểm tra các thành phần sau:
docker version
docker compose version
codex --version
claude --version
curl -fsS http://localhost:20128/v1/models
Model local mặc định hiện dùng Ollama ở host.docker.internal:11434. OmniRoute có Dashboard tại http://localhost:20128 và API base http://localhost:20128/v1.
Không ghi API key vào Git, file Markdown hay biến build frontend. API key chỉ nhập qua màn hình Model connections; backend mã hóa theo tenant trước khi lưu.
3. Khởi động toàn bộ local stack
Từ thư mục gốc repository:
packages/casan-harness/scripts/bash/local-full.sh start
packages/casan-harness/scripts/bash/local-full.sh status
packages/casan-harness/scripts/bash/local-full.sh verify
Các địa chỉ chính:
- Control Panel:
https://localhost:18443 - Dashboard hạ tầng:
http://127.0.0.1:18080 - MinIO Console:
http://127.0.0.1:19091 - OmniRoute:
http://localhost:20128
Local Control Panel dùng chứng chỉ self-signed. Lần đầu, mở URL bằng trình duyệt và chấp nhận chứng chỉ local thủ công. Không dùng cách bỏ qua cảnh báo chứng chỉ cho production.
Khi cần dừng:
packages/casan-harness/scripts/bash/local-full.sh stop
Lệnh stop xóa bridge token. Lần start tiếp theo sinh token mới.
4. Kết nối model
4.1 Tài khoản Codex hoặc Claude
- Mở Ask CASAN.
- Chọn Manage model connections.
- Trong Local account connector, xem trạng thái Codex và Claude.
- Nếu chưa đăng nhập, chọn Login. Browser login chính thức của CLI sẽ mở và redirect theo cơ chế của Codex/Claude.
- Control Panel chỉ nhận trạng thái đã được làm sạch. Credential OAuth vẫn thuộc CLI trên Mac, không nằm trong browser hoặc container.
Goal orchestrator ưu tiên một tài khoản cloud đã đăng nhập. Nếu cả hai sẵn sàng, Claude được ưu tiên làm reviewer; nếu Claude chưa đăng nhập thì dùng Codex. Nếu account connector không sẵn sàng, hệ thống mới dùng cloud/gateway connection đã cấu hình.
4.2 Ollama local
Trong Model connections:
- Chọn Ollama Local.
- Endpoint local Docker:
http://host.docker.internal:11434. - Chọn Refresh để tải danh sách model.
- Đặt model mặc định, ví dụ
ornith:9b.
4.3 OmniRoute hoặc cloud API key
Với OmniRoute:
- Endpoint:
http://host.docker.internal:20128/v1 - Model được lấy từ
/models. - OmniRoute là fallback khi account connector không dùng được.
Với OpenAI/Anthropic API:
- Chỉ dùng endpoint chính thức được allowlist.
- API key được gửi thẳng tới backend qua HTTPS local và lưu mã hóa theo tenant.
- UI không đọc lại hoặc hiển thị key đã lưu.
5. Case 1 — Hỏi hệ thống mà không cần IDE
Mở Ask CASAN, chọn model và hỏi:
Hạ tầng local hiện có những thành phần nào, phần nào chưa có bằng chứng chạy thật?
CASAN sẽ:
- phân loại prompt;
- chỉ đọc nguồn nằm trong allowlist;
- chạy security scan input/output;
- trả câu trả lời có source;
- ghi audit và telemetry.
Sau khi có câu trả lời, chọn Open live H1–H7 trace để xem đường đi.
6. Case 2 — Chỉ đưa mục tiêu, local và cloud cùng giải quyết
Mở Goal orchestrator và nhập một mục tiêu, ví dụ:
Lập kế hoạch đưa ứng dụng OKR hiện tại lên production, có rollback, theo dõi lỗi và tiêu chí nghiệm thu rõ ràng.
Luồng thực tế:
- H1 kiểm tra hợp đồng mục tiêu và độ dài.
- H4 quét mục tiêu trước khi đưa cho model.
- Ollama local tạo phương án đầu tiên.
- Output local được quét lại.
- Codex/Claude account hoặc cloud connection phản biện và viết kết quả cuối.
- Kết quả cuối được H4 quét lần nữa.
- H5 tạo audit hash; H6 ghi runtime/token; H7 kết thúc.
Trạng thái có ý nghĩa như sau:
completed: local và cloud đều đóng góp thành công;degraded: local thành công nhưng cloud/gateway không sẵn sàng; kết quả local được giữ lại và cảnh báo rõ;failed: security hoặc local worker không cho phép tiếp tục.
7. Case 3 — Tìm chính xác input bị dừng ở đâu
Có hai cách mở Trace Explorer:
- từ nút Open live H1–H7 trace sau câu trả lời;
- từ Run observability, chọn Open H1–H7 ở một run.
Mỗi H có thể click để xem:
- trạng thái mới nhất;
- lý do pass/warning/blocked/error;
- thời gian;
- evidence an toàn như model, token, latency, hash và decision.
Trace không đưa raw prompt, API key hoặc credential vào evidence.
8. Thêm một app mới trong cùng workspace
Không cần di chuyển app OKR đang có. Với app độc lập, tạo domain pack riêng thay vì trộn yêu cầu vào apps/okr:
apps/<app-slug>/
├── domain/
│ ├── input/ # yêu cầu nguồn
│ ├── corpus/ # tài liệu dùng làm evidence
│ └── golden-runs/ # case chuẩn để đánh giá
├── config/ # cấu hình riêng của app
├── src/ # code riêng nếu app dùng cấu trúc package
└── test/ # test riêng
Sau đó thêm project vào packages/casan-harness/level5/project-registry.json với domain_root trỏ tới apps/<app-slug>/domain, rồi chạy:
packages/casan-harness/scripts/bash/verify-harness-reuse.sh
Không làm các việc sau:
- đặt yêu cầu app mới trong
apps/okr/domain/input; - dùng chung secret hoặc state giữa hai tenant/project;
- sửa gate H1–H7 chỉ để một app mới pass;
- copy toàn bộ harness vào app mới.
9. Khi nào cần máy Linux 192.168.1.5
Giữ Control Panel và account connector trên Mac trong giai đoạn local. Dùng máy Linux khi cần:
- chạy model hoặc workload nặng;
- thử Docker/Kubernetes gần production hơn;
- chạy worker riêng trong LAN;
- kiểm tra backup/restore hoặc benchmark.
Không copy credential Codex/Claude từ Mac sang Linux. Với production, dùng API credential trong Vault/KMS hoặc workload identity, không dùng developer browser login.
10. Troubleshooting nhanh
Control Panel không mở
packages/casan-harness/scripts/bash/local-full.sh status
docker compose -f docker-compose.control-panel.local.yml ps
docker logs --tail 100 output_casan5_refined-control-panel-api-1
Codex/Claude không hiện đã login
codex login status
claude auth status --json
curl -fsS http://127.0.0.1:20130/healthz
Nếu CLI chưa login, thực hiện login từ Control Panel hoặc CLI chính thức. Không copy token vào cấu hình CASAN.
Goal dừng ở degraded
Mở H3 trong Trace Explorer. Các nguyên nhân thường gặp:
- account CLI chưa login;
- account model bridge bận hoặc rate limited;
- OmniRoute/provider đang unavailable;
- cloud preflight chặn dữ liệu nhạy cảm.
Kết quả degraded không được trình bày như kết quả hai-model hoàn chỉnh.
Trace cũ chỉ có một H
Đó là legacy trace được sinh trước khi event schema H1–H7 được thêm. Các chat/goal mới tự động có event chi tiết.
11. Checklist trước khi dùng hàng ngày
local-full.sh verifypass.- Ollama connected và có default model.
- Ít nhất Codex/Claude account hoặc một cloud connection sẵn sàng.
- Một Goal smoke có local worker và cloud reviewer đều
pass. - Trace của smoke đạt 7/7.
- Không có API key trong Git diff.
- Chưa dùng cấu hình local này như production.