# Dùng CASAN để làm dự án — giải thích thực tế, dễ hiểu

Tài liệu này trả lời thẳng ba câu hỏi:

1. CASAN có phải là một IDE hay một coding agent thay Codex/Claude Code không?
2. Có thể dùng CASAN mà không cần Codex, VS Code hoặc Claude Code không?
3. Với một dự án cụ thể, người dùng phải thao tác như thế nào?

## 1. Câu trả lời ngắn gọn

**CASAN không phải IDE. CASAN là lớp điều phối và kiểm soát quá trình dùng AI để
làm phần mềm.**

- VS Code là nơi con người mở và sửa file.
- Codex/Claude Code là coding agent có thể đọc, sửa và chạy code.
- Model local/OpenAI/OmniRoute là bộ máy sinh nội dung.
- CASAN quyết định model/agent được làm gì, quét input/output, yêu cầu approval,
  chạy test, ghi audit, lưu evidence và chặn hành động không an toàn.

Do đó:

- **Không cần Codex hoặc Claude Code:** có thể chạy CASAN bằng browser, CLI và CI.
- **Không cần VS Code:** có thể dùng terminal hoặc bất kỳ trình soạn thảo nào.
- **Muốn browser tự xây trọn một dự án:** phiên bản hiện tại **chưa hoàn thành
  bước này**. Chat mới sinh và chứng nhận `CODEGEN_DRAFT`; nó chưa được phép tự
  ghi tùy ý vào source tree.

Điểm cuối cùng là chủ ý bảo mật, không phải lỗi giao diện. “Model sinh được code”
khác với “model được quyền thay đổi repository”. CASAN tách hai quyền này.

## 2. Hình dung CASAN như một dây chuyền có kiểm soát

![Luồng dùng CASAN cho dự án](assets/casan-project-usage-flow.svg)

```mermaid
flowchart LR
  U["Người dùng mô tả yêu cầu"] --> I["Control Panel hoặc bin/casan"]
  I --> R{"CASAN phân loại ý định"}
  R --> M["Model local / OmniRoute tùy chọn"]
  M --> D["Sinh câu trả lời hoặc bản nháp"]
  D --> G{"H4 bảo mật + H5 audit + H3/test/loop gate"}
  G -- "Không đạt" --> X["Chặn, sửa hoặc yêu cầu người duyệt"]
  G -- "Đạt: chỉ đọc" --> E["Trả kết quả kèm evidence"]
  G -- "Đạt: có ghi file" --> A{"Registered action + approval"}
  A -- "Đã được cho phép" --> W["Ghi workspace, chạy test, tạo commit"]
  A -- "Chưa có action" --> H["Giữ draft, chưa thay đổi dự án"]
```

Model chỉ là một công nhân trong dây chuyền. CASAN là cổng kiểm soát, nhật ký,
người điều phối và bộ tiêu chí nghiệm thu.

## 3. Những gì dùng được ngay hôm nay

| Nhu cầu | Browser Control Panel | Terminal `bin/casan` | Trạng thái |
|---|---:|---:|---|
| Hỏi về trạng thái, plan, audit, evidence | Có | Có | Hoàn chỉnh |
| Chọn agent, skill và model provider | Có | Có qua tham số/config | Có policy và audit |
| Chạy bộ test đã đăng ký | Có | Có | Hoàn chỉnh |
| Build/verify Evidence Pack | Có | Có | Hoàn chỉnh |
| Sinh code draft qua model | Có | Có | Có, nhưng draft chưa tự apply |
| Tự sửa bất kỳ file nào bằng chat | Không | Chỉ qua command/action được cho phép | Chưa mở tự do |
| Tạo toàn bộ dự án từ chat rồi test/commit | Chưa | Có thể ghép thủ công bằng CLI | Project Builder chưa hoàn thành |
| Chạy CI, CVE scan, SBOM, attestation | Xem evidence | CI thực hiện | Đã có pipeline |

Ba agent hiện tại:

| Agent | Dùng khi nào | Quyền |
|---|---|---|
| Evidence Reader | Hỏi đáp, đọc plan/evidence | Chỉ đọc |
| Ops Operator | Chạy test, build pack, verify pack | Chỉ action đã đăng ký |
| Codegen Draft | Yêu cầu sinh code | Tạo draft trong vùng state; không tự ghi source |

## 4. Cách chạy hệ thống local mà không cần Codex/Claude Code

Bạn chỉ cần Docker và browser. Terminal được dùng để bật dịch vụ một lần.

```bash
cd /Users/thanhnguyen/Documents/AI/HarnessHkt/Harness_Hakathon/Output_CASAN5_REFINED
bash packages/casan-harness/scripts/bash/local-full.sh start
bash packages/casan-harness/scripts/bash/local-full.sh status
```

Sau đó mở:

- Control Panel: `https://localhost:18443`
- Trang Chat: `https://localhost:18443/chat`
- AgentOps dashboard: `http://localhost:18080`
- OmniRoute dashboard: `http://localhost:20128`

Local dùng chứng thư self-signed nên browser có thể yêu cầu xác nhận lần đầu. Mock
OIDC đăng nhập local với quyền `org-admin` để thử nghiệm.

Nếu UI chưa thấy selector Agent/Skill/Model mới, chạy lại `local-full.sh start` để
rebuild image Control Panel từ source mới nhất.

## 5. Case 1 — chỉ dùng browser để kiểm tra và vận hành dự án

Đây là case đã chạy đầy đủ nhất.

### Kết nối và tải model lần đầu

1. Mở `/chat`, trong cột **Governance context** chọn
   **Manage model connections**.
2. Với model local, bấm **Kết nối & tải model** tại `Ollama Local`. Endpoint mặc
   định trong Docker là `http://host.docker.internal:11434`.
3. Với OmniRoute, giữ endpoint
   `http://host.docker.internal:20128/v1` rồi bấm kết nối. Local gateway không
   bắt buộc key; nếu production gateway có authentication thì cấu hình key ở
   backend trước khi triển khai.
4. Với OpenAI/Codex API hoặc Anthropic/Claude API, nhập **API key**, không nhập
   mật khẩu tài khoản ChatGPT/Claude. CASAN gọi Models API chính thức để tải
   danh sách model mà key đó được phép dùng.
5. Chọn **Model mặc định**, đóng bảng kết nối, rồi chọn model cụ thể ngay trong
   selector **Model** của Chat.

API key chỉ được gửi khi kết nối/reconnect, sau đó được mã hóa AES-256 theo
tenant trong CASAN state store. UI không có chức năng đọc lại key. Nếu bấm
**Disconnect**, bản ghi kết nối và secret tương ứng bị xóa.

Đăng nhập bằng tài khoản người dùng qua `codex login` hoặc Claude Code OAuth là
luồng đăng nhập riêng của các CLI đó. CASAN Chat không sao chép token đăng nhập
đã cache từ Codex/Claude Code; đây là ranh giới an toàn có chủ ý.

### Hỏi đáp trên evidence

1. Mở `/chat`.
2. Chọn Agent `Evidence Reader`.
3. Chọn Skill `evidence-summary`.
4. Chọn model đã tải, ví dụ `Ollama Local · ornith:9b` hoặc
   `OmniRoute Gateway · auto/best-coding`.
5. Hỏi: `Summarize the remaining production gaps and cite the evidence.`

CASAN sẽ quét câu hỏi, lấy context trong whitelist, gọi model nếu provider sẵn
sàng, quét câu trả lời và chỉ đánh dấu `certified` khi đạt gate.

### Chạy một action an toàn

1. Chọn Agent `Ops Operator`.
2. Chọn Skill `registered-actions`.
3. Gõ đúng một trigger đã đăng ký:
   - `run tests`
   - `build evidence pack`
   - `verify evidence pack`

Chat không biến câu chữ thành shell command tùy ý. Nó ánh xạ vào
`operator-actions.yaml`, chạy `action-gate`, rồi mới thực thi command cố định.

### Sinh code draft

1. Chọn Agent `Codegen Draft`.
2. Chọn Skill `sourcegen-draft`.
3. Chọn provider `local` hoặc `omniroute`.
4. Gõ: `Generate code for a small ticket SLA validation function.`

Kết quả nằm trong vùng runtime dưới
`.specify/logs/chat/codegen-artifacts/` (hoặc tenant state tương ứng). Draft đi
qua artifact scan và loop certification, nhưng **không được tự chép vào source
tree**.

## 6. Case 2 — áp CASAN vào một repository đã có sẵn

Ví dụ repository hiện có là `my-ticketing`.

### Bước 1: cài harness vào repository

Chạy từ CASAN source hub:

```bash
packages/casan-devkit/install.sh \
  --target ../my-ticketing \
  --project ticketing \
  --domain "Ticketing"
```

Lệnh này thêm:

```text
my-ticketing/
├── bin/casan
├── packages/casan-harness/
├── apps/ticketing/domain/
└── .gitea/workflows/casan-ci.yml
```

Nó không bắt buộc repository phải dùng VS Code, Codex hoặc Claude Code.

### Bước 2: khai báo domain của dự án

Điền các file sau:

- `input/requirement.md`: danh sách `FR-xx`.
- `input/architecture.md`: kiến trúc và constraint.
- `traceability-map.json`: FR nào được thực hiện bởi code/test nào.
- `golden-runs/`: output chuẩn để phát hiện drift.
- `corpus/`: dữ liệu benign và red-team riêng của domain.

### Bước 3: chạy governance gate

```bash
cd ../my-ticketing
CASAN_DOMAIN_ROOT=apps/ticketing/domain bin/casan gate
bin/casan reuse
```

Kết quả đúng phải có `CI_GATE_SUMMARY ... FAIL=0` và, khi registry có ít nhất hai
dự án active hợp lệ, `HARNESS_REUSE_VALID`.

### Bước 4: bọc một command bằng CASAN

Ví dụ chạy test mà vẫn đi qua security, governance, telemetry và output scan:

```bash
printf 'Run the ticketing test suite\n' > /tmp/casan-ticketing-input.txt
bin/casan run \
  /tmp/casan-ticketing-input.txt \
  /tmp/casan-ticketing-result.txt \
  test_ticketing -- npm test
```

CASAN không cần biết command được gõ từ Terminal, Jenkins, Gitea Actions hay một
coding agent. Miễn command đi qua harness, evidence được ghi theo cùng contract.

## 7. Case 3 — dự án Service Desk thật đã có trong repository này

Đây là bằng chứng CASAN không chỉ dùng được cho OKR:

```bash
node --test apps/service-desk/test/ticket.test.mjs

python3 packages/casan-harness/scripts/bash/traceability-matrix.py \
  --requirements apps/service-desk/domain/input/service-desk-requirement.md \
  --map apps/service-desk/domain/traceability-map.json \
  --out /tmp/service-desk-traceability.json \
  --gate

bash packages/casan-harness/scripts/bash/verify-harness-reuse.sh
```

Service Desk có source/test riêng và Domain Pack riêng. Nó dùng chung đúng một
harness version với OKR. Không có gate nào được copy riêng cho Service Desk.

## 8. Case 4 — muốn model thực sự “xây dự án cho tôi”

Mục tiêu mong muốn sẽ là:

```text
Browser Chat
  → mô tả dự án
  → chọn Project Builder + model + skill
  → sinh nhiều file vào workspace tạm
  → H4 scan từng file
  → chạy build/test/H3 evaluation
  → hiển thị diff
  → con người approve
  → apply vào repository
  → commit + CI + evidence pack
```

Luồng CLI/project-shell production hiện đã hoàn chỉnh ở lớp repository:

```bash
packages/casan-devkit/install.sh --target ../my-app --project my-app \
  --domain "My App" --template nestjs-react
cd ../my-app
npm install
bin/casan project validate --manifest apps/my-app/domain/project.manifest.json
bin/casan pipeline --manifest apps/my-app/domain/project.manifest.json
```

Scaffolder tạo shell NestJS/React, Docker, CI, Domain Pack, manifest, quality profile và harness;
pipeline lấy FR/SCR, artifact, source root, build/test và verification hoàn toàn từ manifest.
Patch chỉ được áp sau approval và tự rollback khi verification thất bại.

Phần còn thiếu chỉ dành cho trải nghiệm **browser-only** là:

1. Workspace service quản lý nhiều file/diff.
2. UI gọi project-scaffold và hiển thị manifest form.
3. Streaming token/delta và progress build/test trong browser.
4. UI release/deployment adapter theo từng môi trường đích.

CLI, CI và registered automation đã có thể tạo/kiểm chứng/apply project; browser hiện vẫn dùng
cho chat, evidence và approval thay vì thay thế hoàn toàn terminal/CI.

## 9. Cách dùng khuyến nghị cho môi trường hiện tại

### Nếu bạn là người quản lý/kiểm soát

Dùng browser Control Panel. Không cần IDE hay coding agent. Hỏi evidence, xem
security/FinOps, duyệt proposal, chạy registered action và theo dõi audit.

### Nếu bạn là developer nhưng không muốn dùng coding agent

Dùng editor bất kỳ + `bin/casan gate` + `bin/casan run`. Bạn tự sửa code, CASAN
kiểm soát quá trình và chứng minh kết quả.

### Nếu bạn muốn AI hỗ trợ mạnh

Dùng Chat với local/OmniRoute để sinh draft, sau đó review và apply. Có thể thay
Chat bằng Codex/Claude Code nếu muốn; cả hai vẫn phải chạy command qua CASAN để
giữ governance và evidence.

### Nếu bạn muốn hoàn toàn browser-only

Cần hoàn thiện Project Builder ở mục 8. Đây là một sản phẩm phía trên CASAN core,
không phải chỉ thêm một prompt hoặc bật quyền ghi file cho model.

## 10. Kết luận

CASAN dùng độc lập được mà không cần Codex, VS Code hay Claude Code cho các chức
năng governance, chat evidence, vận hành, test, CI và evidence pack. Nhưng bản
hiện tại chưa phải một “AI IDE trên browser” có thể tự xây toàn bộ repository.

Cách hiểu đúng nhất:

> **Coding tool tạo thay đổi. CASAN quyết định thay đổi đó có được tin, được chạy,
> được áp dụng và được phát hành hay không.**

Mục tiêu Project Builder sẽ đưa luôn bước tạo thay đổi vào Control Panel, nhưng
vẫn giữ nguyên nguyên tắc: model không có đường ghi file hoặc chạy command tự do.