Tài liệu

Tài liệu RunMacro

Tạo robot đầu tiên, rồi tiến xa theo nhu cầu.

Hướng dẫn rõ ràng từng bước để tạo, chạy và cải thiện robot cho công việc máy tính lặp lại.

Ctrl K

📨 Tính năng

Gửi đề xuất để template của bạn được xem xét tích hợp

Lưu workflow đã kiểm thử thành Template của tôi, hoàn thiện tên, ID, mô tả, loại, mode, version, tags và README. Mở File › Mở macro mẫu..., chọn entry cá nhân rồi bấm Suggest. Nhập tên người gửi, thông tin liên hệ và ghi chú, bấm OK; thông báo thành công chỉ xác nhận gói đã được nhận để xem xét.

Điều kiện cần

Entry nguồn nằm trong Template của tôi; nút Suggest không bật cho template tích hợp hoặc Đội nhóm.
File chính của template còn tồn tại và TemplateLibrary có thể phân giải đường dẫn an toàn.
Kết nối Internet tới endpoint gửi đề xuất qua HTTPS.
Nên có metadata và README đầy đủ; nếu không có README, dịch vụ chỉ tạo nội dung dự phòng từ tên và mô tả.

Chế độ hỗ trợ

Chế độ Desktop — Có thể gửi template cá nhân khi Studio đang ở Chế độ Desktop. Trường Mode đề xuất trong gói có thể là window, chrome_cdp hoặc mixed và không bị đổi theo workspace lúc bấm gửi.
Chế độ Browser — Luồng gửi cũng dùng được ở Chế độ Trình duyệt và không cần Chrome/CDP đang kết nối; app gửi file template đã lưu chứ không chạy workflow trong lúc submission.

Chức năng này làm gì

Đề xuất Template tích hợp đóng gói một entry trong Template của tôi thành file ZIP tạm để gửi tới endpoint tiếp nhận của RunMacro. Gói gồm file macro dưới tên template.pmacro-template, submission.json, SUBMISSION_INFO.txt và README. Metadata template, version app, thời điểm tạo cùng ba trường Người gửi, Liên hệ và Ghi chú được đưa vào payload rồi POST qua HTTPS. Phản hồi ok: true chỉ xác nhận hệ thống đã nhận gói để xem xét; template không tự chuyển thành built-in trong thư viện.

Khi nào nên dùng

Bạn có workflow hoặc block tổng quát, đã kiểm thử và hữu ích cho nhiều người dùng khác.
Template có metadata, hướng dẫn và dữ liệu mẫu đủ rõ để người duyệt hiểu mà không cần xem macro của bạn.
Muốn gửi ứng viên built-in qua luồng tích hợp một lần bấm thay vì tự tạo gói ZIP.
Cần kèm thông tin liên hệ hoặc ghi chú triển khai cho người duyệt.

Khi nào không nên dùng

Template chỉ phục vụ riêng một nhóm — dùng Upload Đội nhóm thay vì gửi built-in.
Workflow còn chứa tài khoản thật, token, cookie, đường dẫn cá nhân hoặc dữ liệu bí mật.
Template chưa chạy thử, còn dependency thiếu hoặc dùng command không có trong bản hiện tại.
Bạn cần xuất bản ngay hoặc theo dõi trạng thái duyệt trong app; luồng này chỉ gửi gói tiếp nhận.

Các bước cấu hình

Chạy thử workflow hoặc block ở mode dự kiến và xóa mọi dữ liệu thật khỏi lệnh.
Chọn File › Lưu macro hiện tại làm mẫu...; đặt tên, ID, mô tả, Category, Tags, Mode đề xuất, Full/Block, Version, icon và README/ghi chú.
Mở File › Mở macro mẫu... và mở nhóm Template của tôi.
Chọn đúng entry; kiểm tra chi tiết, danh sách lệnh và dependency. Dùng Edit hoặc lưu lại nếu metadata cần sửa.
Bấm Suggest hoặc nút có tooltip đề xuất template này làm template tích hợp.
Nhập Người gửi, Liên hệ và Ghi chú. Ba trường có thể để trống, nhưng thông tin rõ giúp việc xem xét thuận lợi hơn.
Bấm OK. RunMacro tạo ZIP tạm gồm macro, metadata JSON, file thông tin và README rồi gửi tới endpoint.
Đợi thông báo. Đã gửi đề xuất template thành công nghĩa là server trả về ok: true.
Nếu gửi thất bại, đọc lỗi và ghi lại đường dẫn ZIP hiển thị trong thông báo; sửa mạng hoặc nội dung rồi mở lại Suggest để gửi một gói mới.

Giải thích từng tùy chọn

Entry Template của tôi

Suggest chỉ bật khi source là user. Nội dung macro, metadata và README được lấy từ entry đang chọn; template built-in và Đội nhóm không đủ điều kiện.

Người gửi

Tên người đóng góp, được ghi vào submission.json, file thông tin và trường POST author. UI không bắt buộc nhập.

Liên hệ

Qua email, Zalo, Telegram hoặc cách liên hệ khác nếu người duyệt cần hỏi thêm. Trường được gửi nguyên văn và có thể để trống.

Ghi chú

Nội dung bổ sung cho người duyệt như mục đích, bước chuẩn bị, dependency hoặc tình huống đã kiểm thử. Ghi chú được đưa vào JSON, file thông tin và request.

Metadata template được đóng gói

Gồm ID, title, description, Full/Block, recommended mode, icon, tags, version app và thời gian tạo. Giá trị ưu tiên manifest entry, sau đó mới dùng metadata trong file macro.

README dự phòng

Nếu entry khai báo README tồn tại, nội dung được copy vào ZIP. Nếu không đọc được, RunMacro tạo README tối thiểu từ title và description.

OK / Cancel

OK tạo ZIP và gửi ngay; Cancel đóng hộp mà không tạo submission. Không có màn hình xem trước gói sau bước OK.

Gói ZIP submission

Chứa template.pmacro-template, submission.json, SUBMISSION_INFO.txt và README.md. File nằm trong thư mục tạm và đường dẫn được trả lại cho UI.

Phản hồi server

Chỉ JSON có ok: true được xem là thành công. HTTP error, lỗi kết nối hoặc phản hồi khác sẽ hiện thông báo; khi thất bại, UI kèm đường dẫn ZIP để bạn giữ gói.

Kết quả mong đợi

RunMacro tạo file template_submission__<id>__<timestamp>.zip trong thư mục tạm và POST nội dung Base64 cùng metadata. Khi endpoint trả ok: true, app báo đã gửi thành công. Kết quả này là biên nhận submission; template local vẫn nằm trong Template của tôi và chưa trở thành built-in.

Ví dụ thực tế

Ví dụ: đề xuất block điền form tổng quát

Thay email, mật khẩu và URL thật bằng các biến, rồi chạy thử block ở Chế độ Trình duyệt.
Lưu thành Template của tôi với ID fill-form-block, loại Block, mô tả rõ input và README nêu cách chọn selector.
Mở thư viện, chọn entry, kiểm tra dependency không thiếu rồi bấm Suggest.
Nhập tên người gửi, email liên hệ và ghi chú rằng block đã thử trên hai form HTML tiêu chuẩn.
Bấm OK và chỉ xem là đã tiếp nhận khi app báo Đã gửi đề xuất template thành công.

Ví dụ: gửi lại sau lỗi kết nối

Bấm Suggest, điền thông tin và gửi; app báo lỗi kết nối kèm đường dẫn ZIP tạm.
Ghi lại đường dẫn đó để biết gói đã được tạo, rồi kiểm tra kết nối Internet và thời gian hệ thống.
Nếu metadata hoặc README cần sửa, cập nhật Template của tôi trước khi gửi lại để gói mới chứa nội dung đúng.
Mở lại thư viện, chọn cùng entry, bấm Suggest và nhập lại thông tin người gửi.
Gửi gói mới và chờ phản hồi ok: true; không suy ra gói cũ đã được nhận chỉ từ việc ZIP tồn tại local.

Giới hạn và trường hợp lỗi

Chỉ entry trong Template của tôi được đề xuất; nút bị tắt với built-in và Đội nhóm template.
Thông báo thành công chỉ xác nhận endpoint đã nhận gói, không phải đã duyệt, xuất bản hoặc thêm vào lần phát hành tiếp theo.
RunMacro không có danh sách submission, trạng thái duyệt, nút rút lại hoặc lịch sử trao đổi trong giao diện.
Người gửi, Liên hệ và Ghi chú không bắt buộc và không được kiểm tra định dạng; thiếu thông tin có thể làm việc hỏi lại khó hơn.
Luồng phụ thuộc endpoint tích hợp và kết nối Internet; lỗi HTTP chỉ hiện mã, còn phản hồi không phải JSON có thể chỉ hiện đoạn text ngắn.
ZIP chỉ gom file macro chính, metadata và README. File ngoài hoặc PMacro con được tham chiếu nhưng không nhúng sẵn sẽ không được thu thập riêng cho submission.
Luồng Suggest không tự chạy kiểm thử hoặc bắt buộc kiểm tra dependency trước khi gửi; chất lượng và khả năng chạy vẫn do người gửi xác nhận.
File ZIP tạm không được xóa tự động sau thành công hoặc thất bại, nên thư mục temp có thể tích lũy nhiều gói.
Hộp Suggest chỉ cho sửa ba trường người gửi; muốn đổi title, ID, mode, version, tags hoặc README phải cập nhật template trước.
Không có bước xem trước nội dung ZIP hoặc payload POST trong UI trước khi bấm OK.

Mẹo & lỗi thường gặp

Quét toàn bộ lệnh và README để loại mật khẩu, token, cookie, URL riêng và dữ liệu khách hàng trước khi gửi; submission chứa chính file macro của bạn.

Viết mô tả và README theo góc nhìn người chưa biết workflow: nêu mục đích, input, mode, dependency, bước cấu hình và kết quả mong đợi.

Tên, loại, mode, icon và tags trong submission lấy từ entry/metadata đã lưu, không lấy từ ba ô trong hộp Suggest.

Cung cấp một kênh liên hệ có thể dùng được và ghi rõ môi trường đã kiểm thử để người duyệt tái hiện nhanh hơn.

Nếu gửi lỗi, giữ lại đường dẫn ZIP để chẩn đoán nhưng hãy mở lại Suggest để gửi gói mới; file local tự nó không phải biên nhận server.

Thông tin kiểm chứng

core/template_submission.py
ui/main_window.py
core/template_library.py
storage/json_store.py