Plugin cho Claude Code và Codex

Cài đặt

Plugin nằm trong hai kho GitHub, một cho Claude Code và một cho Codex. Cả hai có cùng nội dung và cùng số phiên bản. Chúng chỉ khác ở cách mỗi công cụ nạp chúng. Hãy cài kho dành cho công cụ của bạn, vì kho kia sẽ không nạp được.

Chuyển sang công cụ của bạn và chạy lần lượt cả hai lệnh:

Lệnh thứ nhất thêm danh mục plugin (marketplace) từ GitHub. Sau đó lệnh thứ hai cài html2wp từ danh mục đó. Codex cần kho riêng vì nó tìm plugin qua file .agents/plugins/marketplace.json, và kho của Claude Code không có file đó.

Cập nhật

Lệnh cập nhật có tên khác nhau ở mỗi công cụ. Trong Codex là upgrade, trong Claude Code là update:

Để xem phiên bản đã cài, chạy codex plugin list trong Codex. Trong Claude Code, vào /plugin → Marketplaces → html2wp.

Nếu phiên bản trong Codex không đổi sau khi cập nhật, Codex đang lưu một bản cũ. Hãy xóa nó và cài lại plugin:

Nếu vẫn không được, Codex có thể còn một bản cũ khác từ lần cài thủ công. Lệnh codex plugin marketplace list in ra mọi danh mục. Nếu bạn thấy html2wp@<other-name> ở đó, hãy gỡ nó bằng codex plugin remove html2wp@<that-name>.

Phần lớn công việc diễn ra trong dịch vụ html2wp, và dịch vụ tự cập nhật, nên lần chuyển đổi tiếp theo đã chạy phiên bản mới. Bạn chỉ phải cập nhật phần chạy trên máy tính của bạn: các bước kiểm tra, các script và bộ lọc dữ liệu gửi đi. Những gì thay đổi trong mỗi phiên bản có trong lịch sử commit trên GitHub.

Yêu cầu hệ thống

Bạn không phải tự kiểm tra những thứ này. Khi bạn bắt đầu chuyển đổi, trước tiên plugin kiểm tra máy tính và liệt kê những gì còn thiếu:

Node.js                ok        v22.14.0
Python                 ok        3.12.4
Playwright             MISSING   mirroring, prerendering and every screenshot
Docker                 NOT RUNNING  installed, but the daemon is not up

Với các gói chỉ cài vào thư mục người dùng, như Playwright hay trình duyệt chromium, plugin đề nghị cài giúp bạn. Nó hỏi trước mỗi lệnh. Những thứ thay đổi toàn hệ thống, như Docker Desktop hay Node.js mới hơn, nó chỉ báo, rồi chờ đến khi bạn tự cài.

Nếu bạn muốn tự cài các gói Python:

Nên dùng model nào

Trong lúc chuyển đổi, AI phải đưa ra rất nhiều quyết định. Ví dụ: trang nào là trang chủ, vì sao một bước kiểm tra không đạt, hay liệu khách hàng có nhận ra khác biệt giữa hai ảnh chụp màn hình không. Vì vậy lựa chọn model ảnh hưởng tới kết quả nhiều hơn mọi cài đặt khác.

Trong Claude Code, Opus 5 làm việc và Fable 5 được hỏi ý kiến ở các quyết định quan trọng, nơi việc chuyển đổi hay đi sai nhất.

Khóa giấy phép

Ở bản miễn phí, bạn không cần khóa, nên hãy bỏ qua phần này. Nếu có giấy phép, hãy lưu khóa trên máy tính trước lần chuyển đổi đầu tiên. Bạn chỉ làm việc này một lần, từ thư mục bất kỳ:

Bạn cũng có thể truyền khóa qua biến môi trường H2WP_KEY, biến này được ưu tiên hơn file. File an toàn hơn, vì khi đó khóa không nằm lại trong lịch sử terminal.

File này nhận khóa giấy phép html2wp mà bạn nhận khi mua Pro. Khóa Visual Edit Pro không đặt ở đó. Bạn nhập khóa đó vào plugin Visual Edit trên site bạn sửa, và nó không dùng được cho chuyển đổi.

Để biết khóa có hợp lệ không, dùng được cho việc gì và đến khi nào, hãy chạy npx html2wp-license YOUR-KEY. Phần kiểm tra khóa trên trang giấy phép giải thích kết quả có nghĩa là gì. Giấy phép bao gồm những gì và cách mua có trên trang giấy phép.

Chuyển đổi một dự án

Mở terminal trong thư mục dự án bạn muốn chuyển đổi, và khởi động agent ở đó:

Nếu bạn dùng Claude Code, hãy gõ claude thay cho codex ở dòng cuối.

Sau đó đưa cho agent một lệnh duy nhất:

Chỉ vậy thôi. Bạn không chạy npm install hay npm run build, và không cấu hình gì. Dự án từ Bolt, v0, shadcn hay bản xuất Next.js đều chuyển đổi theo cùng cách. Bạn cũng có thể chỉ gõ /html2wp:html2wp trong Claude Code, hoặc nhờ Codex dùng html2wp. Khi đó plugin sẽ hỏi bạn muốn chuyển đổi gì.

Những phút đầu của một lần chuyển đổi

> convert this project

  Checking this machine first…
    Node.js     ok    v22.14.0
    Playwright  MISSING
  Two Python packages are missing. Shall I install them? (they go in your
  user directory, no root)

> yes

  … installed. Building the project, then prerendering it.
  7 routes found: /, /about, /pricing, /blog, /blog/launch, /contact, /faq
  Decided: /blog is the listing, /blog/launch an article, the rest are pages.
  Written to the manifest; carrying on.

Ở những dòng cuối, plugin ghi lại cách nó phân loại các trang: /blog là trang danh sách bài viết, /blog/launch là một bài viết và phần còn lại là trang thường. Hãy kiểm tra quyết định này trên site hoàn chỉnh ở cuối.

Đầu vào khác

Lệnh convert this project chuyển đổi thư mục bạn đang đứng. Nếu file nằm ở chỗ khác, hãy gõ đường dẫn tới chúng, ví dụ convert ./dist.

Đầu vào luôn phải nằm trên ổ đĩa của bạn. Plugin không chuyển đổi địa chỉ của một site đang chạy. Nó cần các file tạo nên site, không phải thứ trình duyệt hiển thị.

Dự án Lovable được chuyển đổi thế nào

Ứng dụng Lovable được dựng bằng React. File index.html của nó chỉ chứa một phần tử trống và một script, và trang chỉ sống dậy trong trình duyệt. Vì vậy trước tiên plugin build dự án, mở nó trong một trình duyệt thật và lưu từng trang thành HTML hoàn chỉnh. Nó cũng ghi lại nội dung chỉ xuất hiện sau khi script chạy, như accordion đang mở hay menu thả xuống. Sau đó nó tạo theme từ các trang này. Chi tiết có trong hướng dẫn chuyển Lovable sang WordPress.

Những gì nó quyết định thay bạn

Trang nào là trang nào

Một quyết định ảnh hưởng lớn nhất tới kết quả: trang nào là trang chủ, trang nào là danh sách bài viết, trang nào là bài viết và trang nào là sản phẩm. Plugin xác định điều này từ mã trang, ghi lại và tiếp tục mà không hỏi. Nó chỉ dừng khi không quyết định được. Ví dụ, khi site có nhiều trang hơn giới hạn của bạn, hoặc khi hai trang trông như là một.

Nếu nó phân loại sai, cách sửa rất rẻ. Bạn sửa lại phân loại và chạy chuyển đổi lần nữa. Đó là một lần chạy lại, và nó không tính vào giới hạn chuyển đổi của bạn.

Sau đó phần lớn tự chạy

Flash mất khoảng nửa giờ, Full khoảng một giờ, tùy số trang và tốc độ máy tính của bạn. Trong lúc đó plugin build site, so sánh với bản gốc và gửi nó tới dịch vụ html2wp để chuyển đổi. Sau đó nó cài theme hoàn chỉnh vào một WordPress tạm thời trong Docker trên máy bạn và kiểm thử ở đó.

Bước rà soát không thể bỏ qua

Cuối cùng plugin cho bạn xem từng trang cạnh bản gốc trong một ảnh. Hãy xem từng ảnh và nói bạn thấy gì.

Bạn nhận được gì

• Theme dưới dạng file ZIP. Bạn tải nó lên WordPress tại Giao diện → Giao diện → Thêm mới → Tải giao diện lên. Plugin hoàn toàn không build theme bị lỗi: ví dụ, nếu PHP có lỗi cú pháp, thiếu nội dung, ảnh chụp theme sai kích thước, hoặc không mua được gì trong cửa hàng.
• Báo cáo CONVERSION-REPORT.md trong cùng thư mục với file ZIP. Nó liệt kê các trang đã chuyển đổi, các menu đã nối, mọi thứ bạn tìm thấy khi rà soát, mọi cảnh báo trong quá trình chuyển đổi và những gì còn phải làm.
• Link tới Visual Edit Lite, trình chỉnh sửa miễn phí để sửa bằng cách trỏ và bấm. Trình chỉnh sửa không thuộc theme, và theme chạy được khi không có nó. Visual Edit Pro là giấy phép trả phí riêng.

Theme độc lập. Trang, blog, form, menu, SEO và chuyển hướng là một phần mã của nó và chạy không cần plugin. Mã là PHP, CSS và JavaScript dễ đọc. Nó thuộc về bạn và không bị ràng buộc với chúng tôi. Theme không kết nối đi đâu cả. Cách sửa nó bằng cú bấm được mô tả trong phần Visual Edit của tài liệu ứng dụng.

Những gì rời khỏi máy tính của bạn

Máy tính của bạn làm phần việc trình duyệt: dựng trang, so sánh ảnh chụp màn hình và chạy một WordPress tạm thời trong Docker cho các bước kiểm tra cuối. Bản thân theme do dịch vụ html2wp tạo ra. Vì vậy plugin gửi cho dịch vụ site đã build và nhận lại theme.

Các bước kiểm tra theme chạy ở phía bạn, nên dịch vụ không thấy kết quả của chúng. Vì vậy cuối cùng plugin gửi kết quả cho dịch vụ. Việc này là bắt buộc: dịch vụ không bắt đầu lần chuyển đổi tiếp theo cho đến khi lần trước đã gửi kết quả.

• Những gì được gửi: tên các bước kiểm tra, đạt hay không, số trang, tỷ lệ khớp tệ nhất và tên ngắn của các trang không đạt, như about hoặc pricing.
• Những gì không được gửi: địa chỉ hay tên miền của site, mã, nội dung chữ, ảnh chụp màn hình, đường dẫn file, khóa giấy phép hay tên site. Plugin chỉ gửi các trường đã định sẵn, không gì khác.
• Tự kiểm tra: lệnh send-verdicts.sh <workspace> --dry-run in ra chính xác những gì sẽ được gửi, nhưng không gửi gì. Đó là một script ngắn bạn có thể đọc.

Plugin không gửi dữ liệu nào khác, và theme hoàn chỉnh không gửi gì cả. Mô tả đầy đủ, kể cả việc chúng tôi giữ dữ liệu bao lâu, có trên trang quyền riêng tư.

Báo lỗi

Nếu chính công cụ chuyển đổi mắc lỗi, hãy báo bằng lệnh này:

Một người đọc từng báo cáo. Bản sửa sau đó đi vào dịch vụ, nên nó giúp mọi người dùng.