Feature/delta team/epic r04 (#7)

## Summary

epic r04 - begin refactor

## Change Type

- [x] Cowork feature
- [ ] Bug fix
- [ ] Core AI contribution
- [ ] Test / hardening
- [ ] Performance
- [ ] Documentation

## Related Work

Cowork Task:

Core Repo: http://34.143.229.138/gitea-admin/fsg-ai-core-assets

Core AI Issue:

Core Task:

Related PR:

## Scope

What is intentionally included?

What is intentionally NOT included?

## Validation

- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual verification
- [ ] Regression check

Commands / evidence:

## Security Impact

Permission / credential / network / customer data impact:

## Compatibility

- [ ] No breaking change
- [ ] Breaking change documented

## Reviewer Notes

Anything Cowork reviewers should pay attention to.

---------

Co-authored-by: Anh Tran Nguyen Minh <anhtnm1@fpt.com>
Co-authored-by: Huong Le Thi Thien <huongltt35@fpt.com>
Co-authored-by: Nam Pham Dinh Thanh <nampdt@fpt.com>
Co-authored-by: Vu Dam Tuan <vudt15@fpt.com>
Co-authored-by: Hiep Ha Van <hiephv3@fpt.com>
Co-authored-by: Lam Hoang Van <lamhv7@fpt.com>
Reviewed-on: #7
Co-authored-by: Duy Le Huu <duylh19@fpt.com>

security/attachment_validator.py

@@ -7,5 +7,6 @@ ATTACHMENT_DENIED_MESSAGE = "Attached content failed security validation."
 
 
 def validate_attachment(path: str, mime_type: str = "") -> bool:
+    """``True`` nếu tệp được phép đính kèm vào lượt chat."""
     result = classify_attachment(path, mime_type or None)
     return not result.blocked

security/audit_logger.py

@@ -21,6 +21,12 @@ logger = logging.getLogger("cowork_local.security.audit")
 
 @dataclass
 class AuditEntry:
+    """Một dòng nhật ký kiểm toán, đủ trường để dựng lại bối cảnh sau này.
+
+    Cố ý KHÔNG lưu nguyên văn lệnh: chỉ giữ ``command_hash`` (SHA-256, 16
+    ký tự đầu) để đối chiếu hai lần chạy có giống nhau không, mà không đưa
+    nội dung nhạy cảm vào file log.
+    """
     timestamp: str = ""
     user: str = ""
     project: str = ""
@@ -38,6 +44,11 @@ class AuditEntry:
     approval_status: str = ""  # auto, approved, rejected
 
     def __post_init__(self):
+        """Điền mốc thời gian và mã băm lệnh nếu bên gọi chưa đặt.
+
+        Mã băm thay cho nội dung lệnh gốc: nhật ký cần truy được về sau nhưng không
+        nên chứa nguyên văn thứ đã chạy.
+        """
         if not self.timestamp:
             self.timestamp = datetime.now(timezone.utc).isoformat()
         if not self.command_hash and self.action_type:
@@ -47,6 +58,7 @@ class AuditEntry:
 
 
 def _audit_dir() -> Path:
+    """Thư mục chứa nhật ký kiểm toán. Import muộn để tránh vòng import với ``config``."""
     from ..config import CONFIG_DIR
     return CONFIG_DIR / "audit"
 

security/command_risk_classifier.py

@@ -20,6 +20,11 @@ from typing import List, Optional
 
 
 class RiskLevel(str, Enum):
+    """Bậc rủi ro của một lệnh, prompt hay tệp đính kèm.
+
+    Kế thừa ``str`` để so sánh và ghi log thẳng bằng chuỗi mà không phải
+    ``.value`` ở từng chỗ dùng.
+    """
     SAFE = "safe"
     MODERATE = "moderate"
     HIGH = "high"
@@ -29,6 +34,11 @@ class RiskLevel(str, Enum):
 
 @dataclass
 class RiskResult:
+    """Kết quả một lần phân loại: điểm, bậc, lý do, và có chặn hẳn không.
+
+    ``reasons`` giữ lại đúng mẫu regex đã khớp — nhật ký kiểm toán phải trả
+    lời được "vì sao lệnh này bị chặn", không chỉ "bị chặn".
+    """
     score: int           # 0-100
     level: RiskLevel     # categorized bucket
     reasons: List[str]   # why this score was assigned
@@ -65,6 +75,13 @@ _MODERATE_PATTERNS = [
 
 
 def classify_command(command: str, is_cowork_mode: bool = True) -> RiskResult:
+    """Chấm điểm rủi ro một lệnh shell.
+
+    Ba tầng mẫu: ``_BLOCK_PATTERNS`` chặn thẳng (100 điểm, dừng ngay khi
+    khớp mẫu đầu tiên), ``_HIGH_PATTERNS`` và ``_MODERATE_PATTERNS`` cộng
+    dồn điểm. ``is_cowork_mode`` nới tay hơn cho màn Cowork, nơi người dùng
+    đang chủ động ngồi xem từng bước.
+    """
     score = 0
     reasons: List[str] = []
     blocked = False
@@ -114,10 +131,20 @@ def classify_command(command: str, is_cowork_mode: bool = True) -> RiskResult:
 
 
 def classify_prompt(prompt: str, is_cowork_mode: bool = True) -> RiskResult:
+    """Chấm điểm rủi ro một prompt — dùng chung bộ mẫu với lệnh shell.
+
+    Cố ý dùng chung: tấn công tiêm lệnh viết bằng văn xuôi ("ignore previous
+    instructions") và lệnh shell nguy hiểm đều nằm trong cùng danh sách mẫu.
+    """
     return classify_command(prompt, is_cowork_mode=is_cowork_mode)
 
 
 def classify_attachment(path: str, mime_type: Optional[str] = None) -> RiskResult:
+    """Chặn tệp đính kèm chạy được, theo đuôi tệp rồi tới kiểu MIME.
+
+    Chặn theo danh sách đen — mã nguồn và tệp thực thi không được đưa vào
+    ngữ cảnh chat. Tệp ngoài danh sách được coi là an toàn (30 điểm).
+    """
     import os
     _, ext = os.path.splitext(path.lower())
     blocked_ext = {
@@ -141,6 +168,11 @@ def classify_attachment(path: str, mime_type: Optional[str] = None) -> RiskResul
 
 
 def classify_action(action_type: str, action_details: Optional[dict] = None) -> RiskResult:
+    """Chấm điểm rủi ro một loại hành động theo từ khoá trong tên.
+
+    Hành động lạ nhận 50 điểm (mức trung bình) chứ không phải 0 — thứ chưa
+    biết thì không được mặc định là an toàn.
+    """
     a = action_type.lower()
     if any(kw in a for kw in ('execute', 'run', 'shell', 'system')):
         return RiskResult(70, RiskLevel.HIGH, [f"high: action '{action_type}'"])