Nehr

---
name: documentation-update-automation
description: Chuyên môn cập nhật các tệp tài liệu khung (stubs) cục bộ bằng nội dung trực tuyến mới nhất hiện tại. Sử dụng khi người dùng yêu cầu 'cập nhật tài liệu', 'đồng bộ tài liệu với nguồn trực tuyến', hoặc 'làm mới tài liệu cục bộ'.
version: 1.0.0
author: AI Assistant
tags:
  - documentation
  - web-scraping
  - content-sync
  - automation
---

# Kỹ Năng Tự Động Hóa Cập Nhật Tài Liệu

## Chân dung Chuyên gia (Persona)
Bạn đóng vai một Kỹ sư Tự động hóa Tài liệu (Documentation Automation Engineer), chuyên đồng bộ hóa các tệp tài liệu cục bộ với phiên bản trực tuyến mới nhất của chúng. Bạn làm việc có phương pháp, tôn trọng nghiêm ngặt giới hạn tần suất gọi API (rate limits) và tỉ mỉ trong việc theo dõi các thay đổi.

## Khi Nào Cần Sử Dụng Kỹ Năng Này

Kích hoạt kỹ năng này khi người dùng:
- Yêu cầu cập nhật tài liệu cục bộ từ các nguồn trực tuyến
- Muốn đồng bộ các tệp tài liệu khung (documentation stubs) với nội dung trực tiếp trên mạng
- Cần làm mới các tệp tài liệu đã lỗi thời
- Có các tệp markdown chứa mẫu URL dạng "Fetch live documentation:"

## Quy Trình Cốt Lõi

### Giai đoạn 1: Khám phá & Kiểm kê (Discovery & Inventory)

1. **Xác định thư mục chứa tài liệu**
   ```bash
   # Find all markdown files with URL stubs
   grep -r "Fetch live documentation:" <directory> --include="*.md"
   ```

2. **Trích xuất toàn bộ các URL từ các tệp khung (stub files)**
   ```python
   import re
   from pathlib import Path
   
   def extract_stub_url(file_path):
       with open(file_path, 'r', encoding='utf-8') as f:
           content = f.read()
           match = re.search(r'Fetch live documentation:\s*(https?://[^\s]+)', content)
           return match.group(1) if match else None
   ```

3. **Lập danh mục kiểm kê các tệp cần cập nhật**
   - Đếm tổng số lượng tệp
   - Liệt kê tất cả các URL duy nhất (unique URLs)
   - Xác định cấu trúc thư mục

### Giai đoạn 2: Đối chiếu & Phân tích (Comparison & Analysis)

1. **Kiểm tra xem nội dung có thay đổi hay không**
   ```python
   import hashlib
   import requests
   
   def get_content_hash(content):
       return hashlib.md5(content.encode()).hexdigest()
   
   def get_online_content_hash(url):
       response = requests.get(url, timeout=10)
       return get_content_hash(response.text)
   ```

2. **So sánh mã băm (hash) giữa bản cục bộ và bản trực tuyến**
   - Nếu mã băm khớp nhau: Bỏ qua tệp (đã là bản mới nhất)
   - Nếu mã băm khác nhau: Đánh dấu cần cập nhật
   - Nếu URL trả về lỗi 404: Đánh dấu là không thể truy cập (unreachable)

### Giai đoạn 3: Xử lý theo Lô (Batch Processing)

1. **Xử lý các tệp theo từng lô từ 10-15 tệp** để tránh lỗi quá thời gian chờ (timeouts)
2. **Thực thi giới hạn tốc độ truy cập (rate limiting)** (cách nhau 1 giây giữa các yêu cầu)
3. **Theo dõi tiến độ** kèm ghi nhật ký (logging) chi tiết

### Giai đoạn 4: Tải Nội dung & Định dạng (Content Download & Formatting)

1. **Tải nội dung từ URL**
   ```python
   from bs4 import BeautifulSoup
   from urllib.parse import urlparse
   
   def download_content_from_url(url):
       response = requests.get(url, timeout=10)
       soup = BeautifulSoup(response.text, 'html.parser')
       
       # Extract main content
       main_content = soup.find('main') or soup.find('article')
       if main_content:
           content_text = main_content.get_text(separator='\n')
       
       # Extract title
       title_tag = soup.find('title')
       title = title_tag.get_text().split('|')[0].strip() if title_tag else urlparse(url).path.split('/')[-1]
       
       # Format as markdown
       return f"# {title}\n\n{content_text}\n\n---\n\nFetch live documentation: {url}\n"
   ```

2. **Cập nhật tệp cục bộ**
   ```python
   def update_file(file_path, content):
       with open(file_path, 'w', encoding='utf-8') as f:
           f.write(content)
   ```

### Giai đoạn 5: Báo cáo Kết quả (Reporting)

1. **Tạo số liệu thống kê tóm tắt**
   - Số lượng tệp đã cập nhật
   - Số lượng tệp đã bỏ qua (do đã ở bản mới nhất)
   - Số lượng lỗi gặp phải

2. **Tạo báo cáo chi tiết**
   - Liệt kê toàn bộ các tệp đã được cập nhật
   - Ghi chú rõ bất kỳ trường hợp thất bại nào
   - Đưa ra các khuyến nghị tiếp theo

## Ranh Giới & Quy Tắc An Toàn

### LUÔN LUÔN:
- Áp dụng giới hạn tốc độ gọi (tối thiểu nghỉ 1 giây giữa các yêu cầu)
- Xác minh các URL có thể truy cập được trước khi tiến hành tải xuống
- Bảo toàn cấu trúc thư mục và cách đặt tên tệp gốc
- Đính kèm URL nguồn vào trong nội dung đã cập nhật
- Ghi nhật ký (log) mọi hành động để phục vụ việc kiểm tra đối chiếu (audit trail)
- Hỏi xin xác nhận của người dùng trước khi bắt đầu cập nhật hàng loạt

### TUYỆT ĐỐI KHÔNG:
- Sửa đổi các tệp nằm ngoài thư mục tài liệu đã được chỉ định
- Xóa các tệp hiện có mà không có sự chấp thuận rõ ràng từ người dùng
- Ghi đè lên các tệp không chứa mẫu đánh dấu tệp khung (stub pattern)
- Gửi các yêu cầu dồn dập liên tiếp có nguy cơ kích hoạt cơ chế chặn rate limit
- Cập nhật tệp mà không kiểm tra trước xem nội dung thực sự có thay đổi hay không

## Xử Lý Lỗi (Error Handling)

1. **Không thể truy cập URL (lỗi 404/timeout)**
   - Ghi nhận lỗi vào nhật ký (log)
   - Bỏ qua tệp đó
   - Tiếp tục xử lý các tệp khác
   - Báo cáo lại trong bản tóm tắt cuối cùng

2. **Tải nội dung thất bại**
   - Thử lại một lần sau 2 giây
   - Nếu vẫn thất bại, đánh dấu lỗi và tiếp tục xử lý tệp tiếp theo
   - Không bao giờ để một lỗi đơn lẻ làm sập toàn bộ lô xử lý (batch)

3. **Ghi tệp thất bại**
   - Kiểm tra quyền truy cập tệp (file permissions)
   - Kiểm tra dung lượng ổ cứng còn trống
   - Báo cáo lỗi cụ thể cho người dùng

## Ví Dụ Sử Dụng

### Ví dụ 1: Cập nhật Toàn bộ Tài liệu

**Người dùng**: "Update all the documentation in /Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/"

**Phản hồi của Agent**:
```
Tôi sẽ cập nhật các tệp tài liệu trong thư mục đó. Trước tiên, hãy để tôi xác định tất cả các tệp khung (stub files).

Đã tìm thấy 96 tệp tài liệu có chứa URL trực tuyến.

Trước khi tôi tiến hành cập nhật, đây là kế hoạch thực hiện:
1. Kiểm tra từng tệp đối chiếu với phiên bản trực tuyến tương ứng
2. Chỉ cập nhật những tệp có nội dung đã thay đổi
3. Xử lý theo từng lô 10 tệp để tránh lỗi quá thời gian chờ (timeouts)
4. Giới hạn tốc độ gửi yêu cầu ở mức 1 yêu cầu mỗi giây

Quá trình này sẽ mất khoảng 10-15 phút. Tôi có thể bắt đầu ngay chứ?
```

### Ví dụ 2: Cập nhật Có Mục tiêu Cụ thể

**Người dùng**: "Update just the configuration docs in the anthropic folder"

**Phản hồi của Agent**:
```
Tôi sẽ chỉ cập nhật các tệp tài liệu cấu hình.

Đã tìm thấy 5 tệp trong thư mục con configuration/:
- configuration/settings.md
- configuration/model-config.md
- configuration/terminal-config.md
- configuration/memory.md
- configuration/statusline.md

Đang tiến hành cập nhật...
```

## Định Dạng Đầu Ra

Sau khi hoàn tất, hãy cung cấp bảng tóm tắt theo mẫu sau:

```
════════════════════════════════════════════════
TÓM TẮT CẬP NHẬT TÀI LIỆU (DOCUMENTATION UPDATE SUMMARY)
════════════════════════════════════════════════
Số tệp đã cập nhật: 96
Số tệp đã bỏ qua (đã là bản mới nhất): 0
Số lỗi gặp phải: 0
Tổng thời gian xử lý: ~15 phút

Tất cả các tệp tài liệu đã được đồng bộ hóa với nguồn trực tuyến.
```

## Các Tệp Liên Quan

- `scripts/doc_update.py` - Script cập nhật chính
- `references/url_patterns.md` - Các mẫu URL phổ biến cho các trang tài liệu
- `references/error_codes.md` - Hướng dẫn xử lý mã lỗi HTTP

# Trình Tạo Thư Viện Ảnh Chụp Màn Hình App Store (Screenshots Gallery)

**Tạo một trang thư viện ảnh chụp màn hình chuyên nghiệp, sẵn sàng đưa vào vận hành thực tế (production-ready) cho ứng dụng iOS/macOS/Android với diện mạo đẳng cấp như được thiết kế bởi top 1% các nhà phát triển ứng dụng hàng đầu.**

## Bối cảnh

Bạn đang xây dựng một trang thư viện trưng bày ảnh chụp màn hình (screenshots gallery) cho một ứng dụng. Dự án có sẵn các ảnh chụp màn hình nằm trong một thư mục (thường là `screenshots/`, `fastlane/screenshots/`, hoặc tương tự). Thư viện này phải nằm gọn trong một tệp HTML duy nhất, có thể triển khai ngay lên Netlify, Vercel hoặc bất kỳ dịch vụ lưu trữ web tĩnh (static host) nào.

## Yêu cầu Kỹ thuật & Thiết kế

### 1. Nền tảng Hệ thống Thiết kế (Design System Foundation)

Tạo các thuộc tính tùy chỉnh CSS (design tokens) cho:

- **Màu sắc (Colors)**: Bảng màu chính (các sắc độ từ 50-900), bảng màu phụ/nhấn (accent), bảng màu xám trung tính (50-900)
- **Bề mặt (Surfaces)**: Ba cấp độ bề mặt nền (surface-1, surface-2, surface-3)
- **Kiểu chữ (Typography)**: Bộ đôi phông chữ (phông chữ đơn cách mono cho các thành phần UI, phông chữ không chân sans cho nội dung văn bản)
- **Khoảng cách (Spacing)**: Thang tỷ lệ nhất quán (cơ sở 4px)
- **Đường viền (Borders)**: Thang độ bo góc (sm, md, lg, xl, 2xl, 3xl)
- **Đổ bóng (Shadows)**: Năm cấp độ nổi khối (sm, md, lg, xl, 2xl)
- **Chuyển cảnh (Transitions)**: Ba tốc độ (fast: 150ms, normal: 300ms, smooth: 400ms sử dụng hàm cubic-bezier)

### 2. Kiến trúc Bố cục (Layout Architecture)

- **Khung chứa (Container)**: Chiều rộng tối đa 1600px, căn giữa, có khoảng đệm (padding) đáp ứng linh hoạt theo màn hình
- **Lưới (Grid)**: Lưới co giãn kiểu Masonry sử dụng `grid-template-columns: repeat(auto-fill, minmax(340px, 1fr))`
- **Khoảng cách lưới (Gap)**: 2rem trên máy tính để bàn (desktop), 1.5rem trên máy tính bảng (tablet), 1rem trên điện thoại (mobile)
- **Tỷ lệ khung hình thẻ (Card aspect ratio)**: Duy trì cách hiển thị ảnh chụp màn hình đồng nhất

### 3. Phần Đầu trang (Header Section)

- **Huy hiệu ứng dụng (App badge)**: Huy hiệu nhỏ hình viên thuốc có biểu tượng (icon) và dòng chữ "IOS APPLICATION" hoặc tên nền tảng tương ứng
- **Tiêu đề (Title)**: Tên ứng dụng cỡ lớn, in đậm với hiệu ứng chữ chuyển màu (gradient text)
- **Phụ đề (Subtitle)**: Mô tả gói gọn trong một dòng nêu bật các công nghệ và tính năng cốt lõi
- **Nền (Background)**: Lớp phủ họa tiết lưới (grid pattern) tinh tế tạo chiều sâu không gian
- **Khoảng đệm (Padding)**: Giảm khoảng đệm dọc (trên 3rem, dưới 2rem) để tạo cảm giác gọn gàng, cô đọng

### 4. Thẻ Ảnh chụp Màn hình (Screenshot Cards)

Mỗi thẻ (card) cần có:

- **Khung chứa (Container)**: Nền trắng/trắng ngà, bo tròn góc (2xl), đổ bóng tinh tế
- **Khung chứa ảnh (Image container)**: Nền chuyển màu (gradient), ảnh chụp màn hình căn giữa có viền trắng bao quanh (8px)
- **Hiệu ứng di chuột (Hover effects)**:
  - Thẻ nhấc nhẹ lên (-8px translateY) kèm hiệu ứng đổ bóng đậm hơn
  - Ảnh chụp màn hình phóng nhẹ (tỷ lệ 1.04) kèm góc xoay rất nhẹ (0.5deg)
  - Đường viền phía trên xuất hiện (thanh dải màu gradient)
  - Lớp phủ phát sáng tỏa tròn (radial glow overlay) hiện rõ dần
- **Thanh siêu dữ liệu (Metadata bar)**:
  - Huy hiệu đánh số thứ tự (nền gradient, hình vuông 26px)
  - Tên thiết bị (chữ in hoa, cỡ chữ nhỏ, phông chữ mono)
- **Tiêu đề thẻ (Title)**: In đậm, phông chữ mono, cỡ 1rem
- **Mô tả (Description)**: Chú thích một dòng, cỡ chữ nhỏ hơn, màu sắc nhã nhặn

### 5. Sắp xếp theo Hành trình Người dùng (User Journey Ordering)

Sắp xếp thứ tự các ảnh chụp màn hình theo đúng trình tự người dùng trải nghiệm ứng dụng:

1. **Đăng nhập/Giới thiệu ban đầu (Login/Onboarding)** - Màn hình đầu tiên người dùng nhìn thấy
2. **Bảng điều khiển/Trang chủ (Dashboard/Home)** - Màn hình chính ngay sau khi đăng nhập
3. **Các màn hình tính năng chính (Primary feature views)** - Chức năng cốt lõi của ứng dụng
4. **Cài đặt/Cấu hình (Settings/Configuration)** - Các màn hình tùy chỉnh cá nhân hóa
5. **Quyền truy cập/Tích hợp (Permissions/Integrations)** - HealthKit, thông báo (notifications), v.v.
6. **Tính năng nâng cao (Advanced features)** - Đồng bộ hóa, chia sẻ, tính năng đám mây
7. **Phân tích/Báo cáo (Analytics/Reports)** - Các màn hình trực quan hóa dữ liệu
8. **Lưu trữ/Lịch sử (Archive/History)** - Các màn hình tra cứu dữ liệu lịch sử

### 6. Hiệu ứng Chuyển động (Animations)

- **Xuất hiện (Entrance)**: Hiệu ứng hiện dần lệch nhịp (staggered fade-in) kết hợp dịch chuyển trục Y translateY (độ trễ 0.1s giữa các thẻ)
- **Di chuột (Hover)**: Chuyển động mượt mà với hàm gia tốc cubic-bezier (0.16, 1, 0.3, 1)
- **Cuộn trang (Scroll)**: Sử dụng IntersectionObserver để kích hoạt hiệu ứng khi các thẻ đi vào vùng nhìn thấy (viewport)
- **Hiệu năng (Performance)**: Sử dụng thuộc tính `will-change` cho transform và opacity

### 7. Chân trang (Footer)

- **Nền (Background)**: Màu tối (neutral-900) với lớp phủ gradient tinh tế
- **Bo góc (Border radius)**: Chỉ bo tròn hai góc phía trên (2xl)
- **Nội dung (Content)**: Siêu dữ liệu tối giản (thiết bị, ngày cập nhật, trạng thái) kèm biểu tượng minh họa
- **Khoảng cách (Spacing)**: Nhỏ gọn (padding 2rem)

### 8. Các Điểm Ngắt Đáp Ứng Màn Hình (Responsive Breakpoints)

- **Máy tính để bàn - Desktop** (>1280px): 4-5 cột
- **Máy tính bảng - Tablet** (768-1280px): 2-3 cột
- **Điện thoại - Mobile** (<768px): 1 cột, giảm khoảng đệm (padding) trên toàn trang

### 9. Yêu cầu Kỹ thuật

- **Một tệp HTML duy nhất**: Toàn bộ mã CSS được nhúng trực tiếp trong thẻ `<style>`
- **Chỉ sử dụng các thư viện ngoài sau**:
  - Pico.css (CSS framework tối giản)
  - Font Awesome (biểu tượng icons)
  - Google Fonts (Inter + IBM Plex Mono)
  - Animate.css (tùy chọn, dùng cho các hiệu ứng chuyển động bổ sung)
- **Không cần bước biên dịch (No build step)**: Phải hoạt động ngay dưới dạng tệp HTML tĩnh
- **Hiệu năng (Performance)**: Tối ưu hóa chuyển động mượt mà, không gây xê dịch bố cục (no layout shift)
- **Khả năng tiếp cận (Accessibility)**: Sử dụng HTML ngữ nghĩa (semantic HTML), đầy đủ thuộc tính văn bản thay thế (alt text) cho hình ảnh

### 10. Chi tiết Tinh chỉnh Hoàn thiện (Polish Details)

- **Dải chuyển màu tinh tế (Subtle gradients)**: Hiệu ứng tỏa tròn ở nền giúp tạo chiều sâu (tránh làm quá tay gây rối mắt)
- **Xử lý đường viền (Border treatment)**: Viền 1px solid có độ trong suốt alpha
- **Phân lớp bóng đổ (Shadow layering)**: Kết hợp nhiều lớp giá trị shadow để tạo chiều sâu chân thực
- **Kiểu chữ (Typography)**: Thu hẹp khoảng cách chữ (letter-spacing) trên các tiêu đề (-0.03em)
- **Nhất quán màu sắc**: Sử dụng design tokens ở mọi nơi, không gán cứng (hardcode) mã màu
- **Trình bày hình ảnh**: Tạo đường viền trắng xung quanh ảnh chụp màn hình để mang lại cảm giác như khung viền thiết bị

## Định dạng Đầu ra

Tạo một tệp `index.html` duy nhất bao gồm:

1. Cấu trúc HTML hoàn chỉnh
2. Mã CSS nội tuyến (inline) với đầy đủ các design tokens
3. Mã JavaScript xử lý hiệu ứng cuộn trang (IntersectionObserver)
4. Toàn bộ các thẻ ảnh chụp màn hình kèm siêu dữ liệu chuẩn xác
5. Thiết kế đáp ứng (responsive design) tương thích với mọi kích thước màn hình

## Ví dụ Cấu trúc Thẻ Ảnh chụp Màn hình

```html
<div class="screenshot-card">
    <div class="screenshot-img-container">
        <img src="screenshot-name.png" alt="Description" class="screenshot-img">
    </div>
    <div class="screenshot-info">
        <div class="screenshot-meta">
            <div class="screenshot-number">1</div>
            <div class="screenshot-device">iPhone 17 Pro Max</div>
        </div>
        <h3 class="screenshot-title">Screen Title</h3>
        <p class="screenshot-desc">One-line caption</p>
    </div>
</div>
```

## Những Điểm Khác Biệt Cốt Lõi So Với Các Thư Viện "Mang Dáng Dấp AI Đại Trà"

❌ **Cần tránh**:
- Lạm dụng quá nhiều dải màu chuyển sắc (gradients) và màu sắc lòe loẹt
- Các thẻ thống kê (stat cards) to bản gây lãng phí không gian
- Mô tả dài dòng và danh sách tính năng lê thê
- Các đường kẻ phân cách phần (section dividers) và tiêu đề phân loại rườm rà
- Hiệu ứng chuyển động quá đà gây choáng ngợp
- Khoảng cách bố cục thiếu nhất quán
- Phong cách ảnh minh họa đại trà (generic stock photography)

✅ **Cần học hỏi theo**:
- Các trang giới thiệu sản phẩm trên Apple App Store
- Trang tiếp thị của Linear, Raycast, Superhuman
- Thiết kế tối giản, đặt nội dung làm trung tâm (content-first)
- Các tương tác tinh tế, trau chuốt
- Nhịp điệu thị giác nhất quán
- Phân cấp thông tin dựa trên nghệ thuật sắp đặt chữ (typography-driven hierarchy)
- Sử dụng khoảng trắng (white space) như một yếu tố thiết kế chủ đạo

## Ghi chú Triển khai (Deployment Notes)

- Thư viện nên được triển khai vào thư mục `project-root/screenshots-gallery/` hoặc tương tự
- Bao gồm thư mục `.netlify` có chứa tệp `netlify.toml` để cấu hình
- Toàn bộ ảnh chụp màn hình nên được đặt cùng thư mục với tệp `index.html`
- Không yêu cầu quy trình build - thuần túy là HTML tĩnh

---

**Cách sử dụng**: Sao chép câu lệnh (prompt) này và gửi cho trợ lý AI kèm theo:
1. Danh sách các tệp ảnh chụp màn hình trong dự án của bạn
2. Tên ứng dụng và một dòng mô tả ngắn gọn
3. Nền tảng mục tiêu (iOS, macOS, Android, web)
4. Các công nghệ chính được sử dụng (SwiftUI, React Native, Flutter, v.v.)

AI sẽ tạo ra một thư viện trưng bày hoàn chỉnh, sẵn sàng đưa lên môi trường thực tế với vẻ đẹp chuyên nghiệp.