cowork-local/docs/governance/contributor-recipes.md

Contributor Recipes — Hướng Dẫn Mở Rộng Hệ Thống (EPIC R10-T04)

Tài liệu này cung cấp các công thức chuẩn hóa (Step-by-Step Recipes) giúp các lập trình viên mở rộng tính năng trong hệ thống Cowork Local mà vẫn tuân thủ tuyệt đối Kiến trúc 4 Tầng Sạch (4-Tier Clean Architecture) và các tiêu chuẩn kiểm duyệt CASAN.

---

🍳 Recipe 1: Thêm Một Model Provider Mới (AI Provider)

Khi bạn muốn tích hợp một nhà cung cấp mô hình AI mới (ví dụ: Cohere, Groq, DeepSeek, AWS Bedrock...):

Bước 1: Khai báo định danh trong Domain Layer

Mở file domain/models/provider_descriptor.py:

• Thêm định danh provider vào enum hoặc hằng số.
• Khai báo model mặc định và năng lực hỗ trợ (Streaming, Tool Calling, Vision, Reasoning).

Bước 2: Cài đặt Adapter trong Infrastructure Layer

Tạo file mới tại infrastructure/providers/<provider_name>_provider.py (hoặc mở rộng module hiện có):

• Kế thừa lớp BaseModelProvider hoặc cài đặt interface adapter tương ứng.
• Đảm bảo xử lý streaming qua generator / callbacks.
• Đọc API key từ SecretStore (Keyring), tuyệt đối không lưu hardcoded credentials.

# infrastructure/providers/custom_provider.py
from cowork_local.domain.models.provider_descriptor import ProviderDescriptor

class CustomProviderAdapter:
    """Adapter for Custom AI Provider supporting streaming and tool execution."""
    def __init__(self, api_key: str, base_url: str | None = None) -> None:
        self._api_key = api_key
        self._base_url = base_url

    def stream_chat(self, prompt: str, system_prompt: str = ""):
        # Yield text chunks
        yield "..."

Bước 3: Đăng ký vào Provider Registry

Mở infrastructure/providers/provider_registry.py:

• Đăng ký adapter factory vào registry.

Bước 4: Viết Contract Test

Mở tests/contracts/test_providers.py:

• Thêm test case kiểm tra hợp đồng cho Provider mới bằng FakeProvider hoặc offline contract.

---

🛠️ Recipe 2: Thêm Một Tool Nội Bộ Hoặc Kết Nối MCP Server Mới

Bước 1: Khai báo Tool Descriptor & Quyền Hạn

Mở domain/models/tool_descriptor.py:

• Định nghĩa tên tool, mô tả, JSON Schema tham số.
• Thiết lập cờ Capability: READ_ONLY, GATED, DANGEROUS, v.v.

Bước 2: Cài đặt Tool Executor

• Nếu là Built-in Tool: Cài đặt trong infrastructure/tools/ hoặc tích hợp qua ToolPolicyGateway.
• Nếu là MCP Server: Cấu hình qua infrastructure/mcp/mcp_tool_source_manager.py với stdin/stdout JSON-RPC protocol.

# Example: Adding a safe read-only tool
descriptor = ToolDescriptor(
    name="system_disk_usage",
    description="Inspect available disk space on the local workstation.",
    parameters_schema={
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"],
    },
    capabilities=ToolCapability.READ_ONLY,
)

Bước 3: Viết Unit Test & Kiểm Tra Gate

• Thêm test case vào tests/unit/test_tool_registry_and_policy.py.
• Xác nhận tool tôn trọng cờ an toàn (ToolPolicyGateway) trước khi thực thi.

---

🖥️ Recipe 3: Thêm Một Màn Hình / Tab / Widget Giao Diện Mới

Bước 1: Tạo module dưới presentation/<feature>/

• Tạo thư mục riêng (ví dụ: presentation/analytics/).
• Tách các widget con nhỏ gọn, mỗi file < 400 dòng code (LOC).
• Giao diện kế thừa PySide6.QtWidgets.QWidget và sử dụng CSS token từ cowork_local.theme.

# presentation/analytics/analytics_tab.py
"""Analytics Tab Widget (LOC < 400)."""
from PySide6.QtWidgets import QWidget, QVBoxLayout, QLabel
from cowork_local.state import AppContext
from cowork_local.i18n import tr

class AnalyticsTab(QWidget):
    """Analytics view displaying workspace telemetry."""
    def __init__(self, ctx: AppContext, parent: QWidget | None = None) -> None:
        super().__init__(parent)
        self.ctx = ctx
        self._setup_ui()

    def _setup_ui(self) -> None:
        layout = QVBoxLayout(self)
        self.title = QLabel(tr("analytics.title") if tr("analytics.title") != "analytics.title" else "Analytics Dashboard")
        layout.addWidget(self.title)

Bước 2: Nối Dữ Liệu Qua Tầng Application Service

• QUY TẮC CỐT TỬ: Widget giao diện CHỈ ĐƯỢC gọi xuống các Service của tầng application/ (ví dụ: TaskApplicationService, DashboardQueryService, ConversationApplicationService).
• Tuyệt đối không query trực tiếp SQLite/JSON hoặc thực thi AI logic trực tiếp trong GUI thread.

Bước 3: Đăng Ký Vào Shell Navigation

• Mở presentation/shell/page_registry.py và thêm trang mới vào danh sách menu điều hướng (NavRail).

Bước 4: Viết Integration Test Cho Widget

• Tạo file test dưới tests/integration/ hoặc tests/ui/.
• Đảm bảo test chạy được ở chế độ headless (QT_QPA_PLATFORM=offscreen).

---

🛡️ Kiểm Duyệt Chất Lượng Trước Khi Gửi PR (Checklist CASAN)

Trước khi commit và tạo Pull Request, chạy lệnh kiểm tra tổng thể:

python scripts/run_quality_gate.py

Nếu toàn bộ 4 cổng báo [PASS] thì mã nguồn của bạn đã sẵn sàng được merge vào nhánh chính!