# Quy Trình Điều Phối Agent & Giám Sát

> **Dành cho Architect** — điều phối tuần tự + giám sát tiến độ dịch thuật (Translator agent)
> Cập nhật: 2026-05-16 | Phiên bản: 1.1
>
> 📌 **Cần điều phối Editor (hiệu đính OCR)?** → Xem [[01A-Dieu-Phoi-Editor-OCR]]

---

## I. NGUYÊN LÝ CỐT LÕI

```
ONE BATCH AT A TIME — Dịch xong batch này, QA đạt, mới chạy batch sau.
```

### Tại sao tuần tự?
- **Tránh race condition** — context-summary của batch N phải hoàn tất mới có ích cho batch N+1
- **Tránh lãng phí token** — nếu batch lỗi, các batch sau dùng context sai → dịch sai hàng loạt
- **Dễ debug** — biết chính xác batch nào lỗi, context nào sai
- **Kiểm soát chất lượng** — mỗi batch qua QA gate trước khi tiếp tục

---

## II. FLOW CHÍNH

```
┌─────────────────────────────────────────────────────────┐
│                    ARCHITECT LOOP                        │
│                                                          │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐           │
│  │ 1.PREP   │───→│ 2.SPAWN  │───→│ 3.YIELD  │           │
│  │ Đọc      │    │ Gọi      │    │ Chờ      │           │
│  │ context  │    │ translator│   │ kết quả  │           │
│  └──────────┘    └──────────┘    └────┬─────┘           │
│                                       │                  │
│                                       ▼                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐           │
│  │ 6.NEXT   │←───│ 5.QA     │←───│ 4.WAKE   │           │
│  │ Lặp lại  │    │ Kiểm tra │    │ Nhận     │           │
│  │ batch sau│    │ chất lg  │    │ completion│          │
│  └──────────┘    └──────────┘    └──────────┘           │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

### Chi tiết từng bước

#### Bước 1: PREP — Chuẩn bị spawn
```
1. Xác định batch tiếp theo (từ danh sách file split)
2. Đọc context-summary của batch TRƯỚC:
   cat {output-dir}/context-summary/{batch-trước}-context-summary.md
3. Soạn prompt spawn (theo mẫu Mục IV)
4. Paste context-summary vào prompt
5. BẮT BUỘC: Gắn lệnh sqlitevec glossary vào prompt (xem mục IV)
```

#### Bước 2: SPAWN — Gọi translator
```javascript
sessions_spawn({
  task: "[prompt đã soạn]",
  mode: "run",
  agentId: "translator",  // BẮT BUỘC: spawn translator agent
  model: [anh Tuấn yêu cầu],
  runTimeoutSeconds: 600,
  cleanup: "delete"
})
```

#### Bước 3: YIELD — Chờ kết quả
```
sessions_yield("Đang chờ translator hoàn tất {batch-name}...")
```
> Không poll, không sleep, không kiểm tra file. Yield và chờ completion event.

#### Bước 4: WAKE — Nhận completion
- Subagent completion tự động đẩy về Architect dưới dạng user message
- Architect kiểm tra: output file + context-summary file đã tồn tại?

#### Bước 5: QA — Kiểm tra chất lượng
Theo checklist Mục VI bên dưới.

#### Bước 6: NEXT — Quyết định
- **QA PASS** → quay lại Bước 1 cho batch tiếp theo
- **QA FAIL** → báo user + đề xuất hành động (retry/spawn lại)

---

## III. CẤU TRÚC FILE QUẢN LÝ TIẾN ĐỘ

### File `progress.json` (đặt trong thư mục output)
```json
{
  "project": "An Duc Tam Bao",
  "total_batches": 87,
  "batches": [
    {
      "name": "Introduction",
      "status": "done",
      "output": "translate-my-vi/Introduction.md",
      "context_summary": "context-summary/Introduction-context-summary.md",
      "completed_at": "2026-05-13T20:39:00+07",
      "qa_passed": true
    },
    {
      "name": "tam-bao-001-005",
      "status": "in_progress",
      "output": "",
      "context_summary": "",
      "spawned_at": "2026-05-13T21:11:00+07",
      "qa_passed": false
    },
    {
      "name": "tam-bao-006-010",
      "status": "pending",
      "output": "",
      "context_summary": "",
      "qa_passed": false
    }
  ]
}
```

### Cập nhật `progress.json`
Sau mỗi batch:
```bash
# Ví dụ cập nhật bằng script Python nhỏ
python3 -c "
import json
with open('progress.json') as f: data = json.load(f)
for b in data['batches']:
    if b['name'] == 'tam-bao-001-005':
        b['status'] = 'done'
        b['completed_at'] = '...'
        b['qa_passed'] = True
        break
with open('progress.json', 'w') as f: json.dump(data, f, indent=2)
"
```

---

## IV. MẪU PROMPT SPAWN (Chuẩn hóa)

```
Dịch song ngữ Myanmar → Việt cho batch: {BATCH-NAME}

## Hướng dẫn
Đọc Guide: ~/workspace/obsidian/Translator-Guide-Myanmar-Vi.md

## 📚 BẮT BUỘC: Tra cứu glossary trước khi dịch
Chạy lệnh này để load toàn bộ thuật ngữ từ SQLite-vec:
python3 -c "
import sqlite3
conn = sqlite3.connect('/home/tuan-nguyen/.openclaw/workspace/data/myanmar_pali_viet_terms_vec.db')
cur = conn.cursor()
cur.execute('SELECT pali, vietnamese, desc_vi, category FROM terms ORDER BY category, id')
for r in cur.fetchall():
    print(f'{r[0]} | {r[1]} | {r[3]}')
"
⚠️ TUYỆT ĐỐI KHÔNG đọc file .md glossary nào.

## Files
- Nguồn: {SOURCE-PATH}
- Output: {OUTPUT-PATH}
- Context-summary output: {OUTPUT-DIR}/context-summary/{BATCH-NAME}-context-summary.md

## Bối cảnh từ batch trước
{PASTE CONTEXT-SUMMARY CỦA BATCH N-1 — HOẶC "Đây là batch đầu tiên, không có bối cảnh trước."}

## Thuật ngữ bổ sung
{THÊM NẾU CÓ — format bảng giống Translator Guide}

⚠️ TUYỆT ĐỐI:
- CHỈ dịch, không thêm tiêu đề, footer, attribution vào output
- Mỗi đoạn: Myanmar gốc → Việt dịch
- Không paraphrase, không bỏ sót
- Ghi context-summary sau khi dịch xong
- KHÔNG đọc file .md glossary — mọi thuật ngữ lấy từ sqlitevec database
```

---

## V. CƠ CHẾ GIÁM SÁT (MONITORING)

### Theo dõi thủ công (Architect)
Sau mỗi completion, Architect tự động:
1. Kiểm tra file output tồn tại?
2. Kiểm tra context-summary tồn tại?
3. Chạy QA checklist
4. Cập nhật `progress.json`

### Theo dõi bán tự động (Healthcheck Cron)
Nếu pipeline dài (>20 batch), tạo cron job giám sát:

```javascript
// Cron: mỗi 30 phút kiểm tra — gửi systemEvent về main session
cron add({
  name: "tam-bao-healthcheck",
  schedule: { kind: "every", everyMs: 1800000 },
  payload: {
    kind: "systemEvent",  // BẮT BUỘC: systemEvent mới dùng được sessionTarget="main"
    text: "🔍 HEALTHCHECK: Kiểm tra tiến độ Tam Bảo. Đọc progress.json → báo cáo batch done/pending/stuck."
  },
  sessionTarget: "main"
})
```

> ⚠️ **Constraint của OpenClaw:**
> - `sessionTarget="main"` → PHẢI dùng `payload.kind="systemEvent"`
> - `sessionTarget="current"|"isolated"|"session:xxx"` → PHẢI dùng `payload.kind="agentTurn"`
> - KHÔNG thể dùng `agentTurn` với `sessionTarget="main"` — sẽ bị reject

**Cách 2: Dùng named session (agentTurn)**
```javascript
cron add({
  schedule: { kind: "every", everyMs: 1800000 },
  payload: {
    kind: "agentTurn",
    message: "Kiểm tra tiến độ Tam Bảo...",
    timeoutSeconds: 120
  },
  sessionTarget: "session:agent:architect:main",  // named session
  delivery: { mode: "announce", channel: "webchat" }
})
```

**Nhiệm vụ của healthcheck:**
1. Đọc `progress.json`
2. Tìm batch `in_progress` quá 30 phút → BÁO ĐỘNG stuck
3. Đếm batch `done` vs `pending` → báo tiến độ
4. Nếu tất cả `done` → báo HOÀN TẤT

> ⚠️ **KHÔNG** để healthcheck tự động re-enable hay spawn — đó là việc của Architect.

### Phát hiện batch stuck
| Triệu chứng | Chẩn đoán | Hành động |
|---|---|---|
| `in_progress` > 30 phút, không có output | Translator treo/timeout | Kill + spawn lại |
| Output tồn tại, không có context-summary | Translator crash giữa chừng | Tạo context-summary thủ công → next |
| Output + context đều có, nhưng format sai | Translator không đọc Guide | Báo user, quyết định retry/sửa tay |
| Output = 0 byte | Translator không ghi được file | Kiểm tra quyền/đường dẫn → retry |

---

## VI. QA CHECKLIST (Mỗi Batch)

### Kiểm tra nhanh (30 giây)
```
□ File output tồn tại? (ls -la)
□ File output > 0 byte?
□ Context-summary tồn tại?
```

### Kiểm tra cấu trúc (2 phút)
```
□ Mỗi đoạn có Myanmar gốc → Việt dịch?
□ Dùng đúng dấu → phân cách?
□ KHÔNG có header/footer/attribution thừa? (grep "^# ")
□ Số đoạn dịch ≈ số đoạn nguồn?
```

### Kiểm tra nội dung (spot-check 3 đoạn)
```
□ Pāḷi giữ đúng dấu macron?
□ Thuật ngữ đúng bảng chuẩn (từ sqlitevec database)?
□ Văn phong trang trọng, không cường điệu?
```

### Kiểm tra glossary (mới)
```
□ Translator đã chạy lệnh sqlitevec chưa? (kiểm tra log)
□ KHÔNG có dấu hiệu đọc file .md glossary?
```

### Kiểm tra context-summary
```
□ ≤ 200 từ?
□ Tóm tắt đúng nội dung batch vừa dịch?
□ Bao gồm cả nội dung từ các batch trước?
```

---

## VII. XỬ LÝ SỰ CỐ

### Batch fail — Làm lại
```
1. Xóa file output cũ (nếu có)
2. Đọc context-summary của batch TRƯỚC batch fail
   → Ví dụ: batch 006-010 fail → đọc context-summary của 001-005
3. Spawn lại translator với context đó
4. QA lại
```

### Context-summary bị thiếu — Tạo thủ công
```
1. Đọc file output của batch đó
2. Viết tóm tắt ≤ 200 từ
3. Lưu vào context-summary/{batch-name}-context-summary.md
```

### Translator liên tục fail — Đổi model
```
Thử model khác: modelstudio/qwen3.6-plus (nếu deepseek fail)
```

---

## VIII. BÀI HỌC TỪ DỰ ÁN TRƯỚC

### ❌ ANTI-PATTERNS (tránh lặp lại)

| Lỗi | Hậu quả | Cách phòng |
|---|---|---|
| **Dùng cron thay vì spawn tuần tự** | Job treo không track được | Dùng `sessions_spawn` + `sessions_yield` |
| **Chạy nhiều batch song song** | Context sai, khó debug | Mỗi lần 1 batch, tuần tự |
| **Không QA batch trước khi chạy tiếp** | Lỗi lan truyền | QA gate bắt buộc |
| **Không có context-summary riêng mỗi batch** | Làm lại batch cũ không có context | Mỗi batch 1 file context-summary riêng |
| **Tự mãn sau batch tốt** | Batch sau kém chất lượng | Checklist QA áp dụng mọi batch |
| **Prompt quá dài** | Translator bị "lost in the middle" | Guide trong file riêng, prompt chỉ truyền tham số |

### ✅ BEST PRACTICES

| Practice | Lý do |
|---|---|
| **Guide tái sử dụng trong obsidian** | Translator đọc 1 lần, dùng nhiều lần |
| **Context-summary ≤ 200 từ** | Vừa đủ context, không làm loãng prompt |
| **Đường dẫn tuyệt đối** | Tránh nhầm thư mục giữa các session |
| **progress.json** | Single source of truth cho tiến độ |
| **sessions_yield thay vì poll** | Không tốn token chờ đợi |

---

## IX. VÍ DỤ HOÀN CHỈNH: DỰ ÁN TAM BẢO

### Trạng thái hiện tại
```
✅ Introduction.md (đã dịch + QA + context-summary)
🔄 tam-bao-001-005.md (đang dịch)
⏳ 85 batch còn lại
```

### Bước tiếp theo (do Architect thực hiện)
```
1. Chờ completion của tam-bao-001-005
2. QA batch 001-005 → PASS
3. Đọc context-summary/tam-bao-001-005-context-summary.md
4. Spawn translator cho tam-bao-006-010
5. Lặp lại đến batch cuối
```

---

## X. CÔNG CỤ HỖ TRỢ

### Script tạo `progress.json` từ danh sách file split
```bash
cd "An Duc Tam Bao/ver-2"
ls split/*.md | sed 's|split/||; s|\.md||' | while read name; do
  echo "{\"name\":\"$name\",\"status\":\"pending\",\"output\":\"\",\"context_summary\":\"\",\"qa_passed\":false}"
done
```

### Script kiểm tra nhanh tiến độ
```bash
cd "An Duc Tam Bao/ver-2/translate-my-vi"
echo "=== ĐÃ DỊCH ===" && ls *.md 2>/dev/null | wc -l
echo "=== CONTEXT-SUMMARIES ===" && ls context-summary/*.md 2>/dev/null | wc -l
echo "=== TỔNG BATCH ===" && ls ../split/*.md | wc -l
```

---

## XI. TỔNG KẾT

```
           ┌──────────────────────────────────┐
           │     ARCHITECT = NHẠC TRƯỞNG      │
           │                                  │
           │  • Điều phối: spawn từng batch   │
           │  • Giám sát: QA + progress.json  │
           │  • Phục hồi: retry khi fail      │
           │  • Báo cáo: cập nhật user        │
           │                                  │
           │  KHÔNG: tự dịch, chạy song song, │
           │  bỏ QA, để pipeline tự chạy      │
           └──────────────────────────────────┘
```

> 📖 **File liên quan:**
> - [[01A-Dieu-Phoi-Editor-OCR]] — Điều phối Editor hiệu đính OCR
> - `Translator-Guide-Myanmar-Vi.md` — Guide cho Translator
> - `Quy-Trinh-Dich-Song-Ngu-Architect-Guide.md` — Guide spawn cơ bản (file này mở rộng)