274 lines
9.6 KiB
Markdown
274 lines
9.6 KiB
Markdown
# CASAN — Workflow & Full Pipeline (biểu đồ trực quan)
|
||
|
||
> Biểu đồ vẽ bằng **Mermaid** (VS Code + Markdown Preview Mermaid hoặc GitHub render trực tiếp).
|
||
> Gồm: **1 biểu đồ FULL** + các biểu đồ nhỏ zoom vào từng harness trọng tâm (H4·H5·H6) và luồng tự chấm điểm.
|
||
|
||
---
|
||
|
||
## 1. BIỂU ĐỒ FULL — AI-SDLC Pipeline bọc trong CASAN Harness
|
||
|
||
> Mỗi bước (STEP) là **một AI agent**. Mọi lời gọi agent **đi xuyên qua 7 harness** rồi mới sinh ra artifact. Có 2 vòng lặp tự sửa: review-spec và BACK-TO-PLAN.
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
IN["📥 INPUT
|
||
okr-requirement.md · technical_architecture.md"]
|
||
|
||
subgraph BOSS["🧠 Orchestrator: okr.bossbuiltin"]
|
||
direction TB
|
||
S1["STEP 1 · okr.srs → SRS"]
|
||
S2["STEP 2 · okr.bd → BD (外部設計)"]
|
||
S3["STEP 3 · speckit.specify → spec.md"]
|
||
S4["STEP 4 · speckit.clarify"]
|
||
S5{"STEP 5 · okr.reviewspec
|
||
🔄 auto-retry"}
|
||
S6["STEP 6 · speckit.plan → plan.md"]
|
||
S7{"STEP 7 · okr.reviewplan
|
||
🔄 BACK-TO-PLAN"}
|
||
S8["STEP 8 · okr.dd → DD (内部設計)"]
|
||
S8b["STEP 8b · okr.testkit → gen-testcases"]
|
||
S9["STEP 9 · speckit.tasks → tasks.md"]
|
||
S10["STEP 10 · speckit.implement 🔄"]
|
||
S11{"STEP 11 · okr.reviewcode 🔄"}
|
||
S12{"STEP 12 · okr.testkit run-tests"}
|
||
S13["STEP 13 · Deploy: build BE+FE, launch UI"]
|
||
|
||
S1 --> S2 --> S3 --> S4 --> S5
|
||
S5 -- REJECTED --> S3
|
||
S5 -- APPROVED --> S6 --> S7
|
||
S7 -- REJECTED --> S6
|
||
S7 -- APPROVED --> S8 --> S8b --> S9 --> S10 --> S11
|
||
S11 -- REJECTED --> S10
|
||
S11 -- APPROVED --> S12
|
||
S12 -- FAIL --> S6
|
||
S12 -- PASS --> S13
|
||
end
|
||
|
||
subgraph HARNESS["🛡️ CASAN HARNESS — mọi agent call đi qua"]
|
||
direction LR
|
||
H1["H1 Context"]:::ctx
|
||
H2["H2 Tool"]:::tool
|
||
H3["H3 Eval"]:::eval
|
||
H4["H4 Security"]:::sec
|
||
H5["H5 Governance"]:::gov
|
||
H6["H6 AgentOps"]:::ops
|
||
H7["H7 Orchestration"]:::orch
|
||
end
|
||
|
||
OUT["📤 OUTPUT
|
||
backend/ + frontend/ (source code)
|
||
+ EVIDENCE: audit chain · cost metrics · test reports"]
|
||
|
||
IN --> BOSS
|
||
BOSS -. "mỗi step gọi agent
|
||
đi xuyên harness" .-> HARNESS
|
||
HARNESS -. "gate: APPROVE / REJECT / BLOCK" .-> BOSS
|
||
BOSS --> OUT
|
||
|
||
classDef sec fill:#ffe0e0,stroke:#c0392b,stroke-width:2px;
|
||
classDef gov fill:#e0e8ff,stroke:#2c3e91,stroke-width:2px;
|
||
classDef ops fill:#e0ffe8,stroke:#1e8449,stroke-width:2px;
|
||
classDef ctx fill:#fff6e0,stroke:#b9770e;
|
||
classDef tool fill:#fff6e0,stroke:#b9770e;
|
||
classDef eval fill:#fff6e0,stroke:#b9770e;
|
||
classDef orch fill:#f0e0ff,stroke:#6c3483;
|
||
```
|
||
|
||
**Đọc biểu đồ:** Input → Boss chạy 13 bước; mỗi bước gọi agent **đi qua 7 harness** (kiểm soát); harness trả verdict APPROVE/REJECT/BLOCK → Boss quyết đi tiếp hay lặp lại (STEP5, STEP7 BACK-TO-PLAN, STEP11, STEP12). Kết quả: source code + **evidence chứng minh được**.
|
||
|
||
---
|
||
|
||
## 2. Zoom: MỘT LỜI GỌI AGENT đi qua harness thế nào (sequence)
|
||
|
||
> 3 harness trọng tâm **H4 · H5 · H6** nằm ngay trên đường thực thi (không đứng bên lề).
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant Boss as 🧠 Boss (casan-step.mjs)
|
||
participant HS as casan-harness.sh
|
||
participant H4 as 🔴 H4 security-check
|
||
participant MR as model-router → model-call.py
|
||
participant OL as 🤖 Ollama ornith:9b
|
||
participant H6 as 🟢 H6 telemetry
|
||
participant H5 as 🔵 H5 audit chain
|
||
participant H7 as 🟣 H7 checkpoint
|
||
|
||
Boss->>HS: chạy step (input, output)
|
||
HS->>H4: scan input (injection/secret/PII)
|
||
alt phát hiện tấn công
|
||
H4-->>Boss: BLOCKED rc=2 (fail-closed)
|
||
else an toàn
|
||
H4->>MR: prompt đã làm sạch
|
||
MR->>OL: classify / judge / generate
|
||
OL-->>MR: verdict + token thật
|
||
MR->>H6: ghi provider-usage.jsonl (tokens)
|
||
MR->>H5: ghi audit.jsonl (hash-chain + ký RSA)
|
||
H7->>H7: checkpoint TRƯỚC khi ghi đè
|
||
H5-->>Boss: verdict APPROVED/REJECTED
|
||
alt REJECTED
|
||
H7-->>Boss: rollback → restore file gốc
|
||
end
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Zoom H4 — Security (regex + semantic)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["Input / Artifact"] --> B{"Regex + normalization
|
||
(fold leetspeak, gộp space)"}
|
||
B -- "khớp mẫu đã biết" --> BLK["🚫 BLOCKED rc=2"]
|
||
B -- "không khớp" --> C{"Semantic classify
|
||
ornith:9b"}
|
||
C -- "INJECTION" --> BLK
|
||
C -- "SAFE" --> OK["✅ Cho qua"]
|
||
B -. "artifact-scan (indirect injection)" .-> BLK
|
||
A2["Secret / PII trong input"] --> BLK
|
||
|
||
style BLK fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
|
||
style OK fill:#d0ffd0,stroke:#1e8449,stroke-width:2px
|
||
```
|
||
|
||
**Điểm chốt:** regex bắt câu *đã biết* (recall 0.00 với paraphrase mới) → **model bù phần semantic**. Có secret/PII → chặn cứng luôn.
|
||
|
||
---
|
||
|
||
## 4. Zoom H5 — Governance (audit chain + chống giả mạo)
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
R1["record 1"] --> R2["record 2"] --> R3["record 3"]
|
||
R3 --> HEAD["HEAD hash"]
|
||
HEAD --> SIG["🔏 Ký RSA head
|
||
(mỏ neo ngoài)"]
|
||
SIG --> V{"verify-audit-chain"}
|
||
V -- "chain khớp + chữ ký hợp lệ" --> OK["✅ AUDIT_CHAIN_VALID"]
|
||
ATK["👺 Kẻ tấn công sửa 1 ký tự"] -.-> R1
|
||
R1 -. "hash lệch" .-> V
|
||
V -- "phát hiện" --> BAD["🚨 AUDIT_HASH_MISMATCH line=1"]
|
||
|
||
style OK fill:#d0ffd0,stroke:#1e8449
|
||
style BAD fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
|
||
```
|
||
|
||
**Vì sao cần ký RSA:** hash-chain tự chứa → sửa xong tính lại cả chain thì hash vẫn khớp. Ký head bằng private key (kẻ tấn công không có) → sửa xong **không ký lại được** → verify gãy.
|
||
|
||
---
|
||
|
||
## 5. Zoom H6 — AgentOps (cost-spike + drift)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph SRC["Nguồn dữ liệu (AI local cấp)"]
|
||
T["provider-usage.jsonl
|
||
token THẬT mỗi step"]
|
||
end
|
||
T --> M["Tính median total_tokens"]
|
||
M --> TH["threshold = 3 × median"]
|
||
TH --> D{"step > threshold?"}
|
||
D -- "có (710 > 660)" --> SPIKE["🚨 COST_SPIKE_DETECTED exit=2"]
|
||
D -- "không" --> NONE["✅ COST_SPIKE_NONE exit=0"]
|
||
G["golden vs candidate"] --> DR{"drift-detect
|
||
similarity under 1.0?"}
|
||
DR -- "0.66 under 1.0" --> WARN["⚠️ DRIFT_WARN"]
|
||
|
||
style SPIKE fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
|
||
style NONE fill:#d0ffd0,stroke:#1e8449
|
||
style WARN fill:#fff0c0,stroke:#b9770e
|
||
```
|
||
|
||
**Câu hỏi chốt H6:** *"step tốn 3× token có ai biết không?"* → CÓ, gate đỏ (`exit=2`). Logic deterministic; **AI local chỉ cấp token thật**.
|
||
|
||
---
|
||
|
||
## 6. Luồng TỰ CHẤM ĐIỂM → suy ra CASAN Level
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
START["Chạy self-scoring
|
||
security-gate.sh + per-harness"] --> SCORE["Chấm H1..H7 (0-100)"]
|
||
SCORE --> GAP{"Có harness duoi 30?
|
||
GAP"}
|
||
GAP -- "3+ GAP hoặc TB duoi 40" --> L2["Level 2 — Augmented"]
|
||
GAP -- "toi da 2 GAP, TB 40-65" --> L3["Level 3 — Standard"]
|
||
GAP -- "toi da 1 GAP, TB 65-80" --> L34["Level 3 to 4"]
|
||
GAP -- "0 GAP, TB tren 80" --> L4["Level 4 — Automated ✅"]
|
||
L4 --> L5Q{"Moi harness tren 70
|
||
+ Multi-Agent?"}
|
||
L5Q -- "có" --> L5["Level 5 — Native"]
|
||
L5Q -- "chưa" --> L4
|
||
|
||
style L4 fill:#d0ffd0,stroke:#1e8449,stroke-width:2px
|
||
style L5 fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px
|
||
style L2 fill:#ffe8d0,stroke:#b9770e
|
||
```
|
||
|
||
**Quy tắc "harness thấp nhất quyết định trần":** 1 harness < 30 (GAP) → cả pipeline không thể là Level 4, dù các harness khác cao.
|
||
|
||
---
|
||
|
||
## 7. Luồng chọn MODEL (Ollama vs OpenAI)
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Q{"Có gì để chạy model?"}
|
||
Q -- "Ollama ở nhà" --> A["Path A: SSH tunnel → 127.0.0.1:11434"]
|
||
Q -- "Ollama trên Mac" --> B["Path B: ollama serve local
|
||
(không cần Linux server)"]
|
||
Q -- "OpenAI key" --> C{"model-call.py hỗ trợ?"}
|
||
C -- "STUB chưa cài" --> C1["⚠️ fail: cloud_backend_not_implemented
|
||
→ cần patch ~20 dòng (Runbook Mục 4)"]
|
||
C -- "sau khi patch" --> C2["Path C: openai:gpt-4o-mini
|
||
(không cần Ollama/server)"]
|
||
A --> RUN["Chạy pipeline / self-scoring"]
|
||
B --> RUN
|
||
C2 --> RUN
|
||
|
||
style C1 fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
|
||
style RUN fill:#d0ffd0,stroke:#1e8449
|
||
```
|
||
|
||
**Nhắc:** OpenAI backend hiện là **stub** — có key vẫn phải patch mới chạy. Ollama local trên Mac = bỏ được Linux server.
|
||
|
||
---
|
||
|
||
## 8. Bản đồ 3 harness trọng tâm × mô hình tấn công
|
||
|
||
```mermaid
|
||
mindmap
|
||
root((CASAN H4 H5 H6))
|
||
H4 Security
|
||
Direct injection rc2
|
||
Paraphrase then semantic model
|
||
Leetspeak whitespace
|
||
Indirect via artifact
|
||
Secret and PII block
|
||
Red-team recall over regex
|
||
H5 Governance
|
||
Tamper 1 char then HASH_MISMATCH
|
||
Re-forge chain then RSA anchor
|
||
Secrets-scan
|
||
No-bypass no-verify
|
||
Tool audit trace
|
||
H6 AgentOps
|
||
Cost-spike 3x then exit2
|
||
Negative control then exit0
|
||
Drift-detect
|
||
Telemetry token that
|
||
Hallucination scan
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Ghi chú đọc biểu đồ
|
||
|
||
- **Mở bằng:** VS Code (cài extension *Markdown Preview Mermaid Support*) hoặc đẩy lên GitHub (render tự động).
|
||
- Màu quy ước: 🔴 đỏ = H4 Security · 🔵 xanh dương = H5 Governance · 🟢 xanh lá = H6 AgentOps · 🟣 tím = H7 · vàng = H1/H2/H3.
|
||
- Chi tiết số liệu & lệnh: xem `CASAN_MASTER_RUNBOOK.md`, `CASAN_TEAM_QA.md`, `CASAN_OLD_vs_CASAN5_Executive_Assessment.md`.
|
||
|
||
---
|
||
|
||
_Biểu đồ mô tả luồng thật của pipeline (`scripts/run-casan-pipeline.mjs` + `casan-step.mjs` + `.specify/scripts/bash/*`). Các verdict/exit code trong biểu đồ là kết quả đã kiểm chứng trong phiên đánh giá._ |