System One Harness

1. System One Harness là gì?

System One Harness là một bộ công cụ dòng lệnh viết bằng Python, dành cho lập trình viên và người nghiên cứu AI. Nó không phải chatbot và không có giao diện để bấm. Việc của nó là biến một loại mô hình AI đặc biệt, gọi là mô hình "System One", thành một tác nhân (agent) tự làm việc từng bước.

Khác với ChatGPT, mô hình System One không viết ra chữ. Nó chỉ trả lời các câu hỏi có sẵn đáp án (chọn một trong nhiều phương án, có hoặc không, mức độ) kèm xác suất, và trả lời rất nhanh. Harness là vòng điều khiển bao quanh: quan sát tình huống, đổi các hành động được phép thành câu hỏi, gọi mô hình một lần cho mỗi bước, chỉ thực hiện khi mô hình đủ chắc chắn, rồi ghi lại toàn bộ quá trình. Mô hình đầu tiên được hỗ trợ là Jev của TypeSafe.

Phần mềm miễn phí, mã nguồn mở (Apache-2.0). Tuy vậy, để chạy bạn cần khóa API của OpenRouter hoặc TypeSafe, và mỗi lần gọi mô hình có tính phí theo lượng dùng.

Hợp với bạn nếu:

• Bạn là lập trình viên hoặc đang học về AI agent và muốn thử một cách làm khác: AI chỉ được chọn trong danh sách hành động cho trước, không tự bịa ra lệnh.
• Bạn tò mò và sẵn sàng gõ vài dòng lệnh để chạy ví dụ mẫu có sẵn.

Chưa hợp nếu:

• Bạn cần một ứng dụng trò chuyện hay trợ lý dùng ngay. Ở đây không có.
• Bạn chưa từng dùng dòng lệnh và không muốn tạo khóa API.

2. Cần chuẩn bị gì?

• Máy tính chạy macOS, Linux hoặc Windows. Tài liệu chính thức chỉ viết lệnh cho macOS/Linux; trên Windows có một lệnh phải đổi cách viết (xem Bước 4).
• Python 3.10 trở lên: ngôn ngữ lập trình mà công cụ này dùng. Khi cài Python bạn có luôn pip, công cụ cài gói Python. Tải ở https://www.python.org/downloads/
• Git: công cụ tải mã nguồn từ GitHub về máy. Tải ở https://git-scm.com
• Khóa API (một chuỗi ký tự bí mật dùng để gọi mô hình): lấy ở OpenRouter (https://openrouter.ai) hoặc TypeSafe (https://typesafe.ai). Có tính phí theo lượng dùng; bảng giá xem trên trang của nhà cung cấp. Trong ví dụ mẫu của tài liệu, một lần chạy năm bước tốn khoảng 0,0002 USD.
• Tùy chọn: trình duyệt Chrome nếu sau này bạn muốn cho tác nhân điều khiển trang web.

Phiên bản mới nhất lúc viết bài là v0.4.0, phát hành ngày 21/9/2026. (Một vài chỗ trong README vẫn ghi 0.3.1; file cấu hình của dự án và trang Releases ghi 0.4.0.)

3. Cài đặt từng bước

Dự án chỉ có một cách cài: tải mã nguồn rồi cài bằng pip. Không có file cài .exe hay bản trên cửa hàng ứng dụng.

Bước 1: Kiểm tra Python và Git

Mở Terminal (hoặc PowerShell trên Windows) và gõ lần lượt:

python --version

git --version

Thấy gì là đúng: mỗi lệnh in ra một số phiên bản, và Python phải từ 3.10 trở lên. Trên macOS/Linux, nếu python không chạy thì thử python3 --version.

Bước 2: Tải mã nguồn về máy

git clone https://github.com/HarnessRouter/SystemOneHarness.git
cd SystemOneHarness

Thấy gì là đúng: một thư mục tên SystemOneHarness được tạo ra và dòng lệnh của bạn đang đứng trong thư mục đó.

Bước 3: Cài đặt

pip install -e .

Dấu chấm ở cuối là một phần của lệnh. Lệnh này cài công cụ cùng hai thư viện nó cần, và tạo ra lệnh s1 trên máy bạn.

Thấy gì là đúng: pip chạy xong không báo lỗi. Kiểm tra bằng:

s1 run --help

Màn hình in ra danh sách tùy chọn của lệnh s1 run.

Bước 4: Khai báo khóa API

Công cụ đọc khóa từ biến môi trường (một giá trị tạm lưu trong cửa sổ dòng lệnh). Thay phần sau dấu bằng khóa thật của bạn.

macOS / Linux:

export OPENROUTER_API_KEY=sk-or-...

Windows PowerShell (lệnh export không có trên PowerShell, nên dùng cú pháp của PowerShell):

$env:OPENROUTER_API_KEY = "sk-or-..."

Nếu bạn dùng khóa của TypeSafe, đổi tên biến thành TYPESAFE_API_KEY.

Lưu ý: Biến này chỉ tồn tại trong cửa sổ dòng lệnh đang mở. Đóng cửa sổ là mất, lần sau phải khai báo lại. Không chia sẻ khóa API cho người khác và không dán nó lên mạng.

Bước 5: Chạy ví dụ mẫu

s1 run --env order:ship_fastest_gift

Đây là môi trường mẫu có sẵn: một đơn hàng giả lập cần được ghi chú là quà tặng rồi gửi bằng hãng vận chuyển nhanh nhất.

Thấy gì là đúng: màn hình in ra mục tiêu, tên mô hình, rồi khoảng năm dòng, mỗi dòng là một bước (thêm ghi chú, lấy hàng, đóng gói, chọn hãng vận chuyển, gửi đi) kèm xác suất p= và thời gian tính bằng mili giây. Dòng cuối cùng có status=completed cùng số bước, tổng thời gian và chi phí.

4. Dùng lần đầu

Sau khi ví dụ mẫu chạy được, hãy đọc kết quả theo ba ý:

• Mỗi dòng là một quyết định. Mô hình không gõ lệnh; nó chọn một hành động trong danh sách mà môi trường cho phép.
• Số p= là mức chắc chắn thấp nhất mà bước đó cần. Hành động càng rủi ro thì ngưỡng yêu cầu càng cao. Trong ví dụ của tài liệu, ngưỡng là 0,5 cho hành động chỉ đọc, 0,6 cho hành động ghi và 0,8 cho hành động không hoàn tác được.
• Dòng cuối cho biết lần chạy kết thúc thế nào. Mỗi lần chạy luôn kết thúc ở một trong các trạng thái: hoàn thành, chưa hoàn thành, thất bại hoặc bị hủy, kèm lý do rõ ràng.

Muốn lưu toàn bộ quá trình ra file để xem lại, thêm --json:

s1 run --env order:ship_fastest_gift --json trace.json

File trace.json xuất hiện trong thư mục hiện tại, ghi lại trạng thái, câu hỏi, xác suất và kết quả của từng bước.

Nếu chưa có khóa API mà vẫn muốn biết phần mềm cài đúng chưa, bạn chạy bộ kiểm thử. Bộ này dùng câu trả lời đã ghi sẵn nên không cần khóa:

pip install -e . pytest
pytest -q tests

Khi muốn đi xa hơn, công cụ nối được với bốn loại môi trường: một chương trình của riêng bạn kèm file khai báo hành động dạng YAML, một máy chủ MCP (chuẩn để AI gọi công cụ), trình duyệt Chrome, hoặc code Python. Mỗi loại cần cài thêm phần tương ứng, ví dụ cho MCP:

pip install -e ".[mcp]"

Và cho trình duyệt:

pip install -e ".[browser]"

Các bước này đòi hỏi biết lập trình. Hướng dẫn chi tiết nằm trong thư mục docs/ của repo: https://github.com/HarnessRouter/SystemOneHarness

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Gõ s1 thì máy báo không tìm thấy lệnh	Chưa chạy Bước 3, chạy sai thư mục, hoặc thư mục chứa lệnh của Python chưa nằm trong PATH (danh sách nơi máy tìm lệnh)	Vào lại thư mục SystemOneHarness và chạy lại pip install -e .. Nếu vẫn lỗi, đóng và mở lại cửa sổ dòng lệnh
pip báo phiên bản Python không phù hợp	Máy đang dùng Python cũ hơn 3.10	Cài Python mới từ https://www.python.org/downloads/ rồi chạy lại
Máy báo không tìm thấy git	Chưa cài Git	Cài Git từ https://git-scm.com và mở lại cửa sổ dòng lệnh
Trên Windows, lệnh export báo lỗi	export là lệnh của macOS/Linux	Dùng cú pháp $env:... của PowerShell ở Bước 4
Lệnh s1 run dừng ngay với lỗi liên quan đến khóa hoặc xác thực	Chưa khai báo khóa API, khai báo ở một cửa sổ khác, hoặc khóa sai	Khai báo lại khóa trong chính cửa sổ đang dùng rồi chạy lại. Kiểm tra khóa còn hiệu lực trên trang nhà cung cấp
Lần chạy kết thúc với lý do no_confident_action hoặc hành động escalate	Mô hình không đủ chắc chắn để vượt ngưỡng nên dừng lại và chuyển cho người xử lý. Đây là thiết kế, không phải hỏng	Lưu lại bằng --json trace.json và xem phần handoff: nó ghi tình huống, câu hỏi và xác suất tại lúc dừng
File khai báo hành động bị từ chối vì tham số dạng chữ tự do	Mô hình System One không sinh chữ, nên mọi tham số phải liệt kê được	Đổi tham số sang danh sách lựa chọn cố định, giá trị lấy từ quan sát, cờ đúng/sai hoặc các mức có thứ tự
Dùng --mcp hoặc --browser thì báo thiếu gói	Chưa cài phần mở rộng tương ứng	Chạy pip install -e ".[mcp]" hoặc pip install -e ".[browser]"

6. Gỡ cài đặt / cập nhật

Cập nhật lên bản mới: vào thư mục SystemOneHarness, lấy mã nguồn mới rồi cài lại.

git pull
pip install -e .

Gỡ cài đặt: gỡ gói Python (tên gói là systemone-harness), sau đó xóa thư mục SystemOneHarness đã tải về.

pip uninstall systemone-harness

Nếu không dùng nữa, bạn cũng nên vào trang OpenRouter hoặc TypeSafe để thu hồi khóa API đã tạo.

7. Câu hỏi hay gặp

Có mất tiền không? Phần mềm miễn phí. Bạn trả tiền cho nhà cung cấp mô hình (OpenRouter hoặc TypeSafe) theo lượng dùng. Theo số liệu trong tài liệu, mỗi lần chạy ví dụ mẫu tốn từ khoảng 0,00004 đến 0,0003 USD; giá thực tế xem trên trang nhà cung cấp.

Có cần mạng không? Có. Mỗi bước đều gọi mô hình qua Internet. Riêng bộ kiểm thử ở mục 4 chạy được không cần khóa API.

Dữ liệu của tôi có bị gửi đi đâu không? Mục tiêu và thông tin quan sát của mỗi bước được gửi tới nhà cung cấp mô hình mà bạn chọn để lấy câu trả lời. Đừng đưa dữ liệu nhạy cảm vào khi thử nghiệm.

Máy yếu có chạy được không? Bản thân công cụ rất nhẹ, chỉ cần hai thư viện Python nhỏ, vì mô hình chạy ở phía nhà cung cấp chứ không chạy trên máy bạn.

Nó làm được việc phức tạp không? Tác giả nói rõ giới hạn: các phép đo trong tài liệu chỉ chứng minh những nhiệm vụ nhỏ, rõ ràng. Họ không cam kết kết quả tương tự với tình huống mơ hồ, phép tính, ngày tháng hay ngữ cảnh dài có nhiều thông tin thừa.