DEV Community

Cover image for Cách Đóng Gói Kỹ Năng AI Đa Nền Tảng (Cursor, Claude Code, Antigravity) & Kiểm Thử Đột Biến 239 Chốt Chặn Bằng Node.js
Longwave AI Lab
Longwave AI Lab

Posted on

Cách Đóng Gói Kỹ Năng AI Đa Nền Tảng (Cursor, Claude Code, Antigravity) & Kiểm Thử Đột Biến 239 Chốt Chặn Bằng Node.js

#ai #cursor #claudecode #vietnam

Cách Đóng Gói Kỹ Năng AI Đa Nền Tảng (Cursor, Claude Code, Antigravity) & Kiểm Thử Đột Biến 239 Chốt Chặn Bằng Node.js

Khi làm việc hàng ngày với Google Antigravity, Cursor IDE hay Claude Code, nhiều kỹ sư tại Việt Nam đã đúc kết được những bộ quy tắc kiểm soát mã nguồn (SKILL.md, .mdc, CLAUDE.md) rất giá trị. Thế nhưng khi đóng gói thành sản phẩm Open-Core ($0+ miễn phí kèm bản thương mại $19), 95% dự án lại vắng bóng người dùng chỉ sau hai tuần ra mắt.

Khi mổ xẻ hàng trăm kho mã nguồn kỹ năng AI trên GitHub và các trang bán sản phẩm số, nhóm kỹ thuật tại Longwave AI Lab nhận thấy bốn nguyên nhân cơ học lặp đi lặp lại:

  1. Rác đồng bộ đa nền tảng (Multi-Agent Drift): Người dùng Cursor cần file .cursor/rules/*.mdc có khai báo YAML frontmatter. Người dùng Claude Code cần CLAUDE.md trỏ vào .claude/skills/. Người dùng Antigravity cần GEMINI.md và .agents/skills/. Nếu bạn sửa tay từng thư mục, chỉ sau hai lần cập nhật là các bản miễn phí và bản trả phí sẽ lệch nhau hoàn toàn.
  2. Trôi bộ nhớ chú ý vì file gốc quá dài (Context Rot): Nhiều bạn nhồi nhét 1.200 đến 1.500 dòng quy tắc vào một file CLAUDE.md duy nhất. Nghiên cứu thực nghiệm tại Stanford TACL 2023 (Lost in the Middle) đã chứng minh mô hình ngôn ngữ bị suy giảm từ 30% đến 46% khả năng tuân thủ các quy tắc nằm kẹp ở đoạn giữa của một file quá dài.
  3. Vỡ nát định dạng trên Gumroad & Vô hình trước công cụ tìm kiếm AI (GEO Invisibility): Trình soạn thảo TipTap của Gumroad không hỗ trợ bảng Markdown thô. Khi bạn chép thẳng bảng biểu (| Cột A | Cột B |) dán vào Gumroad, toàn bộ bảng sẽ biến thành những dòng ký tự gạch dọc rất khó đọc trên điện thoại.
  4. Kiểm thử đối phó (Potemkin Verification): Rất nhiều script kiểm tra chất lượng chỉ dùng lệnh fs.existsSync() xem file có tồn tại hay không chứ chưa từng chạy thử đoạn mã bên trong trên các mẫu lỗi giả lập.

Để giải quyết tận gốc cả bốn vấn đề trên bằng kỹ thuật phần mềm thuần túy, chúng tôi xây dựng bộ công cụ AI Skill & DevTool Commercialization Factory (@longwave-ai-lab/skill-commercialization-factory). Toàn bộ hệ thống chạy bằng Node.js chuẩn mà không phụ thuộc bất kỳ thư viện ngoài nào.

Bạn có thể xem hồ sơ kỹ năng đạt chuẩn trên SkillsDirectory (longwave-ai-lab-open-core-skill-compiler) hoặc tải mã nguồn mở MIT tại github.com/longwave-ai-lab/skill-commercialization-factory.

1. Biên Dịch Đa Nền Tảng Từ Một Nguồn Duy Nhất (Mô-đun 01)

Thay vì phải mở 6 thư mục khác nhau để sửa tay từng dòng mỗi khi nâng cấp sản phẩm, kiến trúc nhà máy của chúng tôi gom toàn bộ dữ liệu gốc về hai nơi duy nhất:

  • File cấu hình trung tâm product.manifest.json (khai báo thông tin sản phẩm, danh sách mô-đun miễn phí/trả phí và bộ mẫu kiểm thử hai chiều).
  • Thư mục quy tắc gốc pro-bundle/rules/01..04.md (nơi chứa nội dung song ngữ Anh - Việt cùng đoạn mã bộ lọc Node.js của từng mô-đun).

Khi bạn gõ một lệnh duy nhất node factory.mjs compile ., trình biên dịch sẽ tự động thực hiện 6 công việc trong vòng chưa đầy 2 giây:

Bước 1: Khóa trần 200 dòng cho từng file cấu hình gốc

Trình biên dịch tự động tạo ra file chỉ mục gốc CLAUDE.md và GEMINI.md với độ dài dưới 120 dòng (~950 token). Nhờ vậy, công cụ AI tiết kiệm được hơn 95% lượng token nạp vào ở mỗi lượt hội thoại và chỉ mở đúng file kỹ năng chuyên biệt khi thực sự cần đến.

Bước 2: Sinh tự động .cursor/rules/*.mdc kèm YAML Frontmatter

Mỗi mô-đun được biên dịch sang file .mdc chuẩn của Cursor IDE với đầy đủ ba trường description, globs và alwaysApply ở đầu file để Cursor tự động kích hoạt quy tắc khi bạn mở đúng loại file.

Bước 3: Đồng bộ tự động các thư mục kỹ năng chuyên biệt

Hệ thống tự động tạo các thư mục kỹ năng con chứa file SKILL.md chuẩn hóa cho cả Claude Code (.claude/skills/) lẫn Google Antigravity (.agents/skills/) mà không cần sao chép thủ công.

Bước 4: Trích xuất các bộ lọc Node.js thực thi (scripts/lint_*.mjs)

Mọi đoạn mã nằm dưới mục ## 3. Ready-to-Run Node.js Linter trong file Markdown đều được trình biên dịch tách riêng ra thành file scripts/lint_*.mjs để chạy kiểm tra trực tiếp trên dòng lệnh.

Bước 5: Tạo chỉ mục tìm kiếm kèm trình cài đặt dòng lệnh

Người dùng chỉ cần gõ npx @longwave-ai-lab/skill-commercialization-factory --check hoặc init ./du-an-moi là có thể kiểm tra và cài đặt toàn bộ quy tắc trong 30 giây.

Bước 6: Đóng gói file nén trên RAM để cô lập ranh giới trả phí

Trình biên dịch tự đóng gói starter-free-pack.zip (chỉ chứa Mô-đun 01 miễn phí chuẩn MIT) và pro-skill-commercialization-factory.zip (chứa trọn bộ 4 Mô-đun bản Pro $19) với đường dẫn gạch chéo xuôi chuẩn quốc tế (/), loại bỏ sạch thư mục ẩn .git/.

Xem chi tiết cơ chế biên dịch tại Chuyên khảo 01: Biên dịch kỹ năng từ một nguồn duy nhất (docs/01-single-source-skill-compilation-and-multi-agent-packaging.md).

2. Tối Ưu Hóa Trích Dẫn AI (GEO) & Biên Dịch HTML TipTap Cho Gumroad (Mô-đun 02)

Ngày nay, khi các lập trình viên tìm kiếm công cụ mới, họ thường hỏi trực tiếp Perplexity, ChatGPT Search hoặc Claude. Theo nghiên cứu tại hội nghị ACM SIGKDD 2024 (Generative Engine Optimization), các mô hình tìm kiếm AI ưu tiên trích dẫn những tài liệu có số liệu định lượng, bảng đối sánh kỹ thuật và nguồn tham khảo xác thực. Cách trình bày này giúp tăng từ 30% đến 40% tỷ lệ xuất hiện trong câu trả lời.

Bên cạnh đó, để khắc phục triệt để lỗi vỡ bảng biểu trên Gumroad, Mô-đun 02 tích hợp sẵn bộ chuyển đổi compileMarkdownToTipTapHtml():

  • Chuyển đổi toàn bộ file GUMROAD-COPY-PASTE.md sang file gumroad-package/GUMROAD-TIPTAP-PAYLOAD.html.
  • Tự động biến các bảng Markdown thành danh sách <ul><li> trình bày rõ ràng, giữ nguyên định dạng thẻ <h3>, <h4>, <p>, <pre><code>.
  • Bạn chỉ cần mở file .html trên trình duyệt web, nhấn Ctrl+A, Ctrl+C rồi dán thẳng (Ctrl+V) vào ô mô tả của Gumroad là giao diện đẹp mắt ngay lập tức.

Đọc thêm phân tích chi tiết tại Chuyên khảo 02: Tối ưu hóa công cụ tìm kiếm AI & Thuyết phục kỹ thuật 6 tầng (docs/02-generative-engine-optimization-and-6-tier-technical-copywriting.md).

3. Kiểm Thử Đột Biến Hai Chiều & Xử Lý Biểu Thức Chính Quy Tiếng Việt (Mô-đun 03)

Một bộ lọc tốt không chỉ báo PASS khi mọi thứ đúng, mà quan trọng hơn là phải bắt trúng lỗi (exit code 1) khi có bất kỳ sai sót nào lọt vào.

Trong quá trình xây dựng bộ kiểm thử đột biến 36 phép thử (challenge_verification_suite.mjs), chúng tôi đã xử lý một lỗi kỹ thuật rất điển hình khi kiểm tra văn bản tiếng Việt bằng JavaScript:

  • Ký hiệu ranh giới từ \b mặc định trong JavaScript chỉ hiểu bảng chữ cái tiếng Anh không dấu ([A-Za-z0-9_]).
  • Khi gặp các chữ cái tiếng Việt có dấu như à, ự, ệ, JavaScript coi đó là ký tự đặc biệt (\W). Do đó, biểu thức /\bvà\b/i sẽ hoàn toàn thất bại và bỏ lọt các tiêu đề ghép hai chủ đề rời rạc bằng chữ "và".
  • Giải pháp chuẩn xác trong Mô-đun 03 là sử dụng biểu thức nhìn trước và nhìn sau theo thuộc tính chữ cái Unicode (/(?<!\p{L})và(?!\p{L})/iu), giúp bắt chính xác 100% từ tiếng Việt trên mọi hệ điều hành.

Đồng thời, khi chạy kiểm toán ngoại tuyến với cờ --no-jev, hệ thống tuân thủ nghiêm ngặt nguyên tắc trung thực thực thi: ghi nhận rõ executionState: "NOT_RUN", verdict: "UNDETERMINED" và probability: null, tuyệt đối không bao giờ tự gán điểm 1.0 giả tạo.

Xem toàn bộ kiến trúc kiểm thử tại Chuyên khảo 03: Hệ thống kiểm chứng hai lớp và kiểm thử đột biến (docs/03-dual-layer-deterministic-and-semantic-verification-harnesses.md).

4. Phân Phối Đa Kênh Không Chứa Link Ngoài & Chống Bóp Tương Tác (Mô-đun 04)

Sau khi đã đóng gói xong kho mã nguồn và vượt qua 239 bài kiểm tra tự động, bước tiếp theo là đưa sản phẩm đến tay cộng đồng kỹ sư mà không vi phạm quy định của các nền tảng mạng xã hội.

Tại sao hầu hết các bài giới thiệu công cụ mới trên hội nhóm Facebook hoặc Reddit đều bị tụt giảm từ 70% đến 85% lượt hiển thị tự nhiên? Nguyên nhân là do thuật toán của các nền tảng này hạn chế tối đa những bài đăng chứa đường dẫn (https://..., github.com, gumroad.com) kéo người đọc rời khỏi ứng dụng.

Trong Mô-đun 04 (Hệ Thống Phân Phối Đa Kênh Tuân Thủ Thuật Toán), chúng tôi thiết lập ba quy trình kỹ thuật tự động:

  1. Bài Đăng Chia Sẻ Kiến Thức 100% Không Chứa Link (Zero-Link Facebook Kit):
    • Toàn bộ thân bài đăng chính (<!-- ZERO_LINK_POST_START -->) chỉ tập trung mổ xẻ bài toán kỹ thuật thực tế với độ dài trên 180 chữ, tuyệt đối không chèn bất kỳ đường link hay tên miền nào.
    • Bài viết đi kèm 2 tấm ảnh sơ đồ kiến trúc độ phân giải Retina 2K (2400x1800) rõ nét từng dòng chữ. Cuối bài có câu dẫn tự nhiên hướng người đọc nhìn xuống góc dưới ảnh hoặc ghé xem bài ghim trên trang cá nhân.
  2. Kịch Bản Bình Luận Giải Đáp Kỹ Thuật 80/20 (Trojan Horse Comment Playbook):
    • Khi tham gia thảo luận dưới các bài viết hỏi đáp về Cursor hay Claude Code, 80% dung lượng bình luận dùng để hướng dẫn cách sửa lỗi trực tiếp cho người hỏi.
    • Chỉ 20% cuối bình luận nhắc nhẹ đến bộ công cụ mã nguồn mở, đồng thời bắt buộc xoay vòng luân phiên giữa Phương án Kết A và Phương án Kết B để không bao giờ lặp lại một mẫu câu giống hệt nhau.
  3. Bộ Chặn Trùng Lặp 3-Gram Jaccard (<= 0.50) & Khóa An Toàn PAGE_READ_ONLY:
    • Trước mỗi lần đăng bài, lệnh node scripts/verify_facebook_ops_action.mjs sẽ tính toán tỷ lệ trùng lặp cụm 3 từ (3-gram Jaccard) giữa bài nháp với lịch sử đăng bài trong facebook-ops-ledger.json.
    • Nếu độ trùng lặp vượt quá 50% hoặc đăng nhầm vào trang cá nhân chỉ đọc (PAGE_READ_ONLY), bộ lọc sẽ chặn lại ngay lập tức với exit code 1.

5. Vận Hành Máy Trạng Thái Không Phụ Thuộc (factory.mjs) & Biên Bản Kiểm Chứng Hai Lớp (product-state.json)

Để quy trình đóng gói kỹ năng AI không còn phụ thuộc vào trí nhớ thủ công, chúng tôi gom toàn bộ các bước vào một công cụ dòng lệnh Node.js duy nhất (scripts/factory.mjs). Công cụ này kết nối trực tiếp với sổ đăng ký products-registry.json. Chỉ với bốn câu lệnh ngắn gọn, bạn có thể quản lý trọn vẹn vòng đời của bất kỳ sản phẩm công nghệ nào:

  1. Bước 1 (factory.mjs init <product-dir>):
    • Tự động dựng khung thư mục chuẩn hai tầng Open-Core gồm pro-bundle/, github-repo/, gumroad-package/, distribution-kit/, scripts/ và starter-free-pack/.
    • Khởi tạo file cấu hình gốc product.manifest.json khai báo định danh sản phẩm và hai mức giá ($0+ Gói Miễn phí chuẩn MIT và $19 Gói Bản Pro). File này cũng khai báo danh sách 4 mô-đun quy tắc song ngữ (01..04) cùng 3 bài chuyên khảo kỹ thuật (docs/01..03.md).
  2. Bước 2 (factory.mjs compile <product-dir>):
    • Đọc nội dung chuẩn từ pro-bundle/rules/01..04.md để biên dịch đồng bộ sang .cursor/rules/*.mdc, .claude/skills/*/SKILL.md và .agents/skills/*/SKILL.md.
    • Trích xuất tự động các bộ lọc Node.js nhúng bên trong từng mô-đun bằng bộ phân tích khối lệnh neo theo đầu dòng. Bộ phân tích này xử lý an toàn cả khối lệnh 4 dấu backtick lẫn các biểu thức chính quy chứa dấu backtick bên trong.
    • Sinh tự động file gốc CLAUDE.md và GEMINI.md nằm gọn dưới trần 200 dòng, đồng thời tạo chỉ mục llms.txt cùng trình cài đặt bin/cli.mjs. Tiếp đó, trình biên dịch chuyển đổi GUMROAD-COPY-PASTE.md sang mã HTML sạch gumroad-package/GUMROAD-TIPTAP-PAYLOAD.html và nén 2 gói .zip chuẩn POSIX ngay trên bộ nhớ RAM.
  3. Bước 3 (factory.mjs audit <product-dir>):
    • Thực thi Lớp 1 (HARD và CONTEXTUAL tất định): kiểm tra cấu trúc product.manifest.json, độ đầy đủ của toàn bộ file thành phẩm và đọc trực tiếp kích thước nhị phân IHDR của 6 ảnh PNG.
    • Chạy kiểm thử hai chiều (Pass/Fail Fixtures) cho cả 4 bộ lọc Node.js và chạy thử lệnh npx init trong thư mục cách ly.
    • Quét rò rỉ danh tính cá nhân trên toàn bộ văn bản lẫn lịch sử Git, kiểm tra câu văn không quá 45 chữ và không có dấu gạch ngang dài hay dấu chấm phẩy văn xuôi. Hệ thống cũng chặn mọi đề mục tiếng Việt ghép hai chủ đề bằng chữ và và xác nhận các chốt chặn [FB-GATE-6..8].
    • Thực thi Lớp 2 (SEMANTIC cấu trúc thuyết phục và tích hợp quyết định Jev): kiểm tra cấu trúc thuyết phục 6 tầng trên README.md (>= 3.000 chữ) và GUMROAD-COPY-PASTE.md (>= 2.500 chữ). Hệ thống đồng thời kiểm tra đủ 3 tình huống đối chiếu tiếng Anh, 3 tình huống tiếng Việt, bảng trích dẫn học thuật và tỷ lệ từ vựng độc nhất (>= 0.23) của 3 bài chuyên khảo.
    • Tách biệt rạch ròi giữa trạng thái thực thi (NOT_RUN, SUCCESS, TOOL_ERROR) với kết luận đánh giá (PASS, FAIL, HARD_FAIL, GREY_ZONE_WHITE_FLAG, UNDETERMINED). Khi bỏ qua bộ chấm điểm ngữ nghĩa ngoại tuyến, biên bản product-state.json ghi chính xác executionState: "NOT_RUN", verdict: "UNDETERMINED" và probability: null, tuyệt đối không bao giờ tự điền điểm 1.0 giả tạo.
  4. Bước 4 (factory.mjs status):
    • Đọc danh sách toàn bộ sản phẩm trong products-registry.json (PROD-01, PROD-02, PROD-03) và in bảng tổng hợp trạng thái thực tế ngay trên cửa sổ dòng lệnh.

6. Trải Nghiệm Ngay Gói Open-Core Miễn Phí Trong 30 Giây

Bạn có thể mở cửa sổ dòng lệnh và chạy thử ngay trình kiểm tra của bộ công cụ trong vòng 30 giây với Node.js (>= 18):

  1. Chạy kiểm tra chẩn đoán nhanh qua npx không cần cài đặt:
    • Gõ lệnh npx @longwave-ai-lab/skill-commercialization-factory --check để xác minh cú pháp AST của bộ lọc và kiểm tra cấu trúc gói.
  2. Khởi tạo bộ quy tắc vào bất kỳ dự án nào của bạn:
    • Gõ lệnh npx @longwave-ai-lab/skill-commercialization-factory init ./du-an-cua-ban để chép trọn bộ .cursor/rules/01-open-core-skill-packaging-compiler.mdc, .claude/skills/, .agents/skills/, CLAUDE.md, GEMINI.md, product.manifest.json, llms.txt, package.json và scripts/lint_open_core_compiler.mjs.
  3. Chạy trực tiếp bộ lọc đóng gói Mô-đun 01:
    • Gõ lệnh node scripts/lint_open_core_compiler.mjs . để kiểm tra tự động giới hạn 200 dòng của file gốc cùng toàn bộ cấu hình đa nền tảng. 
npx @longwave-ai-lab/skill-commercialization-factory --check
Enter fullscreen mode Exit fullscreen mode

Top comments (0)