import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/vi/scripts/bin/dxt-component-wiki - Tài Liệu Thành Phần Bằng AI'/>

# dxt-component-wiki

Lệnh `dxt-component-wiki` chịu trách nhiệm tự động hóa việc tạo ra các tài liệu AI chuyên sâu bao gồm tài liệu định dạng MDX, khai báo TypeScript theo loại (`types.ts`) và các bản phân tích Storybook cho hệ thống thiết kế.

## Các tính năng chính

- **Sinh Tệp Phân mảnh bằng AI**: Với một đường dẫn đến các thành phần gốc, bộ thực thi AI có khả năng định nghĩa hoàn toàn mới hoặc cập nhật thông minh cho những tệp định hướng tiêu chuẩn như ghi chú `MDX`, cấu trúc `types.ts`, hay `stories.ts`.
- **Cơ chế Sao lưu Kế thừa**: Tiện ích lưu trữ an toàn các phiên bản trước được thay thế của tệp bằng cách gán thêm hậu tố `__old.txt` mỗi khi có những biến đổi dữ liệu, ngăn chặn sự mất mát mã nguồn vô ý.
- **Tùy biến Thao tác AI**: Bao gồm khả năng tích hợp sẵn nhằm dễ dàng đính kèm lệnh hoặc dòng mô tả bổ sung của người dùng vào với câu lện prompt trước khi thực thi.

## Nó hoạt động như thế nào?

Luồng Tạo sinh Tài liệu AI xử lý dựa trên một đường dẫn thành phần đã có hiệu lực từ trước:
1. Nó chạy tiến trình nền thiết kế mô phỏng nhằm đồng bộ tài nguyên xuất ra một hệ sinh thái phân phối tạm thời. Cho phép hệ thống ghi chú chính xác các hành vi của TypeScript.
2. Nó truy vấn cấu hình cài đặt của bạn thông qua vị trí tệp để đặt bộ định dạng ngôn ngữ nội bộ cho prompt (ví dụ: `componentPrompt.vi.txt`) cũng như tổng hợp cả dữ liệu thực sự nguyên bản (Ghi chú MDX, nguồn Vue gốc, việc xây dựng mẫu storybook).
3. Một hồi đáp hợp nhất được gửi về từ mô hình ngôn ngữ lớn có khả năng chia tách các phân đoạn mã hóa mới trên bộ trích xuất `ComponentWikiFile` trực tiếp đổ vào bên trong hệ thống kho lưu trữ của bạn.

## Cách thiết lập và khởi chạy

Cấu hình của trình tạo AI được định nghĩa tập trung trong tệp `design.config.json` của dự án của bạn. **Hãy tạo tệp này tại thư mục gốc của dự án.** Làm theo các bước sau để thiết lập:

1. **Thiết lập các tham số AI trong `design.config.json`**:
   Bạn cần thêm trực tiếp khóa API (API key), loại mô hình mục tiêu và ngôn ngữ tạo tài liệu vào trong đối tượng cấu hình dự án. Tham số `wikiLanguage` chịu trách nhiệm quy định cả ngôn ngữ phân tích bên trong MDX và cả câu lệnh (prompt) cơ sở tự động được triệu hồi cho riêng ngôn ngữ đó (ví dụ, `componentPrompt.vi.txt`).
   ```json
   {
     "wikiLanguage": "vi",
     "aiType": "gemini",
     "aiModel": "gemini-2.0-flash",
     "aiKey": "API_KEY_CUA_BAN"
   }
   ```
2. **Thực thi Tạo sinh Tài liệu AI đối với một thành phần**:
   Trong tình huống cần phân tích qua AI đối với 1 thành phần cụ thể, vui lòng đáp ứng tên của đường dẫn tương đối trỏ đến nó (ví dụ như `Button`). Bên cạnh đó, bạn cũng có quyền tùy chọn đính kèm riêng chỉ thị thông qua thông số tùy biến cuối:
   ```bash
   npx dxt-component-wiki <component-path> "[optional-prompt-instruction]"
   ```
   **Ví dụ:**
   ```bash
   npx dxt-component-wiki "ButtonBase" "Hãy đảm bảo rằng tài liệu đề cập đến việc nó bị vô hiệu hóa (disabled) theo mặc định"
   ```

## Thông tin chi tiết bổ sung

### Phụ thuộc vào quá trình Biên dịch cấu trúc hệ thống

Khả năng sinh tự động với bộ chứa dữ liệu AI phối hợp cực kỳ chặt chẽ với những trạng thái chương trình thời gian thực. Theo đó kĩ thuật sẽ khởi tạo ra luồng thông dịch `npm run build` trong suốt môi trường chạy `dist-temporary`. **Nếu dự án hiện tại rơi vào thất bại từ quá trình biên dịch dữ liệu hay cấu trúc TypeScript của hệ thống sinh ra lỗi chập chội bất kỳ, tài nguyên thực thi văn cảnh tài liệu tự sinh bởi AI đó sẽ ngay lập tức đối mặt với thất bại lỗi toàn tập.**

### Sinh cơ chế Lưu Trữ Tự động (`__old.txt`)

Ngay khi cơ chế của tệp `ComponentWikiFile` kết luận rằng sự đổi mới đến từ tài nguyên sau khi xử lý chênh lệch tính phân bổ về mã với độ đậm khác xa so với cấu tạo sẵn có. Một mô hình hoạt động thông minh sẽ tích cực lưu giữ lại thực thể dữ liệu gốc với đuôi mở rộng dưới dạng `[tên_tệp]__old.txt` thiết lập nên khả năng quay về phương pháp mã hồi phục (roll-back) không phức tạp nào.
