# HƯỚNG DẪN KẾT NỐI & VẬN HÀNH DEEPSEEK HARNESS (DSH) VỚI DSCONS ERP

## 1. Tổng Quan Kiến Trúc
[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) là Agent Runtime mã nguồn mở chính thức của DeepSeek AI. DSCons tích hợp với `dsh` thông qua chuẩn mở **Model Context Protocol (MCP)** để cung cấp toàn bộ công cụ thực địa cho các mô hình DeepSeek (DeepSeek-R1, DeepSeek-V3, Stealth OX, Qwen Coder).

```
┌─────────────────────────────────────────────────────────────┐
│                 DeepSeek Harness (dsh Web / CLI)            │
│            npx @deepseek-ai/dsh web (Port :3080)            │
└──────────────────────────────┬──────────────────────────────┘
                               │ Model Context Protocol (JSON-RPC stdio)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│            DSCons ERP MCP Server (dscons-erp-mcp)           │
│             app/mcp/dscons_mcp_server.py                    │
└──────┬───────────────────────┼───────────────────────┬──────┘
       │                       │                       │
       ▼                       ▼                       ▼
[Qdrant 2,510 Vectors]   [PostgreSQL 16 Ledger]   [4 Trụ Cột Định Sơn]
(Hồ sơ thiết kế, Luật)  (Thiết bị, Hóa đơn VAT)  (IPC 03a, Xe Howo, OEE)
```

---

## 2. Danh Mục 6 Công Cụ Thực Tế (MCP Tools)
1. **`search_dscons_knowledge`**: Tra cứu tri thức hồ sơ thiết kế và Thư viện Pháp chế Luật Xây dựng 2025.
2. **`query_erp_ledger`**: Truy xuất thiết bị máy móc, nhật ký, tài liệu công trường từ PostgreSQL.
3. **`audit_3way_matching`**: Đối soát 3 bên Hóa đơn VAT - Kho - Hợp đồng mua sắm.
4. **`calculate_ipc_03a`**: Bóc tách BOQ Phụ lục 03a thanh toán giai đoạn (khấu trừ tạm ứng 10%, retention 5%).
5. **`audit_equipment_and_fuel`**: Đối soát xe Howo bùn nạo vét (dầu $24\text{L}/\text{h}$) & ca máy Kobelco (OEE).
6. **`check_fidic_compliance`**: Kiểm toán hợp đồng FIDIC Clause 14.3 & Luật Xây dựng 2025 (Luật 135/2025/QH15).

---

## 3. Khởi Chạy DeepSeek Harness (DSH)
### Bước 1: Khởi chạy DSCons Backend
```bash
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### Bước 2: Khởi chạy DeepSeek Harness Web UI
```bash
npx @deepseek-ai/dsh web
```
Truy cập giao diện tại: `http://127.0.0.1:3080`.

### Bước 3: Cấu hình MCP Server trong DSH
Chỉ định file cấu hình `c:/Projects/DSCons/dsh_config/dsh.config.json` để `dsh` tự động nạp MCP Server `dscons-erp`.

---

## 4. Lịch Phân Ca Làm Việc & Bộ Đệm Chống Spam (Anti-Spam Shield)
Để tránh bị OpenRouter áp đặt giới hạn tần suất (Rate Limit `429 Too Many Requests`) hoặc nghi ngờ spam, hệ thống áp dụng:
1. **Phân ca so le 8 khung giờ (07:30 - 19:30)**:
   - Phúc (07:30 - 09:00): Chạy Local LM Studio Offline (0% chi phí, không giới hạn).
   - Hùng (09:00 - 10:30): Llama 3.3 70B Free (Max 10 RPM).
   - Quỳnh (10:30 - 12:00): Qwen Coder 32B Free (Max 8 RPM).
   - Nam (13:30 - 15:00): Gemini 2.0 Flash Free (Max 15 RPM).
   - Thảo (15:00 - 16:30): DeepSeek R1 Free (Max 6 RPM).
   - Tùng (16:30 - 17:30): Stealth OX-Alpha (Max 8 RPM).
   - Thủy (17:30 - 18:30): Mistral Small 24B Free (Max 10 RPM).
   - Minh (18:30 - 19:30): Stealth OX-Alpha (Max 8 RPM).
2. **Dynamic Request Jitter**: Tự động chèn độ trễ ngẫu nhiên $1.5\text{s} - 3.5\text{s}$ giữa các lệnh gọi API.
3. **Multi-Provider Failover**: Tự động chuyển tải sang Local LM Studio hoặc Google Gemini API Direct khi gặp mã lỗi `429`.