en

blog

Gate nguồn cứng check:sources: chặn build khi bài có số chưa khai nguồn

Agent viết bài thì số đúng lúc viết vẫn trôi hoặc bị bịa. check:sources chặn prebuild khi bài thiếu sidecar .sources.yml hoặc còn số dạng dữ liệu chưa khai. Cách nó chạy và 4 chỗ nó không bắt được.

Ngày đăng
Claude CodeAI AgentBuild gateFact-checking
Sơ đồ 3 khối nối nhau: file post.md có các thẻ số, khối check:sources tô màu accent ở giữa nhận thêm file sidecar từ bên dưới, khối build bên phải nối bằng đường nét đứt

Gate nguồn của repo này là 1 script Node chạy trong prebuild. Bài trong content/blog/ thiếu file <slug>.sources.yml, hoặc có con số dạng dữ liệu chưa khai trong đó, thì build fail và deploy không chạy. Gate ép khai nguồn cho mọi con số, không kiểm nguồn đó có đúng không; phần cuối bài nêu chỗ nó bỏ sót, kiểm bằng một file thử.

Vì sao bài do agent viết cần gate nguồn cứng

Nội dung của site được viết cùng agent, và agent sai theo 2 kiểu. Bịa: dựng câu nghe hợp lý, như bài PageSpeed từng viết "Tài liệu của Chrome nói thẳng không có thay đổi nào về cách tính điểm", trong khi không tài liệu nào nói câu đó. Trôi: số đúng lúc viết, sai dần sau đó, ví dụ số issue mở của một repo đi từ 301 lên 311.

Sidecar không ngăn được việc viết sai. Nó làm cho việc viết sai kiểm được: 6 tháng sau vẫn biết con số nào lấy ở đâu và cái nào cần đo lại. Quy tắc nền là nguồn người dùng đưa là căn cứ duy nhất, trừ 2 ngoại lệ: thứ kiểm chứng được bằng một lệnh chạy tại chỗ, và số đo của chính tác giả. Không ground được thì cắt; cắt mà gãy lập luận thì hỏi.

Sidecar khai nguồn: 3 tier, 3 dạng from

Mỗi bài có 1 file .sources.yml nằm cạnh nó. Ví dụ rút gọn từ bài về cắt AGENTS.md:

yaml
checked: '2026-11-17'

sources:
  - id: repo
    tier: local
    for: mọi số đo và mô tả commit dời bẫy khỏi AGENTS.md

claims:
  - text: 'AGENTS.md trước khi cắt 23.551 byte, sau khi cắt 17.282 byte'
    numbers: ['23.551', '17.282']
    from: 'cmd: git show b89dd27^:AGENTS.md | wc -c ; git show b89dd27:AGENTS.md | wc -c'

tier nhận primary (trang chính chủ của thứ đang nói tới), web (nguồn thứ cấp tự tìm được) hoặc local (máy mình, repo mình). Mọi tier trừ local bắt buộc có url. Trường from của claim là id của một source, hoặc local, hoặc cmd: <lệnh>. Dạng cmd: mạnh nhất vì người sau chạy lại được.

Số sẽ trôi (số sao, giá, version được hỗ trợ) thì thêm volatile: true. npm run check:freshness và cron hàng tuần báo khi claim đó quá 90 ngày chưa kiểm lại.

Gate chặn build ở prebuild

json
"prebuild": "npm run check:sources && node scripts/check-i18n.js && ..."

npm run build tự chạy prebuild trước next build. Workflow deploy chạy npm run build:static, lệnh này gọi npm run build, và job publish có needs: build, nên gate đỏ nghĩa là không có gì được publish. Script thoát với mã 1 và in từng lỗi. Đây là kết quả chạy trên một file thử, đường dẫn đã rút gọn:

text
check-sources: nguồn khai thiếu

  gate-probe.sources.yml: claims[1].from = "nguon-khong-co" không khớp source id nào, cũng không phải cmd:/local
  gate-probe.md:7: số "17%" không khai trong sidecar
  gate-probe.md:7: số "123 MB" không khai trong sidecar

10 lỗi. Sửa sidecar hoặc bỏ số khỏi bài.

Có 3 loại lỗi: bài không có sidecar, sidecar sai schema (thiếu checked, tier lạ, from không khớp id nào, còn chữ TODO), và số chưa khai. Khung sidecar do new-post.js blog dựng chứa TODO có chủ đích, nên khung chưa điền không lọt được vào build. Điều kiện kiểm là cả sidecar không được chứa chữ đó ở bất kỳ đâu: sidecar của chính bài này bị chặn ở lần chạy đầu vì một claim mô tả cơ chế trên có viết ra chữ TODO, và tôi phải tả nó vòng vo. Bài Anh dùng sidecar của bản Việt qua translationOf. Script chuẩn hoá dấu phẩy thành dấu chấm, nên 21,066 ở bản Anh khớp 21.066 đã khai ở bản Việt.

Liệt kê số cần khai bằng --list

bash
node .claude/skills/blog-post/scripts/check-sources.js --list content/blog/<slug>.md

Đây là đầu ra thật khi tôi viết bài về AGENTS.md, trước lúc có sidecar:

text
cat-agents-md-duoi-20k-ky-tu.md  7 số chưa khai
  21.066 · 15.562 · 0,1 · 23.551 · 17.282 · 10.782 · 12.444

Quy trình: viết bài từ nguồn được đưa, chạy --list, viết sidecar gom số theo claim (1 claim gom được nhiều số), chạy lại không cờ cho tới khi sạch. Số nào không truy được về nguồn thì bỏ khỏi bài, đừng bịa một from.

Gate bắt dạng số nào: thử bằng file có sẵn mọi dạng

Script chỉ bắt số có hình dạng dữ liệu: thập phân hoặc version (2,5, 13.3.0), phân cách nghìn (23.551), số kèm đơn vị (%, ms, MB, kB, GB, KB, USD, K, B), ngày (7/5/2026, 2/2026). Số cấu trúc như "3 chỗ" hay "5 release" là cách hành văn nên bị bỏ qua. Frontmatter, code fence và inline code cũng bị bỏ qua. File thử, rút gọn:

markdown
---
layout: BlogPost
title: 'Probe 99% title'
---

Số trần 17282 và 258 dòng. Chữ thường 95k và 20k ký tự.
Có đơn vị: 17% và 200ms và 123 MB và 95K. Thập phân 2,5 và 13.3.0.
Phân cách nghìn 23.551 và ngày 7/5/2026 và 2/2026.
Trong code `4311 bytes 88%` thì bỏ qua.

| cột | số |
| --- | --- |
| a | 12,5 |

--list trên file này in 10 số: 17%, 200ms, 123 MB, 95K, 2,5, 13.3.0, 23.551, 7/5/2026, 2/2026 và 12,5 trong ô bảng. Không số nào trong 5 thứ còn lại bị bắt: 17282, 258, 95k, 20k và 99% ở title.

4 chỗ check:sources không bắt được

1. Số trần, k chữ thường, frontmatter. 17282 và 258 không khớp mẫu nào. Đơn vị K và B chỉ khớp chữ hoa, nên 95K bị bắt còn 95k thì lọt. Phần trăm trong title hay description không bị quét vì frontmatter bị bỏ qua, dù chúng là thứ người đọc thấy đầu tiên.

2. Khai theo chuỗi số, không theo claim. Script gom mọi số khai trong sidecar vào 1 tập, rồi so từng số trong prose với tập đó. Thử gán 200ms cho một claim chẳng liên quan tới câu có 200ms trong bài: dòng đó không bị báo. Số nằm ngay trong text của claim cũng tính là đã khai.

3. Không kiểm nguồn thật. from chỉ cần khớp id của một source, hoặc bắt đầu bằng cmd:, hoặc là local. Lệnh không được chạy và URL không được mở. Thử khai 17% cho một claim có from: 'cmd: echo khong-lien-quan': lỗi của 17% biến mất, trong khi lệnh đó không hề in ra con số nào. Gate bắt được from trỏ vào id không tồn tại (có trong đầu ra ở trên).

4. Claim định tính. "Tài liệu X nói Y", gán sai nguồn cho một con số đúng, mô tả lệch nội dung issue: không có số nào để đối chiếu nên script bỏ qua. Riêng dạng "tài liệu X nói Y" chỉ chặn được bằng cách mở X ra tìm đúng câu Y; không thấy thì viết thành lập luận của mình và nói rõ đó là lập luận.

Việc chưa làm cho gate

Chỗ 1 sửa được bằng cách quét frontmatter và bắt thêm k chữ thường, nhưng số cấu trúc như "5 release" cũng sẽ dính vào, nên mỗi lần nới mẫu là đổi lấy thêm dương tính giả. Chỗ 2 cần gắn số với claim theo từng câu, và đó là phần việc lớn nhất. Chỗ 3 và 4 là việc của người đọc lại: gate không thay được bước mở nguồn ra đối chiếu, nó chỉ để lại dấu vết cho bước đó.

Bài viết liên quan

tất cả bài viết →