Preview tệp và tạo visual với ak:preview

Dùng ak:preview để xem tệp hay thư mục hiện có, hoặc tạo visual explanation, slide deck, diagram, diff review, plan review hay recap project. Mode đã chọn quyết định Skill chỉ đọc content hay còn ghi visual mới, mở browser, khởi động process HTTP local, đọc Git history hoặc liên hệ CDN hay GitHub.

Chọn preview mode nhỏ nhất

Dùng ak:preview khi

• Bạn cần visual explanation cho workflow marketing hoặc luồng review đã duyệt.
• Bạn muốn diagram tập trung, ASCII thân thiện với terminal hoặc HTML slide deck.
• Bạn cần xem tệp Markdown hiện có hoặc duyệt thư mục trong reader UI.
• Bạn muốn visual diff, so sánh plan hoặc recap project gần đây dựa trên bằng chứng.

Chọn workflow khác khi

• Bạn cần thay đổi marketing plan, content, code hoặc campaign bên dưới. Hãy preview bằng chứng trước rồi dùng workflow sở hữu phần việc đó.
• Bạn cần artifact kiến trúc SVG hoặc PNG không theo template và đạt mức publish. Dùng workflow technical graph chuyên biệt khi khả dụng.
• Bạn cần image generation hoặc multimodal analysis thay vì visual HTML, Markdown, Mermaid hay ASCII.
• Bạn cần publish, deploy, liên hệ audience, đổi account hoặc spend. ak:preview không cấp quyền cho các tác động đó.

Chuẩn bị input và ranh giới tác động

Trước khi bắt đầu:

• Hoàn thành Làm quen và cài Marketing Kit cho runtime cùng scope đang hoạt động.
• Chọn path hiện có hoặc topic có scope hẹp.
• Với --diff, xác nhận Git ref, commit, range, working tree hoặc pull request có thể được đọc.
• Với --plan-review, cung cấp plan đã duyệt hoặc xác nhận active plan.
• Với --recap, chọn time window; source workflow mặc định dùng hai tuần.
• Loại secret và customer data riêng tư khỏi mọi nội dung có thể được render, serve, mở trong browser hay nhúng vào tệp tạo ra.
• Quyết định tác động local server, browser launch, CDN, GitHub CLI và file write có chấp nhận được không.

Gọi Skill

Để bắt đầu theo cách dễ di chuyển nhất, hãy yêu cầu rõ visual HTML chỉ tạo tệp và từ chối browser launch mặc định cho tới khi review external resource reference:

/ak:preview --html --diagram "Luồng review launch đã duyệt từ draft tới duyệt brand, legal và publish. Không dùng customer data. Ghi tệp HTML nhưng không mở hoặc publish; báo external URL"

/ak:preview --html --diagram "Luồng review launch đã duyệt từ draft tới duyệt brand, legal và publish. Không dùng customer data. Ghi tệp HTML nhưng không mở hoặc publish; báo external URL"

$ak:preview --html --diagram "Luồng review launch đã duyệt từ draft tới duyệt brand, legal và publish. Không dùng customer data. Ghi tệp HTML nhưng không mở hoặc publish; báo external URL"

Đọc Runtime adapter trước khi giả định server, background task, browser, Agent hoặc Hook có parity.

Chọn mode có chủ đích

Argument resolution ưu tiên --stop cao nhất. --html đổi loại output, generation flag chọn workflow, còn path hiện có chọn view mode. Nếu không resolve được path, Skill nên hỏi thay vì đoán.

Chọn tham gia route HTML AK Render

--ak-render ngầm bật --html và áp dụng cho HTML của --explain, --diff, --plan-review và --recap; --slides và --diagram vẫn ở route mặc định. Thay vì viết tay trang HTML, Skill ghi <slug>.page.yaml cạnh HTML output rồi compile bằng compiler được ghim npx -y @bestagentkits/render@0.2.0, yêu cầu Node 20.11 trở lên. Project có thư mục .ak-render/ chứa theme preset của AK Render sẽ tự chọn route này, không có cách tắt cho từng lần chạy.

• Route HTML viết tay vẫn là mặc định. AK Render vẫn là opt-in vì phép so sánh có đo lường với route mặc định chưa vượt quality gate.
• Trang giữ đủ các section bắt buộc như route mặc định.
• Hướng dẫn dùng CDN kiểu cũ chỉ áp dụng cho route mặc định, và route đó phải nêu rõ phụ thuộc network trong report.
• Trang đã compile mở qua file:// với zero network request. Lần chạy npx đầu tiên tải package đã ghim từ npm registry; các lần sau dùng cache.
• Để sửa trang, hãy sửa spec rồi compile lại. Không vá HTML đã compile.
• Marketing Kit không có ak:diagram, nên diagram panel hiển thị fallback dạng văn bản có cấu trúc và Skill thể hiện thêm luồng bằng các bước hoặc timeline.
• Nếu thiếu Node, npx hoặc không tải được package, hoặc spec vẫn không hợp lệ sau ba lần sửa, Skill dùng route mặc định và nêu lý do trong report.

Kiểm soát editorial visual layer

HTML generation giờ mặc định bật hai editorial engine bổ sung khi request ánh xạ rõ tới chúng. AntV Infographic có thể render KPI panel, ranked comparison và timeline; diagram-design có thể render layout architecture, quadrant, timeline, security, integration và medallion có chủ đích. Mermaid cùng Chart.js vẫn là fallback và tiếp tục xử lý automatic layout cùng interactive chart.

• Tắt cả hai engine bằng --no-editorial-visuals, chỉ tắt AntV bằng --no-antv hoặc chỉ tắt diagram-design bằng --no-diagram-design.
• Thứ tự resolve preference là invocation flag, .agentkit/config.yaml của project, ~/.agentkit/config.yaml của user, rồi tới mặc định enabled. Không có tier environment variable. Nested key đã resolve cho diagram_design là diagramDesign trong JSON do ak config prefs resolve --json trả về.
• AntV được pin ở @antv/infographic@0.2.19 và tải dist/infographic.min.js từ jsDelivr với SRI. Chỉ dùng nó cho ít nhất ba panel vì bundle có kích thước 874 KB chưa nén và 288 KB sau gzip. Load timeout, render error hay target rỗng sẽ fallback mà không làm hỏng artifact và ghi log [antv] fell back to <engine>.
• diagram-design được pin ở commit 09df49d8 và tạo HTML cùng SVG self-contained, không dùng JavaScript. Motion tier mặc định là none; các tier tùy chọn reveal, step và loop lấy từ visual.diagram_design.motion và phải tôn trọng reduced-motion preference. Các Python validator đi kèm chỉ mang tính advisory và bỏ qua an toàn khi không có python3. Sau một geometry failure ban đầu và một lần corrective retry, generation fallback sang Mermaid.

Editorial layer căn chỉnh cả hai engine theo Instrument Serif, Geist và Geist Mono. Source chỉ tải reference tương ứng sau khi route request; nó không preload cả hai engine. Trong môi trường air-gapped, hãy tắt AntV. Đồng thời tắt mọi engine khác dựa trên CDN mà artifact đã chọn yêu cầu nếu output offline hoàn toàn là bắt buộc.

Hiểu các giai đoạn tệp và process

1. Resolve request. Skill chọn view hoặc generation mode, validate topic hay path và chuyển topic thành slug tối đa 80 ký tự.
2. Tập hợp bằng chứng có scope. Skill chỉ đọc nguồn mà mode yêu cầu. Các HTML mode nặng về Git có ranh giới đọc rộng hơn như bảng trên.
3. Chọn output path. Khi có active plan, output đi tới {plan_dir}/visuals/{slug}.md hoặc .html; nếu không, output đi tới plans/visuals/{slug}.md hoặc .html. Thư mục thiếu sẽ được tạo.
4. Tạo và review. Diagram phải được render rồi kiểm tra trực quan; riêng syntax validation là chưa đủ.
5. Mở kết quả. HTML dùng open, xdg-open hoặc start và không cần server. Markdown cùng view mode cố khởi động process Markdown Novel Viewer riêng.
6. Báo bằng chứng. Skill báo output path, URL khi áp dụng, kết quả browser và dependency không khả dụng hoặc check thất bại.

Source workflow overwrite tệp hiện có tại output path đã chọn mà không hỏi. Hãy kiểm tra target path trước generation khi công việc cũ có thể tồn tại.

Kiểm soát tác động server, network và quyền riêng tư

• Viewer mặc định dùng port 3456 và tìm tới 3500 khi port bận. Process ghi PID record dưới /tmp và tiếp tục hoạt động cho tới khi bị dừng hoặc background task kết thúc.
• --stop dừng mọi viewer instance tìm thấy qua record md-novel-viewer-*.pid, không chỉ tệp mở gần nhất.
• Export Marketing hiện tại có ak:preview nhưng không có dependency ak:markdown-novel-viewer riêng được instruction source nhắc tới. Vì vậy không thể hứa mode dựa trên server hoàn tất chỉ từ Marketing Kit.
• Ngay cả khi viewer riêng hiện diện, source của nó khai báo npm dependency để render Markdown. Không giả định server là zero-dependency hoặc sửa bằng một lần manual install chưa được review.
• HTML output có thể chứa CDN reference cho Google Fonts, Mermaid, Chart.js, AntV Infographic, ELK layout hoặc anime.js. Mở tệp có thể liên hệ provider đó và để lộ request metadata; render offline có thể không đầy đủ.
• Diff theo số PR cần gh và quyền truy cập GitHub. Các thao tác đọc Git khác dùng trạng thái local trừ khi command riêng refresh remote.
• Browser open command và tệp được tạo là tác động local. Chúng không cấp quyền upload, publication, deployment, thay đổi account, outreach hay spend.

Xác minh output

Một lần chạy hoàn tất nên cung cấp:

• Mode đã chọn, input đã resolve và output path chính xác.
• Artifact Markdown hoặc HTML dưới thư mục visuals/ của active plan, hoặc dưới plans/visuals/ khi không có active plan.
• Bằng chứng render và kiểm tra cho diagram, gồm việc sửa overlap, label khó đọc hoặc layout hỏng. Với diagram-design, còn phải báo kết quả validator advisory và mọi fallback sang Mermaid.
• Local và network URL chỉ khi process viewer thực sự khởi động.
• Disclosure về host, port, process đang chạy và cách dừng.
• Disclosure về quyền truy cập CDN hoặc GitHub khi mode đã chọn cần.
• Phân tách rõ review material được tạo ra với mọi mutation, publication, account action hoặc spend còn chưa duyệt.

Với HTML, kiểm tra source tệp để tìm external URL, mở cả light và dark theme, resize trang và xác minh chart hay Mermaid thực sự load. Với review dựa trên Git, so sánh ref đã nêu cùng current status với repository trước khi chấp nhận kết luận.

Xử lý sự cố an toàn

Tiếp tục với Tổng quan Marketing Kit hoặc Projects, artifact và checkpoint trước khi khôi phục từ thao tác ghi ngoài ý muốn.

Biết các giới hạn hiện tại

• Cùng source Skill được đóng gói cho cả ba runtime, nhưng instruction viewer hướng riêng tới Claude và không chứng minh behavior server có thể di chuyển.
• Marketing Kit hiện bỏ dependency viewer mà mode dựa trên server tham chiếu. Trang này không claim các mode đó hoàn tất chỉ từ package Marketing.
• Source viewer riêng còn cần npm dependency để render Markdown; chỉ có ak:preview không chứng minh các dependency đó khả dụng.
• “Một tệp HTML” không nhất thiết nghĩa là offline hoặc không có network vì font và JavaScript library tùy chọn có thể vẫn là CDN import. AntV không được vendor trong release này; diagram-design không có runtime JavaScript dependency.
• Visual review có thể giải thích bằng chứng nhưng không chứng minh hiệu suất campaign, conversion, revenue, trạng thái provider hiện tại hay tính đúng của source data.