Xây dựng mô phỏng máy móc tương tác chân thực với Claude Code và Machine Skill

Machine Skill thực hiện những gì

Machine Skill là một Agent Skill mã nguồn mở dành cho Claude Code. Bạn mô tả một cỗ máy trong một dòng, Claude sẽ nghiên cứu thiết bị thực tế trước khi tạo một mô phỏng 3D tương tác, chân thực về mặt hình ảnh trong một tệp HTML duy nhất.

Các trang được tạo có thể mô phỏng cơ cấu, động cơ, dụng cụ và thiết bị công nghiệp. Chúng sử dụng hình học three.js tạo theo quy trình, tỷ lệ thực, các bộ phận được đặt tên, vật liệu, chế độ tương tác và một bộ giải vật lý nhỏ phù hợp với từng loại máy. Bạn có thể mở tệp HTML kết quả trong trình duyệt, kiểm tra các bộ phận, thay đổi điều kiện vận hành, cắt mở thiết bị hoặc làm hỏng máy theo điều kiện hỏng hóc được tính toán.

Dự án cũng bao gồm trình ghi để tạo phim, ảnh chụp màn hình và các định dạng mạng xã hội có thể lặp lại từ những trang đã tạo.

Tính năng chính

• Cấu tạo máy chân thực: mô hình bao gồm kích thước thực, các bộ phận được đặt tên, chi tiết đặc, cánh, bánh răng, bu lông, đường ống và hình học tạo theo quy trình khác.
• Hành vi do vật lý điều khiển: các bộ giải như mô hình chu trình Brayton, vòi phun tên lửa, đường đặc tính bơm, dao động xoắn, Darcy và Kienzle điều khiển chuyển động cùng các giá trị hiển thị.
• Trình bày tương tác: các trang hỗ trợ kéo, tạm dừng, nhãn trực tiếp, chuyển động chậm, chế độ bung cụm chi tiết, chế độ tia X và mặt cắt với các mặt cắt đặc.
• Kết xuất chất lượng studio: runtime cung cấp vật liệu, ánh sáng, bóng đổ, đổ bóng môi trường, bloom, phát sáng do nhiệt và môi trường trình bày.
• Phim xác định: chế độ phim cho phép trình ghi tiến mô phỏng theo từng khung hình để các lần kết xuất lặp lại có kết quả nhất quán.
• Không cần bước build: các trang được tạo là tệp HTML độc lập, sử dụng runtime nội tuyến và dependency three.js 0.170 CDN được ghim phiên bản.

Yêu cầu

Để xây dựng máy, hãy cài đặt Claude Code hoặc sử dụng một host khác hỗ trợ Agent Skills. Để chạy các trang đã tạo, hãy dùng trình duyệt có WebGL 2, chẳng hạn các phiên bản máy tính hiện tại của Chrome, Safari, Firefox hoặc Edge.

Để chụp ảnh màn hình và tạo phim, bạn cũng cần Node 18 trở lên, Playwright, Chromium và ffmpeg.

npm i -D playwright
npx playwright install chromium

Cài đặt ffmpeg thông qua trình quản lý gói của hệ điều hành. Điện thoại có thể chạy các trang nhẹ hơn, nhưng các mô phỏng phức tạp hoạt động tốt nhất trên máy tính đời mới có GPU thực.

Cài đặt Machine Skill

Cách cài đặt được khuyến nghị sử dụng skills CLI và cài repository dưới dạng một skill của Claude Code.

npx skills add AirsupHQ/machine-skill -g -a claude-code

Bản cài đặt toàn cục đặt skill tại ~/.claude/skills/machine. Để chỉ cài đặt cho dự án hiện tại, hãy bỏ tùy chọn global và agent:

npx skills add AirsupHQ/machine-skill

Bản cài đặt cho dự án đặt skill tại .claude/skills/machine. Bạn cũng có thể clone trực tiếp repository:

git clone https://github.com/AirsupHQ/machine-skill.git ~/.claude/skills/machine

# Hoặc cài đặt vào một dự án
git clone https://github.com/AirsupHQ/machine-skill.git .claude/skills/machine

Claude Code thường tự phát hiện các skill mới trong phiên đang chạy. Nếu thư mục skills chưa tồn tại khi phiên bắt đầu, hãy chạy /reload-skills.

Tạo cỗ máy đầu tiên

Sau khi cài đặt, hãy mở Claude Code và sử dụng lệnh /machine kèm theo một mô tả cụ thể.

/machine a mechanical watch movement, the escapement ticking

Claude tạo một trang HTML như watch.html. Hãy mở tệp đó trong trình duyệt WebGL 2 và tương tác với mô phỏng. Tùy thuộc vào cỗ máy được tạo, bạn có thể kéo góc nhìn, kiểm tra nhãn, bung cụm lắp ráp, cắt mở thiết bị hoặc kích hoạt hành vi hỏng hóc được mô hình hóa.

Các prompt hợp lệ khác gồm:

• /machine a hydroelectric Francis turbine
• /machine a Swiss lever escapement, slowed down so I can see the impulse
• /machine the gearbox of a 5 MW wind turbine, cut open
• /machine a steam locomotive's valve gear, and give me a 30 second video for X

Viết prompt về máy tốt hơn

Machine Skill hoạt động tốt nhất khi prompt cung cấp đủ bối cảnh kỹ thuật để Claude nghiên cứu đối tượng mong muốn và chọn một điểm vận hành hữu ích.

1. Nêu tên cỗ máy thực tế. Một prompt như “a turbofan like the ones on a 787” định hướng cụ thể hơn “a jet engine”.
2. Chỉ rõ chuyển động và hành vi hỏng hóc. Giải thích bộ phận nào cần chuyển động và bộ phận nào cần hỏng, chẳng hạn yêu cầu Claude tăng tốc động cơ cho đến khi xupap bị nổi.
3. Mô tả nơi sử dụng. Cho Claude biết đầu ra dành cho trang nhúng, video mạng xã hội hay ảnh tĩnh. Với video, hãy nêu tỷ lệ khung hình hoặc thời lượng dự kiến.

Vật lý được tạo ra là một mô hình nhỏ trung thực, không phải CFD hay FEA. Mỗi trang giải thích những gì nó tính toán và những gì được đơn giản hóa, vì vậy hãy xem các giá trị này mang tính giáo dục và minh họa, không phải kết quả kỹ thuật được chứng nhận.

Ghi một bộ phim

Sử dụng script record.mjs của repository để kết xuất một trang đã tạo thành tệp video.

node ~/.claude/skills/machine/scripts/record.mjs watch.html out/watch.mp4 --music freepd:Classical/Easy_Lemon

Khi làm việc từ repository đã clone, hãy dùng đường dẫn script cục bộ:

node scripts/record.mjs examples/turbofan.html out/turbofan.mp4 --music freepd:Classical/Easy_Lemon

Bạn có thể tạo video dọc cho bảng tin bằng cách thiết lập kích thước đầu ra:

node scripts/record.mjs examples/turbofan.html out/turbofan-feed.mp4 --w 1080 --h 1350

Để xuất các khung hình tĩnh đã chọn thay vì video, hãy cung cấp một thư mục đầu ra và số thứ tự khung hình:

node scripts/record.mjs examples/turbofan.html out/stills --stills 3,9,14,19

Bộ ghi hỗ trợ thêm các tùy chọn điều khiển kết xuất. Dùng --ss 1.5 để siêu lấy mẫu, --blur 2 để tạo hiệu ứng nhòe chuyển động và --fps 60 cho chuyển động nhanh. Nhạc có thể là tệp cục bộ, URL hoặc một bản nhạc freepd:<Category>/<Name> từ FreePD.

Các trang được tạo có thể chạy ở chế độ phim xác định bằng các tham số truy vấn như ?film=1&shot=main. Ở chế độ này, thời gian chỉ tiến lên khi bộ ghi điều khiển, nhờ đó mọi khung hình đều được kết xuất đầy đủ và các lần ghi lặp lại cho kết quả nhất quán.

Kiểm tra đầu ra đã kết xuất

Machine Skill có các cơ chế bảo vệ trước lỗi kết xuất không giao diện. Bộ ghi kiểm tra ảnh chụp màn hình để phát hiện các khung hình màu hồng đặc, còn pinkscan.mjs có thể quét các video đã hoàn tất.

node scripts/pinkscan.mjs out/*.mp4

Nếu phát hiện khung hình màu hồng, lệnh sẽ thoát với trạng thái khác 0 để có thể sử dụng trong quy trình tự động.

Khám phá kho mã

• SKILL.md định nghĩa tiêu chuẩn chất lượng, quy trình nghiên cứu và mô hình hóa, các vòng đánh giá, quy trình làm phim và phong cách chữ hiển thị trên màn hình.
• kit/lab-kit.js là runtime được nhúng vào các trang đã tạo. Tệp này chứa studio, hậu kỳ, vật liệu, các hàm hỗ trợ hình học, nhãn, hiệu ứng, chế độ tương tác và dòng thời gian phim.
• kit/template.html là mẫu trang khởi đầu để tạo máy móc thủ công.
• references/solvers.md chứa các công thức vật lý và hằng số thực cho những máy móc như tua-bin khí, tên lửa, động cơ piston, máy bơm, rô-to và máy điện.
• scripts/ chứa các công cụ chụp màn hình, ghi hình, kiểm tra khung hình màu hồng và nhúng runtime.
• examples/ chứa các bản trình diễn HTML độc lập, bao gồm động cơ turbofan, động cơ tên lửa, bơm quy trình và máy nén.
• film/launch.html là trang đạo diễn được dùng cho phim ra mắt.

Tìm hiểu mặt cắt tương tác

Hệ thống mặt cắt hoạt động với các khối đặc kín và mặt phẳng cắt. Khi một mặt phẳng mở một khối đặc, runtime sẽ phát hiện bề mặt mặt cắt và kết xuất một mặt cắt đặc với vẻ ngoài gia công của vật liệu cùng hoa văn gạch nhẹ. Vì độ sâu mặt cắt được ghi chính xác, mặt cắt có thể che khuất hình học khác mà không cần các lưới nắp riêng biệt.

Điều này cho phép vị trí cắt quét xuyên qua mô hình mà vẫn giữ được bề mặt kim loại hoặc vật liệu thuyết phục. Runtime tương tự cũng hỗ trợ mặt cắt một nửa và một phần tư, trình bày tia X, cụm lắp ráp tách rời, nhãn, vệt dòng chảy, luồng khí, tia lửa và mảnh vỡ cứng.

Điều chỉnh quy trình cho các máy chủ agent khác

Machine Skill được đóng gói dưới dạng Agent Skill tiêu chuẩn. Trong Claude.ai hoặc ứng dụng Claude trên máy tính, bạn có thể nén thư mục skill rồi tải lên trong Settings, Capabilities và Skills. Với Claude Agent SDK hoặc API, hãy gắn thư mục này dưới dạng thư mục skill. Các công cụ tương thích với Agent Skills khác có thể trỏ trực tiếp đến SKILL.md.

Nếu không sử dụng agent, hãy sao chép kit/template.html và điền thủ công các phần của tệp. Các trang được tạo vẫn là những tệp HTML thông thường có thể chạy trong trình duyệt.

Nắm rõ các giới hạn

• Skill này dành cho máy móc, cơ cấu, động cơ, thiết bị đo và thiết bị nói chung. Con người, phong cảnh và bản đồ là những trường hợp sử dụng kém phù hợp hơn.
• Hình học là nội dung three.js được tạo theo thủ tục. Mục tiêu là đạt tỷ lệ và số lượng bộ phận chính xác, không phải dung sai chế tạo hay độ chính xác khi xuất CAD.
• Các mô hình vật lý được thiết kế nhỏ gọn và minh bạch. Chúng được đối chiếu với các số liệu công khai nhưng không thay thế cho phân tích CFD, FEA hoặc phân tích kỹ thuật được chứng nhận.
• Các trang phức tạp có thể chứa khoảng 600.000 tam giác và có thể cần GPU laptop đời mới để duy trì hiệu năng mượt mà khi bật bóng đổ, che khuất môi trường và hiệu ứng bloom.

Kết luận

Machine Skill biến một yêu cầu kỹ thuật ngắn gọn thành mô phỏng trình duyệt có thể khám phá, với tỷ lệ thực, hành vi được tính toán và khả năng kết xuất sẵn sàng trình bày. Hãy cài đặt bằng skills CLI, mô tả một máy cụ thể cùng các yêu cầu rõ ràng về chuyển động và sự cố, sau đó mở trang HTML được tạo. Khi sẵn sàng phát hành, hãy dùng bộ ghi xác định để tạo video hoặc ảnh tĩnh từ cùng một mô phỏng.