# Antigravity CLI Use

[![CI](https://github.com/wanzdoan/antigravity-cli-use/actions/workflows/ci.yml/badge.svg)](https://github.com/wanzdoan/antigravity-cli-use/actions/workflows/ci.yml)

MCP server và skill giúp AI điều phối giao việc cho các tài khoản Antigravity phụ: chạy song song, quản lý phụ thuộc, tiếp tục hội thoại và thu kết quả gọn.

**AI tự lập kế hoạch theo yêu cầu; MCP thực thi.** Không cần người dùng viết workflow JSON, không có pipeline hay mẫu website làm sẵn.

> Dự án cộng đồng, không phải sản phẩm chính thức của Google hoặc OpenAI. Chỉ sử dụng tài khoản bạn được phép dùng và tuân thủ điều khoản của nhà cung cấp. Không tự tạo tài khoản hay vượt quota.

## Có gì?

- Worker được xác minh email đăng nhập từ log trước khi khôi phục credential chính; không dựa vào một khoảng sleep cố định.
- Một worker hoạt động trên mỗi tài khoản; phần việc còn lại được xếp hàng theo tài khoản/quota khả dụng.
- DAG với `depends_on`, phân tích critical path và ưu tiên nhánh dài.
- Khai báo file đọc/ghi để điều phối worker không giẫm lên nhau.
- Job bất đồng bộ, warm session nhiều lượt, kết quả giới hạn độ dài và thống kê token theo tài khoản.
- `wait_workflow` chờ theo sự kiện với revision cursor. **Chưa có cầu nối tự đánh thức AI sau khi lượt chat kết thúc.**
- Skill tự nhận diện các yêu cầu “Antigravity CLI”, “agy”, “agy-worker-pool”, “tài khoản phụ” để chọn MCP đã kết nối.

## Yêu cầu

- Node.js **20+**, Git; Codex CLI nếu dùng lệnh setup Codex.
- Antigravity CLI `agy` đã cài và đăng nhập. Baseline đã thử: **1.3.5**. Xem [hướng dẫn chính thức](https://www.antigravity.google/docs/cli/install/).
- Account vault riêng đã có tài khoản và session hợp lệ. Không có tài khoản/credential trong repo. Xem [chuẩn bị vault](docs/SETUP.md#account-vault).
- Windows x64: **.NET Runtime 10** cho helper đi kèm; chỉ cần SDK 10 nếu tự build helper.
- Adapter macOS/Linux đã viết nhưng **chưa kiểm chứng với tài khoản thật** trên hai nền tảng đó; xem [giới hạn](#giới-hạn).

## Cài nhanh — Windows / Codex

Chạy trong PowerShell, ở nơi bạn muốn lưu công cụ:

```powershell
git clone https://github.com/wanzdoan/antigravity-cli-use.git
cd antigravity-cli-use
npm ci
npm run setup:codex
```

Lệnh setup cài skill vào `$CODEX_HOME/skills` hoặc `~/.codex/skills`, rồi đăng ký MCP bằng đường dẫn tuyệt đối của Node và repo vừa clone. Không đổi workspace của task và không sửa cấu hình MCP khác. Nếu skill có chỉnh sửa riêng hoặc đăng ký cũ trỏ sang nơi khác, setup sẽ dừng và hướng dẫn cách xử lý.

Khởi động lại/kết nối lại Codex **sau khi công việc đang chạy đã kết thúc**. Đường dẫn đăng ký đúng không có nghĩa tiến trình MCP cũ đã được nạp lại.

Kiểm tra bằng CLI:

```powershell
node src/cli.js health
node src/cli.js accounts
node src/cli.js models
```

Trong Codex, yêu cầu gọi `health_check`: phiên bản kết nối phải khớp `package.json`. Danh sách account/model không đồng nghĩa một worker đã thực thi thành công; cần chạy một task nhỏ trong workspace thử nghiệm để xác nhận.

Hướng dẫn [cài thủ công, client khác, cập nhật và gỡ cài đặt](docs/SETUP.md).

## Cách dùng

Ví dụ prompt:

```text
Dùng Antigravity CLI qua MCP để kiểm tra dự án hiện tại và bổ sung bộ test
cho phần xử lý dữ liệu. Bạn tự xác định các trường hợp biên, chia việc cho
tài khoản phụ khi hữu ích, chạy test và sửa lỗi nằm trong phạm vi yêu cầu.
Không sửa file không liên quan. Báo lại những gì đã xác minh và job ID.
```

Hoặc gọi skill rõ ràng:

```text
$antigravity-cli-use Dùng các tài khoản phụ thực hiện yêu cầu sau: ...
```

Skill hỗ trợ chọn đúng công cụ, không bảo đảm mọi model sẽ tự chọn đúng trong mọi tình huống. Nếu không thấy skill/tool, kiểm tra kết nối rồi restart client; không cần đi tìm một CLI khác trên web.

### Workspace, file và giám sát

- AI phải truyền **cwd tuyệt đối của phiên gọi** trong `workspace`; không dùng đường dẫn cài MCP làm nơi tạo sản phẩm. Cùng một MCP có thể phục vụ task ở các project khác nhau.
- `write_paths` / `read_paths` là đường dẫn cụ thể, không phải glob. Bỏ `write_paths` nghĩa là giữ độc quyền toàn workspace; `[]` khai báo read-only hợp tác.
- AI tự tạo `depends_on` cho quan hệ đầu vào/đầu ra thật. Scheduler tự chạy các task đủ điều kiện; không cần AI khởi động lại từng stage.
- `wait_workflow`: mặc định 60 giây, tối đa 300 giây nếu timeout client cho phép. Hết thời gian chờ không phải job thất bại. Chờ lại cùng ID với revision mới.
- Resource notification là tùy chọn của client, không phải push tự đánh thức mọi AI. Cơ chế chờ hiện tại được giữ nguyên.

## Tài liệu

- [Setup, account vault, cập nhật và gỡ cài đặt](docs/SETUP.md)
- [Danh sách tool và cấu hình](docs/REFERENCE.md)
- [Latency, concurrency và file ownership](docs/PERFORMANCE-AND-CONCURRENCY.md)
- [Mô hình bảo mật và dữ liệu riêng](SECURITY.md)
- [Skill](skills/antigravity-cli-use/SKILL.md)
- [Bằng chứng thiết kế](docs/RESEARCH.md) · [Kiểm chứng phát hành](docs/COMPLETION-AUDIT.md)

## Phát triển

```powershell
npm ci
npm test
npm run check
npm audit --omit=dev
npm pack --dry-run
```

Test tự động dùng dữ liệu giả và thư mục tạm, không cần tài khoản thật. Script `scripts/validate-parallel-workflow.mjs` là smoke test **chủ động tiêu quota**, chỉ chạy khi bạn muốn thử worker thật; không phải template sản phẩm.

Build lại helper Windows từ source:

```powershell
npm run build:helper:windows
```

## Giới hạn

- Windows x64 là môi trường đã thử end-to-end. macOS cần `security`; Linux cần `secret-tool` và một Secret Service khả dụng. CI không thay thế kiểm chứng keyring/tài khoản thật.
- CLI có thể thay đổi định dạng log xác thực. Không xác minh được đúng tài khoản thì worker dừng, không giả định thành công.
- File reservation điều phối khai báo, không chặn worker ở mức hệ điều hành. Worker vi phạm scope hoặc editor bên ngoài vẫn có thể gây xung đột.
- Ưu tiên một scheduler sống lâu cho mỗi state directory; lịch sử job dạng file chưa phải cơ sở dữ liệu phân tán.
- Không hứa thời gian hoàn thành cố định; startup, quota, model và phụ thuộc thật vẫn ảnh hưởng latency.

MIT License. Không kèm Antigravity CLI, tài khoản hay token.