Hermes Review Loop
Thử Nghiệm
Tự Động Hóa Đánh Giá Văn Bản Đa Góc Nhìn

Nâng tầm Markdown với Vòng Lặp Review thông minh.

hermes-review-loop là kỹ năng CLI cục bộ tối ưu hóa tài liệu Markdown qua nhiều vòng lặp. Kết hợp nhiều AI Reviewer chuyên biệt (Rõ ràng, Thực tiễn, Đầy đủ, Kỹ thuật) cùng cơ chế Early-Stop, Resume checkpoint và hỗ trợ cả AI Writer tự động lẫn ChatGPT Fix thủ công.

bash ~ terminal scripts/review_loop.sh
./scripts/review_loop.sh --output Output.md --rounds 3 --target-score 8
4 AI
Reviewer độc lập
Early-Stop
Dừng khi đạt điểm
An Toàn
Backup & Rollback
Compact
Ctags + LLMLingua2
Chu Trình Vòng Lặp Review (Architecture)
round_state.sh
1
Đầu vào Markdown
Kiểm tra hợp lệ & gom context (nếu có --source)
Preflight
2
Batch 4 Reviewer Chấm Điểm
Clarity, Practicality, Completeness, Technical
Score: x/10
3
Kiểm tra Early Stop?
Đạt đủ số reviewer >= TARGET_SCORE
Pass? Dừng
4
Sửa Đổi & Cải Tiến
Writer tự động hoặc ChatGPT Fix Mode thủ công
Fix Flow
5
Validate & Thay File Gốc
Tạo checkpoint backup, sẵn sàng cho round kế
Backup OK
Kết Quả Vận Hành Thực Tế

Báo Cáo Thống Kê Terminal Của Review Loop

Trực quan hóa bảng báo cáo thống kê qua 3 round review thực tế khi chạy lệnh ./scripts/review_loop.sh với chế độ ChatGPT Fix handoff.

⚡ Hermes CLI — Thống kê Review Loop
┌ ⚡ Hermes ──────────────────────────────────────────────────────────────────────────
📊 Thống kê Review Loop
Source: /Users/truongtam/Project/mcp-app (46 files)
Output: /Users/truongtam/Desktop/README.md (9,675 bytes — 274 dòng)
Điểm qua các round
| Round | Clarity | Practicality | Completeness | Technical |
|-------|---------|--------------|--------------|-----------|
| 01    | 8/10 ✓  | 8/10 ✓       | 7/10         | 9/10 ✓    |
| 02    | 7/10    | 7/10         | 8/10 ✓       | 9/10 ✓    |
| 03    | 6/10    | 9/10 ✓       | 10/10 ✓      | 8/10 ✓    |
- 3/3 rounds cần ChatGPT combined-fix handoff (vì không đủ 4/4 reviewer đạt target score)
- Round 01 ✅ applied → Round 02 ✅ applied → Round 03 ⌛ đang chờ fix
- 4 reviewers: clarity (openrouter/free), practicality (deepseek-v4), completeness (openrouter/free), technical (deepseek-v4)
Trạng thái hiện tại
- Round 03 đang in-progress — prompt đã copy vào clipboard
- Output hiện tại là bản đã được fix qua round-01 + round-02
- Source context: 16 files indexed, ~40KB
Bạn paste prompt round-03 lên ChatGPT xong, báo tôi paste để hoàn tất round cuối nhé.
⚡ deepseek-v4-flash-free | 43.8K/1M | [██░░░░░░░░] 4% | 30m | ⏱ 20s | ✓ 0s
HERMES CLI PROMPT
💡

Giải Mã Báo Cáo Thực Tế

Phân tích từ ảnh chụp terminal thực tế
Handoff Thủ Công (3/3 rounds) Chế độ ChatGPT

Vì không có round nào đạt 4/4 reviewer ≥ 8/10 đồng thời, hệ thống không Early Stop mà chuyển prompt sang ChatGPT để người dùng can thiệp sửa đổi.

Tiến Bộ Điểm Số Qua 3 Vòng Cải thiện rõ rệt
  • • Completeness: 7/10 → 8/10 → 10/10 ✓
  • • Practicality: 8/10 → 7/10 → 9/10 ✓
  • • Technical: 9/10 → 9/10 → 8/10 ✓
  • • Clarity: 8/10 → 7/10 → 6/10 (cần tinh gọn lại ở round 3)
Mô Hình & Token Sử Dụng 43.8K / 1M (4%)

Sử dụng kết hợp DeepSeek-v4 và OpenRouter Free tier, xử lý 16 file ngữ cảnh mã nguồn (~40KB) mà chỉ tiêu tốn 4% hạn mức context window.

Chạy mô phỏng vòng lặp tương tự →
Trải Nghiệm Tương Tác Trực Tiếp

Trình Mô Phỏng Hermes Review Loop

Mô phỏng chu trình chấm điểm thực tế của 4 reviewer AI, tính toán Early Stop và kiểm tra phân nhánh sửa đổi.

8/10
Trạng thái vòng lặp: Round 01 Sẵn sàng
Reviewer: Clarity
--/10

Đánh giá tính mạch lạc, cấu trúc câu và diễn đạt súc tích.

Chưa chạy đánh giá.
Reviewer: Practicality
--/10

Khả năng áp dụng thực tế, ví dụ code có thể chạy được.

Chưa chạy đánh giá.
Reviewer: Completeness
--/10

Độ bao phủ các ca biên (edge cases), hướng dẫn chi tiết.

Chưa chạy đánh giá.
Reviewer: Technical
--/10

Độ chính xác đối chiếu source context (file-tree, ctags).

Chưa chạy đánh giá.
Runtime Logger (logs/review_loop.log) 00:00:00
[INFO] Hệ thống khởi tạo. Bấm "Chạy Round Tiếp Theo" để bắt đầu batch review.

Kết quả đánh giá vòng

Số Reviewer Đạt Ngưỡng: 0/4
Trạng thái quyết định
Đang chờ khởi chạy

Vui lòng bấm nút chạy để xem hệ thống ra quyết định dừng sớm (Early Stop) hay phân nhánh sang sửa đổi.

Hành động tiếp theo của hệ thống:
$ scripts/review_loop.sh --idle
Quy Tắc Early Stop

Nếu số reviewer chấm điểm ≥ TARGET_SCORE đạt đủ MIN_TARGET_SCORE_REVIEWS trên cùng một bản output, script sẽ dừng sớm ngay lập tức mà không tốn thêm token cho Writer/ChatGPT.

Kiến Trúc Kỹ Thuật

Luồng Xử Lý Chi Tiết Của Review Loop

Mỗi vòng lặp (round) tuân thủ chặt chẽ nguyên tắc an toàn dữ liệu, tính toàn vẹn markdown và khả năng resume khi bị gián đoạn.

01

Preflight & Context

Xác thực file Markdown đầu vào, kiểm tra awk, cksum và load shell config tin cậy.

  • load_config() từ config.sh
  • validate_markdown.sh
  • Source Scope: file-tree.md
02

Batch Reviewers

Chạy tuần tự các AI reviewer độc lập theo danh sách cấu hình REVIEWER_NAMES.

  • clarity, practicality
  • completeness, technical
  • Lưu reviews/round-XX-*.md
03

Parse Điểm & Early Stop

Trích xuất dòng `Score: x/10` từ review markdown và so khớp ngưỡng pass.

  • Parse: `Score: x/10`
  • Đếm số pass ≥ TARGET_SCORE
  • Pass ≥ MIN_TARGET: Dừng sớm
04

Cải Thiện & Sửa Đổi

Nếu chưa đạt điểm, phân nhánh tùy thuộc vào cấu hình USE_WRITER_MODEL.

  • true: Writer AI tự sửa ngay
  • false: Xuất ChatGPT prompt
  • Dừng chờ paste response
05

Validate & Backup

Kiểm tra hợp lệ văn bản mới, backup bản cũ rồi mới ghi đè file đầu ra.

  • validate_markdown.sh pass
  • Snapshot round-XX.output-start
  • Chuyển sang round tiếp theo

Cơ chế nén ngữ cảnh: Source Scope & Compact Mode

Universal Ctags LLMLingua2 Hybrid

Khi dùng flag --source /path/to/project, script sẽ phân tích toàn bộ cấu trúc dự án. Nếu bật Compact Mode:

1. Đối với README.md (Prose Compression): Phân tích giữ nguyên các đoạn Markdown quan trọng, các đoạn văn bản dài được gửi qua LLMLingua2 để nén token. Nếu tiết kiệm vượt ngưỡng LLMLINGUA2_MIN_SAVINGS sẽ dùng bản hybrid; nếu không giữ nguyên raw.
2. Đối với Code Files (Symbol Outlines): Sử dụng Universal Ctags để chỉ trích xuất chữ ký hàm, class, methods thay vì nhét toàn bộ nội dung code cồng kềnh vào prompt của Technical Reviewer.
Lựa Chọn Chiến Lược

So Sánh 2 Chế Độ Sửa Đổi (Fix Modes)

Tùy theo nhu cầu tự động hóa toàn phần hay muốn can thiệp kiểm duyệt thủ công chất lượng cao qua ChatGPT UI bên ngoài.

USE_WRITER_MODEL=true Tự Động 100%

Writer Model Tự Động

AI Writer model đọc prompt tổng hợp từ reviewer batch, tự sinh văn bản sửa đổi và thay thế file gốc ngay trong cùng phiên chạy CLI.

Không cần can thiệp tay: Vòng lặp chạy liên tục từ Round 1 đến khi đạt TARGET_SCORE.
Tốc độ cao: Phù hợp cho CI/CD pipeline, chạy hàng loạt trong các cronjob.
Chi phí token API: Tốn token gọi writer model trực tiếp qua Hermes Provider.
# Bật cờ CLI:
./scripts/review_loop.sh --use-writer-model
USE_WRITER_MODEL=false Kiểm Soát Thủ Công

ChatGPT Fix Mode (Handoff)

Script tổng hợp toàn bộ nhận xét vào file combined-fix prompt, lưu trạng thái waiting_for_chatgpt_fix và dừng lại để bạn đưa sang ChatGPT bên ngoài.

Tận dụng ChatGPT Plus / Pro: Sử dụng các model cao cấp bên ngoài với zero token cost từ API.
Công cụ trợ giúp chatgpt_helper.sh: Hỗ trợ copy prompt và paste kết quả thẳng vào checkpoint.
An toàn tuyệt đối: Không bao giờ tự ý ghi đè file khi bạn chưa kiểm duyệt kết quả.
# Thao tác với helper:
./scripts/chatgpt_helper.sh copy
./scripts/chatgpt_helper.sh paste

Quy trình 3 bước xử lý ChatGPT Fix Mode với clipboard

Bước 1: Copy Prompt Chạy ./scripts/chatgpt_helper.sh copy để copy combined-fix prompt vào clipboard hệ thống (pbcopy/wl-copy/xclip).
Bước 2: Hỏi ChatGPT Ngoài Dán vào ChatGPT (o1, GPT-4o...), nhận kết quả Markdown đã sửa, rồi sao chép văn bản mới trả về.
Bước 3: Paste & Chạy Tiếp Chạy ./scripts/chatgpt_helper.sh paste. Script ghi file tạm, kiểm tra dòng bắt đầu bằng # rồi áp dụng.
Công Cụ Trực Quan

Bộ Tạo Lệnh CLI & File config.sh

Tùy chỉnh các tham số vòng lặp và nhận ngay câu lệnh Bash cũng như file cấu hình sẵn sàng thực thi.

Tham số cấu hình CLI

8/10
3 vòng
Câu lệnh CLI phát sinh (Bash)
./scripts/review_loop.sh --output Output.md --rounds 3 --target-score 8 --compact
Mẫu tập tin config.sh tương đương 
#!/usr/bin/env bash
# config.sh - Cấu hình đáng tin cậy cho Hermes Review Loop

TARGET_SCORE=8
MAX_ROUNDS=3
MIN_TARGET_SCORE_REVIEWS=3
COMPACT=true
USE_WRITER_MODEL=false

REVIEWER_NAMES=("clarity" "practicality" "completeness" "technical")
Xử Lý Sự Cố Nhanh

Bảng Tra Cứu Lỗi & Cách Khắc Phục

Tra cứu nhanh nguyên nhân và hướng dẫn xử lý cho các thông báo lỗi thường gặp khi chạy Review Loop.

Lỗi / Dấu hiệu nhận biết Nguyên nhân gốc Cách khắc phục đề xuất
hermes: command not found Hermes CLI chưa cài đặt hoặc chưa được đưa vào biến môi trường PATH. Cài đặt Hermes CLI hoặc gán biến: HERMES_BIN=/path/to/hermes
ctags: command not found Thiếu Universal Ctags để trích xuất cấu trúc mã nguồn trong Compact Mode. Cài qua Homebrew: brew install universal-ctags hoặc dùng cờ --no-compact
macOS BSD ctags collision Hệ thống macOS sử dụng mặc định BSD ctags có sẵn thay vì Universal Ctags. Đảm bảo đường dẫn Homebrew ctags đứng trước trong PATH: export PATH="/opt/homebrew/bin:$PATH"
LLMLingua2 is unavailable Module llmlingua2 không tìm thấy trong shell hiện tại. Đây chỉ là tính năng tùy chọn. Script vẫn chạy bình thường với raw README.md. Cài đặt Python package nếu muốn nén hybrid.
Đang chờ ChatGPT Fix (waiting) USE_WRITER_MODEL=false đang chờ người dùng cung cấp bản sửa thủ công. Chạy chatgpt_helper.sh copy, dán sang ChatGPT, copy kết quả rồi chạy chatgpt_helper.sh paste.
Output mới bị reject File Markdown đầu ra không vượt qua script kiểm tra validate_markdown.sh (rỗng, thiếu tiêu đề #). Chạy trực tiếp ./scripts/validate_markdown.sh file.md để xem chi tiết vi phạm cụ thể.
Review quá tốn token / chậm Source context quá lớn hoặc số round / số reviewer cấu hình quá nhiều. Dùng --measure-context trước, giảm bớt reviewer, dùng --rounds 1 hoặc giảm TECH_CONTEXT_MAX_CHARS.
Nên Sử Dụng Hermes Review Loop Khi:
  • ✓ Tài liệu Markdown quan trọng cần kiểm duyệt khắt khe qua nhiều góc nhìn (rõ ràng, thực tiễn, hoàn chỉnh, kỹ thuật).
  • ✓ Cần đối chiếu nội dung bài viết trực tiếp với codebase dự án thật (--source).
  • ✓ Muốn có cơ chế tự động backup snapshot và khả năng resume khi mạng hoặc API bị đứt quãng.
Không Cần Thiết Sử Dụng Khi:
  • × Tài liệu quá ngắn hoặc chỉ là ghi chú cá nhân đơn giản.
  • × Chỉ muốn review một lần tức thì (nên dùng Hermes trực tiếp với prompt đơn).
  • × Không cần đối chiếu code và không cần lưu trạng thái checkpoint.