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

# Mục tiêu

Đưa ứng dụng tới một sản phẩm sạch hơn, nhanh hơn, dễ bảo trì hơn mà không phá vỡ các quy trình hiện tại hoặc che giấu rủi ro trong các lần tái cấu trúc rộng. Công việc nên được đưa vào dưới dạng các lát cắt nhỏ, dễ review, kèm bằng chứng cho từng bề mặt được chạm tới.

# 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 rõ ràng là đang gây nhiễu, tốn chi phí hiệu năng, hoặc tạo lỗi người dùng thấy được.
• Ư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 để maintainer có thể đưa phần việc giá trị cao vào 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 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 dẫn người dùng chính trước: onboarding, 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 toán baseline

Kiểm kê ứng dụng hiện tại trước khi thay đổi.

• Xác định các quy trình người dùng hàng đầu và các bề mặt mã sở hữu chúng.
• Liệt kê các affordance chết, thiết lập trùng lặp, trạng thái lỗi không rõ ràng, và các đường render 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 tài liệu các điểm chặn đã biết cần owner review, đặc biệt là thay đổi API, bảo mật, phát hành, và hợp đồng Plugin.

Định nghĩa hoàn tất:

• Một danh sách vấn đề với tham chiếu tệp từ gốc repo.
• Mỗi vấn đề có mức độ nghiêm trọng, bề mặt owner, tác động người dùng dự kiến, và đường dẫn xác thực được đề xuất.
• Không trộn các mục dọn dẹp 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

Ưu tiên các quy trình thấy được và loại bỏ sự khó hiểu.

• Siết chặt nội dung onboarding 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 affordance chết 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 nhiều chiều rộng responsive 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ữ phần thiết lập cốt lõi nhanh.

Xác thực khuyến nghị:

• Đường dẫn thành công thủ công cho thiết lập lần chạy đầ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 responsive đã thay đổi.

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

Cải thiện khả năng bảo trì mà không viết lại rộng.

• Chuyển các phép biến đổi trạng thái UI lặp lại vào các helper có kiểu hẹp.
• Giữ riêng trách nhiệm fetch 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ó hơn các abstraction mới.
• Chỉ tách component quá lớn khi việc đó giảm coupling hoặc làm rõ kiểm thử.
• Tránh đưa trạng thái global rộng vào cho các tương tác panel cục bộ.

Rào chắn bắt buộc:

• Không thay đổi hành vi công khai như một tác dụng phụ của việc tách tệp.
• Giữ nguyên hành vi accessibility cho menu, dialog, tab, và điều hướng bàn phím.
• Xác minh rằng các trạng thái tải, trống, lỗi, và optimistic vẫn render.

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

Nhắm tới điểm đau đã đo được thay vì tối ưu hóa lý thuyết rộng.

• Đo chi phí khởi động, chuyển tuyến, danh sách lớn, và transcript trò chuyện.
• Thay dữ liệu dẫn xuất tốn kém lặp lại bằng selector được memoize 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 hot path.
• 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 helper nóng và ranh giới hợp đồng.

Định nghĩa hoàn tất:

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

# Giai đoạn 5: Làm cứng kiểu, hợp đồng, và kiểm thử

Nâng độ đúng tại các điểm ranh giới mà người dùng và tác giả Plugin phụ thuộc.

• 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ữ đường dẫn tương thích trong luồng doctor hoặc sửa chữa thay vì các di trú ẩn trong thời gian khởi động.
• Tránh coupling chỉ để kiểm thử vào phần nội bộ Plugin; dùng facade SDK và barrel đã ghi tài liệu.

Xác thực khuyến nghị:

• 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 đã phát hành thay đổi.

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

Giữ tài liệu hướng người dùng khớp với hành vi.

• Cập nhật tài liệu cùng với thay đổi hành vi, API, cấu hình, onboarding, hoặc Plugin.
• Chỉ thêm mục changelog cho các thay đổi người dùng thấy được.
• Giữ thuật ngữ Plugin hướng người dùng; chỉ dùng tên package nội bộ khi cần cho contributor.
• 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.

Định nghĩa hoàn tất:

• 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 sinh ra hoặc drift API đạt khi bị chạm tới.
• Bàn giao nêu rõ mọi xác thực đã bỏ qua và lý do bỏ qua.

# Lát cắt đầu tiên được khuyến nghị

Bắt đầu bằng một lượt có phạm vi cho Control UI và onboarding:

• Kiểm toán thiết lập lần chạy đầ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 chết và làm rõ trạng thái thất bạ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.

Việc này mang lại giá trị người dùng cao với rủi ro kiến trúc hạn chế.

# Cập nhật skill frontend

Dùng phần này để cập nhật SKILL.md tập trung vào frontend được cung cấp cùng tác vụ hiện đại hóa. Nếu áp dụng hướng dẫn này làm một skill OpenClaw cục bộ trong repo, hãy tạo .agents/skills/openclaw-frontend/SKILL.md trước, giữ frontmatter thuộc về skill đích đó, rồi thêm hoặc thay phần hướng dẫn thân bằng nội dung sau.

# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.