Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Kế hoạch hiện đại hóa ứng dụng

​

Mục tiêu

​

Nguyên tắc

• Giữ nguyên kiến trúc hiện tại trừ khi một ranh giới được chứng minh là đang gây biến động, chi phí hiệu năng, hoặc lỗi nhìn thấy được với người dùng.
• Ưu tiên bản vá đúng nhỏ nhất cho từng vấn đề, rồi lặp lại.
• Tách các bản sửa bắt buộc khỏi phần tinh chỉnh tùy chọn để người bảo trì có thể đưa vào công việc có giá trị cao mà không phải chờ các quyết định mang tính chủ quan.
• Giữ hành vi hướng tới plugin được ghi lại trong tài liệu và tương thích ngược.
• Xác minh hành vi đã phát hành, hợp đồng phụ thuộc, và kiểm thử trước khi tuyên bố một hồi quy đã được sửa.
• Cải thiện đường đi chính của người dùng trước: nhập môn, xác thực, trò chuyện, thiết lập nhà cung cấp, quản lý plugin, và chẩn đoán.

​

Giai đoạn 1: Kiểm tra đường cơ sở

• Xác định các quy trình làm việc hàng đầu của người dùng và các bề mặt mã sở hữu chúng.
• Liệt kê các điểm thao tác không còn hiệu lực, thiết lập trùng lặp, trạng thái lỗi không rõ ràng, và các đường kết xuất tốn kém.
• Ghi lại các lệnh xác thực hiện tại cho từng bề mặt.
• Đánh dấu vấn đề là bắt buộc, khuyến nghị, hoặc tùy chọn.
• Ghi lại các điểm chặn đã biết cần chủ sở hữu rà soát, đặc biệt là thay đổi về API, bảo mật, phát hành, và hợp đồng plugin.

• Một danh sách vấn đề có tham chiếu tệp từ gốc repo.
• Mỗi vấn đề có mức độ nghiêm trọng, bề mặt chủ sở hữu, tác động dự kiến đến người dùng, và một đường dẫn xác thực được đề xuất.
• Không trộn các mục dọn dẹp mang tính suy đoán vào các bản sửa bắt buộc.

​

Giai đoạn 2: Dọn dẹp sản phẩm và UX

• Siết chặt nội dung nhập môn và trạng thái trống quanh xác thực mô hình, trạng thái gateway, và thiết lập plugin.
• Xóa hoặc vô hiệu hóa các điểm thao tác không còn hiệu lực khi không có hành động nào khả dụng.
• Giữ các hành động quan trọng hiển thị trên các độ rộng đáp ứng thay vì ẩn chúng sau các giả định bố cục mong manh.
• Hợp nhất ngôn ngữ trạng thái lặp lại để lỗi có một nguồn sự thật duy nhất.
• Thêm tiết lộ lũy tiến cho thiết lập nâng cao trong khi vẫn giữ thiết lập cốt lõi nhanh.

• Đường đi thủ công thành công cho thiết lập lần đầu và khởi động của người dùng hiện có.
• Kiểm thử tập trung cho mọi logic định tuyến, lưu cấu hình, hoặc suy dẫn trạng thái.
• Ảnh chụp trình duyệt cho các bề mặt đáp ứng đã thay đổi.

​

Giai đoạn 3: Siết chặt kiến trúc frontend

• Di chuyển các biến đổi trạng thái UI lặp lại vào các helper được định kiểu hẹp.
• Giữ tách biệt trách nhiệm tìm nạp dữ liệu, lưu trữ, và trình bày.
• Ưu tiên các hook, store, và mẫu component hiện có thay vì các abstraction mới.
• Chỉ tách các component quá lớn khi điều đó giảm ghép nối hoặc làm rõ kiểm thử.
• Tránh đưa vào trạng thái toàn cục rộng cho các tương tác panel cục bộ.

• Không thay đổi hành vi công khai như tác dụng phụ của việc tách tệp.
• Giữ nguyên hành vi hỗ trợ tiếp cận cho menu, hộp thoại, tab, và điều hướng bàn phím.
• Xác minh rằng các trạng thái đang tải, trống, lỗi, và lạc quan vẫn kết xuất.

​

Giai đoạn 4: Hiệu năng và độ tin cậy

• Đo chi phí khởi động, chuyển tuyến, danh sách lớn, và bản ghi trò chuyện.
• Thay thế dữ liệu suy dẫn tốn kém lặp lại bằng selector được memo hóa hoặc helper được cache khi profiling chứng minh có giá trị.
• Giảm các lần quét mạng hoặc hệ thống tệp có thể tránh trên đường nóng.
• Giữ thứ tự xác định cho prompt, registry, tệp, plugin, và đầu vào mạng trước khi xây dựng payload mô hình.
• Thêm kiểm thử hồi quy nhẹ cho các helper nóng và ranh giới hợp đồng.

• Mỗi thay đổi hiệu năng ghi lại đường cơ sở, tác động dự kiến, tác động thực tế, và khoảng cách còn lại.
• Không bản vá hiệu năng nào được đưa vào chỉ dựa trên trực giác khi có thể đo lường rẻ.

​

Giai đoạn 5: Củng cố kiểu, hợp đồng, và kiểm thử

• Thay chuỗi runtime lỏng bằng union phân biệt hoặc danh sách mã đóng.
• Xác thực đầu vào bên ngoài bằng helper schema hiện có hoặc zod.
• Thêm kiểm thử hợp đồng quanh manifest plugin, catalog nhà cung cấp, thông điệp giao thức gateway, và hành vi di trú cấu hình.
• Giữ các đường dẫn tương thích trong luồng doctor hoặc repair thay vì các di trú ẩn lúc khởi động.
• Tránh ghép nối chỉ dành cho kiểm thử với nội bộ plugin; dùng facade SDK và barrel được ghi trong tài liệu.

• pnpm check:changed
• Kiểm thử nhắm mục tiêu cho mọi ranh giới đã thay đổi.
• pnpm build khi ranh giới lazy, đóng gói, hoặc bề mặt đã xuất bản thay đổi.

​

Giai đoạn 6: Tài liệu và sẵn sàng phát hành

• Cập nhật tài liệu khi có thay đổi về hành vi, API, cấu hình, nhập môn, hoặc plugin.
• Chỉ thêm mục changelog cho các thay đổi nhìn thấy được với người dùng.
• Giữ thuật ngữ plugin hướng tới người dùng; chỉ dùng tên gói nội bộ khi cần cho người đóng góp.
• Xác nhận hướng dẫn phát hành và cài đặt vẫn khớp với bề mặt lệnh hiện tại.

• Tài liệu liên quan được cập nhật trong cùng nhánh với thay đổi hành vi.
• Kiểm tra tài liệu được tạo hoặc drift API đạt khi được chạm tới.
• Phần bàn giao nêu rõ mọi xác thực đã bỏ qua và lý do bỏ qua.

​

Phần đầu tiên được khuyến nghị

• Kiểm tra thiết lập lần đầu, mức sẵn sàng xác thực nhà cung cấp, trạng thái gateway, và các bề mặt thiết lập plugin.
• Xóa hành động không còn hiệu lực và làm rõ trạng thái lỗi.
• Thêm hoặc cập nhật kiểm thử tập trung cho suy dẫn trạng thái và lưu cấu hình.
• Chạy pnpm check:changed.

​

Cập nhật kỹ năng frontend

# Tiêu chuẩn bàn giao frontend

Dùng skill này khi triển khai hoặc rà soát công việc UI hướng tới người dùng trong React, Next.js,
desktop webview, hoặc app.

## Quy tắc vận hành

- Bắt đầu từ quy trình sản phẩm và quy ước mã hiện có.
- Ưu tiên bản vá đúng nhỏ nhất cải thiện đường đi hiện tại của người dùng.
- Tách bản sửa bắt buộc khỏi phần tinh chỉnh tùy chọn trong phần bàn giao.
- Không xây dựng trang marketing khi yêu cầu là một bề mặt ứng dụng.
- Giữ hành động hiển thị và dùng được trên các kích thước viewport được hỗ trợ.
- Xóa các điểm thao tác không còn hiệu lực thay vì để lại điều khiển không thể hành động.
- Giữ nguyên trạng thái đang tải, trống, lỗi, thành công, và quyền.
- Dùng component hệ thống thiết kế, hook, store, và icon hiện có trước khi thêm
  primitive mới.

## Danh sách kiểm triển khai

1. Xác định tác vụ chính của người dùng và component hoặc route sở hữu nó.
2. Đọc các mẫu component cục bộ trước khi chỉnh sửa.
3. Vá bề mặt hẹp nhất giải quyết được vấn đề.
4. Thêm ràng buộc đáp ứng cho điều khiển, thanh công cụ, lưới, và
   bộ đếm có định dạng cố định để văn bản và trạng thái hover không thể đổi kích thước bố cục ngoài dự kiến.
5. Giữ rõ trách nhiệm tải dữ liệu, suy dẫn trạng thái, và kết xuất.
6. Thêm kiểm thử khi logic, lưu trữ, định tuyến, quyền, hoặc helper dùng chung
   thay đổi.
7. Xác minh đường đi thành công chính và trường hợp biên liên quan nhất.

## Cổng chất lượng hình ảnh

- Văn bản phải vừa trong vùng chứa trên di động và desktop.
- Thanh công cụ có thể xuống dòng, nhưng điều khiển phải vẫn truy cập được.
- Nút nên dùng icon quen thuộc khi icon rõ hơn văn bản.
- Card nên được dùng cho các mục lặp lại, modal, và công cụ có khung, không phải cho
  mọi phần của trang.
- Tránh bảng màu một nốt và nền trang trí cạnh tranh với
  nội dung vận hành.
- Các bề mặt sản phẩm dày đặc nên tối ưu cho việc quét nhanh, so sánh, và sử dụng
  lặp lại.

## Định dạng bàn giao

Báo cáo:

- Những gì đã thay đổi.
- Hành vi người dùng nào đã thay đổi.
- Xác thực bắt buộc đã đạt.
- Mọi xác thực đã bỏ qua và lý do cụ thể.
- Công việc tiếp theo tùy chọn, được tách rõ khỏi bản sửa bắt buộc.