Fatih Kadir Akın

---
name: log-error-pattern-triage
description: Phân loại các tệp nhật ký (log) ứng dụng, máy chủ và truy cập lớn hoặc hỗn độn - gom nhóm hàng nghìn dòng log thành một danh sách xếp hạng các mẫu lỗi kèm số lượng, thời điểm thấy đầu tiên và cuối cùng, các đợt tăng đột biến (spikes) và các mẫu mới xuất hiện so với bản log cơ sở (baseline) lúc hệ thống ổn định, sau đó tách biệt nguyên nhân gốc rễ khỏi các triệu chứng dây chuyền phía sau và viết báo cáo phân loại sự cố ngắn gọn kèm các bước kiểm tra tiếp theo. Sử dụng khi người dùng dán hoặc tải tệp log lên, hỏi "có chuyện gì đang xảy ra trong các log này?", "tại sao lỗi lại tăng vọt lúc 10:09?" hoặc cần bản tóm tắt sự cố sơ bộ.
---

# Phân Loại Và Chẩn Đoán Mẫu Lỗi Trong Nhật Ký Hệ Thống (Log)

Bạn biến một "bức tường" dày đặc các dòng log thành một danh sách vấn đề ngắn gọn, có xếp hạng ưu tiên cùng bước hành động tiếp theo rõ ràng. Bạn không bao giờ dán trả lại toàn bộ tệp log; bạn đếm, gom nhóm, so sánh và giải thích.

## Các tệp trong kỹ năng này

- `scripts/cluster_logs.py` - gom nhóm các bản ghi log thành những mẫu đã che biến số (masked patterns), xếp hạng chúng, phát hiện các đợt tăng đột biến (spikes) và đánh dấu các mẫu MỚI (`NEW`) so với tệp log cơ sở (chỉ dùng thư viện chuẩn Python 3)
- `references/log-normalization.md` - cách chuyển các dòng log thành mẫu chuẩn, những thành phần nào được che bằng placeholder và cách xử lý các định dạng mà kịch bản chưa nhận diện được
- `references/triage-heuristics.md` - phương pháp xếp hạng các mẫu lỗi, phân biệt nguyên nhân gốc rễ với triệu chứng và quyết định cần kiểm tra gì tiếp theo
- `templates/triage-report.md` - định dạng báo cáo phân loại sự cố
- `examples/example-checkout-incident.md` - bài giải mẫu phân loại một sự cố tăng đột biến lỗi quá thời gian chờ (timeout) khi thanh toán

## Quy trình thực hiện

### 1. Lấy đúng lát cắt dữ liệu log cần thiết
Hỏi (hoặc xác nhận) tên dịch vụ, khoảng thời gian xung quanh lúc xảy ra sự cố kèm theo múi giờ, và nếu có thể thì lấy thêm một tệp log từ khoảng thời gian hệ thống hoạt động ổn định có cùng độ dài để làm mốc cơ sở (baseline). Nếu tệp log quá khổng lồ, hãy chỉ làm việc trên khoảng thời gian quan trọng; một lát cắt 15 phút xoay quanh sự cố thường là đủ.

Loại bỏ các thông tin bí mật trước khi chia sẻ: mã thông báo (tokens), mật khẩu, cookie phiên làm việc và dữ liệu cá nhân. Nếu bạn thấy bất kỳ thông tin nhạy cảm nào trong dữ liệu đầu vào, hãy cảnh báo cho người dùng biết và tuyệt đối không lặp lại chúng.

### 2. Chạy công cụ gom nhóm log
```bash
python3 scripts/cluster_logs.py app.log
python3 scripts/cluster_logs.py app.log --baseline yesterday.log --top 20
python3 scripts/cluster_logs.py access.log --min-level INFO
kubectl logs deploy/api --since=30m | python3 scripts/cluster_logs.py - --json
```
Công cụ sẽ in ra mỗi dòng một mẫu lỗi kèm theo mức độ (level), số lần xuất hiện (count), tỷ trọng (share), thời điểm xuất hiện đầu tiên và cuối cùng, các nhãn cờ (`NEW` = không có trong bản baseline, `SPIKE` = có một phút tăng vọt ít nhất gấp 3 lần tốc độ thông thường), theo sau là một dòng log mẫu thực tế và dòng cuối cùng của dấu vết ngăn xếp (stack trace) cho mỗi mẫu. Mã thoát (exit code) 1 nghĩa là tìm thấy ít nhất một mẫu lỗi ở mức ERROR hoặc FATAL.

Nếu không thể chạy kịch bản, hãy gom nhóm các dòng log thủ công bằng các quy tắc che biến số trong `references/log-normalization.md` và nêu rõ rằng số liệu đếm chỉ mang tính xấp xỉ.

### 3. Phân loại và chẩn đoán (Triage)
Áp dụng `references/triage-heuristics.md`:
1. Sắp xếp các mẫu theo mức độ tác động: ưu tiên FATAL và NEW+SPIKE lên đầu, sau đó xét theo số lượng, rồi đến mức độ ảnh hưởng trực tiếp tới người dùng cuối.
2. Dựng một dòng thời gian (timeline) ngắn gọn từ thời điểm xuất hiện đầu tiên của các mẫu. Mẫu lỗi mới xuất hiện sớm nhất trong một đợt bùng phát thường nằm gần nguyên nhân gốc rễ hơn; các mẫu bắt đầu xuất hiện sau đó vài giây thường là triệu chứng hệ quả.
3. Tách biệt rõ các ứng viên nguyên nhân gốc rễ, các triệu chứng và nhiễu nền (background noise) vốn đã tồn tại sẵn trong bản baseline.
4. Đối với mỗi ứng viên nguyên nhân gốc rễ, hãy chỉ rõ bằng chứng và bước kiểm tra tiếp theo ít tốn công sức nhất (bảng điều khiển giám sát, trang trạng thái của dịch vụ phụ thuộc, bản so sánh thay đổi cấu hình, nhật ký triển khai bản mới hoặc một truy vấn cụ thể).

### 4. Báo cáo kết quả
Điền thông tin vào `templates/triage-report.md`, tương tự như trong `examples/example-checkout-incident.md`. Giữ phần tóm tắt gọn trong ba câu để một người quản lý có thể đọc hiểu ngay.

## Quy tắc
- Trích dẫn các dòng log mẫu có thật; tuyệt đối không tự bịa ra dòng log, số lần xuất hiện hay mốc thời gian.
- Nêu rõ múi giờ của tệp log và giữ nhất quán xuyên suốt báo cáo.
- Không khẳng định chắc chắn 100% nguyên nhân gốc rễ nếu chỉ dựa vào log; hãy dùng cụm từ "có khả năng cao nhất" (most likely) và liệt kê những gì cần kiểm tra để xác nhận nó.
- Đánh giá nhiễu nền một cách trung thực: nếu một mẫu lỗi cũng xuất hiện trong bản baseline với tần suất tương tự thì đó không phải là nguyên nhân của sự cố lần này.
- Tuyệt đối không bao giờ đề xuất xóa log hoặc tắt chức năng ghi log để làm cho lỗi biến mất.
FILE:references/log-normalization.md
# Chuẩn hóa nhật ký: từ các dòng log riêng lẻ đến các mẫu lỗi (patterns)

Cơ chế gom nhóm hoạt động bằng cách biến mỗi thông điệp log thành một khuôn mẫu (template): những từ cố định được giữ nguyên, còn các phần biến thiên sẽ được thay thế bằng ký hiệu giữ chỗ (placeholder). Hai dòng log có cùng khuôn mẫu chính là cùng một vấn đề đang lặp lại nhiều lần.

## Những thành phần được kịch bản che đi (mask)

| Thành phần biến thiên | Ví dụ | Ký hiệu giữ chỗ (Placeholder) |
| --- | --- | --- |
| UUID | `0288ddd8-5e8c-45f9-a0e7-486d8fa66b03` | `<uuid>` |
| Địa chỉ email | `li@example.com` | `<email>` |
| Địa chỉ IPv4 có kèm cổng (tùy chọn) | `192.0.2.44:5432` | `<ip>` |
| Giá trị thập lục phân (hex) và mã hex dài | `0x7f3a`, `9f1c2e7a4b3d` | `<hex>` |
| Chuỗi truy vấn URL (query string) | `?page=2&sort=price` | `?<query>` |
| Giá trị nằm trong dấu ngoặc kép/đơn | `'cart:42'`, `"Bob"` | `<str>` |
| Con số có kèm đơn vị (tùy chọn) | `5000ms`, `89%`, `17` | `<n>` |
| Mã định danh trong ngoặc vuông có chứa chữ số | `[http-nio-8080-exec-9]`, `[req-ab12]` | `[<id>]` |

Dấu thời gian (timestamps) và mức độ nghiêm trọng (levels) được phân tích trước tiên và tách ra khỏi nội dung thông điệp. Đối với các dòng syslog, tên máy chủ (hostname) được lược bỏ để cùng một sự cố xảy ra trên `web-01` và `web-02` được gom chung vào một nhóm. Đối với nhật ký truy cập (access logs), khuôn mẫu sẽ có dạng `METHOD /path -> HTTPstatus`, trong đó các phân đoạn đường dẫn dạng số được che đi để `/api/orders/123` và `/api/orders/456` gom chung thành một mẫu.

## Các định dạng được hỗ trợ

- Các dòng văn bản thuần có dấu thời gian chuẩn ISO-8601: `2026-10-09T10:09:00.123Z ERROR [thread] logger - message`
- Syslog: `Oct  9 03:12:44 web-02 kernel: message`
- Nhật ký truy cập kết hợp (combined access logs) của Nginx và Apache: `... [09/Oct/2026:09:58:02 +0300] "POST /api/checkout HTTP/1.1" 502 ...`
- Các dòng JSON có trường `level` hoặc `severity`, `msg` hoặc `message`, `time` hoặc `timestamp`, và trường tùy chọn `error`

## Các bản ghi kéo dài nhiều dòng (Multi-line entries)

Dấu vết ngăn xếp (stack traces) thuộc về dòng log ngay phía trên chúng. Kịch bản sẽ tự động ghép nối các dòng thụt lề, `Traceback (most recent call last)`, `Caused by:`, các khung gọi hàm Java dạng `at ...(File.java:12)`, `... 12 more`, và các dòng ngoại lệ đứng riêng lẻ như `java.net.SocketTimeoutException: Read timed out`. Dòng được ghép nối cuối cùng sẽ hiển thị tại mục "trace ends" vì nó thường chỉ ra khung gọi hàm sâu nhất hoặc ngoại lệ thực sự gây lỗi.

## Mức độ nghiêm trọng (Levels)

Các nhãn mức độ ghi tường minh sẽ được ưu tiên (`TRACE/DEBUG`, `INFO/NOTICE`, `WARN/WARNING`, `ERROR/ERR/SEVERE`, `CRITICAL/FATAL/PANIC`). Một dòng không có nhãn mức độ sẽ được phân loại dựa theo từ ngữ bên trong: các từ chỉ sự thất bại (failed, out of memory, timed out, refused, denied, killed) được tính là ERROR, còn các từ chỉ việc thử lại hoặc ngừng hỗ trợ (retry, deprecation) được tính là WARN. Mã trạng thái HTTP 5xx trong access log được tính là ERROR, còn mã 4xx ngoài 404 được tính là WARN.

## Khi việc gom nhóm gặp sai lệch

- **Quá nhiều mẫu nhỏ lẻ**: có một từ biến thiên chưa được che đi (tên người dùng, tên máy chủ nằm ngay trong câu thông báo, tên tệp tin). Hãy nêu rõ điều đó và tự gom nhóm các dòng đó lại trong báo cáo, ví dụ: "2 mẫu: tấn công vét cạn SSH từ 2 địa chỉ IP với các tên người dùng khác nhau".
- **Một mẫu khổng lồ che khuất hai vấn đề khác nhau**: thông điệp quá chung chung ("request failed"). Hãy xem xét các dòng mẫu cụ thể và phần đuôi stack trace, hoặc chạy lại trên một khung thời gian hẹp hơn.
- **Định dạng lạ chưa nhận diện được**: nếu hầu hết các bản ghi đều báo không có dấu thời gian, hãy chuyển đổi định dạng tệp log trước (ví dụ dùng `jq -c` cho JSON lồng nhau) hoặc mô tả định dạng và gom nhóm thủ công.
- **Các dòng bị cắt ngắn**: khuôn mẫu được cắt ở mức tối đa 160 ký tự; dòng mẫu thực tế cắt ở mức 200 ký tự.
FILE:references/triage-heuristics.md
# Kinh nghiệm chẩn đoán và phân loại sự cố (Triage heuristics)

## Xếp hạng mẫu lỗi theo mức độ tác động, không chỉ theo số lượng

1. **Các mẫu FATAL hoặc sập tiến trình (crash)** (tiến trình tự thoát, tràn bộ nhớ - out of memory, panic): chỉ cần xuất hiện một lần cũng đã rất nghiêm trọng.
2. **Đi kèm cả hai nhãn NEW và SPIKE**: có thứ gì đó vừa thay đổi. Đây thường chính là tâm điểm của sự cố.
3. **Lỗi ảnh hưởng trực tiếp tới người dùng** (lỗi 5xx trên các endpoint phục vụ khách hàng, thanh toán thất bại, đăng nhập thất bại) được ưu tiên hơn các lỗi nội bộ (trượt bộ nhớ đệm - cache misses, các lần thử lại mà sau đó đã thành công).
4. **Số lần xuất hiện và tỷ trọng**: trong cùng một cấp độ ưu tiên, mẫu nào nhiều hơn sẽ xếp trước.
5. **Nhiễu nền xếp cuối cùng**: các mẫu vốn đã xuất hiện trong bản baseline với tần suất tương đương là nhiễu nền của hệ thống, không phải sự cố hiện tại.

## Nguyên nhân gốc rễ hay triệu chứng?

| Manh mối | Nghiêng về nguyên nhân gốc rễ | Nghiêng về triệu chứng hệ quả |
| --- | --- | --- |
| Thời điểm | mẫu lỗi mới xuất hiện đầu tiên trong đợt bùng phát | bắt đầu xuất hiện vài giây sau một mẫu lỗi khác |
| Vị trí phát sinh | chỉ đích danh một dịch vụ phụ thuộc, cấu hình, giới hạn tài nguyên hoặc đợt triển khai (deploy) | lớp bọc thông báo chung chung ("request failed", "checkout failed") |
| Dấu vết ngăn xếp (Stack trace) | khung gọi hàm sâu nhất nằm ở thư viện client hoặc lời gọi tài nguyên | dấu vết kết thúc ngay trong mã controller của bạn sau khi gọi sang một thành phần khác |
| Tỷ lệ số lượng | số lần xuất hiện khớp với số lệnh gọi dịch vụ đầu nguồn bị thất bại | số lần xuất hiện bằng tổng của một vài mẫu lỗi khác cộng lại |
| So với bản cơ sở (Baseline) | hoàn toàn không có trước đó | đã xuất hiện từ trước nhưng ở tần suất thấp hơn |

Một chuỗi sự cố điển hình: quá thời gian chờ dịch vụ phụ thuộc (nguyên nhân) -> bộ xử lý yêu cầu thất bại (triệu chứng) -> cơ chế tự thử lại làm tăng tải (yếu tố khuếch đại) -> bão hòa vùng chứa kết nối - connection pool (triệu chứng thứ cấp).

## Nguyên nhân điển hình đằng sau các mẫu lỗi phổ biến

- **Quá thời gian chờ (Timeouts) tới một dịch vụ phụ thuộc**: dịch vụ phụ thuộc bị sập hoặc phản hồi chậm, thay đổi về mạng, cấu hình ngưỡng timeout quá thấp sau khi deploy, hoặc cạn kiệt vùng chứa kết nối (connection pool) ở phía bên gọi.
- **Connection pool chạm ngưỡng hoặc gần 100 phần trăm**: các truy vấn chậm hoặc lời gọi dịch vụ hạ nguồn (downstream) chậm làm giữ kết nối quá lâu, rò rỉ kết nối (leak), hoặc lưu lượng truy cập tăng đột biến.
- **Tràn bộ nhớ (Out of memory) và tiến trình bị buộc dừng (killed)**: dữ liệu đầu vào quá lớn, rò rỉ bộ nhớ, giới hạn container bị hạ thấp, hoặc chạy quá nhiều tiến trình worker trên cùng một máy chủ.
- **Từ chối quyền truy cập (Permission denied) / hệ thống tệp chỉ đọc (read-only file system)**: bản deploy làm thay đổi người dùng chạy tiến trình hoặc điểm gắn kết ổ đĩa (volume mount), đầy ổ cứng, hoặc khóa bí mật (secrets) vừa được xoay vòng.
- **Lỗi 429 hoặc bị giới hạn tần suất (throttling)**: một trình khách (client) hoặc tác vụ ngầm đang gọi dồn dập vào một endpoint, hoặc do chính cơn bão thử lại (retry storm) từ hệ thống của bạn.
- **Lỗi SMTP hoặc gửi email thất bại**: thường do chạm giới hạn tần suất hoặc sự cố từ nhà cung cấp dịch vụ email; hiếm khi là sự cố chính trừ khi sản phẩm cốt lõi của bạn là dịch vụ gửi email.

## Các bước kiểm tra tiếp theo ít tốn kém nhất

- Các đợt triển khai (deploys) và thay đổi cấu hình trong vòng 30 phút trước khi xuất hiện mẫu lỗi mới đầu tiên.
- Trang thông báo trạng thái của dịch vụ phụ thuộc cùng bảng điều khiển theo dõi độ trễ và tỷ lệ lỗi của dịch vụ đó.
- Các chỉ số hạ tầng máy chủ ngay tại phút xảy ra đột biến: CPU, bộ nhớ, ổ đĩa, số lượng kết nối đang mở.
- Truy vết trọn vẹn một yêu cầu mẫu từ đầu đến cuối (dựa theo trace id hoặc request id).
- Xem mẫu lỗi đó có tự động biến mất hay không, và điều gì đã thay đổi ngay tại thời điểm đó.

## Cách dùng từ trong báo cáo

- Dùng cụm từ "Nguyên nhân có khả năng cao nhất" (Most likely cause) khi dữ liệu log cộng với trình tự thời gian cùng chỉ về một hướng nhưng chưa có bằng chứng độc lập nào xác nhận.
- Chỉ dùng từ "Đã xác nhận" (Confirmed) khi có bằng chứng độc lập (thông báo sự cố từ nhà cung cấp, hoàn tác bản cập nhật - rollback giúp hết lỗi, hoặc có số liệu đo lường chứng minh).
- Đưa ra con số cụ thể: "30 lỗi quá thời gian chờ thanh toán trong 2 phút, so với 0 lần trong bản baseline".
FILE:templates/triage-report.md
# Báo Cáo Phân Loại Sự Cố Qua Log: <service> <date>

**Khung thời gian:** <start> đến <end> (<time zone>) | **Số bản ghi đã đọc:** <n> | **Từ mức WARN trở lên:** <n> bản ghi thuộc <n> mẫu
**Bản cơ sở (Baseline):** <tệp và khung thời gian, hoặc "none">

## Tóm tắt (3 câu)
<Chuyện gì đã xảy ra, ảnh hưởng tới ai, từ lúc nào và nguyên nhân có khả năng cao nhất là gì, diễn đạt bằng ngôn ngữ dễ hiểu.>

## Bảng xếp hạng các mẫu lỗi

| # | Mức độ | Số lượng | Nhãn cờ | Mẫu lỗi (rút gọn) | Vai trò |
| --- | --- | --- | --- | --- | --- |
| 1 | ERROR | <n> | NEW, SPIKE | <pattern> | ứng viên nguyên nhân gốc rễ / triệu chứng / nhiễu nền |

## Dòng thời gian (Timeline)
- <hh:mm:ss> <mẫu lỗi mới đầu tiên>
- <hh:mm:ss> <sự kiện tiếp theo>
- <hh:mm:ss> <thời điểm phục hồi, hoặc "vẫn đang tiếp diễn ở cuối tệp log">

## Các ứng viên nguyên nhân gốc rễ
1. **<candidate>** - bằng chứng: <dòng log mẫu, số lượng, thời điểm>. Độ tin cậy: <thấp/trung bình/cao>.
   Bước kiểm tra tiếp theo: <một bước kiểm tra cụ thể>.

## Triệu chứng và tác động dây chuyền
- <pattern> gây ra bởi <candidate> vì <lý do>.

## Nhiễu nền (cũng xuất hiện trong bản baseline)
- <pattern> ở tần suất <rate> lần mỗi phút, tương đương với bản baseline.

## Các bước tiếp theo được khuyến nghị
1. <biện pháp giảm thiểu tức thời, nếu có>
2. <bước kiểm tra giúp xác nhận hoặc loại trừ ứng viên chính>
3. <công việc tiếp nối: cải thiện cảnh báo, ngưỡng timeout, cơ chế thử lại hoặc cách ghi log>

## Khoảng trống thông tin
- <các log còn thiếu, chưa rõ múi giờ, các dòng không thể phân tích cú pháp>
FILE:examples/example-checkout-incident.md
# Ví dụ: sự cố tăng đột biến lỗi quá thời gian chờ khi thanh toán đơn hàng

**Người dùng:** Lỗi thanh toán (checkout) tăng vọt vào khoảng 10:09 sáng nay (giờ UTC). Đây là lát cắt 15 phút từ tệp log API và tệp log của ngày hôm qua trong cùng khung giờ đó. Đã có chuyện gì xảy ra?

**Lệnh chạy:**
```bash
python3 scripts/cluster_logs.py app.log --baseline baseline.log
```

**Kết quả đầu ra của kịch bản (đã rút gọn):**
```
Read 138 entries (0 without a timestamp); 60 at WARN or above in 5 patterns.
Time range: 10-09 10:00:00 -> 10-09 10:14:48

 #  LEVEL COUNT  SHARE  FIRST          LAST           FLAGS      TEMPLATE
 1  ERROR    30  50.0%  10-09 10:09:00 10-09 10:10:56 NEW,SPIKE  [<id>] c.s.payments.PaymentClient - payment authorization timed out after <n> for order <n> (provider=psp-eu, attempt=<n>)
 2  ERROR    10  16.7%  10-09 10:09:00 10-09 10:10:48 NEW,SPIKE  [<id>] c.s.checkout.OrderController - checkout failed for session <uuid>
 3  ERROR     3   5.0%  10-09 10:03:30 10-09 10:12:30 -          [<id>] c.s.mail.ReceiptMailer - failed to send receipt to <email>: SMTP <n> try again later
 4  WARN     14  23.3%  10-09 10:00:42 10-09 10:14:42 -          [<id>] c.s.cache.RedisCache - cache miss for key <str> took <n>
 5  WARN      3   5.0%  10-09 10:02:45 10-09 10:11:45 -          [<id>] c.s.db.Hikari - connection pool at <n> (<n>/<n> active)

Details:
 2. ... trace ends: at com.shop.checkout.OrderController.submit(OrderController.java:77)
    spike: 5/min at 10:09 (median 0/min)
```

---

# Báo Cáo Phân Loại Sự Cố Qua Log: checkout API 2026-10-09

**Khung thời gian:** 10:00:00 đến 10:14:48 (UTC) | **Số bản ghi đã đọc:** 138 | **Từ mức WARN trở lên:** 60 bản ghi thuộc 5 mẫu
**Bản cơ sở (Baseline):** baseline.log, 2026-10-08 10:00 đến 10:10 UTC

## Tóm tắt (3 câu)
Từ 10:09:00 đến khoảng 10:11 UTC, các giao dịch thanh toán thẻ bị quá thời gian chờ (timeout) tại nhà cung cấp dịch vụ thanh toán psp-eu khiến khách hàng gặp lỗi thanh toán đơn hàng thất bại. Các lỗi quá thời gian chờ thanh toán này mới hoàn toàn so với ngày hôm qua và đạt đỉnh ở mức 15 lỗi mỗi phút, đồng thời mọi giao dịch checkout thất bại đều mang theo lỗi quá thời gian chờ đọc socket (socket read timeout) từ trình khách thanh toán. Nguyên nhân có khả năng cao nhất là do hệ thống của psp-eu bị chậm hoặc gặp sự cố gián đoạn; không có dấu hiệu nào trong tệp log này chỉ ra lỗi thuộc về mã nguồn hay cơ sở dữ liệu của chúng ta.

## Bảng xếp hạng các mẫu lỗi

| # | Mức độ | Số lượng | Nhãn cờ | Mẫu lỗi (rút gọn) | Vai trò |
| --- | --- | --- | --- | --- | --- |
| 1 | ERROR | 30 | NEW, SPIKE | payment authorization timed out after 5000ms (provider=psp-eu) | ứng viên nguyên nhân gốc rễ |
| 2 | ERROR | 10 | NEW, SPIKE | checkout failed for session ... (SocketTimeoutException) | triệu chứng của mẫu 1 |
| 3 | ERROR | 3 | - | failed to send receipt ... SMTP 421 | nhiễu nền (cũng có trong baseline) |
| 4 | WARN | 14 | - | cache miss for key 'cart:...' | nhiễu nền (cũng có trong baseline) |
| 5 | WARN | 3 | - | connection pool at 85 to 97 percent | cần theo dõi (cũng có trong baseline) |

## Dòng thời gian (Timeline)
- 10:09:00 xuất hiện lỗi quá thời gian chờ cấp phép thanh toán đầu tiên và lỗi checkout thất bại đầu tiên, trong cùng một giây
- 10:09 phút đạt đỉnh: 15 lỗi timeout mỗi phút
- 10:10:56 lỗi timeout thanh toán cuối cùng; không còn lỗi thanh toán nào nữa cho đến cuối tệp log lúc 10:14:48

## Các ứng viên nguyên nhân gốc rễ
1. **Nhà cung cấp thanh toán psp-eu phản hồi chậm hoặc không khả dụng** - bằng chứng: 30 lần quá thời gian chờ sau đúng 5000 ms, tất cả đều thuộc về provider=psp-eu, không có lần nào trong bản baseline; các dấu vết ngăn xếp đều kết thúc tại `PaymentClient.authorize`. Độ tin cậy: trung bình.
   Bước kiểm tra tiếp theo: kiểm tra trang trạng thái của psp-eu và bảng điều khiển độ trễ kết nối gọi ra ngoài của chúng ta trong khoảng 10:08 đến 10:12 UTC.

## Triệu chứng và tác động dây chuyền
- Lỗi "checkout failed for session" gây ra bởi ứng viên 1: bắt đầu cùng một giây, và dấu vết ngăn xếp của nó kết thúc tại `PaymentClient.authorize` thông qua `OrderController.submit`.
- Các lần tự thử lại (attempt=2 và 3 trong các dòng mẫu) có thể đã làm tăng thêm tải trong suốt đợt tăng đột biến.

## Nhiễu nền (cũng xuất hiện trong bản baseline)
- Lỗi gửi biên lai SMTP 421 (3 lần trong 15 phút) và các cảnh báo trượt cache (cache misses) cũng xuất hiện vào ngày hôm qua với tần suất tương đương.
- Các cảnh báo vùng chứa kết nối (connection pool) ở mức 85 đến 97 phần trăm cũng xuất hiện vào ngày hôm qua; đây không phải nguyên nhân sự cố lần này nhưng đã khá sát ngưỡng giới hạn.

## Các bước tiếp theo được khuyến nghị
1. Xác nhận với trang thông báo trạng thái của nhà cung cấp; nếu đúng là sự cố từ phía họ thì không cần hoàn tác bản cập nhật (rollback).
2. Đếm số đơn hàng bị thất bại trong khoảng từ 10:09 đến 10:11 và quyết định xem có nên gửi email hỗ trợ những khách hàng đó hay không.
3. Công việc tiếp nối: thiết lập cảnh báo khi lỗi timeout thanh toán vượt quá 5 lần mỗi phút, giới hạn số lần thử lại kèm thời gian chờ tăng dần (backoff) và kiểm tra lại dung lượng dự phòng của vùng chứa kết nối.

## Khoảng trống thông tin
- Không có log hoặc số liệu đo lường từ phía nhà cung cấp thanh toán; ngưỡng cắt timeout cứng ở mức 5000 ms đã che khuất mất việc nhà cung cấp thực sự bị chậm tới mức nào.
FILE:scripts/cluster_logs.py
#!/usr/bin/env python3
"""Group log lines into error patterns (templates) and rank them for triage.

Usage:
  python3 cluster_logs.py app.log [more.log ...] [options]
  cat app.log | python3 cluster_logs.py - [options]

Options:
  --min-level LEVEL   lowest level to include: DEBUG, INFO, WARN, ERROR (default WARN)
  --top N             show the N largest patterns (default 15)
  --baseline FILE     log from a known-good period; patterns not seen there are marked NEW
  --json              print machine-readable JSON instead of a table

Understands plain lines with an ISO-8601, syslog ("Oct 09 10:01:02") or
nginx ("[09/Oct/2026:10:01:02 +0300]") timestamp, and JSON lines with
level/msg/message/time/timestamp keys, and web server access logs (method,
path and status are kept; 5xx counts as ERROR, 4xx other than 404 as WARN).
Indented lines, "Traceback", "at ...", "Caused by" and bare
"pkg.SomeException: ..." lines are attached to the entry above them.
Lines without an explicit level are rated by wording ("failed", "out of
memory", "timed out" -> ERROR; "retrying", "deprecated" -> WARN).
Variable parts (UUIDs, hex ids, IPs, emails, numbers, quoted values, URL
query strings) are masked so repeats of the same problem group together.
Exit code: 0 no ERROR-level patterns, 1 ERROR or worse found, 2 usage/input error.
Standard library only.
"""
import json
import re
import statistics
import sys
from collections import OrderedDict
from datetime import datetime

LEVELS = {"TRACE": 0, "DEBUG": 0, "INFO": 1, "NOTICE": 1, "WARN": 2, "WARNING": 2,
          "ERROR": 3, "ERR": 3, "SEVERE": 3, "CRITICAL": 4, "CRIT": 4, "FATAL": 4, "PANIC": 4, "ALERT": 4, "EMERG": 4}
CANON = {0: "DEBUG", 1: "INFO", 2: "WARN", 3: "ERROR", 4: "FATAL"}
MONTHS = {m: i for i, m in enumerate(["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], 1)}

TS_ISO = re.compile(r"(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(?:[.,]\d+)?(?:Z|[+-]\d{2}:?\d{2})?")
TS_SYSLOG = re.compile(r"\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+(\d{1,2}) (\d{2}:\d{2}:\d{2})")
TS_NGINX = re.compile(r"\[(\d{2})/(\w{3})/(\d{4}):(\d{2}:\d{2}:\d{2})[^\]]*\]")
LEVEL_RE = re.compile(r"(?<![\w-])(TRACE|DEBUG|INFO|NOTICE|WARNING|WARN|ERROR|ERR|SEVERE|CRITICAL|CRIT|FATAL|PANIC)(?![\w-])", re.I)
ERROR_HINT = re.compile(r"\b(out of memory|oom-?kill\w*|killed process|segfault|panic|fatal|failed|failure|"
                        r"exception|refused|timed out|timeout|denied|unreachable|code=killed)\b", re.I)
WARN_HINT = re.compile(r"\b(deprecated|retrying|retry|slow|degraded|throttl\w*)\b", re.I)
ACCESS_RE = re.compile(r'"(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) (\S+) HTTP/[\d.]+" (\d{3}) ')
CONT_RE = re.compile(r"^(\s+\S|Traceback \(most recent call last\)|Caused by:|\s*at [\w$.<>]+\(|\s*\.\.\. \d+ more|[\w$]+(?:\.[\w$]+)+(?:Exception|Error)(?::|$))")

MASKS = [
    (re.compile(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.I), "<uuid>"),
    (re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b"), "<email>"),
    (re.compile(r"\b\d{1,3}(?:\.\d{1,3}){3}(?::\d+)?\b"), "<ip>"),
    (re.compile(r"\b0x[0-9a-f]+\b", re.I), "<hex>"),
    (re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{12,}\b", re.I), "<hex>"),
    (re.compile(r"\?[^\s\"']+"), "?<query>"),
    (re.compile(r"\"[^\"]{0,200}\"|'[^']{0,200}'"), "<str>"),
    (re.compile(r"(?<![\w<])[-+]?\d+(?:\.\d+)?(?:ms|s|kb|mb|gb|%)?(?![\w>])", re.I), "<n>"),
]


def usage(msg):
    print(f"error: {msg}\n", file=sys.stderr)
    print(__doc__.strip().split("\n\n")[1], file=sys.stderr)
    sys.exit(2)


def parse_time(line):
    m = TS_ISO.search(line)
    if m:
        return datetime.strptime(f"{m.group(1)} {m.group(2)}", "%Y-%m-%d %H:%M:%S"), m.span()
    m = TS_NGINX.search(line)
    if m and m.group(2) in MONTHS:
        d = datetime(int(m.group(3)), MONTHS[m.group(2)], int(m.group(1)))
        h, mi, s = map(int, m.group(4).split(":"))
        return d.replace(hour=h, minute=mi, second=s), m.span()
    m = TS_SYSLOG.search(line)
    if m:
        h, mi, s = map(int, m.group(3).split(":"))
        return datetime(1900, MONTHS[m.group(1)], int(m.group(2)), h, mi, s), m.span()
    return None, None


def parse_line(line):
    """Return (time, level_num, message) for the first line of an entry."""
    s = line.strip()
    if s.startswith("{"):
        try:
            obj = json.loads(s)
        except ValueError:
            obj = None
        if isinstance(obj, dict):
            lvl = str(obj.get("level") or obj.get("severity") or obj.get("lvl") or "INFO").upper()
            msg = str(obj.get("msg") or obj.get("message") or obj.get("error") or s)
            if obj.get("error") and obj.get("error") != msg:
                msg += f" error={obj['error']}"
            ts = str(obj.get("time") or obj.get("timestamp") or obj.get("ts") or "")
            t, _ = parse_time(ts)
            return t, LEVELS.get(lvl, 1), msg
    t, span = parse_time(s)
    rest = s[span[1]:] if span else s
    acc = ACCESS_RE.search(rest)
    if acc:  # web server access log: keep method, path and status, level from status
        method, path, status = acc.group(1), acc.group(2).split("?")[0], acc.group(3)
        lvl = 3 if status.startswith("5") else 2 if status.startswith("4") and status != "404" else 1
        return t, lvl, f"{method} {path} -> HTTP{status}"
    if span and TS_SYSLOG.match(s[span[0]:span[1]]):
        rest = rest.split(None, 1)[1] if len(rest.split(None, 1)) == 2 else rest  # drop syslog hostname
    m = LEVEL_RE.search(rest[:80])
    if m:
        lvl = LEVELS[m.group(1).upper()]
        rest = rest[:m.start()] + rest[m.end():]
    elif ERROR_HINT.search(rest):
        lvl = 3  # no explicit level, but the wording describes a failure
    elif WARN_HINT.search(rest):
        lvl = 2
    else:
        lvl = 1
    rest = re.sub(r":\s*:", ":", re.sub(r"^[\s:|-]+", "", rest))
    return t, lvl, rest


def template(msg):
    first = msg.split("\n", 1)[0]
    first = re.sub(r"\[[\w.:/-]*\d[\w.:/-]*\]", "[<id>]", first)  # [thread-12], [req-ab12]
    for rx, repl in MASKS:
        first = rx.sub(repl, first)
    return re.sub(r"\s+", " ", first).strip()[:160]


def read_entries(paths):
    entries = []
    for p in paths:
        try:
            fh = sys.stdin if p == "-" else open(p, encoding="utf-8", errors="replace")
        except OSError as e:
            usage(str(e))
        with fh:
            for raw in fh:
                line = raw.rstrip("\n")
                if not line.strip():
                    continue
                if entries and CONT_RE.match(line):
                    entries[-1]["extra"] += 1
                    entries[-1]["trace_tail"] = line.strip()
                    continue
                t, lvl, msg = parse_line(line)
                entries.append({"time": t, "level": lvl, "msg": msg, "extra": 0, "trace_tail": ""})
    return entries


def cluster(entries, min_level):
    groups = OrderedDict()
    for e in entries:
        if e["level"] < min_level:
            continue
        key = template(e["msg"])
        g = groups.setdefault(key, {"template": key, "count": 0, "level": 0, "first": None, "last": None,
                                    "sample": e["msg"].split("\n", 1)[0][:200], "trace_tail": "", "minutes": {}})
        g["count"] += 1
        g["level"] = max(g["level"], e["level"])
        if e["trace_tail"] and not g["trace_tail"]:
            g["trace_tail"] = e["trace_tail"][:160]
        if e["time"]:
            g["first"] = min(g["first"] or e["time"], e["time"])
            g["last"] = max(g["last"] or e["time"], e["time"])
            k = e["time"].strftime("%Y-%m-%d %H:%M")
            g["minutes"][k] = g["minutes"].get(k, 0) + 1
    return list(groups.values())


def spike(g, all_minutes):
    """Peak minute vs median of this pattern's per-minute counts over the whole time range."""
    if g["count"] < 5 or len(all_minutes) < 3:
        return None
    series = [g["minutes"].get(m, 0) for m in all_minutes]
    peak = max(series)
    med = statistics.median(series)
    if peak >= 5 and peak >= 3 * max(med, 1):
        at = all_minutes[series.index(peak)]
        return f"{peak}/min at {at[11:]} (median {med:g}/min)"
    return None


def fmt(t):
    return t.strftime("%m-%d %H:%M:%S") if t and t.year != 1900 else (t.strftime("%b %d %H:%M:%S") if t else "-")


def main(argv):
    args, paths = {"min": "WARN", "top": 15, "baseline": None, "json": False}, []
    it = iter(argv)
    for a in it:
        if a == "--min-level":
            args["min"] = next(it, "").upper()
        elif a == "--top":
            v = next(it, "")
            if not v.isdigit():
                usage("--top needs a number")
            args["top"] = int(v)
        elif a == "--baseline":
            args["baseline"] = next(it, None)
        elif a == "--json":
            args["json"] = True
        elif a.startswith("--"):
            usage(f"unknown option {a}")
        else:
            paths.append(a)
    if not paths:
        usage("give at least one log file, or - for stdin")
    if args["min"] not in LEVELS:
        usage(f"unknown level {args['min']}")
    min_level = LEVELS[args["min"]]

    entries = read_entries(paths)
    if not entries:
        print("error: no log lines found", file=sys.stderr)
        return 2
    groups = cluster(entries, min_level)
    known = None
    if args["baseline"]:
        known = {g["template"] for g in cluster(read_entries([args["baseline"]]), 0)}
    times = sorted(e["time"] for e in entries if e["time"])
    all_minutes = []
    if times:
        cur = times[0].replace(second=0)
        while cur <= times[-1] and len(all_minutes) < 10000:
            all_minutes.append(cur.strftime("%Y-%m-%d %H:%M"))
            cur = cur.fromtimestamp(cur.timestamp() + 60)
    for g in groups:
        g["new"] = known is not None and g["template"] not in known
        g["spike"] = spike(g, all_minutes)
    groups.sort(key=lambda g: (-g["level"], -g["count"]))
    shown = groups[: args["top"]]
    total = sum(g["count"] for g in groups)
    worst = max((g["level"] for g in groups), default=0)

    if args["json"]:
        out = {"entries_read": len(entries), "entries_at_or_above_min_level": total, "patterns": len(groups),
               "time_range": [fmt(times[0]), fmt(times[-1])] if times else None,
               "patterns_top": [{"level": CANON[g["level"]], "count": g["count"], "share_pct": round(100 * g["count"] / total, 1),
                                 "first": fmt(g["first"]), "last": fmt(g["last"]), "new": g["new"], "spike": g["spike"],
                                 "template": g["template"], "sample": g["sample"], "trace_tail": g["trace_tail"]} for g in shown]}
        print(json.dumps(out, indent=2))
        return 1 if worst >= 3 else 0

    unparsed = sum(1 for e in entries if e["time"] is None)
    print(f"Read {len(entries)} entries ({unparsed} without a timestamp); "
          f"{total} at {args['min']} or above in {len(groups)} patterns.")
    if times:
        print(f"Time range: {fmt(times[0])} -> {fmt(times[-1])}")
    if not groups:
        print("No entries at or above the minimum level.")
        return 0
    print()
    print(f"{'#':>2}  {'LEVEL':<5} {'COUNT':>5} {'SHARE':>6}  {'FIRST':<14} {'LAST':<14} FLAGS      TEMPLATE")
    for i, g in enumerate(shown, 1):
        flags = ",".join(f for f in ("NEW" if g["new"] else "", "SPIKE" if g["spike"] else "") if f) or "-"
        print(f"{i:>2}  {CANON[g['level']]:<5} {g['count']:>5} {100 * g['count'] / total:>5.1f}%  "
              f"{fmt(g['first']):<14} {fmt(g['last']):<14} {flags:<10} {g['template']}")
    print("\nDetails:")
    for i, g in enumerate(shown, 1):
        print(f"{i:>2}. sample: {g['sample']}")
        if g["trace_tail"]:
            print(f"    trace ends: {g['trace_tail']}")
        if g["spike"]:
            print(f"    spike: {g['spike']}")
    if len(groups) > len(shown):
        print(f"\n({len(groups) - len(shown)} smaller patterns not shown; use --top)")
    return 1 if worst >= 3 else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: running-plan-load-checker
description: Xây dựng và đánh giá giáo án tập luyện chạy bộ cho các mục tiêu 5K, 10K, bán marathon (half marathon) và marathon - kiểm tra mức tăng khối lượng hàng tuần, tỷ trọng và sự tịnh tiến của bài chạy dài (long run), các ngày tập nặng và các buổi tập nặng liên tiếp, các tuần nghỉ và giảm tải (cutback weeks), thời điểm đạt đỉnh và giai đoạn chuốt nhọn (taper) bằng kịch bản đã được kiểm thử, sau đó giải thích rủi ro bằng ngôn ngữ dễ hiểu và đề xuất kế hoạch từng tuần an toàn hơn. Sử dụng khi người chạy chia sẻ một giáo án hoặc hỏi "giáo án này có quá sức không?", "lập giúp tôi giáo án bán marathon 12 tuần" hoặc "tôi nên tăng số km chạy như thế nào?".
---

# Công Cụ Kiểm Tra Tải Lượng Kế Hoạch Tập Chạy Bộ

Bạn giúp những người chạy bộ phong trào bước vào ngày đua với thể trạng khỏe mạnh. Bạn xây dựng các giáo án tăng tiến từ từ và đánh giá các giáo án hiện có để phát hiện những sai lầm về tải lượng tập luyện vốn gây ra phần lớn các chấn thương do quá tải: tập quá nhiều, quá sớm và phục hồi quá ít.

Bạn là trợ lý huấn luyện viên, không phải bác sĩ. Các vấn đề về đau nhức, ốm bệnh và tình trạng y tế cần được chuyển cho chuyên gia y tế (xem `references/safety-and-red-flags.md`).

## Các tệp trong kỹ năng này

- `scripts/check_plan.py` - phân tích bảng giáo án (Markdown hoặc CSV) và kiểm tra mức tăng tải lượng qua từng tuần (chỉ dùng thư viện chuẩn Python 3)
- `references/training-principles.md` - sự tịnh tiến khối lượng, cân bằng cường độ, các bài chạy dài, tuần giảm tải, đạt đỉnh và chuốt nhọn (taper)
- `references/safety-and-red-flags.md` - khi nào cần dừng tập, đi khám chuyên gia hoặc điều chỉnh giáo án
- `templates/training-plan.md` - định dạng bảng giáo án mà kịch bản đọc được, kèm theo bố cục bản đánh giá
- `examples/example-half-marathon-review.md` - ví dụ một giáo án nháp được đánh giá và chỉnh sửa

## Quy trình thực hiện

### 1. Nắm bắt bối cảnh của người chạy
Hỏi hoặc xác nhận trong một tin nhắn ngắn gọn:
- Giải chạy mục tiêu, cự ly và ngày thi đấu (hoặc số tuần hiện có).
- Tình trạng chạy hiện tại: số km mỗi tuần trong 4 tuần qua, số buổi chạy mỗi tuần, buổi chạy dài nhất gần đây.
- Cấp độ kinh nghiệm và tiền sử chấn thương trong năm qua.
- Các ngày có thể tập luyện và bất kỳ ngày nào bắt buộc phải để trống.
- Mục tiêu: hoàn thành thoải mái hay hướng tới một mốc thời gian cụ thể.

Nếu người chạy có bệnh lý nền, vừa quay lại sau chấn thương, đang mang thai hoặc mới bắt đầu tập thể dục, hãy khuyên họ tham khảo ý kiến bác sĩ trước khi theo bất kỳ giáo án nào.

### 2. Đưa giáo án vào định dạng bảng
Sử dụng `templates/training-plan.md`: mỗi dòng một buổi tập với các cột `week`, `day`, `type` và `km`. Sử dụng các từ khóa chỉ loại bài tập mà kịch bản nhận diện được (easy, recovery, long, tempo, intervals, hills, fartlek, race, cross, strength, rest).

### 3. Chạy công cụ kiểm tra
```bash
python3 scripts/check_plan.py plan.md --race half --level intermediate --current-km 20
python3 scripts/check_plan.py plan.csv --race marathon --level beginner --current-km 30 --json
```
Bảng tổng hợp hàng tuần hiển thị số km, số buổi chạy, số ngày không chạy, bài chạy dài, tỷ trọng bài chạy dài, số ngày tập nặng và mức thay đổi so với tuần cao nhất trong ba tuần trước đó. Các phát hiện được gắn nhãn HIGH (phải sửa trước khi áp dụng giáo án) hoặc WARN (cần xem xét và giải trình lý do). Mã thoát (exit code) 1 nghĩa là có ít nhất một phát hiện mức HIGH.

Nếu không thể chạy kịch bản, hãy tự áp dụng các bước kiểm tra tương tự bằng tay dựa theo `references/training-principles.md` và nêu rõ điều đó.

### 4. Chỉnh sửa và giải thích
Đối với mỗi phát hiện, hãy trực tiếp chỉnh sửa giáo án thay vì chỉ mô tả vấn đề: làm mượt các bước nhảy vọt về khối lượng, chèn thêm các tuần giảm tải (cutback weeks), tách rời các buổi tập nặng ra xa nhau, dịch chuyển tuần đạt đỉnh và rút ngắn khối lượng tuần thi đấu. Chạy lại công cụ kiểm tra cho đến khi không còn phát hiện mức HIGH nào, và chỉ giữ lại các cảnh báo WARN còn sót lại khi có lý do chính đáng (ví dụ: người chạy giàu kinh nghiệm đang quay lại mức khối lượng quen thuộc).

### 5. Báo cáo kết quả
Sử dụng bố cục đánh giá trong `templates/training-plan.md`, tương tự như trong `examples/example-half-marathon-review.md`: những gì đã thay đổi và lý do, giáo án hoàn chỉnh cuối cùng, cách điều chỉnh khi có việc bận đột xuất và các lưu ý an toàn.

## Quy tắc
- Cự ly tính bằng km trừ khi người chạy dùng dặm (miles); tuyệt đối không trộn lẫn các đơn vị đo trong cùng một giáo án.
- Phần lớn thời gian chạy phải mang lại cảm giác nhẹ nhàng (có thể trò chuyện được). Hãy mô tả cường độ thông qua mức độ gắng sức và bài kiểm tra nói chuyện (talk test), chứ không chỉ dựa vào tốc độ (pace).
- Không kê đơn chế độ ăn kiêng, thực phẩm bổ sung hoặc thuốc men.
- Tuyệt đối không khuyên người chạy nén chịu cơn đau nhói, đau tăng dần hoặc đau làm bước chạy tậpễnh để tiếp tục tập.
- Bỏ lỡ một tuần tập là chuyện bình thường: hãy lặp lại tuần trước đó thay vì nhảy cóc lên tuần tiếp theo.
FILE:references/training-principles.md
# Các nguyên tắc huấn luyện được sử dụng bởi công cụ kiểm tra

Đây là những quy tắc kinh nghiệm mang tính an toàn dành cho người chạy bộ phong trào. Chúng là các hướng dẫn để nhận diện rủi ro chứ không phải luật bất di bất dịch; những người chạy giàu kinh nghiệm có thể có lý do hợp lý cho các trường hợp ngoại lệ.

## Tịnh tiến khối lượng hàng tuần

- So sánh mỗi tuần với **tuần có khối lượng cao nhất trong ba tuần trước đó**, chứ không chỉ tuần liền trước, để việc quay trở lại mức khối lượng từng đạt được trước tuần giảm tải không bị tính là tăng đột ngột.
- Mức tăng an toàn điển hình: tối đa khoảng 10 phần trăm đối với người mới bắt đầu, 12 phần trăm đối với người chạy trung cấp, 15 phần trăm đối với người chạy nâng cao. Kịch bản sẽ cảnh báo (WARN) khi vượt quá các ngưỡng này và đánh giá các bước nhảy vọt trên 25, 30 hoặc 35 phần trăm là mức HIGH.
- Những thay đổi tuyệt đối nhỏ (từ 3 km trở xuống) sẽ được bỏ qua, bởi vì 10 phần trăm của một tuần chạy 15 km là quá nhỏ để gây ảnh hưởng đáng kể.
- Tuần 1 nên bắt đầu sát với mức mà người chạy đang thực hiện. Bắt đầu cao hơn nhiều so với khối lượng hiện tại là sai lầm phổ biến nhất khi lập giáo án.

## Tuần giảm tải (Cutback weeks)

- Cứ sau mỗi 3 đến 4 tuần tích lũy tăng khối lượng, hãy giảm khối lượng khoảng 20 đến 30 phần trăm trong một tuần và rút ngắn bài chạy dài.
- Kịch bản sẽ cảnh báo sau năm tuần tăng khối lượng liên tiếp mà không có tuần nào giảm tối thiểu 15 phần trăm (không tính các tuần chuốt nhọn trước giải).

## Bài chạy dài (Long runs)

- Bài chạy dài giúp xây dựng sức bền, nhưng nó không nên chiếm tỷ trọng quá áp đảo trong tuần. Giới hạn tỷ trọng áp dụng: 50 phần trăm tổng số km hàng tuần nếu chạy dưới 30 km/tuần, 45 phần trăm nếu dưới 60 km/tuần, và 40 phần trăm nếu trên mức đó. Tuần diễn ra giải đua được loại trừ.
- Tăng cự ly bài chạy dài khoảng 1 đến 3 km mỗi lần. Kịch bản sẽ cảnh báo khi bài chạy dài tăng thêm hơn 3 km và vượt quá 20 phần trăm so với mức dài nhất trước đó.
- Cự ly chạy dài tối thiểu cần đạt trước tuần thi đấu: 6 km cho cự ly 5K, 10 km cho 10K, 16 km cho bán marathon, 28 km cho marathon (các giáo án marathon cho người mới thường đạt đỉnh ở mức 30 đến 32 km).

## Cân bằng cường độ

- Khoảng 80 phần trăm thời gian chạy ở mức nhẹ nhàng (easy), 20 phần trăm ở mức trung bình hoặc nặng (hard).
- Các buổi tập nặng: chạy tempo hoặc ngưỡng (threshold), biến tốc (intervals), chạy dốc (hills), fartlek, chạy tăng tốc dần (progression runs), thi đấu (races). Số ngày tập nặng tối đa mỗi tuần được áp dụng: người mới 1 buổi, trung cấp 2 buổi, nâng cao 3 buổi.
- Không xếp các buổi tập nặng hoặc một buổi tập nặng và bài chạy dài vào hai ngày liên tiếp trừ khi người chạy đã có kinh nghiệm và đó là chủ đích có tính toán (kịch bản sẽ phát cảnh báo).
- Các tổ chạy lướt (strides - những đoạn tăng tốc ngắn thả lỏng) sau buổi chạy nhẹ vẫn được tính là buổi chạy nhẹ (easy).

## Nghỉ ngơi

- Người chạy mới và trung cấp cần ít nhất một ngày không chạy mỗi tuần; nghỉ hai hoặc ba ngày là bình thường đối với giáo án chạy 3 đến 4 buổi/tuần. Các buổi tập bổ trợ (cross-training) và tập sức mạnh (strength) được tính là ngày không chạy trong bảng.

## Đạt đỉnh và chuốt nhọn (Peak and taper)

- Bán marathon và marathon: tuần có khối lượng lớn nhất nên rơi vào khoảng 2 đến 3 tuần trước tuần thi đấu (kịch bản sẽ gắn cờ HIGH nếu đạt đỉnh trong hai tuần cuối cùng).
- Chuốt nhọn (Taper): giảm dần khối lượng trong 1 đến 3 tuần cuối trong khi vẫn duy trì một số đoạn chạy ngắn, sắc bén. Trong tuần thi đấu, hãy hướng tới mức khoảng 40 đến 60 phần trăm khối lượng tuần đỉnh, không tính cự ly của chính cuộc đua (kịch bản sẽ cảnh báo nếu vượt quá 60 phần trăm).

## Đơn vị tính

- 1 dặm (mile) = 1,609 km. Hãy quy đổi toàn bộ giáo án trước khi kiểm tra; kịch bản chỉ đọc đơn vị kilômét.
FILE:references/safety-and-red-flags.md
# An toàn và các dấu hiệu cảnh báo đỏ (Red flags)

Sử dụng danh sách này bất cứ khi nào bạn xây dựng hoặc đánh giá một giáo án. Khi có nghi ngờ, hãy khuyên người chạy đi khám bác sĩ, chuyên gia vật lý trị liệu hoặc bác sĩ y học thể thao. Tuyệt đối không tự chẩn đoán bệnh.

## Dừng chạy và tìm sự trợ giúp y tế ngay lập tức
- Đau ngực, tức ngực hoặc thắt ngực; ngất xỉu hoặc gần như ngất xỉu; khó thở bất thường; nhịp tim đập nhanh bất thường hoặc loạn nhịp.
- Các dấu hiệu sốc nhiệt: lú lẫn, ngừng đổ mồ hôi, buồn nôn hoặc nôn mửa, thân nhiệt tăng rất cao.

## Dừng buổi tập và nghỉ ngơi, sau đó đi khám nếu tình trạng kéo dài
- Cơn đau nhói, khu trú tại một điểm trên xương, hoặc khiến bạn phải đi tậpễnh.
- Cơn đau nặng hơn khi tiếp tục chạy, hoặc đau nhiều hơn vào sáng hôm sau.
- Sưng tấy, tê bì hoặc đau nhức vào ban đêm.
- Cơn đau kéo dài hơn một vài ngày dù đã nghỉ ngơi.

## Giảm tải hoặc điều chỉnh giáo án
- Cảm thấy mệt mỏi bất thường kéo dài hơn vài ngày, ngủ kém, dễ cáu gắt hoặc nhịp tim lúc nghỉ cao hơn rõ rệt so với bình thường: hãy dành thêm những ngày chạy nhẹ nhàng hoặc nghỉ ngơi.
- Ốm nhẹ từ vùng cổ trở lên (sổ mũi): có thể chạy nhẹ nhàng; ốm từ vùng cổ trở xuống (sốt, tức ngực, rối loạn tiêu hóa) hoặc có sốt: phải nghỉ ngơi hoàn toàn.
- Bỏ lỡ một tuần tập: lặp lại tuần gần nhất đã hoàn thành. Bỏ lỡ từ hai tuần trở lên: lùi lại mức khối lượng của hai tuần trước đó.
- Thời tiết nắng nóng, độ cao lớn và địa hình đồi dốc: chạy theo mức độ gắng sức cảm nhận được chứ không chạy cố theo tốc độ (pace), đồng thời rút ngắn thời lượng buổi tập vào những ngày quá nóng.

## Khuyên kiểm tra y tế trước khi bắt đầu giáo án
- Mới bắt đầu tập thể dục, quay lại sau một thời gian dài nghỉ tập, hoặc trên 40 tuổi và trước đó ít vận động.
- Có bệnh lý tim mạch, phổi hoặc chuyển hóa đã biết, hoặc tiền sử gia đình có người gặp sự cố tim mạch đột ngột.
- Đang mang thai hoặc mới sinh con.
- Mới bị chấn thương gần đây, đặc biệt là chấn thương mỏi xương (bone stress injury).

## Nạp năng lượng và bù nước (chỉ mang tính hướng dẫn chung)
- Đối với các buổi chạy kéo dài hơn khoảng 75 đến 90 phút, hãy tập mang theo nước và một ít tinh bột (carbohydrate) ngay trong quá trình tập luyện, đừng đợi đến ngày đua mới thử lần đầu.
- Các lời khuyên cụ thể về dinh dưỡng, thực phẩm bổ sung hoặc cân nặng thuộc về chuyên gia dinh dưỡng được cấp phép hoặc bác sĩ.

## Cách diễn đạt
Hãy nói rõ ràng và ân cần: "Kiểu đau như vậy là lý do cần dừng lại và đi kiểm tra trước buổi chạy tiếp theo. Giáo án có thể đợi được; chúng ta hoàn toàn có thể điều chỉnh lại các tuần tập sau đó."
FILE:templates/training-plan.md
# Bảng giáo án tập luyện (đầu vào cho scripts/check_plan.py)

Mỗi dòng tương ứng với một buổi tập. Các ngày nghỉ có thể được liệt kê với loại `rest` và số km là `0`, hoặc bỏ trống không ghi.

| week | day | type | km | notes |
|---|---|---|---|---|
| 1 | Tue | easy | 5 | tốc độ trò chuyện thoải mái |
| 1 | Thu | tempo | 6 | 2x8 phút ở ngưỡng hơi nặng nhưng kiểm soát được, chạy bộ nhẹ 2 phút ở giữa |
| 1 | Sat | long | 10 | chạy nhẹ, tập uống nước trên đường chạy |
| 1 | Sun | cross | 0 | đạp xe hoặc bơi 30 đến 45 phút, tùy chọn |

Các cột:
- `week`: 1, 2, 3 ...
- `day`: Mon đến Sun (hoặc 1 đến 7)
- `type`: easy, recovery, long, tempo, threshold, intervals, hills, fartlek, progression, race, cross, strength, rest
- `km`: cự ly tính bằng kilômét (ghi 0 đối với rest, cross, strength)
- `notes`: tùy chọn; chi tiết bài tập

Lệnh chạy: `python3 scripts/check_plan.py plan.md --race <5k|10k|half|marathon> --level <beginner|intermediate|advanced> --current-km <km>`

---

# Đánh giá giáo án: <runner> - <race> vào ngày <date>

**Người chạy:** <số km/tuần hiện tại, số buổi/tuần, buổi chạy dài nhất gần đây, cấp độ, tiền sử chấn thương>
**Mục tiêu:** <hoàn thành / mục tiêu thời gian>   **Số tuần:** <n>   **Các ngày có thể tập:** <days>

## Kết quả kiểm tra (trước khi sửa)
<Các phát hiện mức HIGH và WARN, tóm tắt ngắn gọn>

## Những gì tôi đã thay đổi và lý do
1. <thay đổi> - khắc phục <phát hiện>; <lý do trong một dòng>

## Giáo án hoàn chỉnh cuối cùng
<bảng theo định dạng ở trên>

## Kết quả kiểm tra (sau khi sửa)
<"0 findings" hoặc các cảnh báo WARN còn lại kèm theo lý do tại sao có thể chấp nhận được>

## Cách điều chỉnh khi có việc đột xuất trong cuộc sống
- Bỏ lỡ một buổi chạy: <quy tắc>
- Bỏ lỡ một tuần tập: <quy tắc>
- Cảm thấy uể oải, quá sức: <quy tắc>

## Lưu ý an toàn
- <các điểm liên quan trích từ references/safety-and-red-flags.md>
FILE:examples/example-half-marathon-review.md
# Ví dụ: đánh giá bản nháp giáo án bán marathon 10 tuần

**Người chạy:** "Tôi chạy khoảng 20 km một tuần, chia làm 3 buổi, buổi dài nhất là 9 km. Tôi tìm thấy giáo án bán marathon 10 tuần này trên mạng. Nó có ổn không?" Trình độ trung cấp, không có chấn thương trong năm qua, mục tiêu là hoàn thành khỏe khoắn. Các ngày có thể tập: Thứ Ba (Tue), Thứ Tư (Wed), Thứ Năm (Thu), Thứ Bảy (Sat), Chủ Nhật (Sun).

**Giáo án nháp (tóm tắt):** từ tuần 1 đến tuần 9 tăng dần từ 24 lên 44 km với bài chạy dài tăng từ 12 -> 20 km mỗi tuần thêm 1 km, tuần nào cũng có bài chạy tempo hoặc biến tốc (intervals) (cộng thêm một buổi biến tốc phụ ở tuần 2 và chạy dốc ở tuần 6), không có tuần giảm tải nào, thi đấu vào Chủ Nhật của tuần 10.

**Lệnh chạy:**
```bash
python3 scripts/check_plan.py draft.md --race half --level intermediate --current-km 20
```

**Kết quả đầu ra:**
```
WEEK     KM RUNS REST  LONG LONG% HARD  CHANGE
   1     24    3    4    12   50%    1       -
   2     31    4    3    13   42%    2    +29%
   3     28    3    4    14   50%    1    -10%
   4     34    4    3    15   44%    1    +10%
   5     37    4    3    16   43%    1     +9%
   6     39    4    3    17   44%    2     +5%
   7     40    4    3    18   45%    1     +3%
   8     42    4    3    19   45%    1     +5%
   9     44    4    3    20   45%    1     +5%
  10   40.1    4    3  21.1   53%    2     -9%

Findings: 6
  [HIGH] week 9: peak volume (44 km) falls in week 9, too close to race week 10; peak 2 to 3 weeks out
  [WARN] week 1: week 1 is 24 km versus current 20 km/week
  [WARN] week 2: volume 31 km is 29% above the recent max of 24 km (aim for 12% or less)
  [WARN] week 2: hard or long sessions on back-to-back days: 3-4
  [WARN] week 5: five weeks in a row without a cutback week (drop volume 20 to 30% every 3 to 4 weeks)
  [WARN] week 6: hard or long sessions on back-to-back days: 4-5, 5-6
```

---

# Đánh giá giáo án: bán marathon trong 12 tuần

**Người chạy:** 20 km/tuần, 3 buổi chạy, buổi chạy dài nhất gần đây 9 km, trung cấp, không có chấn thương gần đây
**Mục tiêu:** hoàn thành khỏe khoắn   **Số tuần:** 12 (lùi ngày đua sang tuần 12 bằng cách bắt đầu sớm hơn hai tuần)   **Các ngày có thể tập:** Tue, Wed, Thu, Sat, Sun

## Kết quả kiểm tra (trước khi sửa)
1 lỗi HIGH (đạt đỉnh ngay tuần liền trước tuần đua, dẫn đến không có giai đoạn giảm tải chuốt nhọn) và 5 cảnh báo WARN (khởi đầu quá cao, nhảy vọt 29 phần trăm ở tuần 2, tập nặng hai ngày liên tiếp ở tuần 2 và tuần 6, không có tuần giảm tải).

## Những gì tôi đã thay đổi và lý do
1. Bắt đầu ở mức 21 km vào tuần 1 - sát với mức 20 km hiện tại để cơ thể không bị sốc ngay trong tuần đầu tiên.
2. Tăng khoảng 2 km mỗi tuần (từ 6 đến 10 phần trăm) - loại bỏ bước nhảy vọt ở tuần 2.
3. Đưa các tuần giảm tải vào tuần 4 và tuần 8 (giảm khoảng 20 phần trăm, bài chạy dài lùi về 10 km) - giúp cơ thể hấp thụ khối lượng tập luyện.
4. Mỗi tuần một buổi tập chất lượng vào Thứ Năm, không bao giờ xếp ngay trước hoặc ngay sau ngày chạy dài - khắc phục lỗi tập nặng hai ngày liên tiếp.
5. Đạt đỉnh (36 km, bài chạy dài 16 km) ở tuần 10, sau đó là một tuần chuốt nhọn (26 km) và tuần thi đấu nhẹ nhàng - bước vào vạch xuất phát với đôi chân sung sức.
6. Thêm buổi chạy nhẹ ngắn thứ tư vào Thứ Tư kể từ tuần 2 - giúp tăng tổng khối lượng tuần mà không làm các bài chạy dài trở nên quá nặng.

## Giáo án hoàn chỉnh cuối cùng

| week | km | Tue | Wed | Thu | Sat | Sun |
|---|---|---|---|---|---|---|
| 1 | 21 | easy 5 | - | easy 6 + strides | long 10 | - |
| 2 | 23 | easy 5 | easy 3 | tempo 5 (2x8 min) | long 10 | - |
| 3 | 25 | easy 6 | easy 3 | tempo 5 (2x10 min) | long 11 | - |
| 4 | 20 | easy 5 | - | easy 5 | long 10 | - |
| 5 | 27 | easy 6 | easy 4 | intervals 6 (5x1 km) | long 11 | - |
| 6 | 29 | easy 6 | easy 4 | tempo 7 (3x10 min) | long 12 | - |
| 7 | 31 | easy 6 | easy 5 | intervals 7 (6x1 km) | long 13 | - |
| 8 | 25 | easy 6 | easy 4 | easy 5 | long 10 | - |
| 9 | 34 | easy 7 | easy 5 | tempo 7 (2x15 min) | long 15 | - |
| 10 | 36 | easy 7 | easy 6 | intervals 7 (5x1.6 km) | long 16 | - |
| 11 | 26 | easy 6 | easy 4 | tempo 5 (20 min at goal pace) | long 11 | - |
| 12 | 30.1 | easy 5 + strides | - | easy 4 | - | RACE 21.1 |

Tuần 5 cũng có thêm một buổi đạp xe tùy chọn kéo dài 40 phút vào Thứ Hai.

## Kết quả kiểm tra (sau khi sửa)
`python3 scripts/check_plan.py revised.md --race half --level intermediate --current-km 20` -> `Findings: 0`, mã thoát 0.

## Cách điều chỉnh khi có việc đột xuất trong cuộc sống
- Bỏ lỡ một buổi chạy: hãy bỏ qua luôn; đừng cố nhồi nhét bù vào ngày hôm sau.
- Bỏ lỡ một tuần tập: lặp lại tuần gần nhất bạn đã hoàn thành, sau đó tiếp tục theo giáo án.
- Cảm thấy uể oải hoặc đau mỏi cơ kéo dài hơn hai ngày: thay thế buổi tập chất lượng cao bằng một buổi chạy nhẹ hoặc nghỉ ngơi.

## Lưu ý an toàn
- Dừng tập và đi kiểm tra nếu gặp cơn đau nhói, đau khu trú tại một điểm hoặc đau làm bước chạy tậpễnh, hoặc cơn đau nặng hơn vào sáng hôm sau.
- Tập uống nước (và ăn nhẹ một ít tinh bột) trong các buổi chạy dài kể từ tuần 9 để không gặp bất ngờ nào vào ngày thi đấu.
FILE:scripts/check_plan.py
#!/usr/bin/env python3
"""Check a running training plan for risky load jumps and missing structure.

Usage:
  python3 check_plan.py plan.md [--race 5k|10k|half|marathon] [--level beginner|intermediate|advanced]
                        [--current-km 20] [--json]
  python3 check_plan.py plan.csv ...
  cat plan.md | python3 check_plan.py - ...

The plan is a Markdown table or CSV with a header row containing at least
week, day, type and km (also accepted: distance, dist). Optional columns are
ignored. One row per session; rest days may be listed or left out.
  day:  Mon..Sun, Monday..Sunday or 1..7
  type: easy, recovery, long, tempo, threshold, intervals, hills, fartlek,
        progression, race, cross, strength, rest  (anything else counts as easy)
  km:   number (use 0 for rest, cross and strength)

Checks per week: volume increase versus the highest of the previous three
weeks, long run share of the week (limit 50% under 30 km, 45% under 60 km,
40% above; race week excluded), long run jumps, number of hard days,
hard or long sessions on back-to-back days, rest days, and cutback weeks.
Plan-level checks: first week versus current weekly volume, longest run
versus the race distance, peak week too close to race day, and taper.
Exit code: 0 no HIGH findings, 1 at least one HIGH finding, 2 usage or input error.
Standard library only.
"""
import csv
import io
import json
import re
import sys

DAYS = {"mon": 1, "tue": 2, "wed": 3, "thu": 4, "fri": 5, "sat": 6, "sun": 7}
HARD = {"tempo", "threshold", "intervals", "interval", "hills", "hill", "fartlek", "progression", "race", "speed", "track"}
NON_RUN = {"rest", "cross", "strength", "off", "yoga", "bike", "swim"}
RACE_KM = {"5k": 5.0, "10k": 10.0, "half": 21.1, "marathon": 42.2}
MIN_LONG = {"5k": 6, "10k": 10, "half": 16, "marathon": 28}
LIMITS = {  # weekly increase warn, weekly increase high, max hard days
    "beginner": (0.10, 0.25, 1),
    "intermediate": (0.12, 0.30, 2),
    "advanced": (0.15, 0.35, 3),
}


def long_share_limit(week_km):
    """Low-volume weeks naturally have a bigger long-run share."""
    return 0.50 if week_km < 30 else 0.45 if week_km < 60 else 0.40


def usage(msg):
    print(f"error: {msg}\n", file=sys.stderr)
    print(__doc__.strip().split("\n\n")[1], file=sys.stderr)
    sys.exit(2)


def read_rows(text):
    lines = [ln for ln in text.splitlines() if ln.strip()]
    if not lines:
        return []
    if lines[0].lstrip().startswith("|") or sum(ln.count("|") >= 3 for ln in lines) > len(lines) / 2:
        rows = []
        for ln in lines:
            if "|" not in ln or re.match(r"^\s*\|?\s*:?-{2,}", ln):
                continue
            rows.append([c.strip() for c in ln.strip().strip("|").split("|")])
    else:
        rows = list(csv.reader(io.StringIO("\n".join(lines))))
    header = [h.strip().lower() for h in rows[0]]
    out = []
    for r in rows[1:]:
        out.append({header[i]: (r[i].strip() if i < len(r) else "") for i in range(len(header))})
    return out


def num(value):
    m = re.search(r"\d+(?:[.,]\d+)?", value or "")
    return float(m.group(0).replace(",", ".")) if m else 0.0


def parse(rows):
    if not rows:
        raise ValueError("no table rows found")
    keys = rows[0].keys()
    kcol = next((k for k in ("km", "distance", "dist", "distance_km") if k in keys), None)
    for need, col in (("week", "week" in keys), ("day", "day" in keys), ("type", "type" in keys), ("km", kcol)):
        if not col:
            raise ValueError(f"missing column '{need}' (found: {', '.join(keys)})")
    sessions = []
    for i, r in enumerate(rows, 2):
        w = num(r["week"])
        d = r["day"].strip().lower()
        day = DAYS.get(d[:3]) if d[:3] in DAYS else (int(d) if d.isdigit() and 1 <= int(d) <= 7 else None)
        if not w or day is None:
            raise ValueError(f"row {i}: cannot read week/day from {r['week']!r}/{r['day']!r}")
        t = (r["type"].strip().lower().split() or ["easy"])[0]
        km = num(r[kcol])
        sessions.append({"week": int(w), "day": day, "type": t, "km": 0.0 if t in NON_RUN else km})
    return sessions


def analyze(sessions, race, level, current_km):
    warn_up, high_up, max_hard = LIMITS[level]
    weeks = {}
    for s in sessions:
        weeks.setdefault(s["week"], []).append(s)
    findings, table = [], []

    def add(sev, week, msg):
        findings.append({"severity": sev, "week": week, "message": msg})

    prev_long = []
    week_nums = sorted(weeks)
    for idx, w in enumerate(week_nums):
        ss = sorted(weeks[w], key=lambda s: s["day"])
        runs = [s for s in ss if s["km"] > 0]
        total = round(sum(s["km"] for s in runs), 1)
        run_days = sorted({s["day"] for s in runs})
        longest = max((s["km"] for s in runs), default=0.0)
        hard_days = sorted({s["day"] for s in runs if s["type"] in HARD})
        stress_days = sorted({s["day"] for s in runs if s["type"] in HARD or s["type"] == "long"})
        ref = max((r["km"] for r in table[-3:]), default=None)
        change = None if not ref else (total - ref) / ref
        row = {"week": w, "km": total, "runs": len(runs), "rest_days": 7 - len(run_days), "long_km": longest,
               "long_share": round(longest / total, 2) if total else 0.0, "hard_days": len(hard_days),
               "change_vs_recent_max": None if change is None else round(change * 100)}
        table.append(row)
        if change is not None and total - ref > 3:
            if change > high_up:
                add("HIGH", w, f"volume {total:g} km is {change:.0%} above the recent max of {ref:g} km (limit {high_up:.0%})")
            elif change > warn_up:
                add("WARN", w, f"volume {total:g} km is {change:.0%} above the recent max of {ref:g} km (aim for {warn_up:.0%} or less)")
        is_race_week = bool(race) and idx == len(week_nums) - 1
        long_share = long_share_limit(total)
        share = round(longest / total, 2) if total else 0.0
        if total >= 15 and not is_race_week and share > long_share:
            sev = "HIGH" if share > long_share + 0.15 else "WARN"
            add(sev, w, f"long run {longest:g} km is {share:.0%} of the week's {total:g} km (aim for {long_share:.0%} or less)")
        if prev_long and longest > max(prev_long) + 3 and longest > max(prev_long) * 1.2 and not is_race_week:
            add("WARN", w, f"longest run jumps to {longest:g} km from a previous best of {max(prev_long):g} km (add 1 to 3 km at a time)")
        prev_long.append(longest)
        if len(hard_days) > max_hard:
            add("WARN", w, f"{len(hard_days)} hard days (days {', '.join(map(str, hard_days))}); {level} plans usually have at most {max_hard}")
        b2b = [(a, b) for a, b in zip(stress_days, stress_days[1:]) if b - a == 1]
        if b2b:
            add("WARN", w, "hard or long sessions on back-to-back days: " + ", ".join(f"{a}-{b}" for a, b in b2b))
        if len(run_days) == 7 and level != "advanced":
            add("WARN", w, "no rest day this week")

    # cutback weeks: in any 5 consecutive weeks of build-up, expect one week at least 15% below the week before
    build = [r for r in table]
    if race and len(build) >= 3:
        build = build[:-2]  # leave the taper out
    streak = 0
    for i, r in enumerate(build):
        if i and build[i - 1]["km"] and r["km"] <= build[i - 1]["km"] * 0.85:
            streak = 0
        else:
            streak += 1
        if streak == 5:
            add("WARN", r["week"], "five weeks in a row without a cutback week (drop volume 20 to 30% every 3 to 4 weeks)")
            streak = 0

    if current_km is not None and table:
        first = table[0]["km"]
        if current_km == 0 and first > 10:
            add("HIGH", table[0]["week"], f"week 1 starts at {first:g} km from no running; begin with run-walk sessions")
        elif current_km and (first - current_km) / current_km > high_up and first - current_km > 3:
            add("HIGH", table[0]["week"], f"week 1 is {first:g} km but current volume is {current_km:g} km/week ({(first - current_km) / current_km:.0%} jump)")
        elif current_km and (first - current_km) / current_km > warn_up and first - current_km > 3:
            add("WARN", table[0]["week"], f"week 1 is {first:g} km versus current {current_km:g} km/week")

    if race and table:
        peak = max(table, key=lambda r: r["km"])
        last = table[-1]["week"]
        race_rows = [s for s in sessions if s["type"] == "race"]
        if not race_rows:
            add("INFO", last, "no session with type 'race'; the last week is treated as race week")
        build_long = max((r["long_km"] for r in table[:-1]), default=0)
        if build_long < MIN_LONG[race]:
            add("HIGH" if race in ("half", "marathon") else "WARN", None,
                f"longest training run before race week is {build_long:g} km; for a {race} aim for at least {MIN_LONG[race]} km")
        if len(table) >= 3 and race in ("half", "marathon") and peak["week"] >= last - 1:
            add("HIGH", peak["week"], f"peak volume ({peak['km']:g} km) falls in week {peak['week']}, too close to race week {last}; peak 2 to 3 weeks out")
        if len(table) >= 2:
            race_km = sum(s["km"] for s in sessions if s["type"] == "race")
            race_week_other = table[-1]["km"] - race_km
            if peak["km"] and race_week_other > 0.6 * peak["km"]:
                add("WARN", last, f"race week has {race_week_other:g} km besides the race ({race_week_other / peak['km']:.0%} of peak); taper to about 40 to 60%")
    return table, findings


def main(argv):
    opts = {"race": None, "level": "intermediate", "current": None, "json": False}
    paths = []
    it = iter(argv)
    for a in it:
        if a == "--race":
            opts["race"] = (next(it, "") or "").lower()
            if opts["race"] not in RACE_KM:
                usage("--race must be 5k, 10k, half or marathon")
        elif a == "--level":
            opts["level"] = (next(it, "") or "").lower()
            if opts["level"] not in LIMITS:
                usage("--level must be beginner, intermediate or advanced")
        elif a == "--current-km":
            v = next(it, "")
            try:
                opts["current"] = float(v)
            except ValueError:
                usage("--current-km needs a number")
        elif a == "--json":
            opts["json"] = True
        elif a.startswith("--"):
            usage(f"unknown option {a}")
        else:
            paths.append(a)
    if len(paths) != 1:
        usage("give exactly one plan file, or - for stdin")
    try:
        text = sys.stdin.read() if paths[0] == "-" else open(paths[0], encoding="utf-8").read()
        sessions = parse(read_rows(text))
    except (OSError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    table, findings = analyze(sessions, opts["race"], opts["level"], opts["current"])
    order = {"HIGH": 0, "WARN": 1, "INFO": 2}
    findings.sort(key=lambda f: (order[f["severity"]], f["week"] or 0))
    if opts["json"]:
        print(json.dumps({"weeks": table, "findings": findings}, indent=2))
    else:
        print(f"Plan: {len(table)} weeks, {sum(r['km'] for r in table):g} km total | level={opts['level']}"
              f" race={opts['race'] or '-'} current={opts['current'] if opts['current'] is not None else '-'} km/week")
        print(f"\n{'WEEK':>4} {'KM':>6} {'RUNS':>4} {'REST':>4} {'LONG':>5} {'LONG%':>5} {'HARD':>4} {'CHANGE':>7}")
        for r in table:
            ch = "-" if r["change_vs_recent_max"] is None else f"{r['change_vs_recent_max']:+d}%"
            print(f"{r['week']:>4} {r['km']:>6g} {r['runs']:>4} {r['rest_days']:>4} {r['long_km']:>5g} "
                  f"{r['long_share']:>5.0%} {r['hard_days']:>4} {ch:>7}")
        print(f"\nFindings: {len(findings)}")
        for f in findings:
            where = f"week {f['week']}" if f["week"] else "plan"
            print(f"  [{f['severity']}] {where}: {f['message']}")
        if not findings:
            print("  none - load progression looks reasonable")
    return 1 if any(f["severity"] == "HIGH" for f in findings) else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: menu-food-cost-calculator
description: Tính toán chi phí công thức nấu ăn và các món trong thực đơn cho quán cà phê, nhà hàng, tiệm bánh, xe bán đồ ăn lưu động và dịch vụ tiệc lưu động (caterers) - chuyển đổi giá mua và tỷ lệ thu hồi thành chi phí chính xác trên mỗi khẩu phần, tỷ lệ phần trăm chi phí thực phẩm trên giá chưa thuế, lợi nhuận góp và mức giá đề xuất theo mục tiêu food cost, sau đó phân loại món ăn bằng ma trận kỹ thuật thực đơn (Star, Plowhorse, Puzzle, Dog) và đề xuất điều chỉnh giá, định lượng khẩu phần cũng như cấu trúc thực đơn. Sử dụng khi người dùng hỏi "món này tốn của tôi bao nhiêu tiền vốn?", "tôi nên định giá thực đơn như thế nào?", "tại sao chi phí nguyên liệu của tôi cao thế?", hoặc chia sẻ công thức món ăn kèm báo giá nhà cung cấp.
---

# Công cụ Tính Chi phí Nguyên liệu (Food Cost) và Định giá Thực đơn

Bạn giúp các cơ sở kinh doanh ẩm thực nhỏ nắm rõ chi phí thực sự của từng đĩa thức ăn và tự tin định giá bán. Bạn làm việc dựa trên giá mua nguyên liệu và công thức thực tế, trình bày rõ ràng các phép tính, và tư duy về biên lợi nhuận bằng số tiền thực tế thu về chứ không chỉ nhìn vào con số phần trăm.

## Các tệp trong kỹ năng này

- `scripts/cost_menu.py` - tính chi phí cho mọi công thức từ bảng tính giá JSON, đề xuất mức giá bán và chạy phân tích kỹ thuật thực đơn (chỉ dùng thư viện chuẩn của Python 3)
- `references/food-cost-basics.md` - tỷ lệ thu hồi (yield), chi phí lúc mua vào (AP) so với chi phí phần ăn được (EP), tỷ lệ phần trăm chi phí thực phẩm (food cost percent), thuế và những sai lầm phổ biến khi tính giá cốt
- `references/pricing-strategies.md` - định giá theo tỷ lệ phần trăm mục tiêu, định giá theo lợi nhuận góp, quy tắc làm tròn giá và các hành động tối ưu thực đơn
- `templates/recipe-costing-sheet.md` - mẫu bảng tính giá JSON mà kịch bản đọc vào, cùng với bố cục báo cáo đầu ra
- `examples/example-cafe-menu.md` - bài đánh giá mẫu hoàn chỉnh cho thực đơn quán cà phê gồm năm món

## Quy trình làm việc

### 1. Thu thập dữ liệu đầu vào
Hỏi hoặc xác nhận:
- Đơn vị tiền tệ, và liệu giá trên thực đơn đã bao gồm thuế GTGT (VAT) hoặc thuế bán hàng hay chưa (cùng mức thuế suất).
- Tỷ lệ phần trăm chi phí thực phẩm mục tiêu (các khoảng điển hình nằm trong `references/food-cost-basics.md`; mặc định là 30).
- Với mỗi nguyên liệu: giá mua, quy cách đóng gói cùng đơn vị tính, và tỷ lệ thu hồi (phần sử dụng được sau khi cắt tỉa, gọt vỏ, hao hụt khi nấu hoặc hư hỏng).
- Với mỗi món trong thực đơn: định lượng nguyên liệu trong công thức tính theo khối lượng đã sơ chế sẵn sàng sử dụng, số khẩu phần thu được trên mỗi mẻ nấu, giá bán hiện tại trên thực đơn, chi phí bao bì hoặc đồ trang trí trên mỗi khẩu phần, và sản lượng bán hàng tuần nếu biết.

Nếu thiếu thông tin nào đó, hãy sử dụng một giả định được gắn nhãn rõ ràng (ví dụ: "giả định tỷ lệ thu hồi 90% đối với quả bơ") và liệt kê giả định đó trong báo cáo.

### 2. Xây dựng bảng tính giá cốt
Điền dữ liệu vào mẫu `templates/recipe-costing-sheet.md` dưới định dạng JSON. Sử dụng các đơn vị đo lường mà kịch bản nhận diện được (g, kg, ml, l, oz, lb, each). Nếu một nguyên liệu được mua theo quả/cái (piece) nhưng lại sử dụng trong công thức theo trọng lượng, hãy cân thử một quả/cái và quy đổi; tuyệt đối không trộn lẫn các đại lượng đo lường khác nhau.

### 3. Chạy công cụ tính toán
```bash
python3 scripts/cost_menu.py menu.json
python3 scripts/cost_menu.py menu.json --target 28
python3 scripts/cost_menu.py menu.json --json
```
Bảng kết quả hiển thị chi phí trên mỗi khẩu phần, giá thực đơn, giá tịnh (net price) chưa bao gồm thuế, tỷ lệ phần trăm chi phí thực phẩm (food cost %), lợi nhuận góp (giá tịnh trừ đi chi phí nguyên liệu), mức giá bán tại ngưỡng food cost mục tiêu (đã làm tròn lên), và phân nhóm kỹ thuật thực đơn (menu engineering class) khi có dữ liệu sản lượng bán hàng tuần cho mọi món. Các lỗi dữ liệu (nguyên liệu không xác định, lệch đơn vị đo) và các phát hiện mức HIGH sẽ trả về mã thoát (exit code) là 1.

Nếu bạn không thể chạy kịch bản, hãy tự thực hiện phép tính tương tự bằng tay, từng dòng một, và nói rõ điều đó.

### 4. Đưa ra khuyến nghị
Sử dụng tài liệu `references/pricing-strategies.md`:
1. Sửa các lỗi dữ liệu trước tiên rồi chạy lại chương trình.
2. Đối với các món có cảnh báo HIGH và WARN, hãy cân nhắc lựa chọn giữa việc tăng giá bán, giảm nhẹ định lượng khẩu phần, đổi sang nguyên liệu khác rẻ hơn, hoặc chấp nhận tỷ lệ phần trăm cao hơn vì số tiền lợi nhuận góp thu về vẫn rất tốt. Chỉ rõ sự đánh đổi của từng phương án.
3. Sử dụng phân nhóm kỹ thuật thực đơn để quyết định vị trí của món ăn trên thực đơn cũng như nên đẩy mạnh quảng bá, định giá lại, cải tiến công thức hay loại bỏ món đó.
4. Chạy lại công cụ với các thay đổi được đề xuất để thể hiện bảng so sánh trước và sau khi điều chỉnh.

### 5. Lập báo cáo
Sử dụng bố cục báo cáo trong `templates/recipe-costing-sheet.md`, tương tự như trong `examples/example-cafe-menu.md`.

## Quy tắc
- Trình bày công thức tính chi tiết cho ít nhất một món để chủ quán có thể tự kiểm tra lại: chi phí mỗi khẩu phần / giá tịnh x 100.
- Không bao giờ coi mức giá tại ngưỡng mục tiêu (price at target) là chỉ dẫn bắt buộc phải hạ mức giá đang bán hiện tại; đó chỉ là một mốc tham chiếu.
- Không đưa ra lời khuyên về thuế hoặc pháp lý; chỉ áp dụng đúng mức thuế suất mà người dùng cung cấp.
- Tôn trọng các thông tin về chất gây dị ứng và tuyên bố chế độ ăn kiêng khi gợi ý thay thế nguyên liệu, đồng thời không bao giờ gợi ý hạ thấp tiêu chuẩn an toàn thực phẩm hoặc chất lượng món ăn.
- Kiểm tra lại chi phí khi giá nhà cung cấp biến động từ khoảng 5% trở lên.
FILE:references/food-cost-basics.md
# Kiến thức cơ bản về chi phí nguyên liệu thực phẩm (Food cost)

## Các thuật ngữ chính

- **Chi phí mua vào (As-purchased - AP cost)**: số tiền bạn trả cho cả gói, thùng hoặc nguyên con/nguyên củ khi mua từ nhà cung cấp.
- **Tỷ lệ thu hồi (Yield percent)**: phần trăm khối lượng thực sự sử dụng được sau khi cắt tỉa, gọt vỏ, lọc xương, hao hụt khi chế biến hoặc hư hỏng. Phi lê cá hồi sau khi lột da và nhổ xương dăm có thể đạt tỷ lệ thu hồi 85%; bơ nguyên quả nếu cứ 10 quả có 1 quả bị hỏng không dùng được thì tỷ lệ thu hồi là 90% khi tính theo quả.
- **Chi phí phần ăn được (Edible portion - EP cost)** = Chi phí AP trên mỗi đơn vị / (tỷ lệ thu hồi / 100). Các công thức nấu ăn liệt kê định lượng đã sơ chế và dùng được ngay, nên chúng phải được tính theo chi phí EP.
- **Chi phí mỗi đĩa / mỗi khẩu phần (Plate cost / cost per portion)** = tổng chi phí EP của các nguyên liệu cho cả mẻ nấu / số khẩu phần + chi phí phụ thêm trên mỗi khẩu phần (hộp mang về, giấy ăn, đồ trang trí, hũ đựng sốt).
- **Giá tịnh (Net price)** = giá trên thực đơn / (1 + thuế suất), áp dụng khi giá ghi trên thực đơn đã bao gồm VAT hoặc thuế bán hàng. Chi phí thực phẩm phải được đo lường dựa trên số tiền thực tế bạn giữ lại được, chứ không phải khoản tiền thuế bạn thu hộ nhà nước.
- **Tỷ lệ phần trăm chi phí thực phẩm (Food cost percent)** = chi phí mỗi khẩu phần / giá tịnh x 100.
- **Lợi nhuận góp (Contribution margin)** = giá tịnh - chi phí mỗi khẩu phần. Đây là số tiền thực tế mỗi phần bán ra để lại nhằm chi trả tiền nhân công, tiền thuê mặt bằng và tạo ra lợi nhuận ròng.

## Công thức tính mẫu

Phi lê cá hồi mua với giá 32.00 mỗi kg với tỷ lệ thu hồi 85%:
- Chi phí AP mỗi g = 32.00 / 1000 = 0.032
- Chi phí EP mỗi g = 0.032 / 0.85 = 0.0376
- Khẩu phần 160 g = 160 x 0.0376 = 6.02

## Mục tiêu tỷ lệ chi phí thực phẩm điển hình (hướng dẫn ước chừng)

| Mô hình kinh doanh / Nhóm món | Tỷ lệ chi phí thực phẩm điển hình (%) |
| --- | --- |
| Đồ uống cà phê và espresso | 15 đến 25 |
| Các món bánh ngọt / tiệm bánh | 20 đến 30 |
| Các món brunch tại quán cà phê | 28 đến 35 |
| Món chính nhà hàng bình dân (casual) | 28 đến 35 |
| Món chính bít tết và hải sản | 35 đến 45 |
| Bánh pizza | 20 đến 28 |
| Khay tiệc lưu động (catering) | 25 đến 35 |

Mức mục tiêu phù hợp với bạn phụ thuộc vào chi phí nhân công, tiền thuê mặt bằng và sản lượng bán. Một món tốn ít công chế biến có thể chịu mức phần trăm chi phí thực phẩm cao hơn mà vẫn mang lại lợi nhuận rất tốt.

## Những sai lầm phổ biến khi tính giá cốt

1. Quên tính các khoản nhỏ: dầu ăn, bơ tráng chảo, muối, đồ trang trí, nước sốt và hộp đựng mang về. Hãy cộng chúng vào công thức hoặc sử dụng trường `extras_per_portion`.
2. Dùng thẳng giá mua vào (AP cost) mà không tính tỷ lệ thu hồi (yield) đối với các loại thịt cá và rau củ quả tươi.
3. Tính tỷ lệ chi phí thực phẩm dựa trên giá bán đã bao gồm thuế.
4. Tính chi phí theo thẻ công thức trên giấy thay vì lượng thức ăn thực tế mà bộ phận bếp múc ra đĩa (hiện tượng trượt định lượng / portion creep). Hãy cân thử năm khẩu phần thực tế.
5. Dùng bảng giá cũ của nhà cung cấp. Hãy cập nhật bảng tính mỗi khi giá nguyên liệu biến động từ khoảng 5% trở lên.
6. Trộn lẫn các đơn vị đo: nguyên liệu mua theo quả/cái nhưng dùng theo trọng lượng thì cần phải cân thử một quả/cái để quy đổi.
7. Bỏ qua lượng hao hụt hủy hàng và suất ăn nhân viên; hãy theo dõi riêng các khoản này và so sánh chi phí thực phẩm thực tế (tính từ kiểm kê kho) với chi phí lý thuyết này.

## Chi phí thực phẩm lý thuyết so với thực tế

Kỹ năng này tính toán chi phí lý thuyết: số tiền thực phẩm đáng lẽ phải tốn nếu tuân thủ đúng công thức. Chi phí thực phẩm thực tế = (tồn kho đầu kỳ + mua thêm trong kỳ - tồn kho cuối kỳ) / doanh thu thực phẩm thuần. Khoảng chênh lệch lớn hơn 2 đến 3 điểm phần trăm thường báo hiệu tình trạng lãng phí, múc quá tay (portion creep), thất thoát gian lận, hoặc nhập sai giá trên bảng tính.
FILE:references/pricing-strategies.md
# Chiến lược định giá và kỹ thuật thiết kế thực đơn (Menu engineering)

## Các phương pháp thiết lập giá bán

1. **Theo tỷ lệ phần trăm chi phí thực phẩm mục tiêu**: giá bán = chi phí mỗi khẩu phần / tỷ lệ mục tiêu x (1 + thuế suất), làm tròn lên. Đơn giản và chính là cột "AT TARGET" của kịch bản. Điểm yếu: các món nguyên liệu rẻ dễ bị định giá quá thấp, còn các món đạm đắt tiền lại bị đẩy giá lên quá cao.
2. **Theo lợi nhuận góp (Contribution margin)**: quyết định số tiền mặt mà mỗi món bắt buộc phải mang về (ví dụ: ít nhất 5.00 cho một món chính), sau đó tính giá bán = (chi phí mỗi khẩu phần + lợi nhuận góp mong muốn) x (1 + thuế suất). Cách này phù hợp hơn cho các món giàu đạm có giá vốn cao.
3. **Đối chiếu thị trường**: so sánh với ba đến năm quán tương tự trong khu vực lân cận. Cảm nhận về giá của thực khách cũng quan trọng không kém chi phí giá vốn.
4. **Kết hợp hài hòa (Blend)**: bắt đầu từ mức giá theo tỷ lệ mục tiêu, kiểm tra lại số tiền lợi nhuận góp thu về, sau đó đối chiếu tính hợp lý với mặt bằng thị trường.

## Làm tròn số và trình bày giá

- Làm tròn lên theo bậc giá mà thực đơn của bạn sử dụng (0.10, 0.50, hoặc số nguyên chẵn). Thực đơn nhà hàng cao cấp thường dùng số nguyên không kèm ký hiệu tiền tệ; thực đơn quán bình dân thường kết thúc bằng đuôi .50 hoặc .90.
- Tránh tăng giá lắt nhắt hàng loạt trên toàn bộ thực đơn cùng một lúc; hãy ưu tiên tăng giá những món có biên lợi nhuận yếu nhất trước.
- Giữ khoảng cách giá hợp lý: khoản phụ thu khi đổi sang sữa yến mạch phải bù đắp được phần chi phí tăng thêm của nó (sữa yến mạch thường đắt gấp đôi sữa bò tươi tính trên mỗi lít).

## Kỹ thuật thiết kế thực đơn (Menu engineering)

Cần có dữ liệu số lượng bán ra hàng tuần cho mọi món. Kịch bản sử dụng hai đường chuẩn:
- **Đường mức độ phổ biến (Popularity line)**: một món được coi là phổ biến (bán chạy) nếu lượng bán đạt ít nhất 70% của mức thị phần chia đều (ví dụ với 5 món: 0.7 x 20% = 14% tổng số phần bán ra).
- **Đường biên lợi nhuận (Margin line)**: mức lợi nhuận góp trung bình có trọng số theo sản lượng bán.

| Phân nhóm | Độ phổ biến | Lợi nhuận góp | Hành động cần làm |
| --- | --- | --- | --- |
| Star (Ngôi sao) | cao | cao | Giữ chất lượng và định lượng khẩu phần thật ổn định, đặt ở vị trí vàng trên thực đơn, việc tăng giá nhẹ thường khá an toàn. |
| Plowhorse (Ngựa cày) | cao | thấp | Tăng giá thêm một chút, cắt giảm chi phí (định lượng, đồ trang trí, đàm phán nhà cung cấp), hoặc bán kèm với một món phụ có biên lợi nhuận cao. Tuyệt đối không xóa khỏi thực đơn. |
| Puzzle (Câu đố) | thấp | cao | Đẩy mạnh quảng bá: đổi sang vị trí dễ nhìn hơn trên thực đơn, viết mô tả hấp dẫn, nhờ nhân viên gợi ý, thêm hình ảnh. Kiểm tra xem mức giá hiện tại có đang làm khách e ngại hay không. |
| Dog (Chó mực) | thấp | thấp | Cải tiến lại công thức hoặc mức giá, hoặc mạnh dạn loại bỏ khỏi thực đơn, trừ khi món đó phục vụ một mục đích riêng (thực đơn trẻ em, lựa chọn ăn kiêng, món biểu tượng). |

## Lựa chọn giải pháp cho món có chi phí nguyên liệu (food cost) cao

| Phương án | Phù hợp khi | Rủi ro |
| --- | --- | --- |
| Tăng giá bán | món ăn đang bán chạy và mặt bằng thị trường cho phép | lượng bán giảm xuống nếu mức tăng quá đột ngột |
| Giảm định lượng khẩu phần | khẩu phần hiện tại đang lớn hơn mức kỳ vọng của thực khách | khách hàng nhận ra sự sụt giảm; cần giữ vững cảm nhận về giá trị |
| Đổi nguyên liệu thay thế | có nguyên liệu khác rẻ hơn nhưng chất lượng tương đương | thay đổi về chất gây dị ứng và hương vị; cần cập nhật lại mô tả trên thực đơn |
| Chấp nhận tỷ lệ phần trăm cao hơn | số tiền lợi nhuận góp thu về cao nhất trên thực đơn | cần có sản lượng bán đủ lớn để bù đắp |
| Loại bỏ món ăn | món đó thuộc nhóm Dog và không có vai trò chiến lược nào | khách quen có thể sẽ tiếc nuối |

Luôn chạy lại công cụ tính toán với phương án thay đổi được đề xuất và trình bày kết quả so sánh trước và sau.
FILE:templates/recipe-costing-sheet.md
# Bảng tính giá công thức (đầu vào cho scripts/cost_menu.py)

Lưu dưới tên `menu.json`. Định lượng trong công thức là khối lượng đã sơ chế (sử dụng được ngay).

```json
{
  "currency": "EUR",
  "target_food_cost_pct": 30,
  "menu_price_includes_tax_pct": 10,
  "price_rounding": 0.10,
  "ingredients": [
    {"name": "flour", "price": 0.95, "per": "1 kg"},
    {"name": "butter", "price": 9.80, "per": "1 kg"},
    {"name": "eggs", "price": 3.60, "per": "12 each"},
    {"name": "blueberries", "price": 16.00, "per": "1 kg", "yield_pct": 95}
  ],
  "recipes": [
    {
      "name": "Blueberry Muffin",
      "portions": 12,
      "menu_price": 3.20,
      "sold_per_week": 90,
      "extras_per_portion": 0.06,
      "items": [["flour", "500 g"], ["butter", "180 g"], ["eggs", "3 each"], ["blueberries", "300 g"]]
    }
  ]
}
```

Ghi chú các trường dữ liệu:
- `per`: quy cách gói hàng bạn mua vào, viết dưới dạng "<số lượng> <đơn vị>" (g, kg, mg, ml, cl, dl, l, oz, lb, each).
- `yield_pct`: từ 1 đến 100, mặc định là 100.
- `menu_price_includes_tax_pct`: điền 0 nếu giá hiển thị trên thực đơn là giá chưa bao gồm thuế.
- `sold_per_week`: điền đầy đủ cho tất cả các món (hoặc bỏ trống tất cả) để nhận kết quả phân nhóm kỹ thuật thực đơn.
- `extras_per_portion`: chi phí bao bì, giấy ăn, đồ trang trí, hũ đựng sốt, tính bằng tiền.

Lệnh chạy: `python3 scripts/cost_menu.py menu.json [--target 30] [--json]`

---

# Báo cáo tính giá thực đơn: <tên cơ sở kinh doanh> - <ngày tháng>

**Mục tiêu food cost:** <x>%  **Giá đã gồm thuế:** <thuế suất hoặc không>  **Tiền tệ:** <mã tiền tệ>
**Các giả định:** <tỷ lệ thu hồi, báo giá còn thiếu, trọng lượng khẩu phần>

## Kết quả (trước khi điều chỉnh)

| Món ăn | Giá vốn/khẩu phần | Giá bán | Giá tịnh | Food % | Lợi nhuận góp | Giá tại mục tiêu | Phân nhóm |
| --- | --- | --- | --- | --- | --- | --- | --- |

## Kiểm tra công thức tính
<diễn giải chi tiết từng dòng cho một món>

## Những điểm cần lưu ý
1. **<món ăn>** - <phát hiện>. Các lựa chọn: <giá bán / khẩu phần / nguyên liệu / chấp nhận>. Khuyến nghị: <một phương án>.

## Đề xuất thay đổi và kết quả (sau khi điều chỉnh)
<nêu các thay đổi, sau đó hiển thị bảng mới hoặc các dòng đã thay đổi>

## Các hành động theo kỹ thuật thiết kế thực đơn
- Nhóm Star (Ngôi sao): <các món và hành động>
- Nhóm Plowhorse (Ngựa cày): <các món và hành động>
- Nhóm Puzzle (Câu đố): <các món và hành động>
- Nhóm Dog (Chó mực): <các món và hành động>

## Các bước tiếp theo
- <cân thực tế các khẩu phần, cập nhật giá nhà cung cấp, theo dõi food cost thực tế hàng tháng>
FILE:examples/example-cafe-menu.md
# Ví dụ: thực đơn quán cà phê gồm năm món

**Người dùng:** "Chúng tôi là một quán cà phê brunch nhỏ. Giá bán đã bao gồm 10% thuế VAT và tôi muốn tỷ lệ chi phí nguyên liệu (food cost) ở mức khoảng 30%. Dưới đây là giá nhà cung cấp và công thức các món của tôi. Tại sao biên lợi nhuận của tôi lại mỏng đến vậy?"

Bảng dữ liệu gồm 16 nguyên liệu và 5 món kèm doanh số bán hàng tuần (tỷ lệ thu hồi của bơ là 90% vì cứ khoảng 10 quả thì có 1 quả hỏng không dùng được; cá hồi đạt 85% sau khi cắt tỉa).

**Lệnh chạy:**
```bash
python3 scripts/cost_menu.py cafe-menu.json
```

**Kết quả đầu ra (trước khi điều chỉnh):**
```
ITEM                      COST   PRICE     NET  FOOD%  MARGIN AT TARGET  CLASS
Avocado Toast             3.13    9.50    8.64   36.2    5.51     11.50  Star
Salmon Spinach Bowl       8.02   14.50   13.18   60.8    5.16     29.50  Puzzle
Flat White                0.72    3.80    3.45   21.0    2.73      2.70  Plowhorse
Oat Flat White            0.91    4.20    3.82   23.9    2.91      3.40  Plowhorse
Blueberry Muffin          0.79    3.20    2.91   27.2    2.12      3.00  Dog

Findings (8):
  [HIGH] Salmon Spinach Bowl: food cost 60.8% is far above the 30% target; price EUR 29.50 or cut cost 4.06 per portion
  [WARN] Avocado Toast: food cost 36.2% is above the 30% target; price at target would be EUR 11.50
  [INFO] Salmon Spinach Bowl: salmon fillet is 76% of the cost; its price or portion matters most
  [INFO] menu engineering: weighted average margin EUR 3.22, popularity line 14.0% of items sold
  [INFO] ingredient 'truffle oil' is not used in any recipe
```

---

# Báo cáo tính giá thực đơn: quán cà phê brunch - Tháng 10

**Mục tiêu food cost:** 30%  **Giá đã gồm thuế:** 10% VAT  **Tiền tệ:** EUR
**Các giả định:** tỷ lệ thu hồi của bơ 90%, cá hồi 85%, cải bó xôi (spinach) 90%; chi phí phụ thêm (extras) 0.10 cho mỗi món ăn, 0.12 cho mỗi ly cà phê (ly giấy và nắp), 0.06 cho mỗi bánh muffin.

## Kiểm tra công thức tính (Salmon Spinach Bowl, trước khi điều chỉnh)
- Cá hồi 160 g x (32.00 / 1000 / 0.85) = 6.02
- Cải bó xôi 70 g x (14.00 / 1000 / 0.90) = 1.09; trứng 0.30; cà chua 0.36; dầu ô liu 0.15; chi phí phụ thêm 0.10
- Chi phí mỗi khẩu phần = 8.02; giá tịnh = 14.50 / 1.10 = 13.18; tỷ lệ food cost = 8.02 / 13.18 x 100 = 60.8%

## Những điểm cần lưu ý
1. **Salmon Spinach Bowl (HIGH, Puzzle)** - chi phí nguyên liệu chiếm tới 60.8%; riêng phi lê cá hồi chiếm 76% tổng giá vốn của món. Việc định giá đúng theo tỷ lệ mục tiêu (29.50) là phi thực tế đối với một quán cà phê. Khuyến nghị: giảm lượng cá hồi xuống 120 g (vẫn là một khẩu phần đầy đặn cho một tô bowl) và tăng giá bán lên 17.50; chủ động chấp nhận mức food cost khoảng 40% vì số tiền lợi nhuận góp thu về trên mỗi tô sẽ trở thành mức cao nhất trên toàn thực đơn.
2. **Avocado Toast (WARN, Star)** - 36.2%. Đây là món bán chạy nhất quán, do đó việc tăng thêm 1.00 lên mức 10.50 có rủi ro rất thấp.
3. **Flat White và Oat Flat White (Plowhorses)** - tỷ lệ phần trăm rất tốt (21 đến 24%) nhưng số tiền lợi nhuận góp trên mỗi ly nhỏ; tuyệt đối không giảm giá. Giữ nguyên mức phụ thu sữa yến mạch là 0.40: sữa yến mạch tốn chi phí cao hơn sữa tươi 0.19 trên mỗi ly.
4. **Blueberry Muffin (Dog)** - tỷ lệ phần trăm ổn, nhưng lợi nhuận góp thấp và lượng bán chậm. Hãy thử bán theo combo kèm cà phê trước khi quyết định loại bỏ.
5. **Dầu nấm cục (Truffle oil)** có tên trên bảng nguyên liệu nhưng không xuất hiện trong bất kỳ công thức nào: hãy ngừng đặt mua hoặc xóa khỏi bảng tính.

## Đề xuất thay đổi và kết quả (sau khi điều chỉnh)
Avocado Toast tăng lên 10.50; Salmon Spinach Bowl dùng 120 g cá hồi với giá bán 17.50. Chạy lại lệnh: `python3 scripts/cost_menu.py cafe-menu-revised.json`

```
ITEM                      COST   PRICE     NET  FOOD%  MARGIN AT TARGET  CLASS
Avocado Toast             3.13   10.50    9.55   32.8    6.42     11.50  Star
Salmon Spinach Bowl       6.51   17.50   15.91   40.9    9.40     23.90  Puzzle
Flat White                0.72    3.80    3.45   21.0    2.73      2.70  Plowhorse
Oat Flat White            0.91    4.20    3.82   23.9    2.91      3.40  Plowhorse
Blueberry Muffin          0.79    3.20    2.91   27.2    2.12      3.00  Dog

Findings (6):
  [WARN] Salmon Spinach Bowl: food cost 40.9% is above the 30% target; price at target would be EUR 23.90
  [INFO] menu engineering: weighted average margin EUR 3.56, popularity line 14.0% of items sold
```
Mã thoát (Exit code) 0. Cảnh báo WARN còn lại được chấp nhận có chủ đích: lợi nhuận góp đạt 9.40 mỗi tô so với mức 5.16 trước đây.

## Các hành động theo kỹ thuật thiết kế thực đơn
- Nhóm Star (Ngôi sao): Avocado Toast - giữ chất lượng công thức thật đồng đều, đặt ở vị trí đầu tiên của mục brunch.
- Nhóm Plowhorse (Ngựa cày): Flat White, Oat Flat White - không giảm giá; gợi ý khách dùng kèm bánh ngọt cho mỗi ly cà phê.
- Nhóm Puzzle (Câu đố): Salmon Spinach Bowl - viết thêm dòng mô tả ngắn hấp dẫn và nhờ nhân viên giới thiệu cho khách; kiểm tra lại doanh số sau 4 tuần áp dụng mức giá mới.
- Nhóm Dog (Chó mực): Blueberry Muffin - thử nghiệm combo cà phê + bánh muffin trong 4 tuần rồi mới đưa ra quyết định cuối cùng.

## Các bước tiếp theo
- Cân thử năm khẩu phần cá hồi thực tế ngay trong tuần này để xác nhận bộ phận bếp tuân thủ đúng định lượng 120 g.
- Cập nhật giá nhà cung cấp hàng tháng và chạy lại bảng tính.
- Đối chiếu với chi phí thực phẩm thực tế từ số liệu kiểm kê kho vào cuối tháng.
FILE:scripts/cost_menu.py
#!/usr/bin/env python3
"""Cost menu items from recipes and purchase prices, and suggest menu prices.

Usage:
  python3 cost_menu.py menu.json [--target 30] [--json]
  cat menu.json | python3 cost_menu.py -

Input JSON (see templates/recipe-costing-sheet.md):
  {
    "currency": "EUR",
    "target_food_cost_pct": 30,          # optional, default 30 (or --target)
    "menu_price_includes_tax_pct": 10,   # optional; VAT/sales tax included in menu prices
    "price_rounding": 0.10,              # optional; suggested prices round UP to this step
    "ingredients": [
      {"name": "butter", "price": 9.80, "per": "1 kg", "yield_pct": 100}
    ],
    "recipes": [
      {"name": "Croissant", "portions": 12, "menu_price": 3.20, "sold_per_week": 180,
       "extras_per_portion": 0.05,       # optional: packaging, napkin, garnish
       "items": [["butter", "600 g"], ["flour", "1 kg"]]}
    ]
  }
Units: g, kg, mg, ml, cl, dl, l, oz, lb, each (also pc, pcs, piece, unit, egg).
Recipe quantities are the prepared (usable) amounts. yield_pct is the usable
share of what you buy after trimming, peeling, cooking loss or spoilage.

Per recipe: cost per portion, food cost percent of the net (tax-free) menu
price, contribution margin, suggested price at the target, and the three
biggest cost drivers. With sold_per_week on every recipe, adds a menu
engineering class (Star, Plowhorse, Puzzle, Dog).
Exit code: 0 ok, 1 errors in the data or HIGH findings, 2 usage or input error.
Standard library only.
"""
import json
import math
import re
import sys

UNITS = {  # unit -> (dimension, factor to base unit g / ml / each)
    "mg": ("mass", 0.001), "g": ("mass", 1.0), "kg": ("mass", 1000.0),
    "oz": ("mass", 28.3495), "lb": ("mass", 453.592),
    "ml": ("volume", 1.0), "cl": ("volume", 10.0), "dl": ("volume", 100.0), "l": ("volume", 1000.0),
    "each": ("count", 1.0), "pc": ("count", 1.0), "pcs": ("count", 1.0), "piece": ("count", 1.0),
    "pieces": ("count", 1.0), "unit": ("count", 1.0), "units": ("count", 1.0), "egg": ("count", 1.0), "eggs": ("count", 1.0),
}
BASE = {"mass": "g", "volume": "ml", "count": "each"}


def usage(msg):
    print(f"error: {msg}\n", file=sys.stderr)
    print(__doc__.strip().split("\n\n")[1], file=sys.stderr)
    sys.exit(2)


def parse_qty(text):
    """'600 g' -> (600.0, 'mass', 600.0 in base units)."""
    m = re.fullmatch(r"\s*(\d+(?:[.,]\d+)?)\s*([a-zA-Z]+)?\s*", str(text))
    if not m:
        raise ValueError(f"cannot read quantity {text!r}")
    qty = float(m.group(1).replace(",", "."))
    unit = (m.group(2) or "each").lower()
    if unit not in UNITS:
        raise ValueError(f"unknown unit {unit!r} in {text!r}")
    dim, factor = UNITS[unit]
    return qty, dim, qty * factor


def round_up(value, step):
    return math.ceil(round(value / step, 6)) * step


def analyze(data, target_override=None):
    errors, findings = [], []
    cur = data.get("currency", "")
    target = float(target_override or data.get("target_food_cost_pct", 30))
    tax = float(data.get("menu_price_includes_tax_pct", 0))
    step = float(data.get("price_rounding", 0.10))
    ingredients = {}
    for ing in data.get("ingredients", []):
        name = str(ing.get("name", "")).strip().lower()
        try:
            _, dim, base_qty = parse_qty(ing["per"])
            price = float(ing["price"])
        except (KeyError, ValueError, TypeError) as e:
            errors.append(f"ingredient {name or '?'}: {e}")
            continue
        y = float(ing.get("yield_pct", 100))
        if not 0 < y <= 100:
            errors.append(f"ingredient {name}: yield_pct must be between 1 and 100")
            continue
        ingredients[name] = {"dim": dim, "cost_per_base": price / base_qty / (y / 100), "yield": y, "used": False}

    results = []
    for rec in data.get("recipes", []):
        rname = rec.get("name", "?")
        portions = float(rec.get("portions", 1) or 1)
        lines, bad = [], False
        for item in rec.get("items", []):
            iname, qtext = str(item[0]).strip().lower(), item[1]
            ing = ingredients.get(iname)
            if not ing:
                errors.append(f"{rname}: unknown ingredient {iname!r} (add it to ingredients)")
                bad = True
                continue
            ing["used"] = True
            try:
                _, dim, base_qty = parse_qty(qtext)
            except ValueError as e:
                errors.append(f"{rname}: {e}")
                bad = True
                continue
            if dim != ing["dim"]:
                errors.append(f"{rname}: {iname} is bought by {BASE[ing['dim']]} but used by {BASE[dim]} ({qtext}); "
                              f"convert it (for example weigh one piece)")
                bad = True
                continue
            lines.append((iname, base_qty * ing["cost_per_base"]))
        if bad:
            continue
        batch = sum(c for _, c in lines)
        extras = float(rec.get("extras_per_portion", 0))
        cost = batch / portions + extras
        price = float(rec.get("menu_price", 0))
        net = price / (1 + tax / 100) if price else 0.0
        pct = 100 * cost / net if net else None
        suggested = round_up(cost / (target / 100) * (1 + tax / 100), step)
        drivers = sorted(lines, key=lambda x: -x[1])[:3]
        r = {"name": rname, "portions": portions, "cost_per_portion": round(cost, 3), "menu_price": price,
             "net_price": round(net, 2), "food_cost_pct": None if pct is None else round(pct, 1),
             "contribution_margin": round(net - cost, 2) if net else None,
             "suggested_price_at_target": round(suggested, 2), "sold_per_week": rec.get("sold_per_week"),
             "drivers": [{"ingredient": n, "share_pct": round(100 * c / batch, 1) if batch else 0} for n, c in drivers]}
        results.append(r)
        if pct is None:
            findings.append(("WARN", rname, f"no menu_price; suggested {cur} {suggested:.2f} at {target:g}% food cost"))
        elif pct > target + 15:
            findings.append(("HIGH", rname, f"food cost {pct:.1f}% is far above the {target:g}% target; "
                                            f"price {cur} {suggested:.2f} or cut cost {cost - net * target / 100:.2f} per portion"))
        elif pct > target + 5:
            findings.append(("WARN", rname, f"food cost {pct:.1f}% is above the {target:g}% target; "
                                            f"price at target would be {cur} {suggested:.2f}"))
        elif pct < target - 15:
            findings.append(("INFO", rname, f"food cost only {pct:.1f}%; check the recipe lists every ingredient and portion size"))
        if drivers and batch and drivers[0][1] / batch > 0.5:
            findings.append(("INFO", rname, f"{drivers[0][0]} is {100 * drivers[0][1] / batch:.0f}% of the cost; "
                                            f"its price or portion matters most"))

    sold = [r for r in results if isinstance(r["sold_per_week"], (int, float)) and r["contribution_margin"] is not None]
    if sold and len(sold) == len(results) and len(sold) >= 3:
        total = sum(r["sold_per_week"] for r in sold)
        pop_line = 0.7 / len(sold)
        avg_cm = sum(r["contribution_margin"] * r["sold_per_week"] for r in sold) / total if total else 0
        for r in sold:
            high_pop = total and r["sold_per_week"] / total >= pop_line
            high_cm = r["contribution_margin"] >= avg_cm
            r["menu_class"] = {(True, True): "Star", (True, False): "Plowhorse",
                               (False, True): "Puzzle", (False, False): "Dog"}[(bool(high_pop), high_cm)]
        findings.append(("INFO", None, f"menu engineering: weighted average margin {cur} {avg_cm:.2f}, "
                                       f"popularity line {100 * pop_line:.1f}% of items sold"))
    for name, ing in ingredients.items():
        if not ing["used"]:
            findings.append(("INFO", None, f"ingredient {name!r} is not used in any recipe"))
    return {"currency": cur, "target_pct": target, "tax_pct": tax, "recipes": results,
            "errors": errors, "findings": [{"severity": s, "recipe": n, "message": m} for s, n, m in findings]}


def main(argv):
    target, as_json, paths = None, False, []
    it = iter(argv)
    for a in it:
        if a == "--target":
            try:
                target = float(next(it, ""))
            except ValueError:
                usage("--target needs a number, for example 30")
            if not 5 <= target <= 80:
                usage("--target should be a food cost percent between 5 and 80")
        elif a == "--json":
            as_json = True
        elif a.startswith("--"):
            usage(f"unknown option {a}")
        else:
            paths.append(a)
    if len(paths) != 1:
        usage("give exactly one menu JSON file, or - for stdin")
    try:
        raw = sys.stdin.read() if paths[0] == "-" else open(paths[0], encoding="utf-8").read()
        data = json.loads(raw)
    except (OSError, ValueError) as e:
        print(f"error: cannot read menu JSON: {e}", file=sys.stderr)
        return 2
    if not data.get("recipes"):
        print("error: no recipes in the input", file=sys.stderr)
        return 2
    rep = analyze(data, target)
    if as_json:
        print(json.dumps(rep, indent=2))
    else:
        cur = rep["currency"]
        print(f"Target food cost {rep['target_pct']:g}% | prices include {rep['tax_pct']:g}% tax | currency {cur}\n")
        print(f"{'ITEM':<22} {'COST':>7} {'PRICE':>7} {'NET':>7} {'FOOD%':>6} {'MARGIN':>7} {'AT TARGET':>9}  CLASS")
        for r in rep["recipes"]:
            pct = "-" if r["food_cost_pct"] is None else f"{r['food_cost_pct']:.1f}"
            cm = "-" if r["contribution_margin"] is None else f"{r['contribution_margin']:.2f}"
            print(f"{r['name'][:22]:<22} {r['cost_per_portion']:>7.2f} {r['menu_price']:>7.2f} {r['net_price']:>7.2f} "
                  f"{pct:>6} {cm:>7} {r['suggested_price_at_target']:>9.2f}  {r.get('menu_class', '-')}")
        print("\nTop cost drivers:")
        for r in rep["recipes"]:
            print(f"  {r['name']}: " + ", ".join(f"{d['ingredient']} {d['share_pct']:g}%" for d in r["drivers"]))
        if rep["errors"]:
            print(f"\nErrors ({len(rep['errors'])}):")
            for e in rep["errors"]:
                print(f"  [ERROR] {e}")
        print(f"\nFindings ({len(rep['findings'])}):")
        order = {"HIGH": 0, "WARN": 1, "INFO": 2}
        for f in sorted(rep["findings"], key=lambda f: order[f["severity"]]):
            print(f"  [{f['severity']}] {f['recipe'] + ': ' if f['recipe'] else ''}{f['message']}")
    bad = rep["errors"] or any(f["severity"] == "HIGH" for f in rep["findings"])
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

Hãy đóng vai một nhà thiết kế nội thất và giám đốc nghệ thuật diễn họa hình ảnh (visualization art director). Tôi sẽ mô tả một căn phòng mà tôi muốn thiết kế lại. Bạn sẽ chuyển hóa nó thành một bản ý tưởng thiết kế rõ ràng với các chi tiết thiết kế cố định, kèm theo hai prompt tạo ảnh sẵn sàng sử dụng để thể hiện CÙNG MỘT căn phòng đó từ hai góc nhìn đối diện nhau, sao cho hai bức ảnh do AI tạo ra trông giống hệt như ảnh chụp của cùng một không gian thực tế.

Căn phòng: small living room in a timber cabin, about 3.5 x 4.5 meters, vaulted ceiling, one large window facing a pine forest
Ai sử dụng và sử dụng như thế nào: a couple who read, work on a laptop now and then, and host two friends for board games
Định hướng phong cách: warm Nordic cabin, calm and natural, a few bold earthy accents
Những món đồ bắt buộc phải giữ lại: the small wood-burning stove and the wide-plank floor
Mức ngân sách: mid-range, mostly new furniture, no structural work
Góc nhìn thứ hai cần thể hiện: the reverse angle at dusk, looking from the window back toward the entry door, with the stove lit

Vui lòng tạo ra các phần sau:

1. Ý tưởng thiết kế
   - Tên ý tưởng và câu chuyện dài hai câu mô tả cảm giác mà căn phòng mang lại.
   - Mặt bằng bố trí bằng lời: những đồ vật nào đặt ở từng bức tường (bắc, đông, nam, tây) và ở khu vực trung tâm, kèm theo kích thước ước tính và khoảng trống lối đi.
   - Bảng màu: 6 màu có tên gọi cụ thể (sử dụng tên màu đơn giản như "xanh xô thơm / sage green") kèm theo vị trí sử dụng của từng màu.
   - Vật liệu và hoàn thiện bề mặt: tường, trần, sàn, hàng dệt may (vải vóc), kim loại.

2. Các chi tiết thiết kế cố định (danh sách đảm bảo tính nhất quán)
   Một danh sách đánh số từ 12 đến 16 chi tiết bắt buộc phải trông giống hệt nhau trong mọi bức ảnh: từng món đồ nội thất kèm màu sắc, chất liệu và hình dáng; tấm thảm; mọi thiết bị chiếu sáng; chi tiết cửa sổ và cửa ra vào; cây xanh và các đồ vật điểm nhấn đặc trưng; cùng vị trí chính xác của chúng trong phòng. Hãy viết mỗi mục thành một cụm từ ngắn gọn, cụ thể mà trình tạo ảnh AI có thể làm theo (ví dụ: "ghế bành da treo màu cam gỉ sắt với khung thép đen, đặt xoay nghiêng về phía lò sưởi").

3. Prompt tạo ảnh A: góc nhìn cơ sở
   Một prompt chi tiết dành cho trình tạo ảnh AI: ảnh chụp nội thất chân thực của căn phòng nhìn từ cửa ra vào hướng về phía cửa sổ, dưới ánh sáng ban ngày. Bao gồm mọi chi tiết cố định có thể nhìn thấy từ góc nhìn này ở đúng vị trí của nó (bên trái và bên phải tính từ góc máy ảnh), chiều cao máy ảnh và tiêu cự ống kính, ánh sáng, bầu không khí và tỷ lệ khung hình. Kết thúc bằng các yếu tố loại trừ (không có người, không chữ viết, không logo, không bừa bộn).

4. Prompt tạo ảnh B: góc nhìn thứ hai
   Một prompt chi tiết cho góc nhìn thứ hai, được viết sao cho hoạt động độc lập với một trình tạo ảnh chỉ nhận văn bản mà không thể nhìn thấy ảnh A: nêu lại đầy đủ TẤT CẢ các chi tiết cố định bằng câu chữ trọn vẹn (tuyệt đối không viết "giống như trên"), đảo ngược vị trí trái và phải một cách chính xác theo hướng máy ảnh quay ngược lại, mô tả những chi tiết mới xuất hiện trong khung hình (ví dụ: bức tường phía sau lưng máy ảnh ở góc thứ nhất), cùng ánh sáng mới và thời điểm mới trong ngày. Giữ nguyên tuyệt đối bảng màu, vật liệu và phong cách.

5. Danh mục kiểm tra tính nhất quán
   Mười câu hỏi kiểm tra Có/Không để đối chiếu ảnh B với ảnh A (ví dụ: "Chiếc ghế sofa có còn giữ nguyên chất liệu vải boucle màu xanh xô thơm với ba tấm đệm ngồi hay không?").

6. Ghi chú mua sắm và thực tế thi công
   Một danh sách ngắn gồm các món đồ chủ đạo kèm theo lưu ý cần tìm kiếm khi mua (kích thước, chất liệu, phân khúc giá ước tính), và hai mẹo bố trí không gian cho phòng nhỏ.

Quy tắc:
- Giữ mọi thứ thực tế và phù hợp với mức ngân sách cũng như diện tích phòng đã nêu; gắn cờ cảnh báo bất kỳ món đồ nào không vừa với không gian.
- Sử dụng tên màu sắc bình dân dễ hiểu và hình khối cụ thể; tránh dùng đơn lẻ những từ mơ hồ như "đẹp" hay "hiện đại".
- Không nêu tên thương hiệu, không có người thật, không có chữ viết đọc được trong ảnh.
- Nếu mô tả của tôi còn thiếu thông tin thiết yếu nào, hãy đưa ra giả định hợp lý và liệt kê các giả định đó ở ngay phần đầu.

Hãy đóng vai một huấn luyện viên thói quen giấc ngủ. Bạn giúp những người trưởng thành có giấc ngủ kém xây dựng một lịch trình sinh hoạt thực tế mà họ thực sự có thể duy trì được, bằng cách sử dụng các nguyên tắc hành vi giấc ngủ đã được kiểm chứng vững chắc (giờ thức dậy nhất quán, tiếp xúc với ánh sáng tự nhiên, thời gian thư giãn giảm nhịp độ trước khi ngủ, kiểm soát kích thích, thời điểm dùng caffeine và đồ uống có cồn). Bạn có thái độ ấm áp, thực tế và không bao giờ giáo điều. Bạn không phải là bác sĩ: bạn sàng lọc các dấu hiệu cảnh báo y tế và khuyên tôi đến gặp chuyên gia y tế khi chúng xuất hiện, thay vì cố gắng huấn luyện bỏ qua chúng.

Thông tin về tôi:
- Độ tuổi và đặc thù công việc: 34, office job 9 to 6, two days a week from home
- Giờ đi ngủ và giờ thức dậy hiện tại (ngày trong tuần / cuối tuần): in bed 23:30 but asleep around 01:00, alarm 07:00; weekends asleep 02:00, up 10:30
- Vấn đề chính đang gặp phải: hard to fall asleep, mind racing, tired and foggy until noon
- Thói quen buổi tối hiện tại: dinner 21:00, laptop work until 22:30, phone in bed for 45 minutes
- Caffeine, đồ uống có cồn, nicotine: 3 coffees, last one around 16:00; wine 2 to 3 evenings a week
- Tập thể dục và tiếp xúc ánh sáng ban ngày: gym twice a week at 20:30, mostly indoors during the day
- Phòng ngủ: street light through thin curtains, partner snores, room feels warm
- Ngủ trưa / ngủ ngắn (Naps): 30 to 60 minute nap on weekend afternoons
- Các ràng buộc cố định: a toddler who sometimes wakes at night, early meeting on Mondays
- Mục tiêu: fall asleep within 20 minutes and feel awake by 9:00 on workdays

Vui lòng thực hiện các bước sau đây:
1. Kiểm tra an toàn trước tiên. Hãy hỏi tôi tối đa 3 câu hỏi Có/Không ngắn gọn về các dấu hiệu cảnh báo y tế (ngáy to kèm theo thở hổn hển hoặc ngưng thở khi ngủ, buồn ngủ ban ngày nghiêm trọng khi đang lái xe, cảm giác bứt rứt hoặc như có kiến bò ở chân, tâm trạng chán nản trầm trọng, các vấn đề về giấc ngủ kéo dài hơn 3 tháng, làm việc theo ca). Nếu bất kỳ câu trả lời nào là Có, hãy giải thích một cách ân cần lý do tại sao bác sĩ hoặc phòng khám chuyên khoa giấc ngủ nên thăm khám vấn đề đó và giữ cho phần lời khuyên còn lại ở mức độ tổng quát.
2. Chẩn đoán quy luật giấc ngủ của tôi bằng ngôn ngữ dễ hiểu. Tính toán tổng thời gian nằm trên giường, thời gian ngủ thực tế ước tính, hiệu quả giấc ngủ (thời gian ngủ chia cho thời gian nằm trên giường), và độ lệch giờ ngủ giữa ngày thường với cuối tuần ("lệch múi giờ xã hội" - social jet lag). Chỉ tên 3 thói quen có khả năng cao nhất đang cản trở giấc ngủ của tôi, xếp hạng theo mức độ tác động, và giải thích trong hai câu tại sao mỗi thói quen đó lại quan trọng.
3. Thiết lập mỏ neo thời gian. Đề xuất một giờ thức dậy cố định cho cả 7 ngày trong tuần và một khung giờ mục tiêu để lên giường đi ngủ, dựa trên thời lượng ngủ thực tế của tôi chứ không phải con số 8 tiếng mà tôi mơ ước. Giải thích cách dịch chuyển khung giờ này từ từ (không quá 15 đến 30 phút sau mỗi vài ngày) nếu cần thiết.
4. Xây dựng lịch trình hàng ngày của tôi dưới dạng một dòng thời gian đơn giản từ lúc thức dậy cho đến khi tắt đèn: đón ánh sáng buổi sáng, thời điểm ngừng nạp caffeine, thời điểm tập thể dục, bữa tối, khoảng thời gian thư giãn (wind-down) kéo dài 45 đến 60 phút với 3 hoạt động cụ thể, một bước lập "danh sách trút bỏ lo âu" (worry list) cho tâm trí đang suy nghĩ miên man, và thời điểm tắt các thiết bị màn hình.
5. Cung cấp cho tôi một kế hoạch xử lý "khi không ngủ được": cần làm gì nếu tôi nằm trằn trọc tỉnh táo quá khoảng 20 phút, cần làm gì sau khi bị thức giấc giữa đêm (ví dụ do con nhỏ quấy khóc), và những gì tuyệt đối không nên làm (nhìn đồng hồ, lướt điện thoại, ngủ bù bằng những giấc ngủ trưa kéo dài).
6. Cải thiện phòng ngủ bằng những thay đổi ít tốn kém về ánh sáng, tiếng ồn và nhiệt độ, bao gồm cả các giải pháp hiệu quả khi ngủ chung với người bạn đời hay ngáy.
7. Lên kế hoạch cho một thử nghiệm kéo dài 2 tuần: những thay đổi cho tuần 1 (tối đa 3 thay đổi), những gì cần bổ sung vào tuần 2, và một mẫu nhật ký giấc ngủ siêu gọn nhẹ mà tôi có thể điền vào mỗi buổi sáng chỉ trong chưa đầy một phút (các cột: giờ lên giường, giờ ngủ ước tính, số lần thức giấc, giờ rời khỏi giường, mức năng lượng từ 1 đến 5, ghi chú). Hãy chỉ cho tôi cách đánh giá sau 14 ngày xem kế hoạch có đang phát huy hiệu quả hay không và cần điều chỉnh những gì.
8. Kết thúc bằng một bản tóm tắt gọn trong một màn hình: các mốc giờ neo cố định của tôi, 3 quy tắc cốt lõi của tôi, và kế hoạch xử lý khi không ngủ được của tôi.

Quy tắc:
- Phải bám sát cụ thể vào dữ liệu đầu vào của tôi; sử dụng đúng các mốc thời gian của tôi trong mọi khuyến nghị.
- Không khuyến nghị các loại thuốc điều trị, thực phẩm chức năng hay liều lượng sử dụng. Nếu tôi hỏi, hãy khuyên tôi trao đổi với bác sĩ hoặc dược sĩ.
- Ưu tiên những thay đổi nhỏ mà tôi có thể duy trì lâu dài hơn là một lịch trình hoàn hảo nhưng tôi sẽ bỏ cuộc chỉ sau ba ngày.
- Nếu có thông tin nào trong dữ liệu đầu vào của tôi bị thiếu, hãy đưa ra một giả định hợp lý và nêu rõ giả định đó.
- Giữ giọng điệu khích lệ và ngôn ngữ đơn giản. Sử dụng các gạch đầu dòng ngắn gọn.

---
name: dependency-license-audit
description: Kiểm toán giấy phép của các gói phụ thuộc trong dự án dựa trên phương thức phân phối thực tế của bạn (SaaS, ứng dụng hoặc thư viện phân phối tới người dùng, hoặc công cụ nội bộ): chuẩn hóa tên giấy phép theo chuẩn SPDX, phân giải các biểu thức OR và AND, gắn cờ cảnh báo các giấy phép bị thiếu, AGPL, GPL, source-available (mã nguồn khả dụng) và các giấy phép không tương thích, đồng thời lập kế hoạch khắc phục theo thứ tự ưu tiên cùng danh sách thông báo bản quyền. Bao gồm một trình kiểm toán viết bằng thư viện chuẩn Python đã được kiểm thử.
---

# Kiểm toán Giấy phép Gói phụ thuộc (Dependency License Audit)

Bạn giúp các đội ngũ kỹ thuật phát hiện những vấn đề về giấy phép trong các gói phụ thuộc của họ trước khi đợt phát hành sản phẩm, cuộc thẩm định mua bán sáp nhập (M&A), hoặc bảng câu hỏi bảo mật của khách hàng tìm ra chúng. Bạn biến một danh sách gói phụ thuộc thô thành một danh sách ngắn gọn, được xếp hạng ưu tiên gồm những việc cần khắc phục, và giải thích từng mục bằng ngôn ngữ dễ hiểu. Bạn là một kỹ sư cẩn trọng chứ không phải luật sư: bạn gắn cờ cảnh báo rủi ro và chỉ rõ khi nào một chuyên gia có chuyên môn pháp lý cần phải đưa ra quyết định.

## Các tệp trong kỹ năng này

- `scripts/audit_licenses.py` - chuẩn hóa và phân loại mọi giấy phép của gói phụ thuộc, đồng thời đánh giá mức độ rủi ro theo mô hình phân phối đã chọn (chỉ dùng thư viện chuẩn Python 3)
- `references/license-categories.md` - ý nghĩa thực tế của các nhóm giấy phép cấp phép rộng rãi (permissive), copyleft yếu (weak copyleft), copyleft mạnh (strong copyleft), copyleft qua mạng (network copyleft), và mã nguồn khả dụng (source-available), kèm theo các mã định danh SPDX phổ biến
- `references/remediation-playbook.md` - cách khắc phục từng loại phát hiện, từ việc thay thế gói phụ thuộc cho đến bổ sung thông báo bản quyền
- `templates/license-audit-report.md` - bố cục báo cáo kiểm toán
- `examples/example-saas-audit.md` - một bài kiểm toán mẫu hoàn chỉnh cho hệ thống backend SaaS viết bằng Node.js

## Quy trình làm việc

### 1. Hiểu rõ cách dự án được phân phối
Hỏi người dùng, hoặc suy luận và nêu rõ dưới dạng giả định:
- Giấy phép của dự án: độc quyền (proprietary / mã nguồn đóng) hay giấy phép mã nguồn mở (mã SPDX).
- Mô hình phân phối: `saas` (người dùng chỉ truy cập qua mạng), `distributed` (ứng dụng di động hoặc máy tính để bàn, bản cài đặt tại chỗ on-prem, thiết bị phần cứng, SDK, thư viện phát hành công khai, container image cung cấp cho khách hàng), hoặc `internal` (chỉ nhân viên nội bộ sử dụng).
- Bất kỳ chính sách nào của công ty: danh sách các giấy phép luôn được phép và luôn bị chặn.
Cùng một gói phụ thuộc có thể hoàn toàn ổn đối với mô hình này nhưng lại là yếu tố chặn đứng (blocker) đối với mô hình khác, vì vậy tuyệt đối không được bỏ qua bước này.

### 2. Thu thập danh mục gói phụ thuộc (dependency inventory)
Ưu tiên kết quả xuất ra từ công cụ hơn là danh sách lập thủ công, và phải bao gồm cả các gói phụ thuộc bắc cầu (transitive dependencies):
- Python: `pip-licenses --format=json --with-system` (hoặc `pip-licenses --format=csv`).
- Node.js: `npx license-checker --json --production` (chạy lại một lần nữa không có cờ `--production` cho các công cụ phát triển dev tools).
- Bất kỳ ngôn ngữ/hệ thống nào khác: một tệp CSV có các cột `name,version,license,scope` được xuất từ SBOM hoặc trình quản lý gói.
Đánh dấu các công cụ biên dịch (build), kiểm thử (test) và kiểm tra mã nguồn (lint) là `scope=dev`; chúng không được phân phối kèm sản phẩm nên các phát hiện của chúng sẽ giảm xuống mức INFO.

### 3. Chạy kiểm toán
```bash
python3 scripts/audit_licenses.py deps.csv --project-license proprietary --distribution saas
python3 scripts/audit_licenses.py licenses.json --distribution distributed --deny AGPL-3.0-only
python3 scripts/audit_licenses.py deps.csv --json
```
Kịch bản sẽ in ra số lượng theo từng mức độ nghiêm trọng, một bảng liệt kê mọi gói phụ thuộc kèm giấy phép đã chuẩn hóa và danh mục phân loại, các phát hiện kèm lý do, những thay đổi giấy phép giữa các phiên bản, và các giấy phép cần đưa toàn văn vào tệp thông báo bên thứ ba (third-party notices) của bạn. Mã thoát (Exit code) 1 có nghĩa là có ít nhất một phát hiện ở mức HIGH.

Nếu bạn không thể chạy kịch bản, hãy phân loại thủ công từng giấy phép bằng tài liệu `references/license-categories.md` và nêu rõ việc đó trong báo cáo.

### 4. Xác minh trước khi kết luận
- Đối với mọi phát hiện ở mức HIGH hoặc WARN, hãy kiểm tra tệp LICENSE thực tế của gói đó trong kho lưu trữ (repository) hoặc gói nén (archive) của nó; siêu dữ liệu (metadata) thường bị sai hoặc lỗi thời.
- Đối với các mục bị "thiếu" ("missing") hoặc ghi "SEE LICENSE IN", hãy mở tệp được tham chiếu và phân loại dựa trên toàn văn nội dung của nó.
- Đối với các gói có giấy phép kép (OR), hãy ghi nhận rõ lựa chọn nào mà bạn chọn.
- Đối với các gói có giấy phép thay đổi giữa các phiên bản, hãy xác nhận xem phiên bản nào thực sự đang được cài đặt (kiểm tra tệp khóa lock file).

### 5. Khuyến nghị và lập báo cáo
Sử dụng `references/remediation-playbook.md` để đưa ra một hành động cụ thể cho từng phát hiện: thay thế, cô lập (isolate), ghim (pin) về phiên bản cũ hơn có giấy phép rộng rãi (permissive), mua giấy phép thương mại, tuân thủ (công bố mã nguồn hoặc thêm thông báo bản quyền), hoặc chấp nhận rủi ro kèm theo lý do được lưu hồ sơ. Điền vào mẫu `templates/license-audit-report.md`, tương tự như trong `examples/example-saas-audit.md`.

## Quy tắc
- Tuyệt đối không kết luận một giấy phép "hoàn toàn ổn" hay "bất hợp pháp" như một kết luận pháp lý. Hãy nêu những gì giấy phép đó thường yêu cầu và khi nào cần tham vấn cố vấn pháp lý.
- Không đoán mò giấy phép dựa trên tên gói hoặc mức độ phổ biến. Chưa rõ (Unknown) thì vẫn phải giữ là chưa rõ cho đến khi có người đọc văn bản giấy phép thực tế.
- Đánh giá rủi ro dựa trên mô hình phân phối của người dùng, đồng thời lưu ý những gì sẽ thay đổi nếu mô hình phân phối thay đổi (ví dụ hiện tại là SaaS, năm sau bán bản cài đặt tại chỗ on-prem).
- Giữ báo cáo ngắn gọn: liệt kê các yếu tố chặn (blockers) trước, tiếp theo là các nghĩa vụ (thông báo bản quyền, đề nghị cung cấp mã nguồn), sau đó gộp danh sách các gói an toàn thành một con số thống kê.
- Coi bản kiểm toán như một ảnh chụp tại một thời điểm (snapshot); khuyến nghị chạy kiểm toán tự động trong CI mỗi khi có thay đổi về gói phụ thuộc.
FILE:references/license-categories.md
# Các danh mục giấy phép trong thực tế

Mức độ nghiêm trọng trong kịch bản phụ thuộc vào danh mục giấy phép và cách thức dự án được phân phối. Trang này giải thích các danh mục bằng ngôn ngữ đời thường. Đây là bản tóm tắt về mặt kỹ thuật, không phải tư vấn pháp lý.

## Phạm vi công cộng và gần như phạm vi công cộng (Public domain and near public domain)
SPDX: `0BSD`, `Unlicense`, `CC0-1.0`, `MIT-0`, `WTFPL`
- Không có nghĩa vụ đáng kể nào. Việc giữ lại thông báo bản quyền vẫn là một thực hành tốt.

## Cấp phép rộng rãi (Permissive)
SPDX: `MIT`, `ISC`, `BSD-2-Clause`, `BSD-3-Clause`, `Apache-2.0`, `Zlib`, `BSL-1.0` (Boost), `PSF-2.0`, `Python-2.0`, `CC-BY-4.0` (dữ liệu như caniuse-lite)
- Được phép sử dụng, sửa đổi và phân phối trong các sản phẩm mã nguồn đóng.
- Phải giữ lại dòng thông báo bản quyền (copyright notice) và toàn văn giấy phép, thường đặt trong tệp thông báo bên thứ ba (third-party notices) hoặc màn hình "Giới thiệu / Giấy phép" ("About / Licenses").
- Apache-2.0 còn yêu cầu giữ lại mọi tệp NOTICE có sẵn, nêu rõ các thay đổi đáng kể đối với các tệp của nó, và bao gồm điều khoản cấp phép bằng sáng chế (patent grant) sẽ chấm dứt nếu bạn khởi kiện về bằng sáng chế liên quan đến mã nguồn đó.
- BSD-3-Clause cấm sử dụng tên của các tác giả để quảng bá cho sản phẩm của bạn.

## Copyleft yếu - cấp độ tệp hoặc thư viện (Weak copyleft)
SPDX: `LGPL-2.1-*`, `LGPL-3.0-*`, `MPL-2.0`, `EPL-1.0`, `EPL-2.0`, `CDDL-1.0`, `CDDL-1.1`, GPL đi kèm ngoại lệ liên kết (ví dụ `GPL-2.0-only WITH Classpath-exception-2.0`)
- Bạn có thể kết hợp chúng với mã nguồn đóng, nhưng bất kỳ sửa đổi nào đối với chính các tệp của thư viện đó đều phải được chia sẻ theo cùng giấy phép khi bạn phân phối.
- LGPL: người dùng phải có khả năng thay thế thư viện đó bằng phiên bản của riêng họ. Liên kết động (dynamic linking - thư viện dùng chung shared library, tệp jar riêng biệt, gói npm) thường giúp đáp ứng điều này dễ dàng; liên kết tĩnh (static linking) hoặc đóng gói gộp chung vào một tệp thực thi duy nhất (single binary) cần hết sức cẩn trọng.
- MPL-2.0: điều khoản copyleft áp dụng trên từng tệp (per file). Hãy giữ các tệp MPL tách biệt và công bố các thay đổi đối với những tệp đó.

## Copyleft mạnh (Strong copyleft)
SPDX: `GPL-2.0-only`, `GPL-2.0-or-later`, `GPL-3.0-only`, `GPL-3.0-or-later`
- Nếu bạn phân phối phần mềm có bao gồm hoặc liên kết với mã nguồn GPL, tác phẩm kết hợp phải được cung cấp theo giấy phép GPL kèm theo toàn bộ mã nguồn của nó.
- Việc chạy phần mềm GPL trên máy chủ của riêng bạn và để người dùng tương tác với nó qua mạng không được coi là hành vi phân phối (distribution), vì vậy việc sử dụng thuần túy cho mô hình SaaS thường được phép. Việc chuyển giao một ứng dụng, bộ cài đặt tại chỗ (on-prem installer), phần sụn thiết bị (device firmware), hoặc container image cho khách hàng được tính là hành vi phân phối.
- Phiên bản đóng vai trò rất quan trọng: mã nguồn `GPL-2.0-only` không thể kết hợp với mã nguồn GPL-3.0 hoặc Apache-2.0 trong cùng một tác phẩm. Hậu tố `-or-later` mang lại sự linh hoạt cao hơn.

## Copyleft qua mạng (Network copyleft)
SPDX: `AGPL-3.0-only`, `AGPL-3.0-or-later`, `SSPL-1.0` (chưa được OSI phê duyệt)
- Tương tự như GPL, cộng thêm điều khoản: nếu người dùng tương tác với một phiên bản đã sửa đổi qua mạng, bạn bắt buộc phải cung cấp mã nguồn của phiên bản đó cho họ.
- Đối với một sản phẩm SaaS mã nguồn đóng, đây là yếu tố chặn (blocker) phổ biến nhất. Ngay cả việc sử dụng bản gốc không sửa đổi cũng kích hoạt quy trình rà soát nội bộ tại hầu hết các công ty.
- SSPL còn đi xa hơn: việc cung cấp phần mềm đó dưới dạng dịch vụ (as a service) có thể đòi hỏi bạn phải công bố mã nguồn của toàn bộ ngăn xếp dịch vụ (service stack) của mình.

## Mã nguồn khả dụng và phi thương mại (Source-available and non-commercial)
SPDX hoặc tên thường gặp: `BUSL-1.1` (Business Source License), `Elastic-2.0`, các điều khoản bổ sung Commons Clause, `CC-BY-NC-*`, `PolyForm-Noncommercial-1.0.0`
- Mã nguồn được hiển thị công khai, nhưng quyền sử dụng bị hạn chế: thường cấm dùng để cung cấp dịch vụ lưu trữ cạnh tranh (competing hosted service), cấm sử dụng trong môi trường production vượt quá giới hạn cho phép, hoặc cấm hoàn toàn mục đích thương mại, đôi khi áp dụng cho đến một ngày chuyển đổi giấy phép (change date) nhất định.
- Luôn cần phải rà soát từng điều khoản chính xác. Nhiều giấy phép dạng này sẽ chuyển sang giấy phép mở sau một vài năm, vì vậy phiên bản cũ hơn hoặc mới hơn có thể mang điều khoản khác nhau.

## Chưa xác định (Unknown)
- Các trường giấy phép để trống, `UNKNOWN`, `NOASSERTION`, `UNLICENSED`, `SEE LICENSE IN <file>`, `LicenseRef-*`, hoặc một cái tên mà kịch bản không nhận diện được.
- "Không có giấy phép" ("No license") đồng nghĩa với việc tác giả giữ toàn bộ bản quyền (all rights reserved): bạn không có quyền sử dụng mã nguồn đó. Hãy tìm điều khoản cấp phép thực sự hoặc thay thế gói phụ thuộc đó.

## Biểu thức kết hợp (Expressions)
- `MIT OR Apache-2.0`: bạn có thể chọn một trong hai; hãy chọn giấy phép phù hợp với bạn và lưu hồ sơ lựa chọn đó.
- `MIT AND BSD-3-Clause`: bạn bắt buộc phải tuân thủ cả hai; giấy phép nghiêm ngặt nhất sẽ quyết định danh mục phân loại.
- `GPL-2.0-only WITH <exception>`: điều khoản ngoại lệ giúp thu hẹp phạm vi copyleft; hãy đọc kỹ nội dung ngoại lệ đó.
FILE:references/remediation-playbook.md
# Cẩm nang khắc phục (Remediation playbook)

Chọn một hành động cho mỗi phát hiện và ghi lại kèm theo người chịu trách nhiệm (owner). Ưu tiên hành động tốn ít chi phí nhất mà loại bỏ được rủi ro.

## Thứ tự ưu tiên xử lý
1. Các giấy phép chưa xác định (unknown) và bị thiếu (bạn có thể hoàn toàn không có quyền sử dụng mã nguồn đó).
2. Các gói thuộc nhóm copyleft qua mạng (network copyleft) và mã nguồn khả dụng (source-available) nằm trong mã nguồn được phân phối hoặc lưu trữ trên máy chủ dịch vụ (hosted code).
3. Nhóm copyleft mạnh (strong copyleft) trong các sản phẩm phân phối tới khách hàng, và sự không tương thích giữa các phiên bản giấy phép trong các dự án mã nguồn mở.
4. Các nghĩa vụ đối với nhóm copyleft yếu (liên kết động, công bố các thay đổi).
5. Thông báo bản quyền (notices) cho tất cả các gói còn lại.

## Các hành động cụ thể

### Tìm giấy phép thực sự
- Mở kho lưu trữ (repository) và gói nén (archive) của gói phụ thuộc, đọc tệp LICENSE, COPYING, hoặc phần tiêu đề (header) của tệp mã nguồn chính.
- Kiểm tra xem liệu siêu dữ liệu (metadata) có bị lỗi thời hay không (trường hợp rất phổ biến đối với các gói cũ và các bản fork).
- Nếu thực sự không có giấy phép nào, hãy nhờ người bảo trì (maintainer) bổ sung giấy phép (đính kèm liên kết tới choosealicense.com trong yêu cầu) hoặc thay thế gói phụ thuộc đó.

### Thay thế gói phụ thuộc
- Tìm kiếm một giải pháp thay thế đang được bảo trì tốt, có giấy phép rộng rãi (permissive) và API tương tự.
- Ước tính công sức thực hiện theo số giờ và đưa vào danh sách công việc tồn đọng (backlog) gắn với phiên bản phát hành bị nó chặn.
- Đối với các gói phụ thuộc bắc cầu (transitive dependencies), hãy tìm gói phụ thuộc trực tiếp đã kéo nó vào; việc đổi sang một phiên bản khác hoặc bật/tắt một cờ cấu hình thường sẽ loại bỏ được nó.

### Ghim (Pin) phiên bản theo giấy phép cũ
- Khi một dự án chuyển từ giấy phép rộng rãi sang giấy phép mã nguồn khả dụng (hoặc ngược lại), các phiên bản cũ vẫn giữ nguyên giấy phép cũ của chúng.
- Việc ghim phiên bản chỉ là giải pháp ngắn hạn: bạn sẽ không nhận được các bản cập nhật bảo mật. Hãy lên lịch thay thế triệt để.

### Cô lập gói phụ thuộc (Isolate it)
- Chạy công cụ mang giấy phép copyleft dưới dạng một tiến trình hoặc dịch vụ riêng biệt giao tiếp với mã nguồn của bạn qua dòng lệnh (CLI), giao thức HTTP, hoặc hàng đợi tin nhắn (queue), thay vì liên kết (link) trực tiếp nó vào mã nguồn của bạn.
- Giữ nguyên bản gốc không sửa đổi nếu có thể. Ghi lại tài liệu rõ ràng về ranh giới giao tiếp này.
- Đây là cách phổ biến để sử dụng các công cụ dòng lệnh mang giấy phép GPL, nhưng hãy nhờ cố vấn pháp lý xác nhận đối với trường hợp AGPL và SSPL.

### Mua giấy phép thương mại
- Nhiều dự án cấp phép kép (mã nguồn mở song song với bản thương mại) có bán giấy phép thương mại giúp loại bỏ các nghĩa vụ copyleft. Hãy lưu ý kỹ mức giá và điều khoản gia hạn.

### Tuân thủ các điều khoản (Comply)
- Copyleft yếu (Weak copyleft): giữ thư viện dưới dạng một tệp hoặc gói riêng biệt, có thể thay thế được; công bố bất kỳ thay đổi nào đối với chính các tệp của thư viện đó; đính kèm giấy phép của nó.
- GPL trong sản phẩm phân phối tới khách hàng: chỉ khả thi nếu toàn bộ sản phẩm có thể mở mã nguồn theo các điều khoản tương thích. Đây là một quyết định kinh doanh, không phải quyết định kỹ thuật.
- AGPL trong dịch vụ lưu trữ (hosted service): cung cấp mã nguồn tương ứng cho người dùng dịch vụ, bao gồm cả những sửa đổi của bạn.

### Chấp nhận kèm lý do được lưu hồ sơ
- Các công cụ chỉ phục vụ phát triển (linters, trình chạy kiểm thử, công cụ biên dịch) không bao giờ được phân phối kèm sản phẩm thường không gây rủi ro. Hãy ghi nhận rõ: "chỉ dùng cho dev, không phân phối".
- Việc sử dụng nội bộ các công cụ GPL hoặc AGPL thường không gây vấn đề. Hãy ghi nhận rõ ai là người sử dụng và xác nhận rằng công cụ đó không phơi bày ra cho người dùng bên ngoài.

## Thông báo bản quyền bên thứ ba (Third-party notices)
- Tạo một tệp thông báo bản quyền từ danh mục gói phụ thuộc: tên gói, phiên bản, giấy phép, dòng bản quyền (copyright line), toàn văn giấy phép (mỗi nội dung giấy phép khác nhau chỉ cần lưu một bản).
- Đính kèm nguyên trạng các tệp NOTICE của giấy phép Apache.
- Phân phối tệp này bên trong ứng dụng ("Cài đặt > Giới thiệu > Giấy phép"), bộ cài đặt và container image; đối với SaaS, hãy đặt liên kết tới nó ở chân trang (footer) hoặc trong trang tài liệu.

## Duy trì sự minh bạch và sạch sẽ
- Chạy kiểm toán tự động trong CI mỗi khi có thay đổi đối với tệp khóa (lock file) và cho dừng lỗi quá trình biên dịch (fail build) nếu có phát hiện mức HIGH.
- Duy trì một danh sách cho phép (allow list - ví dụ: MIT, BSD, ISC, Apache-2.0) và một danh sách chặn (deny list - ví dụ: AGPL-3.0, SSPL-1.0, BUSL-1.1) đã được thống nhất với cố vấn pháp lý, và truyền chúng vào kịch bản qua tham số `--allow` và `--deny`.
FILE:templates/license-audit-report.md
# Báo cáo Kiểm toán Giấy phép Gói phụ thuộc: <tên dự án>

Ngày: <YYYY-MM-DD>
Giấy phép dự án: <proprietary | mã SPDX>
Mô hình phân phối: <saas | distributed | internal> (<một dòng mô tả cách người dùng tiếp cận phần mềm>)
Nguồn danh mục: <công cụ và câu lệnh, mã commit của tệp khóa lock file>
Số gói đã kiểm toán: <n> (<runtime n>, <dev n>)

## Tóm tắt
- Các yếu tố chặn - Blockers (HIGH): <n> - <một dòng liệt kê tên các gói>
- Các nghĩa vụ - Obligations (WARN): <n> - <một dòng tóm tắt>
- Lưu ý - Notes (INFO): <n>
- Hợp lệ - Clean (OK): <n>
- Kết luận (Verdict): <sẵn sàng phát hành | phát hành sau khi khắc phục | bị chặn> bởi vì <lý do>.

## Các yếu tố chặn (Blockers)
| Gói | Phiên bản | Giấy phép (theo phát hiện) | Danh mục | Tại sao lại quan trọng với chúng ta | Hành động | Người phụ trách | Hạn chót |
|---|---|---|---|---|---|---|---|
| | | | | | | | |

## Các nghĩa vụ (Obligations)
| Gói | Giấy phép | Việc chúng ta phải làm | Đã hoàn thành? |
|---|---|---|---|
| | | | |

## Đã xác minh thủ công
- <tên gói>: siêu dữ liệu ghi là <x>, tệp LICENSE thực tế ghi là <y>.

## Các quyết định và giả định
- Các gói có giấy phép kép và phương án đã chọn: <tên gói: phương án>
- Các rủi ro được chấp nhận kèm lý do: <tên gói: lý do, người phê duyệt>
- Các giả định: <ví dụ: "bảng điều khiển quản trị chỉ dùng trong nội bộ">

## Điều gì sẽ thay đổi nếu chúng ta thay đổi phương thức phân phối
- <ví dụ: "Nếu chúng ta phát hành phiên bản cài đặt tại chỗ (on-prem), gói readline-sync (GPL-3.0) sẽ trở thành yếu tố chặn.">

## Thông báo bản quyền bên thứ ba (Third-party notices)
Các giấy phép cần đưa toàn văn vào tệp thông báo: <danh sách>
Vị trí tệp thông báo: <đường dẫn hoặc URL>

## Đợt kiểm toán tiếp theo
Chạy tự động trong CI mỗi khi tệp khóa (lock file) thay đổi; rà soát toàn diện trước <đợt phát hành tiếp theo hoặc ngày cụ thể>.

_Báo cáo này là bước sàng lọc kỹ thuật, không phải tư vấn pháp lý. Các yếu tố chặn bắt buộc phải được cố vấn pháp lý xác nhận trước khi dựa vào bất kỳ điều khoản ngoại lệ nào._
FILE:examples/example-saas-audit.md
# Ví dụ: Kiểm toán giấy phép cho hệ thống backend SaaS bằng Node.js

## Yêu cầu
"Chúng tôi là một dịch vụ B2B SaaS mã nguồn đóng. Các khách hàng doanh nghiệp liên tục gửi các bảng câu hỏi bảo mật hỏi về giấy phép mã nguồn mở, và năm tới chúng tôi có thể sẽ bán thêm phiên bản cài đặt tại chỗ (on-prem). Đây là bản xuất danh sách các gói phụ thuộc của chúng tôi. Có điều gì chúng tôi cần lo lắng không?"

Danh mục gói phụ thuộc (`deps.csv`, được xuất từ tệp khóa lock file, 18 dòng):
```
name,version,license,scope
express,4.19.2,MIT,runtime
lodash,4.17.21,MIT,runtime
pg,8.12.0,MIT,runtime
sharp,0.33.4,Apache-2.0,runtime
dompurify,3.1.6,(MPL-2.0 OR Apache-2.0),runtime
ghostscript-wrapper,2.1.0,AGPL-3.0-only,runtime
chart-kit-pro,1.4.0,SEE LICENSE IN LICENSE.md,runtime
readline-sync,1.4.10,GPL-3.0,runtime
mariadb-connector,3.3.1,LGPL-2.1-or-later,runtime
fast-csv-lite,0.9.0,,runtime
redis-om,0.4.3,Business Source License 1.1,runtime
jest,29.7.0,MIT,dev
eslint-plugin-gpl-thing,1.0.2,GPL-2.0-only,dev
argparse,2.0.1,Python-2.0,runtime
tslib,2.6.3,0BSD,runtime
lodash,3.10.1,MIT,runtime
search-client,7.10.2,Apache-2.0,runtime
search-client,8.1.0,Elastic License 2.0,runtime
```

## Kết quả chạy kịch bản
```
$ python3 scripts/audit_licenses.py deps.csv --project-license proprietary --distribution saas
Dependency license audit: 18 packages, project license proprietary, distribution saas
HIGH 5  WARN 1  INFO 2  OK 10
...
HIGH  chart-kit-pro@1.4.0           SEE LICENSE IN LICENSE.md    unknown           runtime
HIGH  fast-csv-lite@0.9.0           (missing)                    unknown           runtime
HIGH  redis-om@0.4.3                BUSL-1.1                     source-available  runtime
HIGH  search-client@8.1.0           Elastic-2.0                  source-available  runtime
HIGH  ghostscript-wrapper@2.1.0     AGPL-3.0-only                network-copyleft  runtime
WARN  readline-sync@1.4.10          GPL-3.0-only                 strong-copyleft   runtime
INFO  eslint-plugin-gpl-thing@1.0.2 GPL-2.0-only                 strong-copyleft   dev
INFO  mariadb-connector@3.3.1       LGPL-2.1-or-later            weak-copyleft     runtime
...
Notes:
- search-client: different licenses across versions (Apache-2.0, Elastic-2.0); check which version you ship.
```
Mã thoát (Exit code) 1 (có các phát hiện mức HIGH).

## Báo cáo (mẫu đã điền thông tin, rút gọn)

# Báo cáo Kiểm toán Giấy phép Gói phụ thuộc: acme-api

Giấy phép dự án: proprietary (độc quyền). Mô hình phân phối: saas (khách hàng sử dụng ứng dụng web và REST API; hiện tại không có gì được cài đặt trên máy của khách hàng).
Số gói đã kiểm toán: 18 (16 runtime, 2 dev).

### Tóm tắt
- Các yếu tố chặn - Blockers (HIGH): 5 - hai gói không có giấy phép sử dụng hợp lệ, hai gói thuộc nhóm mã nguồn khả dụng (source-available), một gói mang giấy phép AGPL.
- Các nghĩa vụ - Obligations (WARN): 1 - một gói mang giấy phép GPL-3.0 hoàn toàn ổn đối với mô hình SaaS nhưng sẽ chặn đứng phiên bản cài đặt tại chỗ (on-prem) đang lên kế hoạch.
- Kết luận (Verdict): phát hành sau khi khắc phục. Không có vấn đề nào ở đây là bất thường, và mỗi mục đều có cách khắc phục ít tốn kém.

### Các yếu tố chặn (Blockers)
| Gói | Giấy phép (theo phát hiện) | Tại sao lại quan trọng với chúng ta | Hành động |
|---|---|---|---|
| chart-kit-pro 1.4.0 | SEE LICENSE IN LICENSE.md | Tệp LICENSE.md là một giấy phép thương mại chỉ cho phép sử dụng khi có khóa trả phí (paid key). Chúng ta chưa ghi nhận khóa nào trong hồ sơ. | Xác nhận lại với nhóm đã mua gói này, hoặc thay thế bằng một thư viện vẽ biểu đồ có giấy phép rộng rãi (permissive). |
| fast-csv-lite 0.9.0 | (missing) | Không có giấy phép đồng nghĩa với việc không được phép sử dụng. | Yêu cầu người bảo trì bổ sung giấy phép; trong lúc chờ đợi, chuyển sang sử dụng một trình phân tích CSV đang được bảo trì tốt có điều khoản MIT. |
| redis-om 0.4.3 | BUSL-1.1 | Giấy phép Business Source License giới hạn việc sử dụng trên môi trường production cho đến ngày chuyển đổi giấy phép của nó; các điều khoản cụ thể thay đổi tùy theo từng dự án. | Đọc kỹ điều khoản "Additional Use Grant" chính xác. Nếu nó cấm trường hợp sử dụng của chúng ta, hãy thay thế hoặc mua giấy phép thương mại. |
| search-client 8.1.0 | Elastic-2.0 | Giấy phép Elastic License 2.0 cấm việc cung cấp phần mềm này dưới dạng một dịch vụ được quản lý (managed service). Phiên bản 7.10.2 nằm trong cùng cây phụ thuộc lại mang giấy phép Apache-2.0. | Kiểm tra tệp khóa (lock file): những module nào đang import phiên bản 8.1.0? Ghim cả hai về nhánh phiên bản dùng Apache-2.0 hoặc chuyển sang một nhánh fork được cấp phép theo Apache. |
| ghostscript-wrapper 2.1.0 | AGPL-3.0-only | Chúng ta dùng nó để kết xuất (render) tệp PDF của khách hàng ngay bên trong API; việc sử dụng qua mạng đối với AGPL đòi hỏi phải cung cấp mã nguồn cho người dùng. | Chuyển việc kết xuất PDF sang một dịch vụ worker tách biệt, giữ nguyên không sửa đổi và nhờ cố vấn pháp lý xác nhận, hoặc mua giấy phép thương mại. |

### Các nghĩa vụ (Obligations)
| Gói | Giấy phép | Việc chúng ta phải làm |
|---|---|---|
| readline-sync 1.4.10 | GPL-3.0-only | Hoàn toàn ổn đối với mô hình SaaS. Nó sẽ trở thành yếu tố chặn nếu phiên bản cài đặt tại chỗ (on-prem) được đóng gói kèm theo nó. Gói này chỉ được sử dụng bởi một kịch bản CLI quản trị, vì vậy hãy gỡ bỏ nó khỏi server image. |
| mariadb-connector 3.3.1 | LGPL-2.1-or-later | Giữ nó dưới dạng một gói phụ thuộc npm thông thường (có thể thay thế được); công bố các thay đổi nếu chúng ta có vá (patch) mã nguồn của nó. |

### Đã xác minh thủ công
- dompurify: cấp phép kép `MPL-2.0 OR Apache-2.0`; chúng ta chọn Apache-2.0.
- eslint-plugin-gpl-thing: chỉ dùng cho môi trường dev, không bao giờ được phân phối. Chấp nhận.

### Điều gì sẽ thay đổi nếu chúng ta phân phối bản cài đặt tại chỗ (on-prem)
- readline-sync (GPL-3.0) sẽ chuyển thành mức HIGH, mariadb-connector (LGPL) cần được kiểm tra khả năng thay thế thư viện, và các gói Apache-2.0 cần đưa các tệp NOTICE của chúng vào trong bộ cài đặt. Hãy chạy lại kiểm toán với tham số `--distribution distributed` trước đợt phát hành đó.

### Thông báo bản quyền bên thứ ba (Third-party notices)
Các giấy phép cần đưa toàn văn: Apache-2.0, LGPL-2.1-or-later, MIT, Python-2.0. Đặt liên kết tới trang thông báo bản quyền ở phần chân trang (footer) của ứng dụng.

_Sàng lọc kỹ thuật, không phải tư vấn pháp lý._

## Tại sao đây là một câu trả lời tốt
- Đánh giá mọi gói phụ thuộc dựa trên mô hình phân phối thực tế của công ty này, đồng thời chỉ rõ những gì sẽ thay đổi đối với kế hoạch phát hành bản on-prem.
- Kiểm tra những dữ kiện thực tế mà siêu dữ liệu (metadata) không thể hiển thị (tệp LICENSE.md thương mại, các phiên bản search-client bị trùng lặp).
- Mọi yếu tố chặn đều đi kèm một hành động giải quyết cụ thể và ít tốn kém.
FILE:scripts/audit_licenses.py
#!/usr/bin/env python3
"""Audit third-party dependency licenses against how a project is shipped.

Usage:
  python3 audit_licenses.py deps.csv --project-license proprietary --distribution saas
  python3 audit_licenses.py licenses.json --distribution distributed [--json]
  cat deps.csv | python3 audit_licenses.py - [--allow LIC,LIC] [--deny LIC,LIC]

Input (detected automatically):
  CSV with a header: name,version,license[,scope]   (scope: runtime | dev; default runtime)
  JSON list:   [{"name": "...", "version": "...", "license": "...", "scope": "dev"}]
  pip-licenses --format=json:  [{"Name": "...", "Version": "...", "License": "..."}]
  license-checker --json (npm): {"pkg@1.2.3": {"licenses": "MIT"}, ...}
Options:
  --project-license  your project's license: proprietary (default) or an SPDX id such as MIT, Apache-2.0, GPL-3.0-only
  --distribution     saas (network service, default) | distributed (apps, binaries, devices, libraries) | internal
  --allow / --deny   comma-separated SPDX ids that your policy always allows or always blocks
  --json             machine-readable output

License names are normalized to SPDX ids, expressions with OR take the most
permissive option and AND takes the most restrictive one. Each package gets a
category and a severity (OK, INFO, WARN, HIGH) for the chosen distribution.
Dev-only packages are not shipped, so their findings drop to INFO.
Exit code: 0 no HIGH findings, 1 at least one HIGH, 2 usage or input error.
This is an engineering triage aid, not legal advice. Standard library only.
"""
import argparse
import csv
import io
import json
import re
import sys

ALIASES = {  # lowercased common names -> SPDX id
    "mit": "MIT", "mit license": "MIT", "the mit license": "MIT", "expat": "MIT",
    "isc": "ISC", "isc license": "ISC", "isc license (iscl)": "ISC",
    "apache 2.0": "Apache-2.0", "apache-2": "Apache-2.0", "apache 2": "Apache-2.0", "apache2": "Apache-2.0",
    "apache license 2.0": "Apache-2.0", "apache license, version 2.0": "Apache-2.0",
    "apache software license": "Apache-2.0", "apache license version 2.0": "Apache-2.0",
    "bsd": "BSD-3-Clause", "bsd license": "BSD-3-Clause", "new bsd": "BSD-3-Clause", "bsd-3": "BSD-3-Clause",
    "3-clause bsd": "BSD-3-Clause", "bsd 3-clause": "BSD-3-Clause", "simplified bsd": "BSD-2-Clause",
    "bsd-2": "BSD-2-Clause", "2-clause bsd": "BSD-2-Clause",
    "python software foundation license": "PSF-2.0", "psf": "PSF-2.0", "psfl": "PSF-2.0",
    "mozilla public license 2.0 (mpl 2.0)": "MPL-2.0", "mpl 2.0": "MPL-2.0", "mpl-2": "MPL-2.0", "mpl2": "MPL-2.0",
    "gplv2": "GPL-2.0-only", "gpl-2.0": "GPL-2.0-only", "gpl v2": "GPL-2.0-only", "gpl2": "GPL-2.0-only",
    "gplv2+": "GPL-2.0-or-later", "gpl-2.0+": "GPL-2.0-or-later",
    "gplv3": "GPL-3.0-only", "gpl-3.0": "GPL-3.0-only", "gpl v3": "GPL-3.0-only", "gpl3": "GPL-3.0-only",
    "gplv3+": "GPL-3.0-or-later", "gpl-3.0+": "GPL-3.0-or-later", "gpl": "GPL-3.0-or-later",
    "gnu general public license v2 (gplv2)": "GPL-2.0-only", "gnu general public license v3 (gplv3)": "GPL-3.0-only",
    "gnu general public license v2 or later (gplv2+)": "GPL-2.0-or-later",
    "gnu general public license v3 or later (gplv3+)": "GPL-3.0-or-later",
    "lgpl": "LGPL-2.1-or-later", "lgplv2": "LGPL-2.1-only", "lgplv2+": "LGPL-2.1-or-later", "lgpl-2.1": "LGPL-2.1-only",
    "lgplv3": "LGPL-3.0-only", "lgplv3+": "LGPL-3.0-or-later", "lgpl-3.0": "LGPL-3.0-only",
    "gnu lesser general public license v2 (lgplv2)": "LGPL-2.1-only",
    "gnu lesser general public license v3 (lgplv3)": "LGPL-3.0-only",
    "gnu lesser general public license v2 or later (lgplv2+)": "LGPL-2.1-or-later",
    "agpl": "AGPL-3.0-only", "agplv3": "AGPL-3.0-only", "agpl-3.0": "AGPL-3.0-only",
    "gnu affero general public license v3": "AGPL-3.0-only", "gnu affero general public license v3 (agplv3)": "AGPL-3.0-only",
    "eclipse public license 2.0": "EPL-2.0", "epl 2.0": "EPL-2.0", "epl-2": "EPL-2.0",
    "public domain": "Unlicense", "unlicense": "Unlicense", "the unlicense": "Unlicense", "cc0": "CC0-1.0",
    "boost software license 1.0": "BSL-1.0", "zlib license": "Zlib", "zlib": "Zlib",
    "business source license 1.1": "BUSL-1.1", "elastic license 2.0": "Elastic-2.0",
    "server side public license": "SSPL-1.0", "sspl": "SSPL-1.0",
}
CATEGORY = {  # SPDX id prefix -> category
    "MIT": "permissive", "MIT-0": "public-domain", "ISC": "permissive", "BSD-2-Clause": "permissive",
    "BSD-3-Clause": "permissive", "Apache-2.0": "permissive", "PSF-2.0": "permissive", "Python-2.0": "permissive",
    "Zlib": "permissive", "BSL-1.0": "permissive", "X11": "permissive", "BlueOak-1.0.0": "permissive",
    "CC-BY-4.0": "permissive", "CC-BY-3.0": "permissive", "Unicode-DFS-2016": "permissive", "Unicode-3.0": "permissive",
    "0BSD": "public-domain", "Unlicense": "public-domain", "CC0-1.0": "public-domain", "WTFPL": "public-domain",
    "MPL-2.0": "weak-copyleft", "EPL-1.0": "weak-copyleft", "EPL-2.0": "weak-copyleft", "CDDL-1.0": "weak-copyleft",
    "CDDL-1.1": "weak-copyleft", "LGPL-2.1": "weak-copyleft", "LGPL-3.0": "weak-copyleft", "CC-BY-SA-4.0": "weak-copyleft",
    "GPL-2.0": "strong-copyleft", "GPL-3.0": "strong-copyleft",
    "AGPL-3.0": "network-copyleft", "SSPL-1.0": "network-copyleft",
    "BUSL-1.1": "source-available", "Elastic-2.0": "source-available", "Commons-Clause": "source-available",
    "CC-BY-NC-4.0": "source-available", "CC-BY-NC-SA-4.0": "source-available", "PolyForm-Noncommercial-1.0.0": "source-available",
}
RANK = {"public-domain": 0, "permissive": 1, "weak-copyleft": 2, "strong-copyleft": 3,
        "network-copyleft": 4, "source-available": 5, "unknown": 6}
SEV_ORDER = {"HIGH": 0, "WARN": 1, "INFO": 2, "OK": 3}
NOTICE_LICENSES = {"Apache-2.0"}


def unwrap(text):
    """Remove parentheses that wrap the whole expression: '(MIT OR X)' -> 'MIT OR X'."""
    t = text.strip()
    while t.startswith("(") and t.endswith(")"):
        depth = 0
        for i, ch in enumerate(t):
            depth += ch == "("
            depth -= ch == ")"
            if depth == 0 and i < len(t) - 1:
                return t
        t = t[1:-1].strip()
    return t


def normalize(token):
    t = unwrap(token)
    if not t:
        return ""
    key = t.lower()
    if key in ALIASES:
        return ALIASES[key]
    for spdx in CATEGORY:
        if key == spdx.lower() or key.startswith(spdx.lower() + "-") or key == spdx.lower() + "+":
            return t if key.startswith(spdx.lower() + "-") else spdx
    return t


def category_of(spdx):
    if spdx.upper().startswith("LICENSEREF") or spdx.upper().startswith("SEE LICENSE"):
        return "unknown"
    for prefix, cat in sorted(CATEGORY.items(), key=lambda kv: -len(kv[0])):
        if spdx == prefix or spdx.startswith(prefix + "-") or spdx.startswith(prefix + "+"):
            return cat
    return "unknown"


def classify(expr):
    """Return (normalized expression, chosen license, category, exception) for a license expression."""
    raw = (expr or "").strip()
    if not raw or raw.upper() in ("UNKNOWN", "NONE", "NOASSERTION", "UNLICENSED", "CUSTOM", "N/A"):
        return raw or "(missing)", raw or "(missing)", "unknown", None
    if raw.upper().startswith("SEE LICENSE"):
        return raw, raw, "unknown", None
    whole = unwrap(raw)
    if whole.lower() in ALIASES:  # long names such as "... v2 or later (LGPLv2+)" are one license
        spdx = ALIASES[whole.lower()]
        return spdx, spdx, category_of(spdx), None
    text = re.sub(r"\s+", " ", whole.replace("/", " OR ").replace(";", " OR "))
    exception = None
    m = re.search(r"\bWITH\s+([\w.+-]+)", text, re.I)
    if m:
        exception = m.group(1)
        text = text[:m.start()] + text[m.end():]
    if re.search(r"\sor\s", text, re.I) and not re.search(r"\sand\s", text, re.I):
        parts, mode = re.split(r"\s+or\s+", text, flags=re.I), "or"
    elif re.search(r"\sand\s", text, re.I) and not re.search(r"\sor\s", text, re.I):
        parts, mode = re.split(r"\s+and\s+", text, flags=re.I), "and"
    elif re.search(r"\s(or|and)\s", text, re.I):
        parts, mode = re.split(r"\s+(?:or|and)\s+", text, flags=re.I), "and"  # mixed: be conservative
    else:
        parts, mode = [text], "single"
    lics = [normalize(p) for p in parts if normalize(p)]
    if not lics:
        return raw, raw, "unknown", exception
    scored = sorted(lics, key=lambda l: RANK[category_of(l)])
    chosen = scored[0] if mode == "or" else scored[-1]
    cat = category_of(chosen)
    if exception and cat == "strong-copyleft" and re.search(r"classpath|linking|gcc|runtime|autoconf|bison|bootloader", exception, re.I):
        cat = "weak-copyleft"
    joiner = " OR " if mode == "or" else " AND "
    return joiner.join(lics) + (f" WITH {exception}" if exception else ""), chosen, cat, exception


def assess(cat, chosen, distribution, project):
    proj_cat = "proprietary" if project.lower() == "proprietary" else category_of(normalize(project))
    project_spdx = normalize(project)
    if cat == "unknown":
        return "HIGH", "License is missing or not recognized; find the real license text before shipping."
    if cat == "source-available":
        return "HIGH", "Source-available or non-commercial terms usually restrict commercial use or hosting; needs a license review."
    if project_spdx.startswith("GPL-2.0-only") and chosen.startswith("Apache-2.0"):
        return "HIGH", "Apache-2.0 is generally considered incompatible with GPL-2.0-only projects."
    gpl3_family = re.match(r"(A|L)?GPL-3\.0", chosen)
    if project_spdx.startswith("GPL-2.0-only") and gpl3_family:
        return "HIGH", f"{chosen} cannot be combined with a GPL-2.0-only project; the project would need GPL-3.0 terms."
    if re.match(r"GPL-3\.0|AGPL-3\.0", project_spdx) and chosen.startswith("GPL-2.0-only"):
        return "HIGH", "GPL-2.0-only code cannot be relicensed under GPL-3.0; ask upstream for 'or later' terms or replace it."
    if proj_cat in ("strong-copyleft", "network-copyleft") and cat in ("strong-copyleft", "network-copyleft"):
        if cat == "network-copyleft" and proj_cat != "network-copyleft" and distribution == "saas":
            return "WARN", "AGPL/SSPL in a GPL project run as a service: the whole service source must be offered to users."
        return "OK", "Copyleft dependency in a copyleft project; check version compatibility (for example GPL-2.0-only vs GPL-3.0)."
    if cat == "network-copyleft":
        if distribution == "internal":
            return "WARN", "Network copyleft: fine for purely internal use, but exposing it to outside users triggers source obligations."
        return "HIGH", "Network copyleft (AGPL/SSPL): offering the service or shipping it requires releasing the corresponding source."
    if cat == "strong-copyleft":
        if distribution == "distributed":
            return "HIGH", "GPL code distributed with your product requires the combined work to be released under the GPL."
        if distribution == "saas":
            return "WARN", "GPL is not triggered by network use alone, but any future distribution (apps, on-prem, SDKs) would be."
        return "INFO", "GPL for internal use only has no distribution obligations; keep it out of anything you ship."
    if cat == "weak-copyleft":
        if distribution == "distributed":
            return "WARN", "Weak copyleft: ship the license, keep the library replaceable (dynamic linking for LGPL), and publish changes to its files."
        return "INFO", "Weak copyleft: publish any changes you make to this library's own files if you distribute it later."
    if chosen in NOTICE_LICENSES and distribution == "distributed":
        return "INFO", "Apache-2.0: include the license and any NOTICE file in your distribution."
    return "OK", "Permissive: keep the copyright notice and license text in your third-party notices."


def load(text):
    stripped = text.lstrip()
    if not stripped:
        raise ValueError("input is empty")
    if stripped[0] in "[{":
        data = json.loads(text)
        rows = []
        if isinstance(data, dict):  # license-checker
            for key, val in data.items():
                name, _, ver = key.rpartition("@")
                if not name:
                    name, ver = key, ""
                lic = val.get("licenses", "") if isinstance(val, dict) else val
                if isinstance(lic, list):
                    lic = " OR ".join(lic)
                rows.append({"name": name, "version": ver, "license": str(lic), "scope": "runtime"})
            return rows
        for item in data:
            if not isinstance(item, dict):
                raise ValueError("JSON list items must be objects")
            low = {k.lower(): v for k, v in item.items()}
            lic = low.get("license", low.get("licenses", ""))
            if isinstance(lic, list):
                lic = " OR ".join(lic)
            rows.append({"name": str(low.get("name", "")), "version": str(low.get("version", "")),
                         "license": str(lic or ""), "scope": str(low.get("scope", "runtime") or "runtime").lower()})
        return rows
    reader = csv.DictReader(io.StringIO(text))
    fields = [f.strip().lower() for f in (reader.fieldnames or [])]
    if "name" not in fields or "license" not in fields:
        raise ValueError(f"CSV needs a header with at least 'name' and 'license' columns, got: {', '.join(fields) or '(none)'}")
    rows = []
    for r in reader:
        r = {(k or "").strip().lower(): (v or "").strip() for k, v in r.items()}
        if not r.get("name"):
            continue
        rows.append({"name": r["name"], "version": r.get("version", ""), "license": r.get("license", ""),
                     "scope": (r.get("scope") or "runtime").lower()})
    return rows


def audit(rows, args):
    allow = {normalize(x) for x in args.allow.split(",") if x.strip()} if args.allow else set()
    deny = {normalize(x) for x in args.deny.split(",") if x.strip()} if args.deny else set()
    results, seen = [], {}
    for r in rows:
        expr, chosen, cat, exc = classify(r["license"])
        sev, why = assess(cat, chosen, args.distribution, args.project_license)
        if exc:
            why += f" License exception {exc} applies; read its exact scope."
        if chosen in deny:
            sev, why = "HIGH", f"{chosen} is on your deny list."
        elif chosen in allow and sev != "OK":
            sev, why = "OK", f"{chosen} is on your allow list ({why})"
        dev = r["scope"] in ("dev", "development", "test", "build")
        if dev and sev in ("HIGH", "WARN") and chosen not in deny:
            sev, why = "INFO", "Dev-only (not shipped): " + why
        results.append({"name": r["name"], "version": r["version"], "license_raw": r["license"],
                        "license": expr, "effective": chosen, "category": cat, "scope": "dev" if dev else "runtime",
                        "severity": sev, "reason": why})
        seen.setdefault(r["name"].lower(), set()).add(expr)
    notes = []
    for name, lics in seen.items():
        if len(lics) > 1:
            notes.append(f"{name}: different licenses across versions ({', '.join(sorted(lics))}); check which version you ship.")
    results.sort(key=lambda x: (SEV_ORDER[x["severity"]], -RANK[x["category"]], x["name"].lower()))
    counts = {s: sum(1 for x in results if x["severity"] == s) for s in SEV_ORDER}
    cats = {}
    for x in results:
        cats[x["category"]] = cats.get(x["category"], 0) + 1
    attribution = sorted({x["effective"] for x in results if x["scope"] == "runtime" and x["category"] in ("permissive", "weak-copyleft")})
    return {"project_license": args.project_license, "distribution": args.distribution, "packages": len(results),
            "severity_counts": counts, "category_counts": cats, "attribution_licenses": attribution,
            "notes": notes, "results": results}


def print_text(rep):
    print(f"Dependency license audit: {rep['packages']} packages, project license {rep['project_license']}, distribution {rep['distribution']}")
    c = rep["severity_counts"]
    print(f"HIGH {c['HIGH']}  WARN {c['WARN']}  INFO {c['INFO']}  OK {c['OK']}")
    print("Categories: " + ", ".join(f"{k} {v}" for k, v in sorted(rep["category_counts"].items(), key=lambda kv: RANK[kv[0]])))
    print()
    w = max([len(f"{x['name']}@{x['version']}") for x in rep["results"]] + [7])
    print(f"{'SEV':<5} {'PACKAGE':<{w}} {'LICENSE':<28} {'CATEGORY':<17} SCOPE")
    for x in rep["results"]:
        pkg = f"{x['name']}@{x['version']}" if x["version"] else x["name"]
        print(f"{x['severity']:<5} {pkg:<{w}} {x['license'][:28]:<28} {x['category']:<17} {x['scope']}")
    findings = [x for x in rep["results"] if x["severity"] in ("HIGH", "WARN", "INFO")]
    if findings:
        print("\nFindings:")
        for x in findings:
            print(f"- [{x['severity']}] {x['name']} ({x['license_raw'] or 'no license field'}): {x['reason']}")
    if rep["notes"]:
        print("\nNotes:")
        for n in rep["notes"]:
            print(f"- {n}")
    if rep["attribution_licenses"]:
        print("\nThird-party notices must include license texts for: " + ", ".join(rep["attribution_licenses"]))
    print("\nTriage aid only, not legal advice.")


def main():
    p = argparse.ArgumentParser(description="Audit dependency licenses.", add_help=True)
    p.add_argument("path", help="CSV or JSON file, or - for stdin")
    p.add_argument("--project-license", default="proprietary")
    p.add_argument("--distribution", default="saas", choices=["saas", "distributed", "internal"])
    p.add_argument("--allow", default="")
    p.add_argument("--deny", default="")
    p.add_argument("--json", action="store_true")
    args = p.parse_args()
    try:
        text = sys.stdin.read() if args.path == "-" else open(args.path, encoding="utf-8").read()
        rows = load(text)
    except FileNotFoundError:
        print(f"error: file not found: {args.path}", file=sys.stderr)
        return 2
    except (ValueError, json.JSONDecodeError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    if not rows:
        print("error: no dependencies found in the input", file=sys.stderr)
        return 2
    rep = audit(rows, args)
    if args.json:
        print(json.dumps(rep, indent=2))
    else:
        print_text(rep)
    return 1 if rep["severity_counts"]["HIGH"] else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: markdown-accessibility-checker
description: Đánh giá tài liệu Markdown (README, trang tài liệu, wiki, bài viết blog, nhật ký thay đổi/changelogs) về khả năng tiếp cận (accessibility) - thiếu hoặc viết kém văn bản thay thế (alt text) cho hình ảnh, cấu trúc tiêu đề, văn bản liên kết mơ hồ hoặc trùng lặp, URL trần, tiêu đề bảng để trống, hướng dẫn chỉ dựa vào màu sắc, chữ IN HOA TOÀN BỘ và dấu đầu dòng bằng emoji - sau đó viết alt text chuẩn xác cho từng hình ảnh dựa theo ngữ cảnh và trả về danh sách các điểm cần sửa hoặc tệp đã hoàn chỉnh. Sử dụng khi người dùng yêu cầu "kiểm tra khả năng tiếp cận cho tệp README của tôi", "viết alt text cho những hình ảnh này", "làm cho tài liệu của chúng tôi thân thiện với trình đọc màn hình", hoặc muốn tích hợp bước kiểm tra khả năng tiếp cận cho Markdown vào quy trình CI.
---

# Công cụ Kiểm tra Khả năng Tiếp cận Markdown (Markdown Accessibility Checker)

Bạn giúp các tài liệu Markdown trở nên dễ tiếp cận với tất cả mọi người, bao gồm những người sử dụng trình đọc màn hình (screen readers), điều hướng bằng bàn phím, công cụ phóng đại màn hình hoặc thiết bị hỗ trợ đọc. Bạn phát hiện những vấn đề mà kịch bản tự động có thể nhận diện, rồi thực hiện phần việc mà kịch bản không thể làm thay: viết văn bản thay thế (alt text) và văn bản liên kết có ý nghĩa, bám sát mục đích của tài liệu.

## Các tệp trong kỹ năng này

- `scripts/check_md_a11y.py` - quét các tệp hoặc thư mục Markdown và báo cáo các vấn đề kèm theo số dòng và mức độ nghiêm trọng (chỉ sử dụng thư viện chuẩn của Python 3)
- `references/alt-text-guide.md` - hướng dẫn cách viết alt text theo từng loại hình ảnh (ảnh chụp màn hình, sơ đồ, biểu đồ, ảnh chụp, logo, huy hiệu/badges, hình ảnh trang trí)
- `references/structure-and-links.md` - tiêu đề, văn bản liên kết, bảng biểu, danh sách, nhấn mạnh câu chữ, và ý nghĩa của từng quy tắc trong kịch bản
- `templates/a11y-review.md` - mẫu báo cáo đánh giá và bảng làm việc soạn thảo alt text
- `examples/example-readme-review.md` - ví dụ thực tế về việc đánh giá và sửa lỗi tệp README của một dự án

## Quy trình làm việc

### 1. Xác định phạm vi đánh giá
Hỏi người dùng cần kiểm tra những tệp hoặc thư mục nào, đối tượng độc giả là ai (lập trình viên, người dùng cuối, sinh viên), và liệu người dùng muốn nhận báo cáo đánh giá, tệp đã sửa lỗi, hay cả hai. Nếu tài liệu được kết xuất bởi một trình tạo trang web tĩnh (site generator), hãy hỏi xem hệ thống đó có tự động thêm tiêu đề trang riêng hay không (khi đó tệp Markdown có thể không cần thẻ H1).

### 2. Chạy công cụ kiểm tra
```bash
python3 scripts/check_md_a11y.py README.md docs/
python3 scripts/check_md_a11y.py docs/ --json
python3 scripts/check_md_a11y.py docs/ --fail-on warn     # for CI
```
Công cụ sẽ bỏ qua các khối mã (fenced code blocks) và mã nội tuyến (inline code). Mức `HIGH` có nghĩa là nội dung bị mất đối với một số độc giả (thiếu alt text, liên kết rỗng, tiêu đề rỗng), mức `WARN` là các lỗi nên sửa, mức `INFO` là các điểm cần con người xem xét trực tiếp. Nếu bạn không thể chạy kịch bản, hãy kiểm tra theo đúng các quy tắc đó bằng cách đọc tệp và nói rõ cho người dùng biết.

### 3. Viết văn bản thay thế (alt text)
Đối với mỗi hình ảnh bị gắn cờ cảnh báo, và đối với mỗi hình ảnh đã có sẵn alt text, hãy xác định mục đích của nó dựa theo `references/alt-text-guide.md`:
- Đọc phần văn bản xung quanh hình ảnh: hình ảnh này xuất hiện ở vị trí này trong tài liệu nhằm mục đích gì?
- Nếu bạn nhìn thấy hình ảnh, hãy mô tả những chi tiết quan trọng phục vụ cho mục đích đó. Nếu bạn không nhìn thấy hình ảnh, hãy hỏi người dùng, hoặc viết một bản nháp có đánh dấu rõ ràng dựa trên tên tệp và ngữ cảnh (ví dụ: "BẢN NHÁP: cần đối chiếu lại với hình ảnh thực tế").
- Các hình ảnh mang tính chất trang trí thuần túy thì để alt text rỗng; trong Markdown, tốt nhất nên xóa bỏ chúng hoặc sử dụng thẻ HTML `<img alt="">`.
Điền vào bảng làm việc alt text trong mẫu `templates/a11y-review.md`.

### 4. Sửa cấu trúc và các liên kết
Áp dụng các nguyên tắc trong `references/structure-and-links.md`: chỉ dùng một tiêu đề H1 duy nhất, không nhảy cóc cấp độ tiêu đề, dùng thẻ tiêu đề thực sự thay vì chỉ in đậm cả dòng, đặt văn bản liên kết có tính mô tả và không trùng lặp, bảng biểu phải có hàng tiêu đề, các câu hướng dẫn không được chỉ dựa vào màu sắc đơn thuần.

### 5. Bàn giao kết quả
- Báo cáo: điền vào mẫu `templates/a11y-review.md`, tương tự như trong `examples/example-readme-review.md`, ưu tiên liệt kê các mục sửa lỗi quan trọng nhất lên đầu.
- Tệp đã chỉnh sửa: trả về toàn bộ nội dung Markdown đã được áp dụng các bản sửa lỗi kèm theo danh sách ngắn gọn những thay đổi đã thực hiện. Không làm thay đổi ý nghĩa gốc, các đoạn mã mẫu hay đích đến của các liên kết.
- Chạy lại công cụ kiểm tra trên tệp đã sửa và đính kèm số liệu thống kê lỗi trước và sau khi sửa.

## Quy tắc
- Tuyệt đối không tự bịa ra nội dung hiển thị bên trong một bức ảnh. Nếu bạn chưa trực tiếp nhìn thấy bức ảnh đó, hãy đánh dấu alt text là bản nháp.
- Giữ cho alt text ngắn gọn (thường dưới 150 ký tự); đưa các phần giải thích dài (như số liệu biểu đồ, sơ đồ phức tạp) vào nội dung văn bản chính hoặc dòng chú thích ảnh, đồng thời ghi chú rõ điều đó trong alt text.
- Không bắt đầu alt text bằng cụm từ "hình ảnh của" ("image of") hay "bức tranh về" ("picture of").
- Hãy nhớ rằng các bài kiểm tra tự động chỉ phát hiện được một phần vấn đề; luôn nhắc người dùng những hạng mục vẫn cần kiểm tra thủ công (độ tương phản màu sắc bên trong hình ảnh, thứ tự đọc, phụ đề video).
- Tôn trọng giọng văn của tác giả; chỉ sửa lỗi về khả năng tiếp cận, không tự ý sửa văn phong.
FILE:references/alt-text-guide.md
# Hướng dẫn viết văn bản thay thế (Alt text)

Văn bản thay thế (Alt text) đóng vai trò thay thế cho hình ảnh đối với những người không thể nhìn thấy ảnh. Hãy tự hỏi: "Nếu tôi đọc to tài liệu này lên cho người khác nghe, đến vị trí này tôi sẽ nói gì thay vì giơ bức ảnh ra?" Câu trả lời phụ thuộc vào lý do vì sao bức ảnh được đặt ở đó, chứ không chỉ phụ thuộc vào những gì có mặt trong ảnh.

## Nguyên tắc cơ bản
- Cụ thể và ngắn gọn: thường từ 5 đến 20 từ, hiếm khi vượt quá 150 ký tự.
- Đưa phần thông tin quan trọng nhất lên đầu. Không bắt đầu bằng "hình ảnh về", "bức ảnh chụp" hay "ảnh chụp màn hình của" trừ khi bản thân loại hình ảnh đó mang ý nghĩa quan trọng (từ "Ảnh chụp màn hình" có thể hữu ích khi người đọc cần tìm đúng màn hình tương tự trên thiết bị).
- Kết thúc bằng dấu chấm câu để trình đọc màn hình ngắt nhịp tự nhiên.
- Không lặp lại nguyên văn từng chữ của dòng chú thích ảnh (caption) hoặc câu văn nằm ngay cạnh bức ảnh.
- Đưa cả phần chữ xuất hiện bên trong bức ảnh vào alt text nếu người đọc cần biết thông tin đó (nhãn nút bấm, thông báo lỗi).

## Theo từng loại hình ảnh

### Ảnh chụp màn hình của ứng dụng hoặc trang web
Nêu tên màn hình và một điểm quan trọng nhất mà người đọc cần chú ý.
- Kém: "screenshot" ("ảnh chụp màn hình")
- Tốt hơn: "Settings screen with the Units toggle set to Metric." ("Màn hình Cài đặt với nút chuyển đổi Đơn vị được đặt thành Hệ mét.")

### Ảnh chủ đạo (Hero images) và biểu ngữ (Banners)
Nếu bức ảnh chỉ nhằm tạo bầu không khí cảm xúc, đó là ảnh trang trí. Nếu bức ảnh giới thiệu sản phẩm, hãy mô tả nó trong một câu.
- "Trailhead Weather on a phone, showing a three-day forecast for a mountain pass." ("Ứng dụng Trailhead Weather trên điện thoại, hiển thị dự báo thời tiết ba ngày cho một đèo núi.")

### Sơ đồ và lưu đồ (Diagrams and flowcharts)
Nêu ý chính trong phần alt text, và trình bày toàn bộ cấu trúc chi tiết trong văn bản chính hoặc một danh sách ngay bên dưới bức ảnh.
- Alt: "Architecture diagram: the mobile app calls the API, which reads from a forecast cache and a weather provider. Details in the list below." ("Sơ đồ kiến trúc: ứng dụng di động gọi API, API này đọc dữ liệu từ bộ nhớ đệm dự báo và nhà cung cấp thời tiết. Chi tiết nằm ở danh sách bên dưới.")

### Biểu đồ và đồ thị (Charts and graphs)
Nêu loại biểu đồ, chủ đề và kết luận chính; đưa dữ liệu chi tiết vào bảng nếu người đọc cần tra cứu con số cụ thể.
- "Line chart of daily active users, January to June 2026, rising from 2,000 to 9,500 with a dip in April." ("Biểu đồ đường thể hiện số người dùng hoạt động hàng ngày từ tháng 1 đến tháng 6 năm 2026, tăng từ 2.000 lên 9.500 với một đợt giảm nhẹ vào tháng 4.")

### Ảnh chụp thực tế (Photos)
Mô tả những yếu tố quan trọng phục vụ cho mục đích của tài liệu: chủ thể, hành động, bối cảnh.
- "Snow-covered ridge trail with orange marker poles leading to a hut." ("Đường mòn trên sống núi phủ đầy tuyết với những cọc tiêu màu cam dẫn tới một trạm nghỉ.")

### Logo
Sử dụng tên tổ chức hoặc tên sản phẩm, và chỉ thêm chữ "logo" nếu điều đó giúp làm rõ nghĩa: "Trailhead Weather logo."
Khi logo đồng thời là một đường liên kết, hãy mô tả đích đến của liên kết đó: "Trailhead Weather home." ("Trang chủ Trailhead Weather.")

### Huy hiệu trạng thái (Badges: trạng thái bản dựng, phiên bản, giấy phép)
Viết đúng thông tin mà huy hiệu đó thể hiện: "Build: passing", "License: MIT", "Version 2.4.1".

### Biểu tượng (Icons) nằm trong văn bản hoặc liên kết
Nếu biểu tượng mang một chức năng cụ thể, hãy mô tả chức năng đó ("Tải xuống"); nếu nó chỉ lặp lại nội dung chữ viết ngay bên cạnh, thì đó là biểu tượng trang trí.

### Ảnh động GIF và video ngắn
Mô tả diễn biến xảy ra: "Animation: dragging a pin onto the map adds a new trailhead to the list." ("Hoạt ảnh: kéo một ghim thả vào bản đồ sẽ thêm một điểm xuất phát đường mòn mới vào danh sách.") Video cũng cần có phụ đề và, đối với nội dung quan trọng, cần có văn bản mô tả thay thế.

### Hình ảnh trang trí (Decorative images)
Đường kẻ phân cách, kết cấu nền và các chi tiết hoa văn thuần túy thị giác. Trong HTML, hãy dùng `alt=""` để trình đọc màn hình bỏ qua chúng. Trong Markdown, cú pháp `![](divider.png)` mang tính nhập nhằng (thường bị hiểu là quên viết alt text), vì vậy tốt nhất nên xóa bỏ hình ảnh đó hoặc dùng thẻ `<img src="divider.png" alt="">`.

## Những sai lầm thường gặp
- Dùng nguyên tên tệp làm alt text: "IMG_2041.jpg", "hero-final-v3".
- Chỉ viết vỏn vẹn một từ: "image", "logo", "chart".
- Nhồi nhét từ khóa cho công cụ tìm kiếm (SEO).
- Viết alt text khác nhau cho cùng một bức ảnh được sử dụng ở nhiều nơi.
- Sa đà vào mô tả màu sắc hoặc bố cục trình bày trong khi thứ người đọc cần là thông tin cốt lõi chứ không phải hình thức bên ngoài.
FILE:references/structure-and-links.md
# Cấu trúc, liên kết và ý nghĩa của từng quy tắc

Người dùng trình đọc màn hình thường di chuyển nhanh qua tài liệu bằng danh sách tiêu đề hoặc danh sách liên kết. Một cấu trúc tốt chính là yếu tố giúp việc điều hướng đó khả thi.

## Tiêu đề (Headings)
| Quy tắc | Mức độ | Lý do | Cách sửa |
|---|---|---|---|
| empty-heading | HIGH | Một tiêu đề để trống sẽ được đọc lên là "tiêu đề cấp 2" mà không có bất kỳ nội dung nào phía sau. | Thêm nội dung chữ hoặc xóa bỏ dấu #. |
| no-h1 | WARN | Trang tài liệu không có tiêu đề chính trong sơ đồ dàn ý tiêu đề. | Bắt đầu bằng một dòng `# Tiêu đề`. Bỏ qua lỗi này nếu trình tạo trang web đã tự thêm H1 từ phần khai báo đầu tệp (front matter). |
| multiple-h1 | WARN | Việc có nhiều tiêu đề cấp 1 gây rối loạn sơ đồ dàn ý của trang. | Chỉ giữ lại một thẻ H1 duy nhất; sử dụng `##` cho các phần mục lớn. |
| heading-skip | WARN | Nhảy cóc từ H2 xuống thẳng H4 khiến người nghe tưởng rằng bị thiếu mất một mục ở giữa. | Sử dụng cấp độ kế tiếp ngay bên dưới (H3). Chọn cấp độ tiêu đề dựa theo cấu trúc phân cấp nội dung, không chọn vì kích thước phông chữ. |
| fake-heading | INFO | Một dòng chữ in đậm trông giống như tiêu đề nhưng lại không xuất hiện trong cây dàn ý của trình đọc màn hình. | Sử dụng thẻ tiêu đề thực sự nếu dòng đó mở đầu một mục mới; chỉ giữ nguyên in đậm nếu mục đích đơn thuần là nhấn mạnh câu. |
| no-headings | INFO | Văn bản dài không có tiêu đề phân mục rất khó đọc lướt và định vị thông tin. | Thêm tiêu đề phân mục sau mỗi vài đoạn văn. |

## Liên kết (Links)
| Quy tắc | Mức độ | Lý do | Cách sửa |
|---|---|---|---|
| empty-link | HIGH | Liên kết không có tên hiển thị để trình đọc màn hình đọc lên. | Thêm văn bản mô tả rõ ràng. |
| vague-link | WARN | Các cụm từ "Bấm vào đây" ("Click here") hoặc "xem thêm" ("read more") hoàn toàn vô nghĩa khi được liệt kê tách rời trong danh sách liên kết. | Nêu rõ tên đích đến: "tải xuống bản phát hành mới nhất", "hướng dẫn cài đặt". |
| same-text-different-url | WARN | Hai liên kết cùng có chữ "tài liệu" ("docs") nhưng trỏ tới hai địa chỉ khác nhau sẽ không thể phân biệt được. | Đặt văn bản hiển thị riêng biệt cho từng liên kết: "tài liệu tham khảo API", "hướng dẫn cài đặt". |
| url-as-link-text | INFO | Các đường dẫn URL dài sẽ bị trình đọc màn hình đánh vần từng ký tự một. | Sử dụng cụm từ mô tả ngắn gọn; chỉ giữ nguyên URL hiển thị nếu người đọc bắt buộc phải sao chép trực tiếp đường dẫn đó. |
| bare-url | INFO | Tương tự như trên, đồng thời không phải lúc nào cũng bấm vào được. | Bọc URL trong một liên kết có văn bản mô tả. |

Mẹo viết văn bản liên kết: đặt những từ quan trọng nhất lên đầu, giữ ngắn gọn, nêu rõ khi liên kết mở ra một tệp tải về ("bảng báo giá (PDF, 2 MB)"), và không viết từ "liên kết" ("link") vào trong văn bản hiển thị.

## Hình ảnh (Images)
| Quy tắc | Mức độ | Lý do |
|---|---|---|
| img-missing-alt | HIGH | `![](file.png)` không cung cấp văn bản thay thế nào; một số trình đọc màn hình sẽ đọc to tên tệp ảnh. |
| img-no-alt | HIGH | Thẻ `<img>` không có thuộc tính alt; trình đọc màn hình buộc phải đọc tên tệp ảnh. |
| img-generic-alt | WARN | Những từ chung chung như "image", "screenshot", "logo" đứng một mình không mang lại thông tin gì. |
| img-filename-alt | WARN | "IMG_2041.jpg" là tên tệp chứ không phải lời mô tả hình ảnh. |
| img-long-alt | WARN | Văn bản alt quá dài không thể tua hay điều hướng từng phần được; hãy chuyển nội dung chi tiết ra ngoài văn bản chính. |
| img-redundant-alt | INFO | Cụm từ "Hình ảnh của" ("Image of") bị thừa vì bản thân trình đọc màn hình đã tự thông báo đó là "hình ảnh". |
| img-decorative | INFO | `alt=""` sẽ ẩn hình ảnh khỏi trình đọc màn hình; hãy xác nhận chắc chắn rằng bức ảnh đó thuần túy chỉ để trang trí. |

Xem `alt-text-guide.md` để biết cách viết nội dung văn bản thay thế chuẩn xác.

## Bảng biểu (Tables)
- table-empty-header (WARN): mỗi cột trong bảng đều cần có ô tiêu đề để trình đọc màn hình có thể đọc khớp ngữ cảnh như "Bản Pro, Số ngày dự báo, 10". Hãy thêm tiêu đề cột như "Tính năng" vào cột đầu tiên.
- Chỉ sử dụng bảng để trình bày dữ liệu, không dùng bảng để dàn trang (layout). Giữ bảng nhỏ gọn; tách nhỏ các bảng có quá nhiều cột.

## Các quy tắc khác
- color-only (WARN): Câu hướng dẫn "Nhấn vào nút màu xanh lá" sẽ gây khó khăn cho người mù màu và người dùng trình đọc màn hình. Hãy nêu rõ tên nút bấm: "Chọn Lưu (nút màu xanh lá)".
- all-caps (INFO): Đoạn văn bản dài VIẾT HOA TOÀN BỘ rất khó đọc, và một số trình đọc màn hình sẽ đánh vần từng chữ cái đối với các từ viết hoa ngắn. Hãy sử dụng chữ viết thường đúng ngữ pháp và dùng định dạng in đậm để nhấn mạnh.
- emoji-bullet (INFO): Các biểu tượng emoji sẽ bị đọc to bằng tên mô tả dài dòng ("dấu kiểm đậm màu trắng Dự báo hàng giờ"). Hãy sử dụng dấu đầu dòng danh sách tiêu chuẩn, đồng thời hạn chế dùng emoji và chỉ dùng khi thực sự mang lại ý nghĩa.

## Các hạng mục kịch bản không kiểm tra được (cần kiểm tra thủ công)
- Nội dung văn bản thay thế (alt text) có thực sự chính xác và hữu ích hay không.
- Độ tương phản màu sắc và chữ viết nằm bên trong hình ảnh (ảnh chụp màn hình có cỡ chữ quá nhỏ, biểu đồ có độ tương phản thấp).
- Thứ tự đọc của các bố cục phức tạp và các khối mã HTML nhúng bên trong Markdown.
- Phụ đề (captions) và bản chép lời (transcripts) cho video và âm thanh.
- Ngôn ngữ giản dị, dễ hiểu: câu văn ngắn gọn, giải thích rõ các thuật ngữ chuyên ngành và đặt tên các phần mục mang tính mô tả cao.
FILE:templates/a11y-review.md
# Báo cáo Đánh giá Khả năng Tiếp cận: <tài liệu hoặc thư mục>

Ngày: <YYYY-MM-DD>
Số tệp đã kiểm tra: <n> (<danh sách hoặc thư mục>)
Đối tượng độc giả: <ai là người đọc các tài liệu này>
Kết quả chạy công cụ kiểm tra: `python3 scripts/check_md_a11y.py <paths>` -> HIGH <n>, WARN <n>, INFO <n>

## Các mục ưu tiên sửa hàng đầu (tác động lớn nhất xếp trước)
1. <nội dung sửa> (<tệp:dòng>)
2. <nội dung sửa>
3. <nội dung sửa>

## Bảng làm việc văn bản thay thế (Alt text worksheet)
| Tệp:dòng | Hình ảnh | Mục đích trong tài liệu | Alt hiện tại | Alt mới | Đã xem ảnh trực tiếp? |
|---|---|---|---|---|---|
| | | cung cấp thông tin / chức năng / trang trí / phức tạp | | | đã xem / bản nháp |

## Tiêu đề (Headings)
- Dàn ý hiện tại: <H1 ... / H2 ... / H4 ...>
- Dàn ý đề xuất: <H1 ... / H2 ... / H3 ...>

## Liên kết (Links)
| Tệp:dòng | Văn bản hiện tại | Văn bản mới | Đích đến |
|---|---|---|---|
| | | | |

## Các phát hiện khác
| Tệp:dòng | Quy tắc | Thay đổi thực hiện |
|---|---|---|
| | | |

## Sau khi sửa lỗi
Chạy lại công cụ kiểm tra: HIGH <n>, WARN <n>, INFO <n> (các mục INFO còn lại được giải thích bên dưới).
- <mục INFO: lý do vì sao có thể chấp nhận giữ nguyên>

## Các hạng mục vẫn cần kiểm tra thủ công
- <ví dụ: độ tương phản của chữ bên trong ảnh chụp màn hình, phụ đề video>
FILE:examples/example-readme-review.md
# Ví dụ: đánh giá khả năng tiếp cận cho tệp README của một dự án

## Yêu cầu từ người dùng
"Tệp README của ứng dụng mã nguồn mở bên tôi có lượng truy cập rất lớn. Một người dùng sử dụng trình đọc màn hình phản ánh rằng tài liệu rất khó theo dõi. Bạn có thể kiểm tra và sửa giúp tôi được không? Ảnh hero là hình ứng dụng chạy trên điện thoại hiển thị dự báo 3 ngày; app-main.png là màn hình chính có nhiệt độ hàng giờ, sức gió và đường ranh giới tuyết rơi; còn chiếc huy hiệu (badge) là trạng thái bản dựng (build status) của chúng tôi."

## Chạy công cụ kiểm tra (trước khi sửa)
```
$ python3 scripts/check_md_a11y.py README.md
Markdown accessibility check: 1 file(s), 3 image(s)
HIGH 2  WARN 8  INFO 5

README.md (3 images, 4 headings): 15 finding(s)
     3  HIGH  img-missing-alt          Image hero.png has empty alt text; describe it, or confirm it is purely decorative.
     5  INFO  all-caps                 Long ALL CAPS text is hard to read and some screen readers spell it letter by letter.
     9  WARN  vague-link               Link text "here" does not say where it goes; describe the destination.
     9  WARN  vague-link               Link text "click here" does not say where it goes; describe the destination.
    11  WARN  img-generic-alt          Alt text "screenshot" for app-main.png is generic; say what the image shows or why it is there.
    13  HIGH  img-no-alt               <img src="docs/img/badge.svg"> has no alt attribute.
    15  WARN  heading-skip             Heading level jumps from H2 to H4 ("Configuration"); use H3.
    17  WARN  color-only               Instruction relies on color; add the label, shape, or position too.
    19  INFO  fake-heading             Bold line "Features" looks like a heading; use a real # heading if it starts a section.
    21  INFO  emoji-bullet             Emoji used as a bullet is read aloud by name; use a list marker and put meaning in words.
    22  INFO  emoji-bullet             Emoji used as a bullet is read aloud by name; use a list marker and put meaning in words.
    24  WARN  table-empty-header       Table header has 1 empty cell(s); every column needs a header.
    28  WARN  same-text-different-url  Link text "docs" points to 2 different URLs; make each text unique.
    28  INFO  bare-url                 Bare URL https://example.org/docs; screen readers spell it out. Use [descriptive text](https://example.org/docs).
    35  WARN  multiple-h1              2 H1 headings (lines 1, 35); keep one title and use ## for sections.
```
Cú pháp `![](not-an-image.png)` nằm bên trong khối mã bash và ví dụ mã nội tuyến ở dòng cuối cùng đã được công cụ bỏ qua một cách chính xác.

## Báo cáo đánh giá (đã điền theo mẫu, rút gọn)

# Báo cáo Đánh giá Khả năng Tiếp cận: README.md

Đối tượng độc giả: người đi bộ đường dài (hikers) và các cộng tác viên mã nguồn mở, nhiều người tìm đến từ công cụ tìm kiếm.
Kết quả chạy công cụ kiểm tra: HIGH 2, WARN 8, INFO 5.

### Các mục ưu tiên sửa hàng đầu
1. Cung cấp văn bản thay thế (alt text) thực chất cho ảnh hero và huy hiệu trạng thái bản dựng (dòng 3 và 13).
2. Thay thế cụm từ "here" và "click here" bằng văn bản liên kết nêu rõ tên đích đến (dòng 9).
3. Sửa lại dàn ý tiêu đề: chuyển "Configuration" thành H3, chuyển "Features" thành thẻ tiêu đề H3 thực sự, và hạ thẻ H1 thứ hai "Contributing" xuống thành H2.
4. Nêu rõ tên nút Save thay vì chỉ mô tả màu sắc của nút (dòng 17).
5. Thêm tiêu đề cho cột đầu tiên của bảng (dòng 24).

### Bảng làm việc văn bản thay thế (Alt text worksheet)
| Tệp:dòng | Hình ảnh | Mục đích | Alt hiện tại | Alt mới | Đã xem ảnh? |
|---|---|---|---|---|---|
| README.md:3 | hero.png | cung cấp thông tin: giới thiệu sản phẩm | (trống) | Trailhead Weather on a phone, showing a three-day forecast for a mountain pass. | do người dùng mô tả |
| README.md:11 | app-main.png | cung cấp thông tin: màn hình chính hiển thị những gì | screenshot | Main screen with hourly temperature, wind, and snow line for the selected trailhead. | do người dùng mô tả |
| README.md:13 | badge.svg | cung cấp thông tin: trạng thái bản dựng | (không có thuộc tính alt) | Build: passing | do người dùng mô tả |

### Tiêu đề (Headings)
- Trước khi sửa: H1 Trailhead Weather / H2 Install / H4 Configuration / H1 Contributing (cộng thêm một dòng chữ in đậm "Features").
- Sau khi sửa: H1 Trailhead Weather / H2 Install / H3 Configuration / H3 Features / H2 Contributing.

### Liên kết (Links)
| Dòng | Văn bản hiện tại | Văn bản mới | Đích đến |
|---|---|---|---|
| 9 | here | Download the latest release | https://example.org/releases |
| 9 | click here | setup guide | docs/guides/setup.md |
| 28 | docs (URL trần + "docs") | API reference | https://example.org/docs |
| 28 | docs | setup guide | docs/guides/setup.md |

### Các phát hiện khác
| Dòng | Quy tắc | Thay đổi thực hiện |
|---|---|---|
| 5 | all-caps | Chuyển về chữ thường đúng ngữ pháp bên trong phần ghi chú in đậm. |
| 17 | color-only | Đổi thành "Select Save (the green button at the bottom of Settings)". |
| 21-22 | emoji-bullet | Đổi thành các mục danh sách gạch đầu dòng "-" thông thường. |
| 24 | table-empty-header | Đặt tiêu đề cột đầu tiên là "Feature". |

### Tệp README sau khi sửa (trích đoạn)
```markdown
# Trailhead Weather

![Trailhead Weather on a phone, showing a three-day forecast for a mountain pass.](docs/img/hero.png)

Trailhead Weather shows mountain forecasts for hikers. **Note: this project is still in beta and things will break often.**

## Install

[Download the latest release](https://example.org/releases), or follow the [setup guide](docs/guides/setup.md).

<img src="docs/img/badge.svg" width="90" alt="Build: passing">

### Configuration

Select Save (the green button at the bottom of Settings) to save your settings.

### Features

- Hourly forecasts
- Avalanche bulletins

| Feature | Free | Pro |
|---|---|---|
| Forecast days | 3 | 10 |
```

### Sau khi sửa lỗi
```
$ python3 scripts/check_md_a11y.py README-fixed.md
Markdown accessibility check: 1 file(s), 3 image(s)
HIGH 0  WARN 0  INFO 0
```

### Các hạng mục vẫn cần kiểm tra thủ công
- Ảnh hero có phần chữ nhỏ hiển thị trên màn hình điện thoại; văn bản thay thế (alt text) đã truyền tải đầy đủ thông điệp cốt lõi nên ở đây như vậy là ổn.
- Nếu sau này tệp README được đưa lên thành một trang trên website tài liệu, hãy kiểm tra để chắc chắn hệ thống tạo trang không tự động chèn thêm một thẻ H1 thứ hai.

## Vì sao đây là một phương án xử lý tốt
- Văn bản thay thế (alt text) mô tả đúng mục đích của từng bức ảnh dựa trên thông tin người dùng cung cấp thay vì tự suy đoán.
- Các liên kết và tiêu đề được chỉnh sửa phù hợp với cách thức điều hướng thực tế của người dùng trình đọc màn hình: duyệt theo danh sách liên kết và sơ đồ dàn ý tiêu đề.
- Bản sửa lỗi được kiểm chứng lại bằng cách chạy công cụ kiểm tra một lần nữa, đồng thời liệt kê trung thực những hạng mục vẫn cần con người kiểm tra thủ công.
FILE:scripts/check_md_a11y.py
#!/usr/bin/env python3
"""Check Markdown files for common accessibility problems.

Usage:
  python3 check_md_a11y.py README.md docs/            # files and folders (*.md, *.markdown)
  python3 check_md_a11y.py docs/ --json
  cat page.md | python3 check_md_a11y.py -
  python3 check_md_a11y.py docs/ --fail-on warn      # exit 1 on WARN too (for CI)

Checks (code blocks and inline code are ignored):
  images   missing alt text, file-name or generic alt ("image", "screenshot"),
           redundant "image of ..." openers, very long alt, HTML <img> without alt,
           empty alt (fine only for decorative images)
  headings no H1 or more than one H1, skipped levels (H2 -> H4), empty headings,
           bold lines used as fake headings
  links    empty link text, vague text ("click here", "read more", "here"),
           bare URLs, the same text pointing to different URLs
  tables   empty header cells
  other    ALL CAPS sentences, emoji used as bullets, color-only instructions
Severities: HIGH (blocks understanding), WARN (should fix), INFO (check by hand).
Exit code: 0 no HIGH, 1 HIGH found (or WARN with --fail-on warn), 2 usage error.
Standard library only.
"""
import argparse
import json
import os
import re
import sys

GENERIC_ALT = {"image", "img", "picture", "pic", "photo", "screenshot", "screen shot", "graphic", "icon",
               "logo", "diagram", "chart", "figure", "untitled", "alt", "alt text", "banner", "placeholder"}
VAGUE_LINK = {"click here", "here", "click", "read more", "more", "learn more", "link", "this", "this link",
              "this page", "go", "details", "more info", "info", "see here", "check it out"}
REDUNDANT_START = re.compile(r"^(an? )?(image|picture|photo|screenshot|graphic) (of|showing)\b", re.I)
FILE_ALT = re.compile(r"^[\w\-. ]+\.(png|jpe?g|gif|svg|webp|bmp|tiff?)$|^(img|image|dsc|screenshot)[_\- ]?\d+", re.I)
IMG_MD = re.compile(r"!\[([^\]]*)\]\(\s*<?([^)\s>]*)>?(?:\s+\"[^\"]*\")?\s*\)")
IMG_REF = re.compile(r"!\[([^\]]*)\]\[[^\]]*\]")
LINK_MD = re.compile(r"(?<!!)\[([^\]]*)\]\(\s*<?([^)\s>]*)>?(?:\s+\"[^\"]*\")?\s*\)")
HTML_IMG = re.compile(r"<img\b[^>]*>", re.I)
BARE_URL = re.compile(r"(?<![(<\"'=\[])\bhttps?://[^\s)>\]]+")
COLOR_ONLY = re.compile(r"\b(click|press|tap|select|choose|use)\b[^.]{0,30}\b(red|green|blue|yellow|orange|purple)\b(?! *\()", re.I)
EMOJI_BULLET = re.compile(r"^\s*[\u2705\u274c\u2b50\u27a1\u2714\u2716\U0001F300-\U0001FAFF]\ufe0f?\s+\S")


def strip_inline_code(line):
    return re.sub(r"`+[^`]*`+", lambda m: " " * len(m.group(0)), line)


def check_text(text, name):
    findings = []

    def add(sev, line, rule, msg):
        findings.append({"file": name, "line": line, "severity": sev, "rule": rule, "message": msg})

    lines = text.replace("\r\n", "\n").split("\n")
    in_fence, fence = False, ""
    headings, link_targets = [], {}
    images = 0
    prev_blank = True
    for no, raw in enumerate(lines, 1):
        stripped = raw.strip()
        m = re.match(r"^\s{0,3}(`{3,}|~{3,})", raw)
        if m:
            if not in_fence:
                in_fence, fence = True, m.group(1)[0] * 3
            elif stripped.startswith(fence):
                in_fence = False
            continue
        if in_fence or raw.startswith("    ") and prev_blank and not stripped.startswith(("-", "*", "+")):
            prev_blank = not stripped if not in_fence else prev_blank
            continue
        line = strip_inline_code(raw)
        hm = re.match(r"^\s{0,3}(#{1,6})(\s+|$)(.*?)\s*#*\s*$", line)
        if hm:
            level, title = len(hm.group(1)), hm.group(3).strip()
            headings.append((no, level, title))
            if not title:
                add("HIGH", no, "empty-heading", f"Empty H{level} heading; screen reader users navigate by headings.")
        elif re.fullmatch(r"\s*(\*\*|__)[^*_]{2,80}(\*\*|__):?\s*", line) and prev_blank:
            add("INFO", no, "fake-heading", f"Bold line \"{stripped.strip('*_:')}\" looks like a heading; use a real # heading if it starts a section.")
        images += len(IMG_MD.findall(line)) + len(IMG_REF.findall(line)) + len(HTML_IMG.findall(line))
        for alt, src in IMG_MD.findall(line):
            check_alt(add, no, alt, src)
        for alt in IMG_REF.findall(line):
            check_alt(add, no, alt, "(reference)")
        for tag in HTML_IMG.findall(line):
            am = re.search(r"\balt\s*=\s*(\"([^\"]*)\"|'([^']*)'|(\S+))", tag, re.I)
            src = re.search(r"\bsrc\s*=\s*[\"']?([^\"'\s>]+)", tag, re.I)
            src = src.group(1) if src else "?"
            if not am:
                add("HIGH", no, "img-no-alt", f"<img src=\"{src}\"> has no alt attribute.")
            else:
                check_alt(add, no, am.group(2) if am.group(2) is not None else (am.group(3) if am.group(3) is not None else am.group(4)), src, html=True)
        no_images = IMG_MD.sub(" ", line)
        for text_, url in LINK_MD.findall(no_images):
            label = re.sub(r"[*_`]", "", text_).strip()
            if not label:
                add("HIGH", no, "empty-link", f"Link to {url or '(no url)'} has no text; screen readers will read the URL or nothing.")
            elif label.lower().rstrip(".!:") in VAGUE_LINK:
                add("WARN", no, "vague-link", f"Link text \"{label}\" does not say where it goes; describe the destination.")
            elif re.fullmatch(r"https?://\S+", label):
                add("INFO", no, "url-as-link-text", f"Link text is a raw URL ({label[:60]}); use a short description.")
            if label:
                link_targets.setdefault(label.lower(), {}).setdefault(url, no)
        for url in BARE_URL.findall(LINK_MD.sub(" ", no_images)):
            add("INFO", no, "bare-url", f"Bare URL {url[:60]}; screen readers spell it out. Use [descriptive text]({url[:40]}).")
        if "|" in line and re.match(r"^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$", line) and no > 1:
            header = lines[no - 2].strip().strip("|")
            cells = [c.strip() for c in header.split("|")]
            if any(not c for c in cells):
                add("WARN", no - 1, "table-empty-header", f"Table header has {sum(1 for c in cells if not c)} empty cell(s); every column needs a header.")
        run = longest = 0
        for w in re.findall(r"[A-Za-z]+", line):
            run = run + 1 if w.isupper() and (len(w) > 1 or w in "AI") else 0
            longest = max(longest, run)
        if longest >= 5 and not hm:
            add("INFO", no, "all-caps", "Long ALL CAPS text is hard to read and some screen readers spell it letter by letter.")
        if EMOJI_BULLET.match(line):
            add("INFO", no, "emoji-bullet", "Emoji used as a bullet is read aloud by name; use a list marker and put meaning in words.")
        cm = COLOR_ONLY.search(line)
        if cm:
            between = line[cm.end(1):cm.start(2)]
            inside_parens = line[:cm.start(2)].count("(") > line[:cm.start(2)].count(")")
            names_label = re.match(r"\s+(\*\*|\"|')?[A-Z]", between)  # "Select Save ..." or "Press **Save**"
            if inside_parens or names_label:
                cm = None
        if cm:
            add("WARN", no, "color-only", "Instruction relies on color; add the label, shape, or position too.")
        prev_blank = not stripped

    h1 = [h for h in headings if h[1] == 1]
    if headings and not h1:
        add("WARN", headings[0][0], "no-h1", "Document has no H1; start with one # title.")
    if len(h1) > 1:
        add("WARN", h1[1][0], "multiple-h1", f"{len(h1)} H1 headings (lines {', '.join(str(h[0]) for h in h1)}); keep one title and use ## for sections.")
    for (pno, plev, _), (no, lev, title) in zip(headings, headings[1:]):
        if lev > plev + 1:
            add("WARN", no, "heading-skip", f"Heading level jumps from H{plev} to H{lev} (\"{title[:50]}\"); use H{plev + 1}.")
    if not headings and len([l for l in lines if l.strip()]) > 15:
        add("INFO", 1, "no-headings", "Long document with no headings; add headings so readers can navigate.")
    for label, targets in link_targets.items():
        if len(targets) > 1 and label not in VAGUE_LINK:
            first = min(targets.values())
            add("WARN", first, "same-text-different-url", f"Link text \"{label}\" points to {len(targets)} different URLs; make each text unique.")
    order = {"HIGH": 0, "WARN": 1, "INFO": 2}
    findings.sort(key=lambda f: (f["line"], order[f["severity"]]))
    return findings, len(headings), images


def check_alt(add, no, alt, src, html=False):
    a = alt.strip()
    base = os.path.basename(src) if src else ""
    if a == "" and html:
        add("INFO", no, "img-decorative", f"<img src=\"{base}\"> has alt=\"\" (marked decorative); confirm it carries no information.")
        return
    if a == "" and src:
        add("HIGH", no, "img-missing-alt", f"Image {base or src} has empty alt text; describe it, or confirm it is purely decorative.")
        return
    low = a.lower().rstrip(".")
    if low in GENERIC_ALT:
        add("WARN", no, "img-generic-alt", f"Alt text \"{a}\" for {base} is generic; say what the image shows or why it is there.")
    elif FILE_ALT.search(a) or (base and low == os.path.splitext(base)[0].lower()):
        add("WARN", no, "img-filename-alt", f"Alt text \"{a}\" looks like a file name; describe the image instead.")
    elif REDUNDANT_START.match(a):
        add("INFO", no, "img-redundant-alt", f"Alt text starts with \"{' '.join(a.split()[:3])}\"; screen readers already say 'image', so start with the content.")
    if len(a) > 150:
        add("WARN", no, "img-long-alt", f"Alt text is {len(a)} characters; keep it under about 150 and move details to the surrounding text or a caption.")


def collect(paths):
    files = []
    for p in paths:
        if p == "-":
            files.append("-")
        elif os.path.isdir(p):
            for root, dirs, names in os.walk(p):
                dirs[:] = sorted(d for d in dirs if not d.startswith(".") and d != "node_modules")
                files += [os.path.join(root, n) for n in sorted(names) if n.lower().endswith((".md", ".markdown"))]
        elif os.path.isfile(p):
            files.append(p)
        else:
            raise FileNotFoundError(p)
    return files


def main():
    ap = argparse.ArgumentParser(description="Markdown accessibility checker")
    ap.add_argument("paths", nargs="+", help="Markdown files, folders, or - for stdin")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--fail-on", choices=["high", "warn"], default="high")
    args = ap.parse_args()
    try:
        files = collect(args.paths)
    except FileNotFoundError as e:
        print(f"error: path not found: {e}", file=sys.stderr)
        return 2
    if not files:
        print("error: no Markdown files (*.md, *.markdown) found", file=sys.stderr)
        return 2
    all_findings, stats = [], []
    for f in files:
        text = sys.stdin.read() if f == "-" else open(f, encoding="utf-8", errors="replace").read()
        name = "<stdin>" if f == "-" else f
        found, nhead, images = check_text(text, name)
        stats.append({"file": name, "images": images, "headings": nhead, "findings": len(found)})
        all_findings += found
    counts = {s: sum(1 for x in all_findings if x["severity"] == s) for s in ("HIGH", "WARN", "INFO")}
    if args.json:
        print(json.dumps({"files": stats, "counts": counts, "findings": all_findings}, indent=2))
    else:
        print(f"Markdown accessibility check: {len(files)} file(s), {sum(s['images'] for s in stats)} image(s)")
        print(f"HIGH {counts['HIGH']}  WARN {counts['WARN']}  INFO {counts['INFO']}")
        for s in stats:
            items = [x for x in all_findings if x["file"] == s["file"]]
            print(f"\n{s['file']} ({s['images']} images, {s['headings']} headings): {len(items)} finding(s)")
            for x in items:
                print(f"  {x['line']:>4}  {x['severity']:<4}  {x['rule']:<24} {x['message']}")
        print("\nAutomated checks cover only part of accessibility; review alt text meaning, reading order, and contrast by hand.")
    bad = counts["HIGH"] + (counts["WARN"] if args.fail_on == "warn" else 0)
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: meeting-agenda-timeboxer
description: Chuyển danh sách thô các chủ đề họp thành một chương trình họp được phân bổ thời gian (timeboxed) với giờ bắt đầu và kết thúc, người phụ trách, cùng kết quả đầu ra rõ ràng cho từng mục (inform, discuss, decide, brainstorm, review), kiểm tra xem lịch trình có vừa vặn với khung giờ kèm khoảng đệm dự phòng hay không, cảnh báo các dấu hiệu bất ổn trong chương trình họp như quyết định bị xếp quá muộn hoặc vội vàng, quá nhiều báo cáo tiến độ, các mục quá dài và thiếu giờ nghỉ giải lao, đồng thời viết bản chương trình họp và tài liệu đọc trước (pre-read) sẵn sàng để gửi đi. Sử dụng khi người dùng yêu cầu "giúp tôi lên kế hoạch cuộc họp này", "chương trình họp này có gói gọn trong một tiếng được không?", "làm cho lịch họp này chặt chẽ hơn", hoặc chia sẻ danh sách chủ đề cho một cuộc họp nhóm, buổi hội thảo (workshop), buổi họp toàn thể (offsite) hay buổi đánh giá.
---

# Công cụ Phân bổ Thời gian Chương trình Họp (Meeting Agenda Timeboxer)

Bạn giúp mọi người điều hành các cuộc họp kết thúc đúng giờ và đưa ra được quyết định. Bạn biến danh sách các chủ đề thành một lịch trình thực tế, gán cho mỗi mục một người phụ trách và một mục đích cụ thể, chuyển các phần cập nhật tiến độ ra ngoài phòng họp, và làm cho bài toán thời gian trở nên minh bạch để không ai phải ngỡ ngàng ở phút thứ 55 rằng quyết định quan trọng nhất đã không còn thời gian để bàn.

## Các tệp trong kỹ năng này

- `scripts/timebox_agenda.py` - lập lịch cho từng mục, kiểm tra độ khớp với khung giờ và thời gian dự phòng, cảnh báo các bất cập trong chương trình họp, và có thể co giãn các mục cho vừa khung giờ theo từng bước 5 phút (chỉ sử dụng thư viện chuẩn của Python 3)
- `references/timeboxing-principles.md` - thời gian thực tế mà từng hoạt động tiêu tốn, kết quả đầu ra của từng mục, thứ tự sắp xếp, thời gian dự phòng và nghỉ giải lao
- `references/facilitation-moves.md` - các kỹ thuật điều phối giúp giữ từng loại mục nằm gọn trong khung thời gian đã định, và cách xử lý khi một mục bị lố giờ
- `templates/agenda.md` - định dạng đầu vào của chương trình họp và mẫu chương trình họp để gửi đi
- `examples/example-roadmap-meeting.md` - ví dụ thực tế về cách chỉnh sửa một cuộc họp lập kế hoạch kéo dài một giờ bị quá tải

## Quy trình làm việc

### 1. Thu thập dữ kiện
Hỏi người dùng, hoặc đưa ra giả định và nêu rõ:
- Mục đích của cuộc họp gói gọn trong một câu: điều gì phải đạt được khi cuộc họp kết thúc?
- Giờ bắt đầu và thời lượng (hoặc giờ kết thúc), số lượng người tham dự, họp trực tiếp hay trực tuyến.
- Các chủ đề, mỗi chủ đề kèm theo người phụ trách và việc mà cả nhóm cần làm với chủ đề đó: `inform` (thông báo), `update` (cập nhật), `discuss` (thảo luận), `brainstorm` (động não), `review` (đánh giá) hoặc `decide` (quyết định).
- Các ràng buộc cứng: những người vào muộn hoặc rời đi sớm, các khung giờ nghỉ giải lao cố định.

### 2. Viết bản nháp chương trình họp
Sử dụng định dạng đầu vào trong `templates/agenda.md` (mỗi mục một dòng: `minutes | topic | owner | outcome`). Dùng dấu `?` cho thời lượng mà chưa ai biết chắc. Ước lượng thời gian dựa theo `references/timeboxing-principles.md`.

### 3. Chạy công cụ phân bổ thời gian (timeboxer)
```bash
python3 scripts/timebox_agenda.py agenda.txt
python3 scripts/timebox_agenda.py agenda.txt --fit     # scale to the slot in 5-minute steps
python3 scripts/timebox_agenda.py agenda.json --json
```
Công cụ sẽ in ra lịch trình với giờ đồng hồ cụ thể, thời gian dự phòng và các phát hiện: `HIGH` khi chương trình họp vượt quá khung giờ, `WARN` cho các dấu hiệu bất ổn, `INFO` cho thời gian chưa lên kế hoạch và chi phí cuộc họp tính theo giờ công (person-hours). Tùy chọn `--fit` sẽ cắt giảm các mục cập nhật tiến độ trước, sau đó co giãn tỷ lệ các mục còn lại; nó không bao giờ tự ý đổi thứ tự các mục, vì vậy bạn hãy tự kiểm tra lại thứ tự sau đó.

Nếu bạn không thể chạy kịch bản này, hãy tự tính toán giờ đồng hồ thủ công cho từng mục một và nói rõ điều đó.

### 4. Sửa bản chất chương trình họp, chứ không chỉ sửa các con số
Xử lý các phát hiện theo thứ tự sau:
1. Loại bỏ hoặc thu gọn các phần cập nhật tiến độ và thông báo: chuyển chúng thành tài liệu đọc trước (pre-read) bằng văn bản.
2. Đưa các mục cần ra quyết định lên đầu (trong nửa đầu cuộc họp), và dành cho mỗi quyết định ít nhất 10 phút kèm theo bản đề xuất bằng văn bản được gửi trước.
3. Gán cho mỗi mục một người phụ trách và một kết quả đầu ra rõ ràng; bỏ mục "AOB" (Các vấn đề khác) hoặc biến nó thành 5 phút rà soát danh sách tồn đọng (parking lot).
4. Chia nhỏ các mục kéo dài trên 45 phút; thêm thời gian nghỉ giải lao sau mỗi 60 đến 90 phút.
5. Nếu vẫn không vừa khung giờ, hãy đề xuất những mục cần cắt bỏ hoặc chuyển sang cuộc họp khác hay trao đổi không đồng bộ (async), và nêu rõ phần nào sẽ bị lược bớt.
Chạy lại kịch bản cho đến khi không còn phát hiện mức `HIGH` nào và mọi cảnh báo `WARN` đều đã được khắc phục hoặc giải trình hợp lý.

### 5. Bàn giao kết quả
Điền hoàn chỉnh bản chương trình họp để gửi đi theo mẫu `templates/agenda.md`: mục đích, kết quả mong muốn, lịch trình có gắn mốc giờ, danh sách tài liệu đọc trước kèm người phụ trách và hạn chót, cùng quy tắc xử lý danh sách tồn đọng (parking lot). Thêm một hoặc hai mẹo điều phối cho mỗi mục có nguy cơ cháy giáo án dựa trên `references/facilitation-moves.md`. Tuân theo phong cách trình bày của `examples/example-roadmap-meeting.md`.

## Quy tắc
- Tuyệt đối không làm đẹp các con số bằng cách ép thời gian của một mục ra quyết định xuống thấp hơn mức cần thiết; hãy cắt hoặc chuyển mục khác đi, hoặc khuyến nghị kéo dài thời lượng cuộc họp.
- Luôn giữ thời gian dự phòng (buffer): khoảng 5 phút cho mỗi giờ họp, hoặc 10 phần trăm đối với các buổi hội thảo (workshop).
- Hãy nói thẳng khi một cuộc họp không nên diễn ra (không có quyết định nào cần chốt, không có gì cần thảo luận trực tiếp) và đề xuất phương án làm việc không đồng bộ (async) thay thế.
- Tôn trọng văn hóa làm việc và các ràng buộc của người dùng; đưa ra gợi ý chứ không lên mặt dạy đời.
- Giờ hiển thị là giờ địa phương của cuộc họp; đối với người tham dự từ xa ở các múi giờ khác, hãy nhắc tới điều đó nhưng không tự động quy đổi trừ khi được yêu cầu.
FILE:references/timeboxing-principles.md
# Nguyên tắc phân bổ thời gian (Timeboxing)

## Mỗi mục đều cần một kết quả đầu ra
| Kết quả đầu ra | Việc cả nhóm thực hiện | Thời lượng điển hình | Ghi chú |
|---|---|---|---|
| inform | Lắng nghe thông tin, đặt câu hỏi làm rõ | 2 đến 5 phút | Tốt hơn nên chuyển thành tài liệu đọc trước bằng văn bản. |
| update | Báo cáo tiến độ từ các cá nhân hoặc nhóm | 1 đến 2 phút mỗi người | Thường nên làm không đồng bộ (async); chỉ giữ lại các vướng mắc (blockers) để bàn trực tiếp. |
| discuss | Khám phá một chủ đề, chia sẻ góc nhìn, chưa chốt quyết định | 10 đến 20 phút | Nêu rõ cuộc thảo luận này phục vụ cho việc gì (một quyết định vào tuần tới, hay một tài liệu). |
| brainstorm | Đưa ra các phương án, ý tưởng | 15 đến 30 phút | Cần một câu hỏi được đóng khung rõ ràng và một phương pháp cụ thể (viết nháp trong im lặng trước). |
| review | Đưa ra phản hồi về bản nháp, thiết kế hoặc kế hoạch | 15 đến 40 phút | Gửi tài liệu trước cuộc họp; thống nhất rõ loại phản hồi nào đang được mong đợi. |
| decide | Lựa chọn giữa các phương án và cam kết thực hiện | 10 đến 30 phút | Cần bản đề xuất viết sẵn, các phương án, người có thẩm quyền quyết định và nguyên tắc ra quyết định. |
| break | Nghỉ ngơi | 5 đến 15 phút | Sau mỗi 60 đến 90 phút. |

Nếu một mục không có kết quả đầu ra rõ ràng, hãy đặt câu hỏi: "Điều gì sẽ thay đổi sau khi bàn xong mục này?" Nếu câu trả lời là "không có gì cả", hãy cắt bỏ mục đó.

## Thời gian thực tế mà các hoạt động tiêu tốn
- Giới thiệu làm quen: khoảng 1 phút mỗi người đối với nhóm mới gặp, 0 phút đối với nhóm làm việc thường xuyên.
- Mỗi người phát biểu một lần về một chủ đề: khoảng 1,5 đến 2 phút mỗi người. Tám người phát biểu một vòng sẽ mất 15 phút.
- Chia sẻ màn hình và khởi động: 2 đến 3 phút, và còn lâu hơn đối với các cuộc họp từ xa sử dụng công cụ mới.
- Một quyết định có sự bất đồng thực sự: hãy nhân đôi thời gian ước tính, hoặc tách thành hai bước "thảo luận" hôm nay và "chốt quyết định" vào buổi sau.
- Các mục nằm ở cuối chương trình họp thường diễn ra nhanh hơn nhưng chất lượng tệ hơn: mọi người làm vội vàng hoặc phải rời phòng họp.

## Thứ tự sắp xếp
1. Bắt đầu bằng phần định hướng ngắn gọn: mục đích và các kết quả đầu ra mong muốn (2 đến 5 phút).
2. Xếp các quyết định và những chủ đề khó nhất vào nửa đầu cuộc họp, khi năng lượng và sĩ số tham dự đang ở mức cao nhất.
3. Đặt các phần thảo luận và đánh giá ở khoảng giữa.
4. Đẩy các phần thông báo và cập nhật xuống cuối cùng hoặc đưa hẳn ra ngoài cuộc họp.
5. Kết thúc bằng các bước tiếp theo, người phụ trách và thời hạn hoàn thành (5 phút), không bao giờ kết thúc bằng mục AOB (Các vấn đề khác).
Hãy gom nhóm các mục cần sự có mặt của cùng một nhóm người lại với nhau để những người khác có thể rời cuộc họp sớm.

## Thời gian dự phòng và nghỉ giải lao
- Thời gian dự phòng (Buffer): khoảng 5 phút cho mỗi giờ họp, 10 phần trăm đối với hội thảo (workshop). Thời gian dự phòng nằm bên trong khung giờ họp, không phải là thời gian cộng thêm bên ngoài.
- Nghỉ giải lao (Breaks): 5 đến 10 phút sau mỗi 60 đến 90 phút; 15 phút đối với các buổi workshop dài hơn. Họp trực tuyến cần nghỉ giải lao sớm hơn họp trực tiếp.
- Lịch họp nối tiếp liên tục (Back-to-back): kết thúc sớm 5 phút (họp 25 hoặc 50 phút).

## Kiểm tra độ phù hợp (Fit checks)
- Nhiều hơn khoảng 8 mục trong một giờ đồng nghĩa với việc mỗi mục chỉ có chưa đầy 7 phút; hãy gộp lại hoặc cắt bớt.
- Cập nhật tiến độ và thông báo chiếm quá một phần ba tổng thời gian: hãy chuyển chúng thành tài liệu đọc trước.
- Một mục kéo dài trên 45 phút: hãy tách thành các bước nhỏ với kết quả đầu ra riêng biệt (ví dụ: "động não tìm ý tưởng 25 phút" rồi đến "nhóm ý tưởng và chọn lọc 20 phút").

## Chi phí của một cuộc họp
Giờ công (Person-hours) = số người tham dự x thời lượng tính bằng giờ. Một cuộc họp dài một giờ với 9 người tham dự tiêu tốn 9 giờ làm việc. Hãy tự hỏi liệu tất cả mọi người có thực sự cần có mặt trong tất cả các mục hay không.
FILE:references/facilitation-moves.md
# Các kỹ thuật điều phối giúp giữ vững khung thời gian

## Trước cuộc họp
- Gửi chương trình họp và tài liệu đọc trước từ 24 đến 48 giờ, ghi rõ người phụ trách của từng mục.
- Đối với mỗi mục cần ra quyết định, hãy gửi trước bản đề xuất dài một trang: câu hỏi cần giải quyết, các phương án, phương án khuyến nghị và người có quyền chốt.
- Yêu cầu mọi người ghi sẵn câu hỏi vào tài liệu đọc trước để cuộc họp bắt đầu ngay từ việc giải đáp câu hỏi chứ không phải ngồi nghe thuyết trình lại.

## Khi bắt đầu cuộc họp
- Nêu rõ mục đích và các kết quả cần đạt được khi kết thúc cuộc họp.
- Chỉ định một người canh giờ (timekeeper) và thống nhất tín hiệu báo giờ (nhắn vào khung chat, hoặc giơ tay khi còn 2 phút).
- Nêu rõ cách thức ra quyết định trong buổi họp hôm nay: người phụ trách tự quyết định sau khi lắng nghe ý kiến, biểu quyết theo đa số, hay đồng thuận ("có ai phản đối gay gắt không?").

## Theo từng loại mục
- Inform (Thông báo): "Trình bày hai phút, sau đó mỗi người một câu hỏi làm rõ." Các câu hỏi chi tiết sẽ được đưa vào danh sách tồn đọng (parking lot) hoặc trao đổi riêng sau cuộc họp.
- Update (Cập nhật): Chỉ nêu trực tiếp các vướng mắc (blockers) và đề xuất cần hỗ trợ; mọi thông tin khác đã nằm trong tài liệu đọc trước.
- Discuss (Thảo luận): Đóng khung câu hỏi trước ("Điều gì khiến chúng ta lo ngại về phương án B?"). Sử dụng vòng phát biểu nhanh để mọi người đều được nói một lần trước khi có ai đó nói lần thứ hai.
- Brainstorm (Động não): Dành 3 đến 5 phút tự viết ý tưởng trong im lặng trước, sau đó mới chia sẻ và gom nhóm. Ưu tiên số lượng trước khi đánh giá chất lượng.
- Review (Đánh giá): Thống nhất loại phản hồi cần thu thập: các vấn đề gây tắc nghẽn (blocking issues), câu hỏi thắc mắc, hay góp ý chau chuốt câu chữ. Thu thập các vấn đề gây tắc nghẽn trước tiên.
- Decide (Quyết định): Nhắc lại đề xuất, liệt kê các mối quan ngại, kiểm tra xem có ý kiến phản đối nào không, sau đó chốt quyết định và đọc to rõ ràng: "Chúng ta đã quyết định X; người phụ trách là Y; hoàn thành trước ngày Z."

## Khi một mục bị lố giờ
Làm cho sự lựa chọn trở nên minh bạch thay vì âm thầm lấn sang thời gian của mục tiếp theo:
1. "Chúng ta còn 2 phút cho mục này. Chúng ta muốn kéo dài thêm 5 phút và cắt bớt một mục khác, hay đưa nó vào danh sách chờ (parking lot)?"
2. Đưa vào danh sách chờ: ghi mục đó vào parking lot kèm theo người phụ trách và thời hạn xử lý.
3. Thu gọn mục tiếp theo, nhưng tuyệt đối không cắt xén thời gian của các mục ra quyết định.
4. Nếu mục tiêu chính của cuộc họp có nguy cơ không đạt được, hãy lên lịch một buổi họp ngắn tiếp theo chỉ với những người thực sự liên quan.

## Họp từ xa và họp kết hợp (Remote and hybrid)
- Mọi người đều tham gia bằng thiết bị cá nhân của mình để những người họp từ xa có vị thế bình đẳng.
- Sử dụng khung chat để xếp hàng đăng ký phát biểu và thực hiện các cuộc thăm dò ý kiến nhanh.
- Chia sẻ chương trình họp trên màn hình và tô sáng mục đang được thảo luận.

## Khi kết thúc cuộc họp
- Đọc lại các quyết định đã chốt, người phụ trách và thời hạn hoàn thành (5 phút).
- Rà soát danh sách tồn đọng (parking lot): phân công người xử lý cho từng mục hoặc loại bỏ nếu không cần thiết.
- Gửi biên bản cuộc họp trong vòng 24 giờ.
FILE:templates/agenda.md
# Đầu vào chương trình họp (dành cho scripts/timebox_agenda.py)

```
Meeting: <name>
Start: <HH:MM>
Length: <minutes>            # or End: <HH:MM>
Buffer: <minutes or percent, e.g. 5 or 10%>
Attendees: <number>

<minutes> | <topic> | <owner> | <inform | update | discuss | brainstorm | review | decide | break>
? | <topic with unknown duration> | <owner> | <outcome>
```
Một bảng Markdown với các cột Min, Topic, Owner, Outcome cũng hoạt động tương tự, và định dạng JSON cũng vậy:
`{"meeting": "...", "start": "14:00", "length": 60, "buffer": 5, "attendees": 6, "items": [{"minutes": 10, "topic": "...", "owner": "...", "outcome": "decide"}]}`

---

# Mẫu chương trình họp để gửi đi

**<Tên cuộc họp>**
<Thứ, ngày>, <bắt đầu>-<kết thúc> (<thời lượng> phút), <địa điểm hoặc liên kết video>
Người tham dự: <tên hoặc nhóm> | Điều phối viên: <tên> | Người canh giờ: <tên> | Thư ký ghi chép: <tên>

**Mục đích:** <một câu duy nhất: điều gì phải hoàn thành khi chúng ta kết thúc cuộc họp>

**Kết quả cần đạt được**
1. <quyết định hoặc kết quả>
2. <quyết định hoặc kết quả>

**Tài liệu đọc trước (trước <ngày, giờ>)**
- <tài liệu> - <người phụ trách> - <nội dung cần xem, thời gian đọc dự kiến>

**Lịch trình chi tiết**
| Thời gian | Phút | Hạng mục | Người phụ trách | Kết quả đầu ra |
|---|---|---|---|---|
| <HH:MM-HH:MM> | <n> | <chủ đề> | <người phụ trách> | <kết quả> |
| <HH:MM-HH:MM> | <n> | Dự phòng và tổng kết: các quyết định, người phụ trách, thời hạn | <điều phối viên> | |

**Cách thức ra quyết định hôm nay:** <người phụ trách quyết định sau khi nghe ý kiến | đồng thuận | biểu quyết>

**Danh sách tồn đọng (Parking lot):** Các ý kiến ngoài lề sẽ được đưa vào danh sách tồn đọng và phân công người phụ trách vào cuối buổi.

**Các nội dung đã chuyển ra ngoài cuộc họp này**
- <hạng mục> -> <cập nhật không đồng bộ, cuộc họp khác, hoặc tài liệu>, người phụ trách <tên>
FILE:examples/example-roadmap-meeting.md
# Ví dụ: chỉnh sửa một cuộc họp lập kế hoạch kéo dài một giờ bị quá tải

## Yêu cầu từ người dùng
"Tôi có cuộc họp một giờ với 9 người vào thứ Năm lúc 14:00 để lập kế hoạch Quý 4 (Q4). Đây là chương trình họp của tôi. Liệu có kịp giờ không? Việc phân bổ ngân sách bắt buộc phải được phê duyệt trong cuộc họp này, và cả 3 sáng kiến ưu tiên hàng đầu nữa."

Bản nháp chương trình họp (`agenda.txt`):
```
Meeting: Q4 roadmap planning
Start: 14:00
Length: 60
Buffer: 5
Attendees: 9

10 | Welcome and goals | Dana | inform
15 | Team status round (each team lead) | Leads | update
10 | Customer feedback highlights | Priya | inform
20 | Q4 priorities: pick top 3 initiatives | Lee | discuss
10 | Hiring plan for Q4 | | discuss
5 | Approve Q4 budget split | Dana | decide
? | AOB | |
```

## Lần chạy đầu tiên
```
$ python3 scripts/timebox_agenda.py agenda.txt
Q4 roadmap planning: 14:00-15:00 (60 min, buffer 5 min, 55 min for items)
Planned: 70 min

  14:00-14:10   10 min            Welcome and goals (Dana) [inform]
  14:10-14:25   15 min            Team status round (each team lead) (Leads) [update]
  14:25-14:35   10 min            Customer feedback highlights (Priya) [inform]
  14:35-14:55   20 min            Q4 priorities: pick top 3 initiatives (Lee) [discuss]
  14:55-15:05   10 min            Hiring plan for Q4 [discuss]
  15:05-15:10    5 min            Approve Q4 budget split (Dana) [decide]
  15:10-15:10    ? min            AOB [?]
  14:55-15:00    5 min            Buffer / wrap-up

Findings:
- [HIGH] Agenda needs 70 min but only 55 min are available after the 5-min buffer: overrun of 15 min (ends 15:10 instead of 14:55). Cut, shorten, or move items, or run with --fit.
- [WARN] 1 item(s) without a duration: AOB. Remaining time for them: 0 min.
- [WARN] "Hiring plan for Q4" has no owner; name who prepares and leads it.
- [WARN] "Approve Q4 budget split" is a decision with only 5 min; plan at least 10, or decide by a written proposal beforehand.
- [WARN] "Approve Q4 budget split" is a decision starting at 15:05, in the last quarter of the meeting; move it earlier while energy and attendance are high.
- [WARN] "AOB" has no owner; name who prepares and leads it.
- [WARN] "AOB" has no outcome; say whether it is to inform, discuss, decide, or brainstorm.
- [WARN] Status updates and announcements take 50% of the time; send them as a pre-read and keep the meeting for discussion and decisions.
- [INFO] Meeting cost: 9 people x 60 min = 9 person-hours.
```
Mã thoát (Exit code) 1: chương trình họp không vừa với khung giờ.

## Những con số nói lên điều gì
- 70 phút cho các hạng mục (cộng thêm mục AOB) trong một khung thời gian khả dụng chỉ 55 phút: đã bị lố 15 phút ngay cả trước khi bắt đầu mục AOB.
- Một nửa thời gian bị tiêu tốn vào việc cập nhật và thông báo, trong khi hai vấn đề bắt buộc phải chốt quyết định lại chỉ được dành cho 5 phút (ngân sách) và bị gắn nhãn "discuss" (các ưu tiên), hơn nữa quyết định về ngân sách lại bắt đầu lúc 15:05, tức là sau khi cuộc họp lẽ ra đã phải kết thúc.
- Nếu chỉ chạy tùy chọn `--fit` đơn thuần thì mọi thứ sẽ bị ép vào 55 phút nhưng quyết định ngân sách vẫn nằm ở cuối cùng với vẻn vẹn 5 phút. Việc ép các con số cho vừa vặn là chưa đủ; thứ tự và mục đích của từng hạng mục phải được thay đổi.

## Các thay đổi cần thực hiện
1. Vòng báo cáo tiến độ của các nhóm (15 phút) và điểm nhấn phản hồi khách hàng (10 phút) được chuyển thành tài liệu đọc trước bằng văn bản, hạn chót vào 12:00 trưa thứ Tư; các câu hỏi sẽ được để lại trong phần bình luận.
2. Phần phân bổ ngân sách được đẩy lên đầu cuộc họp với thời lượng 10 phút kèm bản đề xuất gửi từ thứ Hai, nhờ đó cuộc họp chỉ cần xác nhận hoặc điều chỉnh nhẹ.
3. Mục "Các ưu tiên Quý 4" được chuyển thành mục ra quyết định (`decide`) với 25 phút: kết quả đầu ra là danh sách 3 sáng kiến hàng đầu đã được xếp hạng.
4. Kế hoạch tuyển dụng có người phụ trách rõ ràng (Priya) và thu hẹp câu hỏi thảo luận: thống nhất mở tuyển những vị trí nào.
5. Mục AOB được thay thế bằng 5 phút tổng kết "các bước tiếp theo, người phụ trách và danh sách tồn đọng".
6. Ba người vốn chỉ cần tham gia vòng báo cáo tiến độ có thể không cần dự họp: rút gọn còn 6 người tham dự thay vì 9 người.

Chương trình họp sau khi chỉnh sửa:
```
Meeting: Q4 roadmap planning
Start: 14:00
Length: 60
Buffer: 5
Attendees: 6

5 | Welcome and goals for today | Dana | inform
10 | Approve Q4 budget split (proposal sent Monday) | Dana | decide
25 | Q4 priorities: pick top 3 initiatives | Lee | decide
10 | Hiring plan for Q4: agree which roles to open | Priya | discuss
5 | Next steps, owners, and parking lot | Dana | inform
```

## Lần chạy thứ hai
```
$ python3 scripts/timebox_agenda.py agenda-revised.txt
Q4 roadmap planning: 14:00-15:00 (60 min, buffer 5 min, 55 min for items)
Planned: 55 min

  14:00-14:05    5 min            Welcome and goals for today (Dana) [inform]
  14:05-14:15   10 min            Approve Q4 budget split (proposal sent Monday) (Dana) [decide]
  14:15-14:40   25 min            Q4 priorities: pick top 3 initiatives (Lee) [decide]
  14:40-14:50   10 min            Hiring plan for Q4: agree which roles to open (Priya) [discuss]
  14:50-14:55    5 min            Next steps, owners, and parking lot (Dana) [inform]
  14:55-15:00    5 min            Buffer / wrap-up

Findings:
- [INFO] Meeting cost: 6 people x 60 min = 6 person-hours.
```
Mã thoát 0, không có cảnh báo nào, và chi phí cuộc họp giảm xuống còn 6 giờ công thay vì 9 giờ công.

## Bản chương trình họp gửi đi (đã điền theo mẫu, rút gọn)

**Lập kế hoạch lộ trình Quý 4 (Q4 roadmap planning)**
Thứ Năm, 14:00-15:00 (60 phút), Phòng 3 và liên kết video
Điều phối viên: Dana | Người canh giờ: Lee | Thư ký ghi chép: Priya

**Mục đích:** Kết thúc cuộc họp với phương án phân bổ ngân sách Quý 4 được phê duyệt và danh sách 3 sáng kiến ưu tiên hàng đầu đã xếp hạng.

**Tài liệu đọc trước (trước 12:00 trưa thứ Tư)**
- Bản tóm tắt tiến độ 1 trang của các nhóm - từng trưởng nhóm - 5 phút đọc
- Điểm nhấn phản hồi từ khách hàng - Priya - 5 phút đọc
- Đề xuất phân bổ ngân sách - Dana - 10 phút đọc

**Lịch trình chi tiết**
| Thời gian | Phút | Hạng mục | Người phụ trách | Kết quả đầu ra |
|---|---|---|---|---|
| 14:00-14:05 | 5 | Chào mừng và nêu mục tiêu hôm nay | Dana | inform |
| 14:05-14:15 | 10 | Phê duyệt phân bổ ngân sách Quý 4 (đề xuất đã gửi thứ Hai) | Dana | decide |
| 14:15-14:40 | 25 | Ưu tiên Quý 4: chọn ra 3 sáng kiến hàng đầu | Lee | decide |
| 14:40-14:50 | 10 | Kế hoạch tuyển dụng Quý 4: thống nhất mở những vị trí nào | Priya | discuss |
| 14:50-14:55 | 5 | Các bước tiếp theo, người phụ trách và danh sách tồn đọng | Dana | inform |
| 14:55-15:00 | 5 | Thời gian dự phòng (Buffer) | | |

**Cách thức ra quyết định hôm nay:** Dana quyết định ngân sách sau khi lắng nghe ý kiến; 3 sáng kiến hàng đầu được chọn theo nguyên tắc đồng thuận (có ai phản đối gay gắt không?).

**Mẹo điều phối**
- Các ưu tiên: dành 3 phút bỏ phiếu chấm điểm (dot voting) trong im lặng trên danh sách ứng viên, sau đó chỉ thảo luận về các mục xếp hạng từ thứ 2 đến thứ 5.
- Nếu mục ngân sách chạm mốc 10 phút, hãy đưa điểm còn bỏ ngỏ vào danh sách chờ kèm người phụ trách và hạn chót 24 giờ thay vì lấn sang thời gian của phần chọn ưu tiên.

**Đã chuyển ra ngoài cuộc họp này:** vòng báo cáo tiến độ các nhóm và phản hồi khách hàng (chuyển thành tài liệu đọc trước).

## Vì sao đây là một phương án xử lý tốt
- Nó sửa tận gốc mục đích và thứ tự ưu tiên, chứ không chỉ cắt gọt số phút.
- Cả hai quyết định bắt buộc đều diễn ra trong 40 phút đầu tiên, với các bản đề xuất đã được chuẩn bị trước.
- Kịch bản kiểm tra xác nhận lịch trình vừa khít khung giờ, và những người vốn chỉ tham gia để báo cáo tiến độ tiết kiệm được trọn vẹn một giờ làm việc.
FILE:scripts/timebox_agenda.py
#!/usr/bin/env python3
"""Timebox a meeting agenda: schedule every item, check the fit, and flag agenda smells.

Usage:
  python3 timebox_agenda.py agenda.txt
  python3 timebox_agenda.py agenda.txt --fit          # scale items to fit the slot (5-minute steps)
  python3 timebox_agenda.py agenda.json --json
  cat agenda.txt | python3 timebox_agenda.py -

Text input: optional "Key: value" header lines, then one item per line as
  minutes | topic | owner | outcome
Markdown table rows (| 10 | Topic | Owner | decide |) also work; header and
separator rows are skipped. Use ? for an unknown duration.
Header keys: Meeting, Start (HH:MM), Length (minutes) or End (HH:MM),
  Buffer (minutes or percent, e.g. 5 or 10%), Attendees (number).
Outcomes: inform, update, discuss, brainstorm, review, decide, break.
JSON input: {"meeting": "...", "start": "14:00", "length": 60, "buffer": 5,
  "attendees": 8, "items": [{"minutes": 10, "topic": "...", "owner": "...", "outcome": "decide"}]}

--fit trims status items (and items with no outcome) first, then scales everything; spare time goes to
decide and discuss items.
Checks: overrun (HIGH), missing durations, owners, or outcomes, late or rushed
decisions, oversized items, long stretches without a break, too many status
updates, too many items per hour, plus the meeting's cost in person-hours.
Exit code: 0 no HIGH findings, 1 HIGH found, 2 usage or input error.
Standard library only.
"""
import argparse
import json
import math
import re
import sys

OUTCOMES = {"inform", "update", "discuss", "brainstorm", "review", "decide", "break"}
ALIASES = {"decision": "decide", "info": "inform", "fyi": "inform", "status": "update", "updates": "update",
           "discussion": "discuss", "ideas": "brainstorm", "ideation": "brainstorm", "feedback": "review",
           "approve": "decide", "approval": "decide", "pause": "break", "coffee": "break"}


class InputError(Exception):
    pass


def hhmm(text):
    m = re.fullmatch(r"\s*(\d{1,2})[:.](\d{2})\s*", str(text))
    if not m or int(m.group(1)) > 23 or int(m.group(2)) > 59:
        raise InputError(f"time must be HH:MM, got {text!r}")
    return int(m.group(1)) * 60 + int(m.group(2))


def fmt(minutes):
    minutes = int(round(minutes)) % (24 * 60)
    return f"{minutes // 60:02d}:{minutes % 60:02d}"


def parse_minutes(text):
    t = str(text).strip().lower()
    if t in ("", "?", "tbd", "-"):
        return None
    m = re.fullmatch(r"(\d+(?:\.\d+)?)\s*(m|min|mins|minutes?)?", t)
    if m:
        return float(m.group(1))
    m = re.fullmatch(r"(\d+(?:\.\d+)?)\s*h(?:ours?)?(?:\s*(\d+)\s*m(?:in)?)?", t)
    if m:
        return float(m.group(1)) * 60 + float(m.group(2) or 0)
    raise InputError(f"cannot read duration {text!r}")


def norm_outcome(text):
    t = (text or "").strip().lower()
    return ALIASES.get(t, t)


def parse_text(text):
    meta, items, errors = {}, [], []
    for no, raw in enumerate(text.replace("\r\n", "\n").split("\n"), 1):
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        hm = re.fullmatch(r"([A-Za-z ]{3,20}):\s*(.+)", line)
        if hm and "|" not in line:
            meta[hm.group(1).strip().lower()] = hm.group(2).strip()
            continue
        if "|" not in line:
            errors.append(f"line {no}: expected 'minutes | topic | owner | outcome', got {line[:60]!r}")
            continue
        cells = [c.strip() for c in line.strip("|").split("|")]
        if all(re.fullmatch(r":?-{2,}:?", c) for c in cells if c):
            continue
        if cells and cells[0].lower() in ("min", "mins", "minutes", "time", "duration"):
            continue
        cells += [""] * (4 - len(cells))
        try:
            minutes = parse_minutes(cells[0])
        except InputError as e:
            errors.append(f"line {no}: {e}")
            continue
        if not cells[1]:
            errors.append(f"line {no}: item has no topic")
            continue
        items.append({"line": no, "minutes": minutes, "topic": cells[1], "owner": cells[2],
                      "outcome": norm_outcome(cells[3])})
    return meta, items, errors


def parse_json(text):
    data = json.loads(text)
    if not isinstance(data, dict) or not isinstance(data.get("items"), list):
        raise InputError("JSON input needs an object with an 'items' list")
    meta = {k.lower(): str(v) for k, v in data.items() if k != "items" and v is not None}
    items, errors = [], []
    for i, it in enumerate(data["items"], 1):
        try:
            minutes = parse_minutes(it.get("minutes", ""))
        except InputError as e:
            errors.append(f"item {i}: {e}")
            continue
        if not str(it.get("topic", "")).strip():
            errors.append(f"item {i}: item has no topic")
            continue
        items.append({"line": i, "minutes": minutes, "topic": str(it["topic"]).strip(),
                      "owner": str(it.get("owner", "") or "").strip(), "outcome": norm_outcome(it.get("outcome", ""))})
    return meta, items, errors


def settings(meta):
    start = hhmm(meta.get("start", "09:00"))
    if "length" in meta:
        length = parse_minutes(meta["length"])
        if not length or length <= 0:
            raise InputError("Length must be a positive number of minutes")
    elif "end" in meta:
        length = (hhmm(meta["end"]) - start) % (24 * 60)
        if length == 0:
            raise InputError("End must be after Start")
    else:
        raise InputError("header needs 'Length: <minutes>' or 'End: HH:MM'")
    b = meta.get("buffer", "0").strip()
    if b.endswith("%"):
        buffer = 5 * round(length * float(b[:-1]) / 100 / 5)  # percent buffers round to 5 minutes
    else:
        buffer = parse_minutes(b) or 0
    if buffer >= length:
        raise InputError("Buffer must be shorter than the meeting")
    attendees = int(meta["attendees"]) if str(meta.get("attendees", "")).strip().isdigit() else None
    return {"meeting": meta.get("meeting", meta.get("title", "Meeting")), "start": start, "length": length,
            "buffer": buffer, "available": length - buffer, "attendees": attendees}


def fit(items, available):
    """Fit items into `available` minutes in 5-minute steps (missing durations count as 10, breaks kept).

    When the agenda is too long, status items (inform, update, or no outcome) are trimmed first, down to half
    their planned time; then every item is scaled proportionally. When it is too short, the
    spare time goes to decide and discuss items first.
    """
    fixed = sum(it["minutes"] or 0 for it in items if it["outcome"] == "break")
    flex = [it for it in items if it["outcome"] != "break"]
    room = available - fixed
    if not flex or room < 5 * len(flex):
        raise InputError(f"cannot fit {len(flex)} items into {room:g} minutes with at least 5 minutes each")
    want = [max(5, 5 * round((it["minutes"] or 10) / 5)) for it in flex]
    cur = list(want)
    status = [i for i, it in enumerate(flex) if it["outcome"] in ("inform", "update", "")]
    while sum(cur) > room:
        cands = [i for i in status if cur[i] - 5 >= max(5, want[i] / 2)]
        if not cands:
            break
        cur[max(cands, key=lambda k: cur[k])] -= 5
    if sum(cur) > room:
        scale = room / sum(cur)
        ref = [c * scale for c in cur]
        cur = [max(5, 5 * round(r / 5)) for r in ref]
        while sum(cur) > room:
            cands = [k for k in range(len(cur)) if cur[k] > 5]
            cur[max(cands, key=lambda k: (cur[k] - ref[k], cur[k]))] -= 5
        while sum(cur) + 5 <= room:
            cur[min(range(len(cur)), key=lambda k: cur[k] - ref[k])] += 5
    else:
        prio = [i for i, it in enumerate(flex) if it["outcome"] in ("decide", "discuss")] or list(range(len(flex)))
        while sum(cur) + 5 <= room:
            cur[min(prio, key=lambda k: cur[k] / want[k])] += 5
    out, it_new = [], iter(cur)
    for it in items:
        copy = dict(it)
        copy["original"] = it["minutes"]
        if it["outcome"] != "break":
            copy["minutes"] = float(next(it_new))
        out.append(copy)
    return out


def analyze(items, cfg):
    findings = []

    def add(sev, msg):
        findings.append({"severity": sev, "message": msg})

    t = cfg["start"]
    for it in items:
        it["start"] = t
        t += it["minutes"] or 0
        it["end"] = t
    planned = sum(it["minutes"] or 0 for it in items)
    avail, end_slot = cfg["available"], cfg["start"] + cfg["length"]
    unknown = [it for it in items if it["minutes"] is None]
    if planned > avail:
        add("HIGH", f"Agenda needs {planned:g} min but only {avail:g} min are available"
            f"{' after the ' + format(cfg['buffer'], 'g') + '-min buffer' if cfg['buffer'] else ''}: overrun of {planned - avail:g} min"
            f" (ends {fmt(cfg['start'] + planned)} instead of {fmt(end_slot - cfg['buffer'])}). Cut, shorten, or move items, or run with --fit.")
    elif avail - planned > 0.15 * avail and not unknown:
        add("INFO", f"{avail - planned:g} min unplanned; end early or give the main decision more time.")
    if unknown:
        add("WARN", f"{len(unknown)} item(s) without a duration: " + "; ".join(it["topic"][:40] for it in unknown)
            + f". Remaining time for them: {max(avail - planned, 0):g} min.")
    for it in items:
        name = f"\"{it['topic'][:50]}\""
        if it["outcome"] != "break" and not it["owner"]:
            add("WARN", f"{name} has no owner; name who prepares and leads it.")
        if not it["outcome"]:
            add("WARN", f"{name} has no outcome; say whether it is to inform, discuss, decide, or brainstorm.")
        elif it["outcome"] not in OUTCOMES:
            add("WARN", f"{name} has unknown outcome '{it['outcome']}' (use: {', '.join(sorted(OUTCOMES))}).")
        m = it["minutes"] or 0
        if it["outcome"] == "decide":
            if it["minutes"] is not None and m < 10:
                add("WARN", f"{name} is a decision with only {m:g} min; plan at least 10, or decide by a written proposal beforehand.")
            if it["start"] - cfg["start"] >= 0.75 * cfg["length"]:
                add("WARN", f"{name} is a decision starting at {fmt(it['start'])}, in the last quarter of the meeting; move it earlier while energy and attendance are high.")
        if it["outcome"] in ("discuss", "brainstorm", "review") and it["minutes"] is not None and m < 5:
            add("WARN", f"{name} is a {it['outcome']} item with {m:g} min; that is a mention, not a {it['outcome']}.")
        if m > 45 and it["outcome"] != "break":
            add("WARN", f"{name} is {m:g} min long; split it into parts with their own outcomes.")
    stretch, stretch_start = 0, cfg["start"]
    for it in items:
        if it["outcome"] == "break":
            stretch, stretch_start = 0, it["end"]
            continue
        stretch += it["minutes"] or 0
        if stretch > 90:
            add("WARN", f"{stretch:g} min without a break from {fmt(stretch_start)}; add a 5 to 10 min break about every 60 to 90 min.")
            stretch = -10**9
    status = sum(it["minutes"] or 0 for it in items if it["outcome"] in ("inform", "update"))
    if planned and status / planned > 0.35:
        add("WARN", f"Status updates and announcements take {round(100 * status / planned)}% of the time; send them as a pre-read and keep the meeting for discussion and decisions.")
    work_items = [it for it in items if it["outcome"] != "break"]
    hours = cfg["length"] / 60
    if hours and len(work_items) / hours > 8:
        add("WARN", f"{len(work_items)} items in {cfg['length']:g} min is more than 8 per hour; merge or drop items.")
    if not any(it["outcome"] == "decide" for it in items):
        add("INFO", "No decision items; check that this meeting needs to be live.")
    cost = None
    if cfg["attendees"]:
        cost = round(cfg["attendees"] * cfg["length"] / 60, 1)
        add("INFO", f"Meeting cost: {cfg['attendees']} people x {cfg['length']:g} min = {cost:g} person-hours.")
    order = {"HIGH": 0, "WARN": 1, "INFO": 2}
    findings.sort(key=lambda f: order[f["severity"]])
    return {"meeting": cfg["meeting"], "start": fmt(cfg["start"]), "end": fmt(end_slot), "length": cfg["length"],
            "buffer": cfg["buffer"], "available": avail, "planned": planned, "person_hours": cost,
            "items": [{k: (fmt(v) if k in ("start", "end") else v) for k, v in it.items()} for it in items],
            "findings": findings}


def main():
    ap = argparse.ArgumentParser(description="Timebox a meeting agenda")
    ap.add_argument("path", help="agenda text/Markdown/JSON file, or - for stdin")
    ap.add_argument("--fit", action="store_true", help="scale item durations to fit the available time")
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()
    try:
        text = sys.stdin.read() if args.path == "-" else open(args.path, encoding="utf-8").read()
        if not text.strip():
            raise InputError("input is empty")
        meta, items, errors = parse_json(text) if text.lstrip().startswith("{") else parse_text(text)
        if errors:
            raise InputError("could not read the agenda:\n  " + "\n  ".join(errors))
        if not items:
            raise InputError("no agenda items found (expected lines like '10 | Topic | Owner | decide')")
        cfg = settings(meta)
        before = sum(it["minutes"] or 0 for it in items)
        n_unknown = sum(1 for it in items if it["minutes"] is None)
        if args.fit:
            items = fit(items, cfg["available"])
    except FileNotFoundError:
        print(f"error: file not found: {args.path}", file=sys.stderr)
        return 2
    except (InputError, json.JSONDecodeError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    rep = analyze(items, cfg)
    rep["fitted_from"] = before if args.fit else None
    if args.json:
        print(json.dumps(rep, indent=2))
    else:
        print(f"{rep['meeting']}: {rep['start']}-{rep['end']} ({rep['length']:g} min, buffer {rep['buffer']:g} min, {rep['available']:g} min for items)")
        if args.fit:
            extra = f" plus {n_unknown} without a duration (counted as 10 min each)" if n_unknown else ""
            print(f"Fitted: {before:g} min of items{extra} fitted into {rep['planned']:g} min (5-minute steps, breaks kept).")
        print(f"Planned: {rep['planned']:g} min\n")
        for it in rep["items"]:
            mins = "?" if it["minutes"] is None else f"{it['minutes']:g}"
            was = f" (was {it['original']:g})" if args.fit and it.get("original") not in (None, it["minutes"]) else ""
            who = f" ({it['owner']})" if it["owner"] else ""
            print(f"  {it['start']}-{it['end']}  {mins:>3} min{was:<10}  {it['topic']}{who} [{it['outcome'] or '?'}]")
        if rep["buffer"]:
            print(f"  {fmt(hhmm(rep['end']) - rep['buffer'])}-{rep['end']}  {rep['buffer']:>3g} min            Buffer / wrap-up")
        print()
        if rep["findings"]:
            print("Findings:")
            for f in rep["findings"]:
                print(f"- [{f['severity']}] {f['message']}")
        else:
            print("Findings: none")
    return 1 if any(f["severity"] == "HIGH" for f in rep["findings"]) else 0


if __name__ == "__main__":
    sys.exit(main())

Hãy đóng vai một nhà thiết kế kiến trúc chuyên về nhà trên cây, phòng làm việc sân vườn (garden studio) và các công trình nghỉ dưỡng nhỏ bằng gỗ, đồng thời là giám đốc nghệ thuật diễn họa hình ảnh. Tôi sẽ mô tả ngôi nhà trên cây mà tôi đang mơ ước. Bạn sẽ chuyển hóa nó thành một bản ý tưởng thiết kế rõ ràng với các chi tiết thiết kế cố định, kèm theo hai câu lệnh tạo ảnh (image prompt) sẵn sàng sử dụng để hiển thị CÙNG MỘT ngôi nhà trên cây trong hai mùa khác nhau và từ hai góc nhìn khác nhau, sao cho hai bức ảnh AI trông giống hệt như ảnh chụp của cùng một công trình có thật ngoài đời.

Cây chủ và khu đất: a single huge old oak in a sloping meadow at the edge of a beech forest, trunk about 1.2 m wide, splitting into three main limbs about 5 m up
Người sử dụng và mục đích sử dụng: a family retreat for reading, sleepovers for two kids, and quiet evenings for the adults
Kích thước và độ cao: a small cabin about 3 x 4 m on a deck about 3.5 m above the ground
Định hướng phong cách: warm natural timber, a little storybook but not cartoonish, simple modern details
Yếu tố bắt buộc phải có: a big window facing the forest, a covered deck, a small wood stove, a rope swing
Mức ngân sách: self-build with a carpenter's help, mid-range materials
Góc nhìn A: summer afternoon, full green canopy, seen from the meadow at the front left
Góc nhìn B: snowy winter evening, bare branches, windows glowing, seen from the front right

Vui lòng tạo ra các nội dung sau:

1. Ý tưởng thiết kế (Design concept)
   - Tên ý tưởng và một câu chuyện ngắn dài hai câu mô tả cảm giác mà ngôi nhà trên cây mang lại.
   - Mô tả kết cấu bằng lời: cách nâng đỡ sàn công trình (bu lông neo vào thân cây, cột chống, thanh giằng chéo), kích thước sàn hiên, diện tích mặt bằng cabin, hình dáng mái nhà, và lối tiếp cận (cầu thang bộ, thang leo, hoặc cầu treo), kèm theo chiều cao và kích thước ước tính.
   - Các mặt đứng (Facades): có những chi tiết gì trên bức tường phía trước, bên trái, bên phải và phía sau (cửa đi, cửa sổ, ống khói), được mô tả theo hướng nhìn từ phía đồng cỏ.
   - Bảng màu: 6 màu có tên gọi cụ thể (sử dụng tên màu dễ hình dung như "tuyết tùng mật ong" hoặc "xanh rêu") và vị trí áp dụng của từng màu.
   - Vật liệu và hoàn thiện: lớp gỗ ốp tường ngoài, mái nhà, sàn hiên, lan can, cửa sổ và cửa đi, các chi tiết kim loại, hệ thống chiếu sáng.

2. Các chi tiết thiết kế cố định (danh sách đảm bảo tính nhất quán)
   Một danh sách đánh số gồm 12 đến 16 chi tiết bắt buộc phải trông giống hệt nhau trong mọi bức ảnh: cây chủ và cách nó giao cắt với sàn hiên, hệ kết cấu đỡ, ván ốp tường, mái nhà, từng ô cửa sổ và cửa đi kèm màu sắc và hình dáng, ống khói, lan can, cầu thang, xích đu, đồ nội thất trên hiên, đèn chiếu sáng, và các chi tiết cảnh quan dưới mặt đất, mỗi chi tiết đều ghi rõ vị trí chính xác. Hãy viết từng mục thành một cụm từ ngắn gọn, cụ thể để công cụ tạo ảnh có thể làm theo chính xác (ví dụ: "cửa kiểu Hà Lan màu xanh mòng két nằm ở nửa bên phải của bức tường mặt trước").

3. Câu lệnh tạo ảnh A (Image prompt A): góc nhìn cơ sở
   Một câu lệnh chi tiết dành cho công cụ tạo ảnh AI: ảnh chụp kiến trúc chân thực (photoreal architectural photography) của ngôi nhà trên cây từ vị trí góc nhìn A, trong mùa và điều kiện ánh sáng của góc nhìn A. Bao gồm mọi chi tiết cố định có thể nhìn thấy từ góc đó ở đúng vị trí tương ứng (bên trái và bên phải tính từ góc máy ảnh), độ cao máy ảnh và tiêu cự ống kính, ánh sáng, bầu không khí, cùng bố cục khung hình ngang tỷ lệ 16:9. Kết thúc bằng các yếu tố loại trừ (không có người, không có chữ viết, không có logo).

4. Câu lệnh tạo ảnh B (Image prompt B): góc nhìn thứ hai
   Một câu lệnh chi tiết cho góc nhìn B, được viết cho công cụ tạo ảnh chỉ nhận văn bản và không thể nhìn thấy bức ảnh A: hãy nêu lại ĐẦY ĐỦ TẤT CẢ các chi tiết cố định bằng từ ngữ trọn vẹn (tuyệt đối không viết "giống như trên"), đặt từng chi tiết vào đúng vị trí tương ứng với góc máy mới, mô tả những phần mới lộ ra ở góc này, và chỉ thay đổi mùa, thời tiết, thời điểm trong ngày và ánh sáng (ví dụ: tuyết phủ trên mái và sàn hiên, cành cây trụi lá, ánh sáng ấm áp hắt ra từ cửa sổ, khói bay lên từ ống khói). Giữ nguyên hoàn toàn vật liệu, màu sắc và tỷ lệ.

5. Danh sách kiểm tra tính nhất quán
   Mười câu hỏi kiểm tra Có/Không để đối chiếu bức ảnh B với bức ảnh A (ví dụ: "Cánh cửa có còn giữ màu xanh mòng két và chia làm hai nửa trên và dưới hay không?").

6. Ghi chú thi công và an toàn
   Một danh sách ngắn gọn bao gồm sức khỏe của cây (cần nhờ chuyên gia cây xanh kiểm tra tình trạng cây), phương pháp liên kết cơ khí cho phép thân cây tiếp tục lớn lên và đung đưa tự nhiên, tải trọng và chiều cao an toàn của lan can, an toàn phòng cháy chữa cháy xung quanh bếp củi/lò sưởi, các loại giấy phép xây dựng cần kiểm tra tại địa phương, và ba cách giúp tiết kiệm chi phí.

Quy tắc:
- Đảm bảo thiết kế có tính khả thi để xây dựng thực tế đối với kích thước, độ cao và mức ngân sách đã nêu; cảnh báo ngay bất kỳ chi tiết nào mất an toàn hoặc phi thực tế.
- Sử dụng tên màu sắc thông dụng và mô tả hình khối cụ thể; tránh dùng đơn lẻ những tính từ mơ hồ như "ấm cúng" hay "hiện đại".
- Không nhắc đến tên thương hiệu, người thật hoặc chữ viết đọc được trong ảnh.
- Nếu phần mô tả của tôi còn thiếu thông tin quan trọng nào, hãy đưa ra giả định hợp lý và liệt kê rõ ở ngay phần đầu.

Hãy đóng vai chuyên gia lập kế hoạch và điều phối đếm ngược quá trình chuyển nhà. Bạn đã tổ chức hàng trăm cuộc chuyển dọn hộ gia đình, từ căn hộ studio nhỏ đến nhà nguyên căn cho gia đình lớn, cả chuyển nhà nội thành lẫn xuyên tỉnh/xuyên quốc gia. Bạn biến sự hỗn loạn của việc chuyển nhà thành một kế hoạch điềm tĩnh, có ngày tháng rõ ràng: cần đặt dịch vụ gì, phân loại thanh lý những gì, đóng gói món nào vào lúc nào, cần thông báo cho ai, và phải làm gì vào đúng ngày chuyển dọn. Bạn thực tế và biết cách trấn an tâm lý, luôn cân nhắc đồng thời cả tiền bạc, thời gian lẫn sức lực, và luôn trù tính trước những việc mọi người hay quên cho đến tận tuần cuối cùng.

Thông tin về đợt chuyển nhà của tôi:
- Chuyển từ đâu đến đâu: a 2-bedroom rented flat on the 3rd floor with no lift, to a small house 40 km away
- Ngày chuyển nhà và mức độ linh hoạt: Saturday 14 November, can shift by one week
- Những ai cùng chuyển nhà: two adults, a 6-year-old, and an indoor cat
- Khối lượng đồ đạc: normal amount for a 2-bedroom flat, full kitchen, a piano, many books
- Thuê dịch vụ chuyển nhà hay tự làm (DIY): not decided yet, budget is tight but we have bad backs
- Ngân sách dành cho việc chuyển nhà: 1500 EUR including everything
- Ràng buộc về công việc và thời gian: both work full-time, evenings and weekends free, can take one day off
- Tình trạng bàn giao nơi ở cũ: must return keys and hand over the flat clean by 30 November to get the deposit back
- Những điều khiến tôi lo lắng nhất: the piano, keeping the child's routine, losing important documents

Vui lòng thực hiện các nội dung sau:
1. Bắt đầu bằng một bước đánh giá thực tế nhanh: số tuần còn lại, 3 rủi ro lớn nhất đối với đợt chuyển nhà của tôi, và liệu ngày chuyển dự kiến cùng ngân sách đó có khả thi hay không. Nêu rõ bất kỳ giả định nào bạn đưa ra.
2. Giúp tôi quyết định giữa việc thuê dịch vụ chuyển nhà trọn gói hay tự chuyển (DIY) bằng một bảng so sánh ngắn gọn sát với hoàn cảnh của tôi: khoảng chi phí ước tính, thời gian, công sức thể chất và rủi ro, cộng thêm các món đồ đặc thù (chẳng hạn như đàn piano) mà đằng nào cũng nên thuê thợ chuyên nghiệp vận chuyển. Hãy cung cấp cho tôi 5 câu hỏi cần hỏi mọi công ty chuyển nhà và những hạng mục bắt buộc phải có trong một bản báo giá minh bạch.
3. Xây dựng lịch trình đếm ngược từng tuần từ hôm nay cho đến ngày chuyển nhà, với 4 đến 8 công việc cụ thể mỗi tuần, mỗi việc đều gắn rõ người phụ trách (tôi, vợ/chồng, cả hai, trẻ nhỏ có thể phụ giúp) và thời gian ước tính. Bao gồm việc đặt công ty chuyển nhà hoặc thuê xe tải, đặt mua thùng carton, dọn dẹp tinh giản đồ đạc theo từng phòng, bán thanh lý hoặc quyên góp, thông báo thay đổi địa chỉ, chuyển đổi hợp đồng điện nước và internet, cập nhật hồ sơ trường học và phòng khám bác sĩ, cũng như đăng ký chỗ đỗ xe tải hoặc đặt lịch dùng thang máy.
4. Đưa ra thứ tự đóng gói theo từng phòng: món gì đóng gói trước tiên (ít sử dụng) và món gì đóng gói sau cùng, dự kiến cần bao nhiêu thùng cho mỗi phòng, cách dán nhãn thùng để lúc dỡ đồ tìm kiếm nhanh nhất, và những gì cần cho vào chiếc thùng "đêm đầu tiên" cùng túi "giấy tờ và đồ quý giá" tuyệt đối không bao giờ chất lên xe tải.
5. Viết danh sách các đơn vị cần thông báo đổi địa chỉ được phân nhóm theo loại hình (cơ quan hành chính và đăng ký cư trú, ngân hàng và bảo hiểm, điện nước/viễn thông, nơi làm việc và trường học, y tế, các gói đăng ký định kỳ và giao hàng, bạn bè và người thân), kèm một cột ghi rõ thời điểm cần thông báo.
6. Lập kế hoạch ngày chuyển nhà chi tiết theo từng giờ: ai có mặt ở đâu, việc trông nom trẻ nhỏ và mèo cưng, thứ tự bốc xếp đồ lên xe, bước kiểm tra rà soát lần cuối tại nơi ở cũ, và lịch trình hai giờ đầu tiên khi đặt chân tới ngôi nhà mới.
7. Hướng dẫn quy trình bàn giao nhà cũ: danh sách kiểm tra việc vệ sinh và sửa chữa nhỏ để lấy lại toàn bộ tiền đặt cọc, chốt chỉ số đồng hồ điện nước và các góc cần chụp ảnh lưu bằng chứng, cũng như những nội dung cần lập biên bản bằng văn bản.
8. Kết thúc bằng bản tóm tắt dài một trang: các mốc ngày quan trọng, bảng phân bổ ngân sách, 5 điều tuyệt đối không được quên, và danh sách công việc cho "tuần đầu tiên tại ngôi nhà mới".

Quy tắc:
- Sử dụng ngày tháng và điều kiện ràng buộc thực tế của tôi; hiển thị mọi hạn chót dưới dạng ngày cụ thể chứ không viết chung chung kiểu "trước vài tuần".
- Giữ cho mỗi đầu việc ngắn gọn và dễ hành động, bắt đầu bằng một động từ.
- Trung thực về chi phí dưới dạng khoảng giá và gắn nhãn rõ đó là mức ước tính cho khu vực của tôi.
- Đưa vào những mẹo nhỏ giúp giữ tâm lý bình tĩnh, nhẹ nhàng cho cả trẻ nhỏ và thú cưng trong suốt quá trình chuyển nhà.
- Nếu thiếu thông tin quan trọng nào, hãy đưa ra giả định hợp lý và nêu rõ thay vì hỏi lại quá nhiều câu hỏi.