Mặc dù Hướng dẫn về web hiện đại hướng đến việc chuyển hoạt động phát triển của bạn sang phương pháp "mặc định là chính xác", nhưng đôi khi bạn có thể gặp phải các vấn đề về việc kích hoạt tác nhân, độ chính xác của việc triển khai hoặc việc khám phá tính năng. Phần này cung cấp các bước chẩn đoán để giúp bạn giải quyết những thách thức thường gặp, chẳng hạn như đảm bảo kỹ năng Web hiện đại được kích hoạt đúng cách bằng các câu lệnh của bạn hoặc xác minh rằng các phương án dự phòng về mã phù hợp với trạng thái Cơ sở đã thiết lập của dự án. Nếu gặp phải các rào cản kỹ thuật dai dẳng hoặc phát hiện hướng dẫn đã lỗi thời, bạn nên báo cáo vấn đề để giúp chúng tôi duy trì tính chính xác và hiệu quả của những tài nguyên này.
Chẩn đoán vấn đề về việc trợ lý không nhận ra Kỹ năng Web hiện đại
Mọi lời nhắc đã cài đặt tiện ích kỹ năng đều có thể kích hoạt tiện ích đó bằng cách sử dụng "hướng dẫn về web hiện đại" theo cách nào đó. Tuy nhiên, nếu vì lý do nào đó mà tác nhân bạn đang sử dụng gặp khó khăn, bạn có thể gọi trực tiếp tiện ích đó như sau:
/modern-web-guidance <your prompt>
Điều này áp dụng cho các IDE dựa trên AI chấp nhận npx skills add <skill-extension>.
Chẩn đoán mã "ảo" hoặc các cách triển khai được đoán
Đây là trường hợp phổ biến khi mô hình LLM sẽ điền vào những chỗ thiếu hụt kiến thức mà không có cảnh báo. Để ngăn chặn việc AI tạo ra thông tin sai lệch, chúng tôi nhận thấy việc thêm chỉ dẫn sau vào câu lệnh của bạn là rất hữu ích
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
Chẩn đoán lỗi không kích hoạt được hướng dẫn cụ thể
Nếu bạn đang nhắm đến một trường hợp sử dụng tính năng cụ thể và không thấy tác nhân phát hiện trường hợp đó, hãy đảm bảo rằng câu lệnh của bạn có các từ khoá cụ thể và yêu cầu về điểm neo để có thể phát hiện đúng. Việc này giúp nhân viên hỗ trợ xác định được hướng dẫn phù hợp (ví dụ: "chuyển đổi chế độ xem", "tối ưu hoá LCP").
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Theo dõi quá trình tư duy của tác nhân:
- Theo dõi nếu phát hiện thấy kỹ năng Hướng dẫn về web hiện đại (ví dụ:
modern-web/SKILL.md). - Tìm lệnh gọi tìm kiếm (ví dụ:
node modern-web.mjs search "scroll snap") và xác định xem từ khoá và hướng dẫn thu được có phải là những từ khoá và hướng dẫn mà bạn mong đợi hay không. Hướng dẫn ở trên cùng trong kết quả tìm kiếm là hướng dẫn được chọn để áp dụng cho câu lệnh của bạn.
/modern-web-guidance Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(node --experimental-strip-types serving/bin/modern-web.ts search "carousel scroll-snap")
⎿ [{"id":"carousel-item-effects","description":"Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller, etc.","category":"user-experience","featuresUsed":["Scroll-driven animations","Scroll snap"]},
{"id":"light-dismiss-content-overlay","description":"Create swipeable layered navigation menus using native overlays and scroll gestures.","category":"user-experience","featuresUsed":["Popover","Scroll snap","inert"]},
{"id":"scroll-target-on-load","description":"Build a scrollable list of elements (e.g. a carousel of images or a chat conversation thread) that can be displayed with a particular element scrolled into view on the initial render.","category":"user-experience","featuresUsed":["scroll-initial-target","scrollIntoView()"]},
{"id":"parallax-scroll-effects","description":"Create scroll-based effects (such as parallax) where foreground and background layers move at different rates, creating a sense
of depth as the user scrolls.","category":"user-experience","featuresUsed":["Scroll-driven animations"]},
{"id":"pull-to-reveal","description":"Build a pull-to-reveal feature that would enable the user to pull down on the screen to reveal more content, like a search bar.", "category":"user-experience","featuresUsed":["scroll-initial-target","Scroll snap"]}]
...
▾ Thought for 1s
Ah, let's look at the actual folder names under `guides/user-experience/` that we listed earlier to find the exact ID mapping.
Let's see the folders we found earlier:
- `carousel-slide-effects`
- `carousel-snap-highlights`
- `scroll-snap-realtime-feedback`
- `scroll-snap-state-sync`
Ah! The ID in the filesystem is `carousel-slide-effects`, while the search index returns `carousel-item-effects`.
- Tự thực hiện lệnh tìm kiếm cho các hướng dẫn có liên quan:
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Chẩn đoán các tính năng dự phòng bị thiếu đối với một số tính năng của trình duyệt web
Việc này phụ thuộc vào trạng thái Đường cơ sở mà bạn đã thiết lập trong dự án. Nếu API mới được phát hành gần đây, thì tác nhân có thể không có phương án dự phòng tương đương để dựa vào, hoặc đó là một tính năng đã có sẵn "Baseline Widely" trong một thời gian đủ dài mà các phương án dự phòng hoặc polyfill có thể không cần thiết.
Chẩn đoán thiên kiến trong dữ liệu huấn luyện đã lỗi thời
Nếu đề xuất một thư viện cũ thay vì một API trình duyệt hiện đại, thì có thể là tác nhân đang dựa vào dữ liệu huấn luyện cơ bản hoặc Trạng thái cơ sở của bạn được định cấu hình để chưa hỗ trợ tính năng đó và phương án dự phòng đã được triển khai.
Để kiểm tra lại, bạn có thể buộc kỹ năng được ưu tiên bằng cách tìm kiếm rõ ràng trong thư viện hướng dẫn bằng CLI:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Chẩn đoán hướng dẫn lỗi thời
Điều quan trọng nhất là thông tin của chúng tôi phải luôn mới nhất. Vì vậy, vui lòng báo cáo vấn đề với kho lưu trữ nếu bạn thấy mã được triển khai từ một hướng dẫn đã lỗi thời. Khi làm như vậy, hãy thu thập bằng chứng cho thấy tác nhân đang đề xuất cho bạn là từ kỹ năng modern-web và hướng dẫn của kỹ năng đó chứ không phải dữ liệu huấn luyện cơ bản từ mô hình LLM mà IDE dựa trên AI của bạn có thể đang sử dụng.
Trong cửa sổ hoặc thiết bị đầu cuối của tác nhân, bạn có thể theo dõi quá trình suy nghĩ của tác nhân, nhưng bạn cũng có thể yêu cầu tác nhân cho bạn biết cách tác nhân đưa ra kết luận về việc thay đổi mã. Sau khi bạn kết luận rằng đó thực sự là do kỹ năng này gây ra, hãy chuyển ý kiến phản hồi và bằng chứng đó cho chúng tôi.
Phản hồi
Nếu bạn có thêm câu hỏi hoặc ý kiến phản hồi về những tính năng mới này, trước tiên, hãy đọc về cách đóng góp cho Hướng dẫn về web hiện đại trước khi gửi vấn đề trong kho lưu trữ Github của chúng tôi. Trong khi tạo vấn đề, hãy cung cấp lời nhắc ban đầu cho tác nhân, ảnh chụp màn hình và nhật ký về quy trình suy nghĩ của tác nhân, cũng như thay đổi mã cuối cùng được đề xuất dựa trên quy trình suy nghĩ đó của tác nhân.