278 lines
13 KiB
Markdown
278 lines
13 KiB
Markdown
# Cài CASAN production (managed hoặc vendored Core) — Plan-21
|
|
|
|
CASAN cài CLI/DevKit **một lần** vào máy (`$CASAN_HOME`). Mỗi project chạy
|
|
`casan init` và chọn một runtime contract rõ ràng:
|
|
|
|
- `managed` (mặc định): Core nằm trong global install, project pin version/hash.
|
|
- `vendored`: Core production-only nằm tại `.casan/runtime/casan-core`, dành
|
|
cho offline, air-gapped hoặc repository cần self-contained.
|
|
|
|
Capability level và runtime placement là hai khái niệm độc lập. Project mặc
|
|
định dùng Level 1/Core dù global package phải là DevKit để có lệnh `init`.
|
|
|
|
## 1. Cài đặt (một lần cho mỗi máy)
|
|
|
|
```bash
|
|
# macOS / Linux
|
|
curl -fsSL https://<your-gitea>/admin/casan5/raw/branch/main/install.sh | sh
|
|
|
|
# Windows (PowerShell)
|
|
irm https://<your-gitea>/admin/casan5/raw/branch/main/install.ps1 | iex
|
|
```
|
|
|
|
Hoặc từ một checkout CASAN có sẵn:
|
|
|
|
```bash
|
|
sh install.sh # macOS/Linux
|
|
pwsh .\install.ps1 # Windows
|
|
```
|
|
|
|
Chọn **level đóng gói** để cài (theo `packaging/levels.json`):
|
|
|
|
```bash
|
|
sh install.sh --level core # L1: harness + gates + CLI (casan run/gate/verify)
|
|
sh install.sh --level devkit # L2 (mặc định): + adoption tooling (casan init, CI, domain-pack)
|
|
sh install.sh --level platform # L3 preview: từ chối — là service, deploy riêng
|
|
sh install.sh --level enterprise# L4 future: từ chối (chưa ship)
|
|
```
|
|
|
|
Levels là cumulative (devkit ⊃ core). `casan init` là tính năng của **L2 (devkit)**;
|
|
cài `--level core` sẽ không có `casan init` (báo rõ ràng).
|
|
|
|
Installer sẽ:
|
|
|
|
- Copy harness vào `$CASAN_HOME/versions/<version>` (mặc định `~/.casan`,
|
|
Windows: `%LOCALAPPDATA%\casan`) và trỏ `current` vào version đó.
|
|
- Ghi **hash toàn vẹn** của gate-code (`.harness-hash`) — mỏ neo cho pin+verify.
|
|
- Ghi level đã cài vào `.casan-level`.
|
|
- Tạo launcher `casan` (tự định vị install của chính nó) và đưa lên PATH
|
|
(`~/.local/bin` hoặc `$CASAN_HOME/bin`).
|
|
|
|
Installer dùng allowlist `packaging/runtime-layout.json`. Runtime global không
|
|
chứa `tests/`, legacy `level5/`, internal test/CI runners, Platform dashboard/local
|
|
lab, source docs hay bản sao installer. Policy cần thiết đã được chuẩn hóa vào
|
|
`packages/casan-harness/config/`.
|
|
|
|
> Windows cần **Git for Windows (Git Bash)** để *chạy* harness (xem
|
|
> [CASAN_AGENTIC_CLIENTS_WINDOWS.md](CASAN_AGENTIC_CLIENTS_WINDOWS.md)) — không
|
|
> cần WSL2. Cả hai OS cần `python3`.
|
|
|
|
Biến môi trường hữu ích: `CASAN_HOME` (đổi nơi cài), `CASAN_SRC` (cài từ checkout
|
|
cục bộ), `CASAN_DIST_URL` (tải tarball), `CASAN_NO_PATH_LINK=1` (không tự thêm PATH).
|
|
|
|
## 2. Adopt vào một dự án bất kỳ
|
|
|
|
```bash
|
|
cd <dự-án-của-bạn>
|
|
casan init # project mới: interactive chọn runtime rồi client
|
|
# hoặc chọn level áp dụng cho project:
|
|
casan init --level 1 --project my-app --client claude
|
|
casan init --level 2 --project my-app --client claude,codex
|
|
casan init --project my-app --client vscode-copilot --vscode-install yes
|
|
casan init --runtime vendored --project offline-app --client claude,codex
|
|
casan level show # xem level đã cài + level project
|
|
casan level set 2 # đổi level project (không cần init lại)
|
|
```
|
|
|
|
Project mới chạy trong terminal tương tác sẽ được hỏi vị trí Core trước:
|
|
`Managed (Recommended)` hoặc `Vendored`, sau đó mới chọn client. Nhấn Enter dùng
|
|
Managed và Claude+Codex. Nhập sai sẽ được hỏi lại thay vì kết thúc bằng payload
|
|
khó đọc.
|
|
|
|
`init` và `level show` luôn in runtime mode/path. Project mới mặc định
|
|
`managed`; chạy lại init giữ nguyên mode đã chọn và không hỏi lại runtime.
|
|
Chuyển mode phải explicit:
|
|
|
|
```bash
|
|
casan init --runtime managed
|
|
casan init --runtime vendored
|
|
```
|
|
|
|
**Áp dụng cho dự án ĐÃ có vỏ (agents/skills/hook sẵn):** an toàn.
|
|
- Mặc định `casan init` áp dụng **Level 1/core**: governance config + hooks,
|
|
không thêm `.gitea` workflow hoặc domain-pack. Level cài global vẫn phải là
|
|
DevKit vì lệnh adoption nằm trong DevKit.
|
|
- `init` **KHÔNG index/parse code, KHÔNG sửa source, KHÔNG dựng lại vỏ** — chỉ thêm config.
|
|
- Hook được **MERGE** idempotent vào `.claude/settings.json` / `.codex/hooks.json`
|
|
hiện có (giữ nguyên hook/agents/skills/khóa khác của bạn), không ghi đè. Chạy
|
|
`init` nhiều lần không nhân đôi hook.
|
|
- **Guardrail:** `init` **từ chối** khi target chính là một CASAN source hub (để
|
|
không tự chặn agent đang phát triển CASAN); dùng `--force` nếu thực sự cần.
|
|
- Project cũ có vendored `packages/casan-harness` **không bị xem là source hub**:
|
|
init tự migrate sang hybrid, giữ nguyên harness/CI/scripts cũ để tương thích và
|
|
không yêu cầu `--force`.
|
|
|
|
`--level 3` (platform) chỉ áp base L2 + nhắc rằng platform là service deploy riêng;
|
|
`--level 4` (enterprise) bị từ chối (chưa ship).
|
|
|
|
`casan uninstall` xóa workflow CASAN trong `.gitea` và các scaffold file còn
|
|
nguyên checksum, sau đó prune thư mục rỗng. Workflow của project và scaffold
|
|
file đã chỉnh sửa được giữ lại. Thêm `--purge` để xóa cả runtime evidence
|
|
`.specify/logs` và `.specify/state`.
|
|
|
|
`casan init` luôn ghi config per-project:
|
|
|
|
| File | Vai trò |
|
|
|---|---|
|
|
| `.casan/config.json` | project id, enforcement/integration mode, clients |
|
|
| `.casan/version.lock` | **pin** harness version + hash gate-code |
|
|
| `.casan/agentic.env` | feature flags bridge Plan-20 |
|
|
| `.casan/casan-hook.py` | bootstrap stdlib: load config, resolve + verify Core managed/vendored, dispatch adapter |
|
|
| `.specify/` | thư mục state runtime (logs/trace/admission) |
|
|
| `.claude/settings.json` | hook Claude Code (Plan-20) |
|
|
| `.codex/hooks.json` | hook Codex theo schema hiện hành; cần review/trust bằng `/hooks` |
|
|
| `.vscode/extensions.json` | recommendations cho IDE đã chọn |
|
|
| `.casan/runtime/casan-core/` | Chỉ mode `vendored`: CLI + Core runtime production-only |
|
|
|
|
Tham số `--client` có thể lặp hoặc comma-separated:
|
|
`claude`, `codex`, `vscode-copilot`, `all`, `none`. Khi chạy `casan init` trực
|
|
tiếp trong terminal, CLI hiển thị menu chọn. Trong automation, dùng
|
|
`--non-interactive` và khai báo rõ runtime/client:
|
|
|
|
```bash
|
|
casan init --non-interactive --level core --runtime managed \
|
|
--mode enforce --client claude,codex
|
|
```
|
|
|
|
`--non-interactive`, `--json` hoặc môi trường không có TTY không bao giờ chờ
|
|
input. Khi không truyền lựa chọn, mặc định là Managed và `claude,codex`.
|
|
|
|
Các command dành cho người vận hành (`init`, `doctor`, `verify-harness`,
|
|
`level show`, `uninstall`) mặc định in bản tóm tắt dễ đọc. Thêm `--json` sau
|
|
command để lấy payload đầy đủ cho automation, ví dụ:
|
|
|
|
```bash
|
|
casan init --client claude,codex --json
|
|
casan doctor --json
|
|
casan level show --json
|
|
```
|
|
|
|
`--mode observe|enforce` mặc định `enforce`; dùng `observe` chỉ cho pilot
|
|
telemetry-only. `--integration-mode` nhận
|
|
`project_hook|managed_hook|casan_owned`; `--target <dir>` mặc định là thư mục
|
|
hiện tại.
|
|
|
|
Bootstrap `.casan/casan-hook.py` tự đọc `config.json`; developer không còn phải
|
|
source `.casan/agentic.env` trước khi mở IDE. Mỗi invocation resolve Core theo
|
|
runtime mode rồi kiểm tra live hash so với `version.lock` trước khi chạy
|
|
adapter. Codex gọi bootstrap bằng đường dẫn tương đối từ project root, không
|
|
phụ thuộc `git rev-parse`; Git vẫn được khuyến nghị để có provenance, diff và
|
|
rollback đáng tin cậy.
|
|
|
|
### Project đã có `.claude`, `.github`, agents, skills hoặc CASAN vendored
|
|
|
|
Chỉ cần commit/backup trạng thái hiện tại, cài CASAN global rồi chạy init tại
|
|
project root, kể cả khi đường dẫn có khoảng trắng:
|
|
|
|
```bash
|
|
cd '/path/to/Basic Design (Screen&Report)_v2.7'
|
|
casan init --project basic-design-v27 --client claude,codex,vscode-copilot
|
|
casan doctor
|
|
```
|
|
|
|
Quy tắc migration:
|
|
|
|
- `.claude/agents`, `.claude/skills`, `.claude/commands`, `.github/**` và
|
|
workflow hiện hữu không bị xóa hoặc ghi đè.
|
|
- CASAN chỉ merge handler của mình vào `.claude/settings.json` và
|
|
`.codex/hooks.json`; cấu hình/hook không thuộc CASAN được giữ nguyên.
|
|
- Nếu có CASAN vendored cũ, `packages/casan-harness`, `bin/casan-chat`, CI và
|
|
evidence cũ được giữ lại. Chỉ xóa chúng sau khi CI/scripts/domain smoke đã
|
|
chuyển sang harness global.
|
|
- Block legacy nằm đúng giữa marker
|
|
`CASAN_PROMPT_ENFORCEMENT_START/END` được nâng cấp tự động.
|
|
- Prose legacy nằm ngoài marker không bị sửa âm thầm; `init` và `doctor` liệt kê
|
|
file cần review. Đặc biệt phải bỏ tuyên bố cũ rằng Claude/Codex direct chat
|
|
luôn nằm ngoài CASAN, vì Plan-20 project hooks đã thay đổi hành vi đó.
|
|
- Codex vẫn cần `/hooks` trust; Copilot built-in vẫn cần explicit `@casan`.
|
|
|
|
Sau `init`, developer gõ prompt bình thường trong client — trace H1→H7 + H6 theo
|
|
Plan-20. Managed mode nâng cấp runtime ở `$CASAN_HOME`; vendored mode được nâng
|
|
cấp có chủ đích bằng cách chạy lại `casan init --runtime vendored` từ release
|
|
đã duyệt.
|
|
|
|
### Capability theo client
|
|
|
|
| Lựa chọn | Local surface được hỗ trợ | Bước trust/cài đặt bắt buộc |
|
|
|---|---|---|
|
|
| `claude` | Claude Code CLI, VS Code extension và JetBrains integration dùng chung project settings/hooks | Mở trusted project; hook chạy tự động |
|
|
| `codex` | Codex desktop app (Local), CLI và IDE extension (Local) dùng `.codex/hooks.json` | Mở `/hooks`, review và trust đúng hook hash |
|
|
| `vscode-copilot` | GitHub Copilot Chat qua route **explicit `@casan`** | Cài VSIX do init tạo/cài; dùng `@casan <prompt>` |
|
|
|
|
Không gắn badge project-hook cho Codex Cloud/Web, Claude Desktop hoặc
|
|
claude.ai. Các surface đó không chạy local project hook; muốn support phải có
|
|
remote/managed integration riêng và một qualification suite riêng.
|
|
|
|
GitHub Copilot Chat mặc định **không** có public API để CASAN intercept mọi
|
|
prompt. Chỉ route `@casan` là `casan_owned`; participant detection/built-in
|
|
Copilot không được quảng bá là certified.
|
|
|
|
Kiểm tra sau init:
|
|
|
|
```bash
|
|
casan doctor
|
|
casan doctor --client claude
|
|
casan doctor --client codex
|
|
casan doctor --client vscode-copilot
|
|
```
|
|
|
|
Với Codex, `doctor` đọc trạng thái hiệu lực bằng API `hooks/list` của chính
|
|
`codex app-server`. Nếu toàn bộ CASAN hook của project đang `trusted`, kết quả
|
|
là `READY` và không yêu cầu Allow lại. Action `/hooks` chỉ xuất hiện khi hook
|
|
thực sự `untrusted`/`modified`, bị tắt, hoặc máy hiện tại không thể xác minh
|
|
trust state. Hash toàn file `.codex/hooks.json` trong `init-manifest.json` là
|
|
checksum ownership phục vụ uninstall an toàn; nó không phải per-hook
|
|
`trusted_hash` mà Codex dùng để quyết định trust.
|
|
|
|
### Gỡ khỏi project
|
|
|
|
```bash
|
|
casan uninstall
|
|
```
|
|
|
|
Command này xóa CASAN project hooks, bootstrap và config nhưng giữ nguyên hook
|
|
người dùng, CI/domain files, `.casan-bak`, VS Code extension dùng chung và
|
|
`.specify` evidence. Nếu project dùng vendored mode, toàn bộ
|
|
`.casan/runtime/casan-core` cũng bị xóa. Dùng `--purge` nếu chủ động muốn xóa
|
|
runtime logs/state; dùng `--remove-vscode-extension` nếu chắc chắn không project
|
|
nào khác trên máy còn dùng route `@casan`.
|
|
|
|
## 3. Pin + Verify (giữ đảm bảo bảo mật khi harness ở ngoài repo)
|
|
|
|
Vì harness không nằm trong repo, dự án **pin** version + hash gate-code lúc
|
|
`init`. Kiểm tra bất cứ lúc nào:
|
|
|
|
```bash
|
|
casan verify-harness
|
|
```
|
|
|
|
- Khớp → hiển thị `Harness integrity verified` (rc 0); `--json` trả
|
|
`"status": "ok"`.
|
|
- Harness global bị đổi/tamper so với pin → `HARNESS_INTEGRITY_DRIFT` (rc 3).
|
|
|
|
`verify-harness` **luôn tính lại hash từ file thật** (không tin hash cache), nên
|
|
sửa lén một gate script sẽ bị phát hiện. Nên chạy `verify-harness` trong CI trước
|
|
khi tin bất kỳ trace nào là certified.
|
|
|
|
> Bước làm mạnh tiếp theo (chưa bật mặc định): ký `.harness-hash` bằng khóa tổ
|
|
> chức để verify cả *chữ ký* chứ không chỉ nội dung — dùng hạ tầng ký của Plan-16.
|
|
|
|
## 4. Chọn runtime mode
|
|
|
|
| | Vendored (`casan init --runtime vendored`) | Managed (`casan init`) |
|
|
|---|---|---|
|
|
| Repo | Tự chứa Core production-only | Nhẹ, chỉ config/lock/hooks |
|
|
| Nâng cấp | Explicit theo từng repo | Tập trung ở `$CASAN_HOME` |
|
|
| Bảo mật | Core local + **pin/hash verify** | Core global + **pin/hash verify** |
|
|
| CI/offline | Phù hợp air-gapped | Runner phải cài đúng CASAN release |
|
|
| Khuyến nghị | Khách hàng offline/regulated | Mặc định cho workstation và managed CI |
|
|
|
|
Cả hai dùng đúng cùng production allowlist và lõi harness; không mode nào mang
|
|
theo tests, legacy `level5`, internal runners hay Platform-only helpers.
|
|
|
|
## 5. Kiểm thử
|
|
|
|
```bash
|
|
bash packages/casan-devkit/tests/hybrid-install-tests.sh
|
|
```
|