Add selectable CASAN IDE integrations
This commit is contained in:
thanhnv
@@ -1,8 +1,8 @@
|
||||
# CASAN Agentic Clients trên Windows (Plan-20)
|
||||
|
||||
Tài liệu hướng dẫn cài đặt tích hợp **transparent agentic client** của CASAN cho
|
||||
Windows: developer gõ prompt bình thường trong Claude Code hoặc Codex, nhưng mọi
|
||||
turn được chứng nhận vẫn có trace H1→H7 và record H6 đầy đủ.
|
||||
Windows: developer dùng Claude Code, Codex, hoặc explicit `@casan` trong GitHub
|
||||
Copilot Chat, nhưng mọi turn được chứng nhận vẫn có trace H1→H7 và record H6.
|
||||
|
||||
Liên quan:
|
||||
[Plan-20](../plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) ·
|
||||
@@ -30,8 +30,8 @@ thuần. Chỉ cần:
|
||||
- **`bash` trên PATH để chạy security gate H4/H2** — khuyến nghị **Git for
|
||||
Windows (Git Bash)**, nhẹ hơn WSL2 nhiều và đa số máy dev đã có. Đây là điều
|
||||
kiện để turn được **certified**.
|
||||
- Repo dự án đã adopt CASAN core (`packages/casan-harness` tồn tại). Nếu chưa,
|
||||
xem [CASAN_ADOPTION_WINDOWS.md](CASAN_ADOPTION_WINDOWS.md).
|
||||
- CASAN global đã cài bằng `install.ps1`; repo consumer **không** cần chứa
|
||||
`packages/casan-harness`.
|
||||
|
||||
> **Graceful degradation:** nếu máy **không có bash**, bridge vẫn chạy —
|
||||
> admission/telemetry/redaction bằng Python thuần — nhưng H4/H2 gate không chạy
|
||||
@@ -49,65 +49,48 @@ Kiểm tra nhanh:
|
||||
|
||||
```powershell
|
||||
python3 --version
|
||||
Test-Path .\packages\casan-harness\scripts\python\agentic_bridge.py
|
||||
# Xác nhận gate chạy được (bash_available / gates_runnable = true)
|
||||
python3 .\packages\casan-harness\scripts\python\agentic_bridge.py doctor
|
||||
casan version
|
||||
```
|
||||
|
||||
## 3. Cài đặt từ clone sạch (không copy file thủ công)
|
||||
|
||||
Installer PowerShell tự đặt config vào đúng chỗ và ghi manifest để gỡ sạch.
|
||||
## 3. Cài global và init project
|
||||
|
||||
```powershell
|
||||
# Cài cho cả Claude Code lẫn Codex, bắt đầu ở chế độ observe (an toàn)
|
||||
pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Client all -Mode observe
|
||||
# Từ checkout CASAN: cài một lần trên máy
|
||||
pwsh .\install.ps1
|
||||
|
||||
# Chỉ Claude Code
|
||||
pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Client claude
|
||||
cd C:\work\my-project
|
||||
|
||||
# Bật enforce khi đã sẵn sàng cấp certified
|
||||
pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Client all -Mode enforce
|
||||
# Menu chọn Claude / Codex / VS Code Copilot
|
||||
casan init
|
||||
|
||||
# Hoặc non-interactive, chọn chính xác client
|
||||
casan init --client claude,codex --mode enforce
|
||||
casan init --client vscode-copilot --mode enforce --vscode-install yes
|
||||
```
|
||||
|
||||
Installer sẽ:
|
||||
|
||||
1. Copy `settings.json` → `.claude\settings.json` và/hoặc `hooks.json`/`config.toml`
|
||||
→ `.codex\`. File cũ của bạn được backup thành `*.casan-bak`.
|
||||
2. Ghi feature flags vào `.casan\agentic.env`.
|
||||
3. Ghi `.casan\agentic-install-manifest.json` để uninstall không đụng config
|
||||
riêng của bạn.
|
||||
4. Chạy doctor tự động.
|
||||
`init` merge CASAN handlers vào config hiện hữu, ghi bootstrap
|
||||
`.casan\casan-hook.py`, pin harness global, và tạo VSIX `@casan` khi Copilot
|
||||
được chọn. Bootstrap tự load `config.json`; không cần source env thủ công.
|
||||
|
||||
> Đường dẫn có dấu cách được xử lý đúng (ví dụ `C:\Users\Nguyen Van A\project`).
|
||||
|
||||
## 4. Doctor và smoke test
|
||||
|
||||
```powershell
|
||||
pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Action doctor -Client all
|
||||
casan doctor
|
||||
casan doctor --client vscode-copilot
|
||||
```
|
||||
|
||||
Doctor kiểm tra: interpreter Python, sự hiện diện của hook config, các gate
|
||||
H4/H2, quyền ghi state, và chạy một turn begin→admission thật trên state tạm.
|
||||
|
||||
Có thể gọi bridge trực tiếp:
|
||||
|
||||
```powershell
|
||||
python3 .\packages\casan-harness\scripts\python\agentic_bridge.py doctor
|
||||
```
|
||||
Doctor kiểm tra: pin/hash live, bootstrap, hook schema, adapter smoke và trạng
|
||||
thái VS Code extension. Codex vẫn cần review exact hook hash bằng `/hooks`.
|
||||
|
||||
## 5. Dùng thử
|
||||
|
||||
1. Mở repo trong Claude Code (hoặc Codex).
|
||||
2. Với Codex: chấp nhận **trust prompt** để project hook được load (bước bắt
|
||||
buộc, doctor sẽ nhắc).
|
||||
3. Gõ prompt bình thường. Một prompt vi phạm policy (ví dụ chứa role-hijack) bị
|
||||
1. Mở repo trong Claude Code hoặc Codex; với Codex mở `/hooks`, review/trust.
|
||||
2. Trong GitHub Copilot Chat, gọi `@casan <prompt>`; chat built-in không được
|
||||
CASAN intercept toàn cục.
|
||||
3. Gõ prompt. Một prompt vi phạm policy (ví dụ chứa role-hijack) bị
|
||||
chặn trước model theo khả năng của client.
|
||||
4. Khi turn kết thúc, xem H6:
|
||||
|
||||
```powershell
|
||||
# Lọc report H6 theo client / integration_mode / trace_id / project
|
||||
python3 .\packages\casan-harness\scripts\python\agentic_bridge.py report --client claude-code
|
||||
```
|
||||
|
||||
## 6. Feature flags
|
||||
|
||||
@@ -116,29 +99,15 @@ python3 .\packages\casan-harness\scripts\python\agentic_bridge.py report --clien
|
||||
| Biến | Mặc định | Ý nghĩa |
|
||||
|---|---|---|
|
||||
| `CASAN_AGENTIC_BRIDGE_ENABLED` | `1` | Bật/tắt tổng. |
|
||||
| `CASAN_AGENTIC_ENFORCEMENT_MODE` | `observe` | `observe` (chỉ telemetry, không certified) → `enforce`. |
|
||||
| `CASAN_AGENTIC_ENFORCEMENT_MODE` | `enforce` qua init | `observe` (pilot) hoặc `enforce`. |
|
||||
| `CASAN_AGENTIC_INTEGRATION_MODE` | `project_hook` | `project_hook` / `managed_hook` / `casan_owned`. |
|
||||
| `CASAN_AGENTIC_CLIENT_ALLOWLIST` | (trống) | Danh sách client; ngoài danh sách → `observed_only`. |
|
||||
| `CASAN_AGENTIC_TTL_SECONDS` | `1800` | TTL admission. |
|
||||
| `CASAN_AGENTIC_INTERNAL_TIMEOUT` | `8` | Internal timeout của bridge (ngắn hơn outer hook timeout). |
|
||||
| `CASAN_AGENTIC_H2_REGISTRY` | `0` | Bật thêm H2 tool-registry gate (cho managed deployment có agent identity). |
|
||||
|
||||
Nạp flags trong PowerShell:
|
||||
|
||||
```powershell
|
||||
Get-Content .\.casan\agentic.env | Where-Object { $_ -and -not $_.StartsWith('#') } | ForEach-Object {
|
||||
$k,$v = $_ -split '=',2; Set-Item -Path Env:$k -Value $v
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Gỡ cài đặt (không xóa config của user)
|
||||
|
||||
```powershell
|
||||
pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Action uninstall -Client all
|
||||
```
|
||||
|
||||
Uninstall chỉ xóa file do CASAN tạo (theo manifest) và khôi phục bản backup
|
||||
`*.casan-bak` nếu có.
|
||||
`.casan\config.json` là nguồn runtime chính; `agentic.env` chỉ còn là reference
|
||||
cho automation tương thích cũ.
|
||||
|
||||
## 8. Xử lý sự cố
|
||||
|
||||
@@ -146,7 +115,7 @@ Uninstall chỉ xóa file do CASAN tạo (theo manifest) và khôi phục bản
|
||||
|---|---|---|
|
||||
| Prompt không bị chặn dù có hook | Outer hook timeout của client (fail-open đã ghi nhận) | Side-effect vẫn bị `PreToolUse` từ chối khi thiếu admission; giảm tải hook, xem log H6 failure |
|
||||
| Codex không chạy hook | Chưa qua trust review | Mở repo trong Codex, chấp nhận trust; chạy lại doctor |
|
||||
| Turn hiện `observed_only` | Đang ở observe mode hoặc client ngoài allowlist | Đặt `-Mode enforce`, thêm client vào allowlist |
|
||||
| Turn hiện `observed_only` | Đang ở observe mode hoặc client ngoài allowlist | Chạy lại `casan init --mode enforce --client ...` |
|
||||
| Token/cost là `null` | Client chưa cấp nguồn usage đáng tin | Đúng theo thiết kế — không bịa số; `telemetry_quality=partial` |
|
||||
| `bridge doctor` báo gate missing | Repo chưa adopt core đầy đủ | Chạy lại DevKit install core |
|
||||
| `casan doctor` báo integrity/bootstrap missing | Global install hoặc project init chưa đầy đủ | Chạy lại `install.ps1`, rồi `casan init` |
|
||||
| Mọi turn hiện `observed_only` trên Windows | Không có `bash` (thiếu Git Bash) → gate H4/H2 không chạy | Cài Git for Windows hoặc set `CASAN_AGENTIC_BASH`; `doctor` sẽ báo `gates_runnable=true` |
|
||||
|
||||
@@ -53,10 +53,11 @@ cục bộ), `CASAN_DIST_URL` (tải tarball), `CASAN_NO_PATH_LINK=1` (không t
|
||||
|
||||
```bash
|
||||
cd <dự-án-của-bạn>
|
||||
casan init # project id lấy theo tên thư mục, level=devkit
|
||||
casan init # interactive: chọn Claude, Codex, VS Code/Copilot
|
||||
# hoặc chọn level áp dụng cho project:
|
||||
casan init --level 1 --project my-app # L1: chỉ gate + hook Plan-20
|
||||
casan init --level 2 --project my-app # L2 (mặc định): + CI workflow + domain-pack
|
||||
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 level show # xem level đã cài + level project
|
||||
casan level set 2 # đổi level project (không cần init lại)
|
||||
```
|
||||
@@ -79,17 +80,50 @@ casan level set 2 # đổi level project (không cần ini
|
||||
| `.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 harness global, dispatch adapter |
|
||||
| `.specify/` | thư mục state runtime (logs/trace/admission) |
|
||||
| `.claude/settings.json` | hook Claude Code (Plan-20) |
|
||||
| `.codex/hooks.json`, `config.toml` | hook Codex (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 |
|
||||
|
||||
Tham số: `--client claude|codex|all` (mặc định `all`), `--mode observe|enforce`
|
||||
(mặc định `observe`), `--integration-mode project_hook|managed_hook|casan_owned`,
|
||||
`--target <dir>` (mặc định thư mục hiện tại).
|
||||
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 không có TTY,
|
||||
mặc định tương thích ngược là `claude,codex`.
|
||||
|
||||
`--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 kiểm tra live hash
|
||||
của harness global so với `version.lock` trước khi chạy adapter.
|
||||
|
||||
Sau `init`, developer gõ prompt bình thường trong client — trace H1→H7 + H6 theo
|
||||
Plan-20. Repo chỉ có mấy file config nhỏ; nâng cấp harness làm ở `$CASAN_HOME`.
|
||||
|
||||
### Capability theo client
|
||||
|
||||
| Lựa chọn | Trải nghiệm | Bước trust/cài đặt bắt buộc |
|
||||
|---|---|---|
|
||||
| `claude` | Claude Code CLI và extension chính thức dùng project hooks | Mở trusted project; hook chạy tự động |
|
||||
| `codex` | Codex CLI và IDE extension 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>` |
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user