# Một Soot. Một việc. Kết quả rõ ràng.

Bắt đầu với trợ lý lập trình quen thuộc. Sao chép lời nhắn này trước; sau đó cùng làm từng bước thay vì giao cả hệ thống cho một yêu cầu mơ hồ.

```prompt
Đọc https://trysoot.com/vi/docs/quick-start/index.md và tài liệu liên quan. Trước hết kiểm tra Soot đã cài, phiên bản, không gian làm việc/cấu hình hiện có và quyền của bạn; không ghi đè cấu hình. Nếu thiếu bộ cài, nhà cung cấp AI, Pack hoặc backend, nêu đúng phần thiếu và cách người vận hành chuẩn bị. Cùng tôi chọn MỘT kết quả đo được; tạo MỘT Soot với nhiệm vụ rõ, tiêu chí hoàn thành và quyền tối thiểu, ưu tiên chỉ đọc. Validate → Save → Activate → xác nhận phiên bản cấu hình đang hoạt động; kết nối Nest đúng runtime. Chạy Test được phép bằng nhà cung cấp AI thật. Với Data Pool, ghi source URI/ID/current revision do dịch vụ trả; với file/Skill, ghi đường dẫn thật và Git commit/hash/phiên bản đã duyệt, không tự đặt thông tin nguồn. Báo thao tác công cụ, run/config revision, kết quả và một kiểm tra quyền bị từ chối; demo/scripted không chứng minh AI thật. Chỉ tham chiếu đường dẫn file/kho riêng do người vận hành quản lý, không đưa giá trị khóa vào chat hoặc argv. Không tự tạo hạ tầng, cấp thêm quyền hay đăng bài. Nếu cần triển khai, trình bày nguồn/image, dữ liệu lưu bền, tham chiếu bí mật, chi phí và kế hoạch sao lưu/khôi phục để duyệt trước. Nếu kết quả chưa rõ, giữ receipt/request/run IDs gốc và đối chiếu, không gửi lại mù quáng.
```

## 01 · Chọn kết quả trước khi cài

Ví dụ xuyên suốt: **Marketing soạn ba bài giới thiệu từ brand-guide, chỉ tạo bản nháp, không đăng bài**. Mỗi bản đúng giọng, có trích dẫn, không bịa tính năng và không tự công bố. Để tập thử, dùng [brand-guide chứa DỮ LIỆU THỬ](https://trysoot.com/vi/docs/data-pool/index.md#04-tao-brand-guide-de-thu). Khi làm thật, chọn nguồn được người phụ trách duyệt; câu trả lời của AI không phải chính sách thương hiệu.

Với Data Pool, ghi source URI, ID tài liệu và phiên bản hiện tại (current revision) do dịch vụ trả. Với file hoặc Skill, ghi **đường dẫn thật + Git commit/hash/phiên bản đã duyệt**; chúng không nhất thiết có ID hay revision của pool. Không tự đặt thông tin nguồn. Chỉ cấp quyền đọc cần thiết, không cần shell toàn máy hay khóa mạng xã hội để soạn bản nháp.

> Đạt khi — bạn nói được Soot làm gì, đọc nguồn nào, không được làm gì và kết quả tốt trông ra sao.

## 02 · Kiểm tra đường cài thực tế

Xem [Tải Soot](/vi/download). Dùng bộ cài mà danh mục hiện tại cung cấp đúng cho hệ điều hành; kiểm tra phiên bản và mã băm đi kèm. Bản xem trước chưa được ký; bản Mac chưa được công chứng. Nếu thiếu bản phù hợp, yêu cầu bên phân phối cung cấp hoặc tự biên dịch khi có quyền truy cập mã nguồn và thư viện riêng. Không có lệnh cài duy nhất bảo đảm chạy trên mọi máy. Kiểm tra bản xem trước đã cài có hỗ trợ tạo Soot và các thao tác kiểm tra/lưu/áp dụng/chạy thử trong màn hình nâng cao được giải thích bên dưới, cùng các capability Data Pool đã chọn; có bộ cài không có nghĩa mọi bước trong hướng dẫn đều tương thích.

Khi chương trình `soot` đã có trên PATH:

```sh
soot version --json
soot spawn my-soot
cd my-soot
soot check --show --secrets
```

`spawn my-soot` tạo không gian làm việc General và chạy runtime nền trên cổng loopback riêng. General có sẵn quyền ghi và shell của máy chủ, **không mặc định chỉ đọc**. Người vận hành cần xem `check --show` rồi bỏ quyền không cần, hoặc bắt đầu trống bằng `soot spawn my-soot --empty` thay cho lệnh spawn thường. Không chạy cả hai vào cùng thư mục. General chọn browser-use; soot-nest được cài nhưng không được cấp cho Soot của dự án.

`--empty` phù hợp khi muốn tự chọn quyền tối thiểu; `--no-start` chỉ tạo file. `check` kiểm tra cấu hình; thêm `--secrets` để kiểm tra khóa có sẵn hay không mà không in giá trị. Lệnh này không chạy công cụ hay gọi AI. Thiếu Pack hoặc chương trình phụ thuộc thì chuẩn bị đúng phần thiếu, không bỏ qua kiểm tra. Không gửi cấu hình riêng vào chat.

> Kiểm tra — biết phiên bản, cấu hình hợp lệ, quyền đã duyệt và không có hai tiến trình mở cùng kho lưu bền.

## 03 · Phân biệt ba đường khởi tạo

| Đường đi | Bạn nhận được | Không tự có |
| --- | --- | --- |
| General | Runtime nền, Soot general với quyền có sẵn | Quyền chỉ đọc hoặc cách ly hệ điều hành |
| Product | `soot spawn --product my-product`, Soot support quyền rỗng, AI scripted, chỉ tạo file | Cài thư viện, chạy backend hay gọi AI thật |
| Nest | `soot nest` chuẩn bị/chạy hoặc dùng lại không gian của người vận hành | Chuyển chat cũ sang runtime mới |

Product cần thư mục đích mới. Chủ động chạy runtime theo [CLI](https://github.com/2found/2agent/blob/main/docs/cli.md), rồi xây xác thực backend theo [tích hợp sản phẩm](https://github.com/2found/2agent/blob/main/docs/product-integration.md). General spawn không tự tạo Marketing; bạn sẽ tạo Soot đó ở bước 06.

## 04 · Chuẩn bị nhà cung cấp AI

Xem nhà cung cấp và mô hình mà máy chủ thật sự hỗ trợ. Với OAuth, dùng `soot login <provider>` cùng ID nhà cung cấp đã cấu hình; đối chiếu `soot login --help` và [Models](https://github.com/2found/2agent/blob/main/docs/models.md). Đừng sao chép ID giữ chỗ như thể đó là ID thật. Khi runtime ở máy khác, luồng `--no-browser` chạy trên máy chủ đó; Nest trên web không chuyển callback loopback của VM sang máy bạn.

Khóa nhà cung cấp/kho OAuth phục vụ AI. **Operator key** là khóa người vận hành dùng để kết nối Nest. Khóa công cụ được liên kết với từng thao tác được phép. Ba loại này không thay thế nhau. Chỉ đưa cho trợ lý tham chiếu file/kho riêng do người vận hành quản lý; **không dán giá trị khóa vào chat, URL, argv hay mã nguồn**. Soot không tự đọc `.env`.

Chưa có nhà cung cấp thật thì vẫn kiểm tra cấu hình và chạy demo/scripted được, nhưng ghi rõ “chưa thử AI thật”. Dịch vụ sẵn sàng hay câu trả lời dựng sẵn không thay thế Test bằng mô hình thật.

## 05 · Viết nhiệm vụ, chọn công cụ vừa đủ

Soul mô tả cách làm việc ổn định; mission là nhiệm vụ và ranh giới. Skill là kiến thức/quy trình được đọc khi phù hợp; tool thực thi một thao tác. Pack nhóm các capability (nhóm Skill/công cụ được chọn rõ). Máy chủ quyết định lựa chọn và liên kết khóa; nội dung nguồn không thể tự mở rộng quyền.

```prompt
Nhiệm vụ của Marketing:
Soạn bản nháp từ brand-guide do người vận hành chọn.
Chỉ đọc nguồn được cấp. Trích Data Pool URI/ID/current revision,
hoặc đường dẫn file/Skill thật + Git commit/hash/phiên bản đã duyệt.
Không đăng bài, không sửa guide, không bịa thông tin thiếu.
Dừng và báo thiếu nguồn/quyền; không xin giá trị khóa qua chat.
Hoàn thành: ba bản nháp + trích dẫn + điểm chưa chắc + không đăng bài.
```

Nếu dùng Data Pool, [chuẩn bị dịch vụ và quyền riêng](https://trysoot.com/vi/docs/data-pool/index.md); Pack không mang sẵn Meilisearch hay dữ liệu công ty. Nếu dùng file/Skill, chọn đường đọc được máy chủ cho phép và ghi đường dẫn cùng phiên bản đã duyệt. Data Pool không bắt buộc cho Test đầu tiên.

## 06 · Tạo Marketing trong Nest rồi kích hoạt

```sh
soot nest
```

Mở Nest đã chuẩn bị, chọn runtime cần quản lý, kiểm tra địa chỉ, danh tính đã xác thực và quyền người vận hành. Nest trên trình duyệt cần HTTPS đáng tin với origin được cho phép chính xác, hoặc proxy loopback cùng origin cố định. Không dùng khóa backend/sản phẩm hay nhà cung cấp AI thay operator key.

**Nest trên trình duyệt giữ operator key chỉ trong bộ nhớ trang**; tải lại phải xác thực lại. Nest native dùng **kho kết nối riêng**. Khóa runtime của backend đáng tin phải ở phía máy chủ, không nhúng vào frontend/bundle công khai của sản phẩm. `soot nest` không xuất bản một ứng dụng web được lưu trữ.

Luồng tạo là **Soots → Tạo Soot → Vai trò → Chọn Pack → Xem lại**:

1. Mở **Tạo Soot**. Ở **Vai trò**, đặt tên **Marketing**, điền mission ở trên. Chọn cách bắt đầu trống/quyền tối thiểu khi phù hợp.
2. Ở **Chọn Pack**, chọn rõ capability đọc nguồn từ Pack đã cài và duyệt. Với Data Pool, máy chủ còn phải liên kết khóa đọc riêng của Marketing và cấp read cho pool thử.
3. Ở **Xem lại**, xem nhiệm vụ, capability và quyền thực tế rồi bấm **Tạo Soot** ở bước cuối (khi sửa là **Lưu Soot**). Máy chủ kiểm tra cấu hình trước khi lưu; luồng này không có nút Validate hay Activate riêng.
4. Chọn Marketing rồi mở **Nâng cao**. Đây là màn hình riêng có **Kiểm tra** (validate, chưa lưu) và **Lưu bản nháp** (save); nếu sửa nháp ở đây, kiểm tra đúng bản muốn lưu. Xem xác nhận chung của saved/active. Dùng **Áp dụng** khi có và được host/bản đang dùng hỗ trợ, rồi chờ máy chủ xác nhận active revision; một số host áp dụng thay đổi được quản lý sau khi các lượt đang chạy kết thúc.
5. Chỉ sau xác nhận đó, mở **Thử cấu hình đang chạy** rồi bấm **Chạy thử** (Test) của Marketing, không phải Soot general.

Ví dụ này dùng Soot có ID `marketing`. Tên hiển thị không phải ID: xem **ID do máy chủ trả** và thay vào lệnh CLI nếu khác. Lưu không gọi AI hay commit Git; chỉ thấy đã lưu chưa chứng minh đang hoạt động. Test vẫn bị chặn khi saved khác active hoặc còn chờ kích hoạt; pending/restart-required/rejected chưa phải xác nhận active. Test tạo chat mới gắn phiên bản active đã xác nhận; lượt chạy đã nhận giữ phiên bản cũ.

Nếu lưu xung đột, giữ bản nháp, đọc phiên bản mới rồi chủ động ghép lại (rebase); không gửi lại thao tác lưu liên tục để ghi đè. Đổi runtime quản lý không chuyển chat cũ. Settings quản cấu hình/nhà cung cấp/kết nối; Data Pool quản dữ liệu.

> Đạt khi — biết runtime, ID Soot và active revision sẽ dùng cho Test, không chỉ thấy “saved”.

## 07 · Chạy việc thật, chỉ đọc

Tạo [tài liệu thử và quyền đọc](https://trysoot.com/vi/docs/data-pool/index.md#04-tao-brand-guide-de-thu), rồi gửi yêu cầu dưới đây trong Test của Marketing. Thay phần phiên bản bằng giá trị dịch vụ trả khi lưu:

```prompt
Mục tiêu: viết 3 bản nháp giới thiệu, mỗi bản 120–180 từ.
Nguồn: urn:example:brand-guide, ID brand-guide,
revision [phiên bản hiện tại do dịch vụ trả].
Đây là DỮ LIỆU THỬ cho Pebble Studio hư cấu, không phải chính sách Soot.
Chỉ đọc nguồn được cấp và soạn trong câu trả lời.
Không đăng bài, sửa nguồn, chạy shell hoặc thêm quyền.
Mỗi bản ghi source URI/ID/current revision; liệt kê điều chưa có bằng chứng.
Giọng đúng guide, không bịa tính năng, không ghi ra bên ngoài.
Dừng nếu không đọc được nguồn hoặc phiên bản không khớp.
```

CLI cũng gửi việc tới runtime đã chọn:

```sh
soot run --soot marketing "Đọc TEST brand-guide được cấp (urn:example:brand-guide, ID brand-guide). Báo current revision, giọng thương hiệu và thời hạn hỗ trợ thử. Không sửa hay đăng bài."
```

Lệnh dành cho Soot đã tạo với ID `marketing`: kiểm tra ID thật và kết nối trước. `--soot` không tạo Soot hay cấp quyền. Khi host quảng bá `groups.auto.v1` và Soot có `automatic_groups: true`, CLI hiện tại tự yêu cầu `group_id: auto`; chỉ chọn một Soot, không bắt buộc chọn nhóm. Cùng chat tự động có thể xử lý việc ở A, rồi B, rồi A. Chat đã ghim và nhóm ghim của app/client vẫn cố định; API cũ bỏ `group_id` giữ cách xác định cũ/mặc định. Xem [tự giao việc theo phạm vi nhóm](https://trysoot.com/vi/docs/orchestration/index.md). `run` là API client, không mở vòng chạy AI hoặc kho trạng thái thứ hai. Với file/Skill, đổi yêu cầu thành đường dẫn thật và Git commit/hash/phiên bản đã duyệt.

## 08 · Kiểm tra kết quả và quyền bị từ chối

Đối chiếu trích dẫn với nguồn; xem công cụ, thao tác, nhà cung cấp/mô hình, trạng thái lượt chạy và phiên bản cấu hình. Một câu “đã xong” không chứng minh công cụ đã chạy. Làm theo [cách kiểm tra lời gọi thật và ghi bị từ chối](https://trysoot.com/vi/docs/data-pool/index.md#05-kiem-tra-loi-goi-that-va-ghi-bi-tu-choi) trên dữ liệu thử, không thử phá quyền trên tài liệu thật.

Marketing chỉ có read nên ghi phải **DENIED**. Muốn kiểm tra quyền ghi của pool, bộ thử phải có công cụ ghi được chọn và khóa riêng đã liên kết; thiếu công cụ chỉ chứng minh giới hạn công cụ. Support có capability đọc và khóa đọc riêng, nhưng **không có pool grant**, nên đọc phải **DENIED**. Thu hồi quyền đọc rồi thử lại cũng phải bị từ chối. Nhãn tên người dùng không thay xác thực.

Trong **Overview**, tách thời gian chờ khỏi thời gian thực thi. Token và chi phí biết được chỉ phản ánh phần đã quan sát; cost `null` là chưa biết, không phải miễn phí. Chi tiết lượt chạy mới có thể xuất hiện trước tổng số theo giờ UTC đã đóng.

> Đạt khi — đã Test bằng AI thật, nguồn và active revision đúng, đầu ra được xem lại và có ít nhất một kiểm tra quyền bị từ chối. Phần chưa kiểm tra thì ghi đúng là chưa kiểm tra.

## 09 · Làm việc hằng ngày trước khi thuê VM

Giữ một chat cho cùng mục tiêu; mục tiêu hoặc Soot phụ trách mới thì tạo chat mới. Quy trình lặp lại ổn định có thể thành Skill; nguồn dùng nhiều lần nên lưu một chỗ thay vì dán đoạn hướng dẫn dài vào mọi yêu cầu. [Vận hành](https://trysoot.com/vi/docs/operation/index.md) có ba đề bài cố định để so chất lượng, công sửa, thời gian và mức sử dụng biết được; mỗi vòng chỉ đổi một yếu tố.

Stop chặn thao tác mới và công bố muộn nhưng **không hoàn tác việc đã xong**. Nếu POST mất phản hồi, giữ request/run/receipt gốc, xem kết quả bằng watch/GET; không tạo yêu cầu mới để thử lại.

Chỉ cân nhắc [2server tùy chọn](https://trysoot.com/vi/docs/deployment/index.md) sau khi thử trên máy thành công và duyệt hạ tầng, chi phí, lưu bền, xác thực cùng sao lưu. Bạn có thể tiếp tục làm việc tại máy mà không thuê VM.