Chạy lệnh này bên trong kho Git mà bạn muốn Truthmark quản lý:
```bash
cd /path/to/your-repo
npm install -g truthmark
truthmark config
```
Bật máy chủ AI mà bạn thực sự sử dụng. Cấu hình mới không gắn với máy chủ nào, vì vậy hãy thêm danh sách `platforms` ở cấp cao nhất vào `.truthmark/config.yml` trước khi khởi tạo:
Sau đó cài đặt tài liệu sự thật cục bộ của kho, định tuyến và các bề mặt quy trình làm việc cho tác tử:
```bash
truthmark init
truthmark check
git diff
```
Bây giờ hãy thử lộ trình áp dụng phổ biến nhất: ghi tài liệu cho một hành vi hiện có từ mã và kiểm thử. Trong máy chủ lập trình AI của bạn, hãy yêu cầu quy trình đã cài đặt:
```text
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
```
Sau đó, người dùng thường không nên gọi Truth Sync trực tiếp. Hãy tiếp tục lập trình qua máy chủ AI của bạn; các chỉ dẫn kho đã cài đặt yêu cầu tác tử chạy các kiểm thử liên quan và thực hiện đánh giá Truth Sync trước khi bàn giao khi mã chức năng thay đổi. Bạn xem xét phần diff mã kết quả cùng với diff tài liệu truth.
Nếu bạn chỉ muốn xác thực bằng CLI và chưa muốn các quy trình AI theo máy chủ, hãy để trống `platforms` và chạy `truthmark init && truthmark check`; bạn có thể thêm nền tảng sau và chạy lại `truthmark init`.
## 💡 Vấn đề: khoảng trống tài liệu AI
Các tác tử lập trình AI cực kỳ giỏi viết mã nhanh. Nhưng tốc độ này tạo ra một kiểu lỗi mới nguy hiểm: **câu chuyện của kho lệch khỏi thực tế.**
* Hành vi bị mất trong lịch sử trò chuyện tạm thời.
* Tài liệu kiến trúc nhanh chóng tụt lại phía sau.
* Quyết định sản phẩm biến mất sau khi bàn giao.
* Người xem xét mã phải xem các diff mã thô mà không hiểu "vì sao".
* Mỗi phiên AI mới buộc phải khám phá lại sự thật của kho từ đầu.
## 🎯 Giải pháp: Truthmark
**Truthmark** cài đặt một lớp quy trình làm việc gốc Git vào kho của bạn. Nó khắc phục phần thường bị hỏng trong phát triển bằng AI: giúp tài liệu luôn khớp với mã.
Thay vì hy vọng con người và tác tử AI nhớ cập nhật tài liệu, Truthmark biến việc ghi tài liệu thành một thói quen có hệ thống, có thể xem xét ngay trong kho của bạn.
### ✨ Vì sao Truthmark khác biệt
Truthmark không chỉ là một công cụ tài liệu khác. Nó được tích hợp sâu vào quy trình AI:
* **🚫 Không bị khóa vào nhà cung cấp:** Không dịch vụ lưu trữ, không cơ sở dữ liệu ẩn, không máy chủ bổ sung để vận hành.
* **🌳 100% gốc Git:** Mọi thứ nằm trong kho của bạn. Sự thật di chuyển cùng nhánh của bạn.
* **✅ Tin cậy qua xác minh:** Công việc AI dễ được tin tưởng hơn vì công việc thay đổi hành vi bao gồm một quyết định hoặc diff tài liệu sự thật mà con người có thể xem xét.
## 🔄 Cách hoạt động
Khi một tác tử AI sửa mã của bạn, công việc chưa kết thúc. Truthmark cài đặt một chốt quy trình lúc hoàn tất mà tác tử tuân theo trước khi bàn giao:
1. 💻 **Mã:** Tác tử sửa mã chức năng.
2. 🧪 **Kiểm thử:** Các kiểm thử liên quan được chạy.
Truthmark cài đặt hướng dẫn cục bộ trong kho cho các AI coding host được hỗ trợ như Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor.
Vòng lặp bình thường rất đơn giản:
1. Yêu cầu tác tử thay đổi mã hoặc ghi tài liệu cho một hành vi hiện có.
2. Hướng dẫn đã cài đặt cho tác tử biết khi nào cần kiểm thử, khi nào cập nhật truth docs và khi nào dừng để con người xem xét.
3. Bạn xem xét các Git diff thông thường: mã cộng với mọi thay đổi truth-doc.
Các yêu cầu tác tử do người dùng khởi động được cố ý giữ ít:
*`/truthmark-document` - ghi tài liệu cho hành vi đã triển khai hiện có từ mã và kiểm thử.
*`/truthmark-realize` - triển khai mã từ truth docs hiện có.
*`/truthmark-check` - kiểm toán sự thật của kho.
Truth Sync không phải cách thông thường để bắt đầu công việc; đó là bước xem xét kết thúc sau các thay đổi mã chức năng.
Truth Structure không phải lệnh hằng ngày; nó chỉ sửa định tuyến hoặc quyền sở hữu khi điều đó chặn công việc.
README là mặt tiền: ngữ cảnh nhanh, bắt đầu nhanh và mô hình tư duy cốt lõi.
Để biết cách sử dụng từng lệnh, so sánh bề mặt, chi tiết nền tảng được hỗ trợ, cấu hình, định tuyến, Portal và ví dụ, hãy đọc [Hướng dẫn người dùng Truthmark](../user-guide.md).
## Trạng thái dự án
Bản phát hành hiện tại cung cấp:
- các lệnh CLI cục bộ cho config, init, check, index, impact và trạng thái quy trình
- chẩn đoán về định tuyến, thẩm quyền, frontmatter, liên kết, độ mới, bề mặt sinh ra, phạm vi nhánh và độ phủ
- tài liệu sự thật theo phạm vi nhánh và các hiện vật trí tuệ kho được suy dẫn
## Tài liệu
- [Hướng dẫn người dùng](../user-guide.md)
- [Chỉ mục tài liệu](../README.md)
- [Tổng quan kiến trúc](../truthmark/engineering/architecture/overview.md)
- [Hợp đồng API và CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
- [Hướng dẫn bảo trì sự thật của kho](../standards/maintaining-repository-truth.md)
Để xem các lệnh phát triển cục bộ và đóng góp, hãy xem [CONTRIBUTING.md](../../CONTRIBUTING.md).
## Ranh giới thiết kế
Truthmark được cố ý giữ nhỏ: cục bộ, được commit, theo phạm vi nhánh và có thể xem xét.
Nó không phải dịch vụ lưu trữ, máy chủ MCP, cơ sở dữ liệu vector, lớp bộ nhớ ẩn, sản phẩm cưỡng chế CI hay động cơ tự động viết lại mã. Nó giúp sự thật của kho luôn hiển thị; nó không thay thế kiểm thử, xem xét mã hay phán đoán của con người.
Sử dụng `truthmark uninstall --dry-run` để xem lại chính xác các bề mặt host đã tạo ra, rồi `truthmark uninstall --apply` để loại bỏ chúng. Các truth đã tạo, cấu hình, mẫu, đầu ra Portal, tệp Gemini và các tệp người dùng không liên quan sẽ được giữ nguyên; hãy gỡ bỏ cài đặt npm toàn cục riêng biệt bằng trình quản lý gói của bạn.
