Preview · Markdown rendered with real HTML tables
SOP — Artifact Preview trước GitHub
Mục đích
Chuẩn hoá cách CEO AI OS tạo và bàn giao artifact như Markdown, HTML, slide deck, video draft, social script, SOP, PDF hoặc tài liệu dài: AI phải tạo file thật, publish preview public để Minh Đức duyệt, rồi mới sync/push vào GitHub hoặc source-of-truth repo.
Quy trình này giúp tránh 3 lỗi thường gặp:
- Đẩy nháp lên GitHub quá sớm.
- Chỉ trả local path khiến người dùng khó xem trên điện thoại/Telegram.
- Làm mất dấu bản nào đã được duyệt.
Phạm vi áp dụng
Áp dụng khi assistant tạo hoặc chỉnh artifact cần review, gồm:
| Loại artifact | Ví dụ | Bắt buộc preview? |
|---|---|---|
| Markdown dài | content plan, SOP, script, bài viết, research note | Có |
| HTML | slide deck, landing draft, mockup, visual preview | Có |
| Slide/deck | HTML deck, Marp, PPTX export preview | Có |
| Video/script | kịch bản video, caption series, shot list | Có nếu dài/cần duyệt |
| Social creative | carousel HTML, caption pack, content calendar | Có nếu là plan hoặc pack nhiều bài |
| Code thuần | patch, backend fix, script nội bộ | Không bắt buộc, dùng test/lint/review thay preview |
Nguyên tắc bắt buộc
- Write disk first: artifact phải được ghi ra file/folder trước, không chỉ trả nội dung trong chat.
- Preview before source sync: publish preview URL trước khi commit/push GitHub, trừ khi user đã yêu cầu rõ là commit ngay.
- One artifact, one preview URL: với content series nhiều bài, mỗi bài có URL riêng; master content plan phải được cập nhật link preview của từng bài.
- Approval gate: chỉ sync GitHub/source-of-truth sau khi Minh Đức approve rõ ràng.
- Verify public access: preview URL phải trả HTTP 200 trước khi gửi.
- No secrets / no repo internals: chỉ publish output cần review, không publish
.env, token, DB, toàn repo hoặc thư mục runtime. - Final reviewer: luôn nhắc user kiểm chứng claim, số liệu, người nhận, chính tả, thông tin nhạy cảm trước khi dùng thật.
Quy trình chuẩn
1. Chọn đúng workflow/skill
- Artifact nói chung: load skill
artifact-preview-workflow. - Sync GitHub/source-of-truth: load skill
github-repo-syncnếu cần commit/push sau approval. - Website live/staging: ưu tiên
staged-site-deployment, không dùng output preview thay cho staging thật. - Content/social/video script: vẫn dùng skill chuyên môn tương ứng, nhưng áp thêm workflow preview này ở bước bàn giao.
2. Tạo artifact trong working directory
Khuyến nghị đặt file nháp ở workspace/task folder hoặc đúng folder dự án nếu đó là source draft đã được yêu cầu.
Ví dụ:
/root/.hermes/kanban/workspaces/<task>/content-plan.md/tmp/<slug>/index.htmlyoutube/content/videos/sources/<series>/post-03/post-03.mdnếu đang làm trong repo nguồn và chưa commit.
Checklist trước publish:
- File tồn tại.
- Tên file rõ nghĩa.
- Không chứa secret, token, dữ liệu riêng tư không cần thiết.
- Markdown có bảng thật nếu cần đọc trên mobile.
- HTML tự chứa asset hoặc copy đủ asset đi kèm.
3. Publish preview
Dùng helper chuẩn từ root CEO AI OS:
python3 lib/publish_preview.py <source-file-or-dir> --name <slug> --title "<title>"Preview server hiện tại:
- Local root:
/root/sds/preview/outputs/ - Public base URL:
https://outputs.185.111.159.12.nip.io/
Lưu ý quan trọng:
--namesẽ được slugify thành một slug phẳng, ví dụseries/post-03thànhseries-post-03.- Không tự đoán URL nếu chưa nhìn output của script.
- Với Markdown, helper tự render
index.htmlđể bảng Markdown hiển thị thành HTML table thật. - Với folder, helper copy folder output và tạo index nếu cần.
4. Verify preview
Bắt buộc chạy kiểm tra HTTP:
curl -I <preview-url>Đạt khi trả 200 hoặc 2xx/3xx hợp lệ. Nếu là HTML quan trọng, nên mở browser/screenshot để kiểm tra layout. Nếu là Markdown render, kiểm tra nhanh index.html đã có nội dung chính.
5. Gửi cho user trước approval
Bàn giao ngắn, gồm:
- Preview URL.
- File/folder đã tạo.
- Những gì cần user review.
- Nói rõ GitHub/source-of-truth chưa được push.
- Nhắc kiểm chứng đầu ra AI trước khi dùng thật.
Mẫu trả lời:
Em đã tạo bản preview để anh duyệt:
Preview: https://outputs.185.111.159.12.nip.io/<slug>/
File nguồn: <path>
Cần anh rà: claim/số liệu/giọng văn/link CTA.
GitHub chưa được push. Sau khi anh duyệt, em mới sync bản này vào repo nguồn.6. Chờ approval rõ ràng
Các câu được coi là approve:
- “duyệt”
- “ok push”
- “đưa lên GitHub”
- “sync repo”
- “deploy live” nếu đúng ngữ cảnh deployment và đã có staging/preview
Các câu chưa đủ approve:
- “xem ổn” nhưng còn yêu cầu sửa.
- “tiếp tục” khi chưa rõ tiếp tục sửa hay push.
- Reaction/emoji mơ hồ.
Nếu mơ hồ, hỏi lại ngắn trước khi sync.
7. Sync GitHub/source-of-truth sau approval
Trước khi stage:
git status --shortKhông stage secrets/runtime state:
.env,auth.json, token/credential files*.db,*.db-shm,*.db-wallogs/,cache/,sessions/- user runtime folders như
users/tg_*/ - preview output server cache nếu không phải source artifact
Stage đúng file đã duyệt, commit/push theo repo hiện hành. Với website CEO AI OS, tuân thủ staging-first và deploy-live chỉ sau approval riêng.
8. Bàn giao sau sync
Sau approval và sync, báo:
- Commit hash/message hoặc kết quả sync.
- GitHub path/URL nếu có.
- Preview/live URL nếu còn hữu ích.
- Kết quả verify.
- Nhắc user vẫn là người duyệt cuối với số liệu/claim.
Checklist nhanh cho agent
| Bước | Câu hỏi kiểm tra | Pass? |
|---|---|---|
| 1 | Đã ghi artifact ra disk chưa? | |
| 2 | Đã publish bằng lib/publish_preview.py chưa? | |
| 3 | Đã dùng URL thực từ output script chưa? | |
| 4 | URL trả HTTP 200 chưa? | |
| 5 | Preview chỉ chứa file cần review, không có secret/repo internals? | |
| 6 | Đã nói rõ GitHub chưa push trước approval chưa? | |
| 7 | Đã có approval rõ trước khi sync/push chưa? | |
| 8 | Sau sync, đã báo commit/kết quả verify chưa? |
Cách áp vào các nhóm việc hiện có
Markdown / content plan / script
- Ghi
.mdvào workspace hoặc folder dự án. - Publish bằng
lib/publish_preview.pyđể có HTML readable preview. - Nếu là series, publish từng bài riêng, rồi cập nhật lại content plan với link preview của từng bài.
HTML / slide deck / carousel
- Ghi nguyên folder HTML + assets.
- Publish folder output, không publish toàn repo.
- Verify bằng HTTP và nếu quan trọng thì mở browser/screenshot.
Video draft
- Nếu mới là script/shot list: publish Markdown preview.
- Nếu đã render video: publish một folder có video file + index, hoặc dùng kênh delivery phù hợp nếu file quá lớn.
- Không push video nặng lên GitHub nếu repo không được thiết kế cho binary media.
Website
- Dùng staging thật của site, không chỉ output preview.
- Preview URL của outputs chỉ phù hợp cho mockup/draft độc lập.
- Live deploy cần approval riêng.
Những file/skill nên cập nhật để workflow bền hơn
AGENTS.md: thêm rule tổng quát rằng mọi artifact dài/để duyệt phải đi qua preview URL trước GitHub.skills/learn/ai-mentor/SKILL.md: thay hướng dẫn “send via MEDIA” thành “lưu artifact; với tài liệu dài publish preview URL; chỉ dùng MEDIA khi là file/media phù hợp kênh chat”.skills/learn/business-mentor/SKILL.md: khi lưu artifact tư vấn dài, publish preview nếu cần review trên mobile.skills/operate/process-doc/SKILL.md: SOP dài nên publish preview trước khi lưu vào KB/GitHub.skills/operate/social-content/SKILL.md: hiện đã có rule preview, nên đổi sang dùng helper chuẩnlib/publish_preview.pythay vì ghi tay vào preview root.- Bản packaged trong
ainativelab/products/ceo-ai-os/app/starter_plus/products/ceo/skills/...cần được sync tương ứng khi đưa thay đổi vào source-of-truth.
Tiêu chuẩn hoàn thành
Một workflow artifact được coi là xong khi có đủ:
- Artifact source/output trên disk.
- Preview URL public đã verify.
- User review/approval rõ ràng nếu cần GitHub sync.
- GitHub/source-of-truth chỉ được cập nhật sau approval.
- Handoff ghi rõ file, URL, trạng thái push, và điều cần kiểm chứng.