1. Giới thiệu
Lập trình theo cảm hứng (sử dụng các tác nhân AI để viết mã từ câu lệnh bằng ngôn ngữ tự nhiên) chuyển vai trò của nhà phát triển từ tác giả sang người điều phối và đánh giá. Chúng ta dựa vào việc chuẩn bị bối cảnh hoàn hảo và tin tưởng các tác nhân AI sẽ làm mọi việc cho chúng ta, có thể bắt đầu từ việc soạn thảo tài liệu đặc tả cho đến khi đảm bảo mã đáp ứng mọi yêu cầu. Rủi ro: trong các chu kỳ lặp lại nhanh, mã chức năng được phê duyệt mà không được xem xét kỹ lưỡng về bảo mật. Theo mặc định, các tác nhân hiện đại thường tạo ra mã bảo mật, nhưng "thường" không phải là "luôn luôn", và các lỗ hổng tích luỹ sẽ lọt qua quy trình xem xét thủ công.
Lớp học lập trình này giải quyết những vấn đề đó bằng cách hướng dẫn 2 phương pháp sử dụng Antigravity làm người đánh giá: tương tác trong quá trình phát triển bằng CLI (bạn đánh giá, sửa rồi PR) và tự động trong Tích hợp liên tục bằng SDK (tác nhân đánh giá mọi Yêu cầu kéo và đăng kết quả dưới dạng bình luận)
Nội dung bạn sẽ khám phá
Bạn đã tạo mã rung cho một ứng dụng CRM về khách hàng tiềm năng – một tác nhân AI đã xây dựng toàn bộ ngăn xếp cho bạn: phần phụ trợ Express, cơ sở dữ liệu SQLite, phần giao diện người dùng React. Cách này hiệu quả. Sau đó, bạn yêu cầu nhân viên hỗ trợ thêm hai tính năng mới: chức năng tìm kiếm khách hàng tiềm năng và chức năng nhập/xuất hàng loạt cùng với số liệu thống kê của quản trị viên. Cả hai tác nhân đều hoạt động nhanh chóng. Mã chạy, các tính năng hoạt động và các PR đã sẵn sàng.
Nhưng vấn đề là bạn không viết mã này. Bạn đã phê duyệt yêu cầu này. Làm cách nào để biết điểm cuối tìm kiếm không dễ bị tấn công bằng cách chèn SQL? Làm cách nào để biết tuyến quản trị không có mật khẩu được mã hoá cứng? Bạn không cần làm vậy. Việc đọc từng dòng mã do AI tạo sẽ làm mất đi lợi thế về tốc độ mà bạn đã có được khi lập trình theo cảm hứng.
Lớp học lập trình này cung cấp cho bạn 2 cách để giải quyết vấn đề này:
- Trường hợp 1 – Đánh giá tương tác: Kiểm tra một nhánh tính năng có lỗ hổng, sử dụng Antigravity CLI được tăng cường bằng các kỹ năng của tác nhân để xem xét điểm khác biệt, khắc phục các vấn đề và tạo một PR rõ ràng.
- Trường hợp 2 – Quy trình xem xét tự động: Thiết lập một GitHub Action dựa trên Antigravity SDK để tự động đánh giá các yêu cầu kéo, đăng các kết quả có cấu trúc dưới dạng bình luận và phản hồi khi nhà phát triển đặt câu hỏi tiếp theo về quy trình xem xét.
Kiến thức bạn sẽ học được
- Cách lập trình theo cảm hứng có thể tạo ra rủi ro bảo mật và lý do quy trình xem xét tự động phát hiện được những điểm mà quy trình đánh giá thủ công bỏ sót
- Cách cài đặt và sử dụng các kỹ năng của tác nhân do cộng đồng duy trì để cung cấp cho Antigravity CLI kiến thức chuyên sâu về bảo mật và xem xét mã
- Cách sử dụng CLI một cách tương tác để xem xét điểm khác biệt của một nhánh tính năng, khắc phục các lỗ hổng bảo mật và tạo một PR rõ ràng
- Cách sử dụng Antigravity SDK để tạo một tác nhân đánh giá mã chỉ đọc bằng các chính sách an toàn khai báo và các lệnh gọi vòng đời
- Cách triển khai tác nhân đánh giá dưới dạng một Thao tác trên GitHub để đánh giá các yêu cầu kéo và đăng kết quả dưới dạng bình luận về yêu cầu kéo
Điều kiện tiên quyết
- Tài khoản Google Cloud
- Tài khoản GitHub
- Hiểu biết cơ bản về Terminal, Version Control và CI/CD
2. Thiết lập môi trường
Bước này phân nhánh kho lưu trữ ứng dụng CRM về khách hàng tiềm năng, sao chép kho lưu trữ đó trong Cloud Shell, thiết lập Antigravity CLI và xác thực.
Phát triển nhánh kho lưu trữ
Bạn cần có bản sao của kho lưu trữ vì bạn sẽ đẩy các cam kết và tạo yêu cầu kéo bằng GitHub Actions.
Chuyển đến kho lưu trữ sau
Sau đó, nhấp vào Phân nhánh. Trên trang tạo nhánh rẽ, hãy bỏ đánh dấu hộp đánh dấu "Chỉ sao chép nhánh main" – bạn cần các nhánh tính năng khác (feature/lead-search và feature/bulk-operations) có trong nhánh rẽ của mình.
Mở Cloud Shell
Mở Cloud Shell trong trình duyệt. Cloud Shell cung cấp một môi trường được định cấu hình sẵn với tất cả các công cụ bạn cần cho lớp học lập trình này. Nhấp vào Uỷ quyền khi được nhắc
Sau đó, nhấp vào "View" (Xem) -> "Terminal" (Thiết bị đầu cuối) để mở thiết bị đầu cuối.Giao diện của bạn sẽ trông tương tự như thế này
Đây sẽ là giao diện chính của chúng ta, IDE ở trên cùng, thiết bị đầu cuối ở dưới cùng
Xác thực bằng GitHub
Theo mặc định, Cloud Shell không có thông tin đăng nhập GitHub được định cấu hình theo mặc định, tuy nhiên, Cloud Shell đã cài đặt sẵn CLI gh. Thiết lập quy trình xác thực để bạn có thể đẩy các cam kết và tạo yêu cầu kéo sau này:
gh auth login
Chọn Github.com
Chọn HTTPS ( hoặc nếu bạn đã quen với cơ chế khác, hãy chọn cơ chế đó)
Sau đó, hãy chọn Y
Sau đó, hãy chọn Login with a web browser
**,**Bạn sẽ được yêu cầu sao chép mã dùng một lần và nhập mã đó khi mở trang đăng nhập trong trình duyệt. Bạn có thể Ctrl + Click vào URL trong thiết bị đầu cuối để mở URL https://github.com/login/device. Bạn sẽ được yêu cầu chọn tài khoản bạn muốn đăng nhập và nhập mã.
Sau đó, quay lại trang bảng điều khiển Cloud Shell và bạn sẽ thấy đầu ra của thiết bị đầu cuối như sau
✓ Authentication complete. - gh config set -h github.com git_protocol https ✓ Configured git protocol ! Authentication credentials saved in plain text ✓ Logged in as alphinside-joonix
Điều này có nghĩa là bạn đã thiết lập thành công quy trình xác thực tài khoản Github trên Cloud Shell.
Sao chép kho lưu trữ đã phân nhánh
Tiếp theo, hãy sao chép kho lưu trữ đã phân nhánh của bạn. Thay thế <YOUR_GITHUB_USERNAME> bằng tên người dùng GitHub của bạn:
git clone https://github.com/<YOUR_GITHUB_USERNAME>/leads-crm-app-demo.git
cloudshell workspace leads-crm-app-demo && cd leads-crm-app-demo
Xác minh các nhánh tính năng
Sau đó, hãy xác minh rằng cả hai nhánh tính năng có lỗ hổng bảo mật được tạo sẵn đều có trong kho lưu trữ từ xa:
git branch -a | grep feature/
Bạn sẽ thấy kết quả sau
remotes/origin/feature/bulk-operations remotes/origin/feature/bulk-operations-solution remotes/origin/feature/email-composer remotes/origin/feature/lead-search
Xác minh Antigravity CLI
Tiếp theo, hãy xác minh rằng Antigravity CLI đã được cài đặt sẵn trong Cloud Shell. Xác minh rằng tính năng này có sẵn:
agy --version
Bạn sẽ thấy phiên bản của Antigravity CLI đã cài đặt, ví dụ: 1.0.13
Giờ đây, nếu chưa xác thực Antigravity CLI, bạn có thể truy cập vào lớp học lập trình này để xem quy trình xác thực chi tiết hơn.
Tại thời điểm này, bạn phải có những thông tin sau:
- kho lưu trữ được phân nhánh đã sao chép
- cả hai nhánh tính năng đều hiển thị
- Lệnh
agycó sẵn và đã được xác thực
3. Vấn đề – Lỗ hổng bảo mật ẩn trong các tính năng được mã hoá bằng rung
Sau đây là tình huống: một đồng nghiệp đã sử dụng một tác nhân AI để thêm 2 tính năng vào ứng dụng CRM Khách hàng tiềm năng – chức năng tìm kiếm khách hàng tiềm năng và các thao tác nhập/xuất hàng loạt. Cả hai tính năng đều hoạt động. Cả hai đều được vận chuyển nhanh mà không cần kiểm tra bảo mật. Bạn sẽ xem xét cả hai nhánh trước khi chúng hợp nhất – một nhánh tương tác với CLI, một nhánh tự động với GitHub Action.
Kiểm tra nhánh tính năng đầu tiên
Xem điểm khác biệt trên feature/lead-search:
git diff main...origin/feature/lead-search
Nhánh này thêm một điểm cuối tìm kiếm. Quét điểm khác biệt – bạn sẽ phát hiện ra các vấn đề như phép nối chuỗi trong truy vấn SQL, thiếu quy trình xác thực thông tin đầu vào, nhật ký gỡ lỗi làm rò rỉ thông tin chi tiết về truy vấn và thông báo lỗi thô được hiển thị cho ứng dụng.
+ app.get("/api/leads/search", (req, res) => {
+ const query = req.query.q as string;
+
+ if (!query) {
+ return res.status(400).json({ error: "Search query is required" });
+ }
...
Kiểm tra nhánh tính năng thứ hai
git diff main...origin/feature/bulk-operations
Nhánh này bổ sung các điểm cuối nhập/xuất hàng loạt và một trang tổng quan về số liệu thống kê của quản trị viên. Các lỗ hổng ở đây bao gồm thông tin đăng nhập quản trị viên được cố định giá trị trong mã, các điểm cuối quản trị viên chưa được xác thực, không có quy trình xác thực thông tin đầu vào khi nhập hàng loạt và rủi ro về path traversal trong quá trình xử lý tên tệp xuất.
...
+ const ADMIN_PASSWORD = "admin123";
+
+ app.post("/api/admin/import", (req, res) => {
+ const { password, leads } = req.body;
+
+ if (password !== ADMIN_PASSWORD) {
+ return res.status(401).json({ error: "Invalid admin password" });
+ }
...
Cả hai nhánh đều thêm các tính năng chức năng. Cả hai đều có vấn đề về bảo mật. Câu hỏi đặt ra là làm cách nào để phát hiện các lỗi này – theo cách thủ công bằng CLI (Trường hợp 1) hoặc tự động bằng một Thao tác trên GitHub (Trường hợp 2).
4. Trường hợp 1 : Đánh giá tương tác bằng Antigravity CLI
Việc xem xét CLI tương tác có giá trị nhất ngay sau một phiên mã hoá theo cảm hứng, xem xét mã bạn vừa viết hoặc xem xét yêu cầu kéo của đồng đội. Nếu chúng ta đang nói về việc mã hoá theo cảm xúc, thì một tác nhân AI đã tạo mã tính năng của bạn một cách nhanh chóng – nhưng bạn có thể không hiểu đầy đủ từng dòng mà tác nhân này tạo ra, đồng thời tác nhân có thể được tối ưu hoá cho chức năng chứ không nhất thiết là bảo mật, tuỳ thuộc vào cấu hình ngữ cảnh trong khi bạn phát triển tính năng.
Trong trường hợp này, chúng ta có những đoạn mã có lỗ hổng bảo mật và sẽ sử dụng Antigravity CLI có kỹ năng đánh giá mã để đánh giá mã một cách tương tác. Mô hình tác nhân đánh giá tác nhân này phát hiện các lỗ hổng bảo mật khi vai trò của nhà phát triển chuyển từ viết mã sang phê duyệt mã do AI tạo. Quy tắc này cũng áp dụng khi xem xét mã do bạn tự viết theo cách thủ công hoặc nhánh của đồng đội trước khi mã đó trải qua quy trình CI. Bạn kiểm soát cuộc trò chuyện: yêu cầu tác nhân tập trung vào các tệp cụ thể, tìm hiểu sâu hơn về một phát hiện hoặc áp dụng các bản sửa lỗi ngay lập tức.
Nếu không có kỹ năng của tác nhân, Antigravity CLI vẫn có thể xem xét mã, nhưng công cụ này dựa vào kiến thức chung về hoạt động huấn luyện, có thể bỏ lỡ các mẫu dành riêng cho miền hoặc áp dụng tiêu chí đánh giá không nhất quán trong các phiên. Kỹ năng của nhân viên hỗ trợ cung cấp cho nhân viên một sổ tay hướng dẫn có cấu trúc: đánh giá theo 5 khía cạnh để đảm bảo chất lượng, gắn nhãn mức độ nghiêm trọng để ưu tiên. Quy trình đánh giá trở nên nhất quán và kỹ lưỡng bất kể bạn diễn đạt câu lệnh như thế nào.
Bước này sử dụng Antigravity CLI với các kỹ năng của tác nhân để xem xét nhánh feature/lead-search, khắc phục các lỗ hổng và tạo một PR sạch.
Kiểm tra nhánh tính năng
Trước tiên, hãy thay đổi nhánh thành nhánh Trường hợp 1:
git checkout feature/lead-search
Tiếp theo, hãy nâng cấp Antigravity CLI bằng các kỹ năng của tác nhân để xem xét
Kỹ năng của tác nhân là gì
Kỹ năng là các tệp markdown khai báo, giúp nhân viên hỗ trợ có được kiến thức chuyên môn. Sau khi được cài đặt, các tiện ích này sẽ trở thành lệnh gạch chéo (ví dụ: /code-review-and-quality). Hãy coi các tiện ích này như việc cung cấp cho một tác nhân đa năng sổ tay bảo mật của một kỹ sư cấp cao.
Các kỹ năng có thể chuyển đổi giữa các tác nhân (Antigravity, Claude Code, Cursor, v.v.) và có thể chia sẻ thông qua Git. Đối với Antigravity CLI, các kỹ năng của không gian làm việc (dự án/cục bộ) nằm trong .agents/skills/ ở gốc dự án. Trong khi đó, các kỹ năng chung nằm trong ~/.gemini/config/skills/. Xem thêm trong tài liệu này
Để minh hoạ các khả năng của kỹ năng tác nhân, lớp học lập trình này sẽ sử dụng kỹ năng xem xét mã từ addyosmani/agent-skills:
code-review-and-quality– Đánh giá theo 5 khía cạnh (tính chính xác, khả năng đọc, cấu trúc, tính bảo mật, hiệu suất) kèm theo nhãn mức độ nghiêm trọng.
Cài đặt kỹ năng của tác nhân xem xét mã
Theo mặc định, bằng cách sử dụng lệnh bên dưới, kỹ năng sẽ được cài đặt vào .agents/skills/ trong thư mục đang hoạt động hiện tại – một bản cài đặt ở cấp không gian làm việc. Điều này có nghĩa là các tệp này sẽ trở thành một phần của kho lưu trữ và có thể được xác nhận cùng với mã của bạn, vì vậy, mọi nhà phát triển (và quy trình CI) trong dự án đều tự động nhận được các kỹ năng đánh giá giống nhau.
npx skills add addyosmani/agent-skills --skill code-review-and-quality -y
Dưới đây là kỹ năng chi tiết mà bạn có thể kiểm tra trên tệp .agents/skills/code-review-and-quality/SKILL.md:
name: code-review-and-quality description: Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch.
Các chức năng chính:
- Đánh giá theo 5 khía cạnh: tính chính xác, khả năng đọc, cấu trúc, tính bảo mật và hiệu suất
- Gắn nhãn cho các phát hiện theo mức độ nghiêm trọng để bạn có thể khắc phục các vấn đề nghiêm trọng trước
- Áp dụng tiêu chuẩn phê duyệt: "phê duyệt khi chắc chắn cải thiện trạng thái tổng thể của mã, ngay cả khi mã đó chưa hoàn hảo"
Giờ thì chúng ta đã sẵn sàng thực hiện một số thao tác. Hãy xác minh kỹ năng trong Antigravity CLI
Ra mắt AGY và xác minh kỹ năng
Hãy chạy Antigravity CLI
agy --dangerously-skip-permissions
Sau đó, hãy chạy lệnh sau
/skills
Bạn sẽ thấy 2 kỹ năng xuất hiện như thế này trong phần Workspace kỹ năng
Chạy quy trình xem xét mã nguồn của chênh lệch tính năng
Gọi kỹ năng bảo mật và yêu cầu kỹ năng này xem xét chi nhánh của bạn. Nhập câu lệnh sau:
Review the git diff between main and my current branch. Find any issues based on the agent skills that are appropriate for this. Write the findings and plan to fix them to code_review.md in the current working directory. Do not apply fixes yet.
Trợ lý sẽ phát hiện kỹ năng code-review-and-quality phù hợp và tự động kích hoạt kỹ năng đó. Công cụ này đọc điểm khác biệt, xác định các lỗ hổng và ghi lại các phát hiện cùng với kế hoạch khắc phục đề xuất vào code_review.md.
Sau khi quá trình quét hoàn tất, bạn sẽ thấy tệp code_review.md được tạo trong thư mục làm việc và có thể kiểm tra tệp đó trong trình chỉnh sửa
Xem xét từng phát hiện và giải pháp đề xuất. Sau khi bạn hài lòng với kế hoạch, hãy yêu cầu nhân viên hỗ trợ áp dụng kế hoạch đó:
Apply the proposed fixes from code_review.md
Tác nhân sẽ đọc kế hoạch và áp dụng từng bản sửa lỗi đã lên kế hoạch cho các tệp nguồn.
Giờ đây, nếu muốn, bạn có thể kiểm tra xem ứng dụng có chạy đúng cách hay không sau khi khắc phục bằng cách cài đặt các phần phụ thuộc và kích hoạt ứng dụng
npm install
npm run dev
Ứng dụng sẽ chạy đúng cách. Nếu không, bạn có thể lặp lại và yêu cầu Antigravity CLI sửa lỗi
Commit và tạo PR
Giờ đây, bạn có thể đẩy các thay đổi vào kho lưu trữ của riêng mình nếu muốn. Trước khi chuyển sang trường hợp tiếp theo, trước tiên, hãy xác nhận các thay đổi vào nhánh hiện tại.
Trước tiên, bạn cần định cấu hình danh tính Git (thay thế bằng tên và email của riêng bạn) nếu chưa làm:
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
Sau đó, hãy xác nhận các thay đổi
git add .
git commit -m "fix: address security vulnerabilities in lead search feature"
Giờ đây, bạn đã sử dụng Antigravity CLI làm trình đánh giá tương tác. Các kỹ năng này mang đến cho mô hình phương pháp luận có cấu trúc – quy trình xem xét mã theo 5 trục. Điều này có hiệu quả khi bạn là nhà phát triển xem xét mã do AI tạo, mã của riêng bạn hoặc đóng góp của đồng đội. Trong phần tiếp theo, chúng ta sẽ tự động hoá toàn bộ quy trình này để biến nó thành một quy trình tự động có thể mở rộng trong kho lưu trữ mã của bạn bằng cách sử dụng Github làm ví dụ
5. Trường hợp 2 : Đánh giá tự động bằng Antigravity SDK – Phần 1 ( Tạo tác nhân)
Bước này sẽ tạo một tác nhân quy trình xem xét tự động bằng Antigravity SDK, triển khai tác nhân đó dưới dạng một Thao tác trên GitHub và kiểm thử tác nhân đó dựa trên nhánh tính năng thứ hai. Tác nhân này xem xét các yêu cầu kéo theo yêu cầu và đăng kết quả dưới dạng bình luận về yêu cầu kéo.
Lý do cần có quy trình xem xét tự động
Quy trình xem xét CLI tương tác (Trường hợp 1) hoạt động khi nhà phát triển chủ động xem xét. Các nhóm cần một quy trình xem xét tự động chạy trên mọi yêu cầu kéo – phát hiện vấn đề từ mọi cộng tác viên, mọi công cụ, mọi lúc. Antigravity SDK (google-antigravity) cung cấp cùng một thời gian chạy tác nhân như CLI, dưới dạng một thư viện Python. Các chính sách và lệnh gọi được định cấu hình trong mã.
GitHub Actions là nền tảng Tích hợp liên tục/Phát triển liên tục (CI/CD) tích hợp sẵn của GitHub. Nó chạy quy trình công việc (các tập lệnh tự động được xác định trong YAML) để phản hồi các sự kiện của kho lưu trữ, chẳng hạn như mở một yêu cầu kéo, đẩy một cam kết hoặc đăng một bình luận. Quy trình chạy trên máy ảo do GitHub lưu trữ và có quyền truy cập vào mã kho lưu trữ. Trong trường hợp này, bạn sử dụng một GitHub Action để chạy tác nhân đánh giá bảo mật mỗi khi tạo một PR.
Sau đây là cách hoạt động của quy trình xem xét tự động:
Antigravity SDK ( google-antigravity) cung cấp cùng một thời gian chạy tác nhân như CLI, dưới dạng một thư viện Python. Bạn viết một tập lệnh Python để định cấu hình tác nhân bằng các chính sách và hook, kích hoạt tập lệnh đó trong một Thao tác trên GitHub và đăng kết quả dưới dạng một bình luận về yêu cầu kéo.
Lấy khoá Gemini API
Trước khi bắt đầu, chúng ta sẽ cần Khoá Gemini API để Antigravity SDK sử dụng. Chuyển đến Khoá API Google AI Studio rồi tạo một khoá API. Bạn có thể sao chép khoá API bất cứ khi nào cần
Khoá này sẽ được dùng khi chạy tác nhân đánh giá cục bộ và sau này sẽ được dùng làm khoá bí mật của GitHub Actions
Phần A: Xây dựng tác nhân đánh giá
Bây giờ, đối với Trường hợp 2, hãy chuyển thư mục làm việc hiện tại sang nhánh feature/bulk-operations:
git checkout feature/bulk-operations
Đây là nhánh tính năng thứ hai trong tình huống này – nhánh này thêm các điểm cuối nhập/xuất hàng loạt và một trang tổng quan về số liệu thống kê của quản trị viên vào ứng dụng CRM.
Thiết lập dự án Python
Antigravity SDK hiện chỉ có trong Python, do đó, chúng ta sẽ cần một môi trường Python để phát triển SDK này. Chúng ta sẽ sử dụng uv cho trình quản lý dự án Python. uv là một trình quản lý dự án và gói Python nhanh được viết bằng Rust ( docs). Lớp học lập trình này sử dụng nó để tăng tốc độ và đơn giản hoá. Nếu bạn sử dụng cloudshell cho hướng dẫn này, thì công cụ này đã được cài đặt sẵn trong phiên bản. Hãy xem hướng dẫn này nếu bạn muốn cài đặt cho ngôn ngữ của mình
Khởi động một dự án Python cho tác nhân đánh giá bằng cách sử dụng uv:
uv init code_review_agent
uv add --project code_review_agent google-antigravity==0.1.7
Thao tác này sẽ tạo một thư mục mới code_review_agent chứa các tệp tác nhân xem xét mã cần thiết của chúng ta.
Cài đặt các kỹ năng đánh giá
Tác nhân đánh giá cần có các kỹ năng bảo mật và xem xét mã tương tự như trong Trường hợp 1. Cài đặt các thành phần này vào code_review_agent/skills/ để tác nhân SDK tải chúng vào thời gian chạy:
npx skills add addyosmani/agent-skills --skill code-review-and-quality -y
cp -r .agents/skills code_review_agent/skills
Tạo nhân viên đánh giá
Giờ thì hãy tạo code_review_agent/review_agent.py . Chạy lệnh sau
cloudshell edit code_review_agent/review_agent.py
Sau đó, sao chép nội dung sau vào tệp
#!/usr/bin/env python3
import asyncio
import json
import os
import sys
import pydantic
from google.antigravity import Agent, LocalAgentConfig, CapabilitiesConfig
from google.antigravity.hooks import hooks, policy
from google.antigravity import types
class Finding(pydantic.BaseModel):
file: str
line: int
severity: str
category: str
description: str
proposed_fix: str = ""
class ReviewResult(pydantic.BaseModel):
findings: list[Finding]
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
OUTPUT_FILE = "code_review.md"
SKILLS_PATHS = [
os.path.join(SCRIPT_DIR, "skills", "code-review-and-quality"),
]
review_policies = [
policy.deny_all(),
policy.allow("view_file"),
policy.allow("list_directory"),
policy.allow("search_directory"),
policy.allow("find_file"),
policy.allow("run_command"),
policy.allow("finish"),
]
@hooks.post_tool_call
async def log_tool_results(data: types.ToolResult):
result_str = str(data.result) if data.result else ""
preview = result_str[:200] + "..." if len(result_str) > 200 else result_str
print(f"[audit] tool={data.name} result_len={len(result_str)} error={data.error} preview={preview}", flush=True)
@hooks.pre_tool_call_decide
async def enforce_safe_tools(data: types.ToolCall) -> types.HookResult:
print(f"[audit] calling tool={data.name} args_keys={list(data.args.keys())}", flush=True)
if data.name == "run_command":
cmd = str(data.args.get("CommandLine", ""))
if not cmd.startswith("git "):
return types.HookResult(
allow=False,
message=f"Only git commands are allowed. Blocked: {cmd}"
)
return types.HookResult(allow=True)
async def review_code(target_dir: str) -> dict:
prompt = f"""Run `git diff main...HEAD -- ':!.github' ':!code_review_agent'` in {target_dir} to get the changes on this branch.
Review ONLY the changed code for security vulnerabilities and code quality issues.
"""
config_kwargs = dict(
system_instructions=(
"You are a code review agent. "
"You review code diffs for vulnerabilities and quality issues using the loaded skills. "
"You can run git commands to inspect the diff. "
"You NEVER modify files."
),
response_schema=ReviewResult,
skills_paths=SKILLS_PATHS,
policies=review_policies,
hooks=[log_tool_results, enforce_safe_tools],
)
if os.environ.get("GEMINI_API_KEY"):
config_kwargs["api_key"] = os.environ["GEMINI_API_KEY"]
else:
config_kwargs["vertex"] = True
config_kwargs["project"] = os.environ.get("GOOGLE_CLOUD_PROJECT")
config_kwargs["location"] = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
config = LocalAgentConfig(**config_kwargs)
async with Agent(config) as agent:
response = await agent.chat(prompt)
last_step = -1
final_text_chunks = []
async for chunk in response.chunks:
if isinstance(chunk, types.ToolCall):
final_text_chunks.clear()
if hasattr(chunk, "text") and hasattr(chunk, "step_index"):
if chunk.step_index != last_step:
final_text_chunks.clear()
last_step = chunk.step_index
final_text_chunks.append(chunk.text)
final_text = "".join(final_text_chunks)
if final_text:
print(final_text)
data = await response.structured_output()
if data and "findings" in data:
return {"findings": data["findings"]}
try:
parsed = json.loads(final_text)
if isinstance(parsed, list):
return {"findings": parsed}
if isinstance(parsed, dict) and "findings" in parsed:
return {"findings": parsed["findings"]}
except json.JSONDecodeError:
pass
return {"findings": final_text}
SEVERITY_EMOJI = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🔵"}
def format_markdown(result: dict) -> str:
findings = result.get("findings", [])
if isinstance(findings, str):
return f"## AI Security Review\n\n{findings}\n"
if not findings:
return "## AI Security Review\n\nNo security issues found.\n"
lines = ["## AI Security Review\n"]
for f in findings:
emoji = SEVERITY_EMOJI.get(f.get("severity", "").lower(), "⚪")
lines.append(f"### {emoji} [{f.get('severity', 'unknown').upper()}] {f.get('category', '')}\n")
lines.append(f"**{f.get('file', '')}:{f.get('line', '')}**\n")
lines.append(f"{f.get('description', '')}\n")
proposed_fix = f.get('proposed_fix', '')
if proposed_fix:
lines.append(f"**Proposed fix:** {proposed_fix}\n")
lines.append("---\n*Powered by Antigravity SDK*")
return "\n".join(lines)
if __name__ == "__main__":
target = sys.argv[1] if len(sys.argv) > 1 else "."
result = asyncio.run(review_code(target))
markdown = format_markdown(result)
with open(OUTPUT_FILE, "w") as f:
f.write(markdown)
print(f"Review written to {OUTPUT_FILE}")
print(json.dumps(result, indent=2))
Xem xét các quyết định quan trọng về thiết kế trong tác nhân này:
- Chính sách từ chối theo mặc định:
policy.deny_all()chặn mọi thứ, sau đó chỉ cho phép các công cụ đọc tệp mở vàrun_command(đối với git). - Thực thi ở hai lớp: các chính sách hạn chế ở cấp khung và lệnh gọi
enforce_safe_toolscung cấp lớp thứ hai – chỉ cho phép các lệnhgitthông quarun_command. - Phạm vi khác biệt của Git: tác nhân chạy
git diff main...HEADđể chỉ xem xét mã đã thay đổi chứ không phải toàn bộ cơ sở mã. - Đầu ra có cấu trúc với phương án dự phòng:
response_schema=ReviewResultthực thi cấu trúc JSON thông qua công cụ hoàn tất của SDK. Nếu không phân tích cú pháp được, chuỗi dự phòng sẽ thử phân tích cú pháptext()dưới dạng JSON, sau đó trả về văn bản thô. - Xác thực dự phòng: sử dụng
GEMINI_API_KEYnếu có, nếu không thì sẽ dự phòng cho Vertex AI thông qua Thông tin xác thực mặc định của ứng dụng. - Đầu ra tệp: ghi các kết quả được định dạng bằng markdown vào
code_review.md– GitHub Action sẽ đọc tệp này và đăng dưới dạng nhận xét PR sau này
Kiểm thử tác nhân đánh giá
Kiểm thử từ thư mục gốc của dự án. SDK sẽ đọc GEMINI_API_KEY từ môi trường, do đó, hãy đặt khoá trong môi trường
export GEMINI_API_KEY=YOUR_API_KEY
Sau đó, hãy chạy lệnh sau để chạy cục bộ
uv run --project code_review_agent code_review_agent/review_agent.py .
Trong khi chạy, công cụ này sẽ cho thấy một số đầu ra của bảng điều khiển, giải thích những công cụ mà công cụ này hiện đang sử dụng. Bạn có thể nhận thấy điều này khi truy cập vào các kỹ năng của tác nhân security-and-hardening và code-review-and-quality
[audit] calling tool=view_file args_keys=['AbsolutePath', 'IsSkillFile'] [audit] tool=view_file result_len=47 error=None preview=Read security and hardening skill documentation [audit] calling tool=view_file args_keys=['AbsolutePath', 'IsSkillFile'] [audit] tool=view_file result_len=48 error=None preview=Read code review and quality skill documentation [audit] calling tool=run_command args_keys=['CommandLine', 'Cwd', 'WaitMsBeforeAsync'] ...
Tác nhân này chạy git diff main...HEAD, chỉ xem xét mã đã thay đổi, ghi các kết quả được định dạng vào code_review.md và in JSON có cấu trúc ra bảng điều khiển. Bạn có thể kiểm tra code_review.md đã viết trong trình chỉnh sửa như minh hoạ bên dưới
Thao tác này đã hoạt động cục bộ, giờ hãy chuyển sang phần tiếp theo. Tạo cấu hình Thao tác trên Github
6. Trường hợp 2 : Đánh giá tự động bằng Antigravity SDK – Phần 2 ( Định cấu hình các thao tác trên Github)
Trước khi bắt đầu, hãy xoá tệp code_review.md đã tạo trước đó (nếu có).
rm -f code_review.md
Bây giờ, chúng ta cần tạo tệp cấu hình YAML của Thao tác Github.
mkdir -p .github/workflows
cloudshell edit .github/workflows/code_review.yml
Sau đó, hãy thêm nội dung sau vào tệp
name: AI Code Security and Quality Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
container:
image: ghcr.io/astral-sh/uv:python3.12-bookworm
steps:
- name: Install git
run: apt-get update && apt-get install -y git
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run security review
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
run: |
git config --global --add safe.directory $GITHUB_WORKSPACE
uv run --project code_review_agent code_review_agent/review_agent.py .
- name: Post findings as PR comment
if: always()
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const body = fs.readFileSync('code_review.md', 'utf8');
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: body
});
Quy trình này sẽ tự động kích hoạt khi một yêu cầu kéo được mở hoặc cập nhật. Thao tác này kiểm tra nhánh PR có nhật ký git đầy đủ (cần thiết cho git diff main...HEAD), chạy tác nhân đánh giá để ghi các kết quả vào code_review.md và đăng nội dung tệp dưới dạng nhận xét PR.
Bây giờ, hãy xác nhận tất cả các thay đổi và đẩy chúng lên Github từ xa, chúng ta đã sẵn sàng kiểm thử tính năng tích hợp này
git add .
git commit -m "Add AI code security-quality review agent and GitHub Action"
git push origin feature/bulk-operations
7. Trường hợp 2 : Đánh giá tự động bằng Antigravity SDK – Phần 3 (Kiểm thử tính năng đánh giá mã tự động)
Bây giờ, chúng ta sẽ chuyển đến trang web https://github.com/<YOUR_GITHUB_USERNAME>/leads-crm-app-demo của kho lưu trữ được phân nhánh và nhấp vào Settings
Sau đó, trên bảng điều khiển bên trái, hãy tìm biểu tượng Secrets and variables rồi nhấp và chọn Actions
Sau đó, hãy nhấp vào New repository secret để định cấu hình khoá bí mật GEMINI_API_KEY
Sau đó, chọn Pull Request và tạo Pull Request (Yêu cầu kéo) mới từ nhánh feature/bulk_operations đến nhánh main của kho lưu trữ của riêng bạn
Sau khi yêu cầu kéo được tạo, yêu cầu đó sẽ chạy Github Actions mà bạn có thể kiểm tra trong trình đơn Checks hoặc gần nút Merge pull request
Bạn có thể nhấp vào Actions đang chạy để xem thông tin chi tiết và khi hoàn tất, Actions sẽ đăng kết quả đánh giá dưới dạng bình luận về Yêu cầu kéo như minh hoạ bên dưới
8. Tóm tắt
Xin chúc mừng!
Bạn đã xây dựng 2 quy trình xem xét mã hoàn chỉnh để phát hiện các lỗ hổng bảo mật trong các tính năng được lập trình theo cảm hứng:
- Trường hợp 1 (Tương tác): Antigravity CLI có các kỹ năng của tác nhân đã xem xét một nhánh tính năng khác biệt, xác định được lỗi chèn SQL và các lỗ hổng khác, khắc phục các lỗi đó theo mẫu OWASP và tạo ra một PR sạch.
- Trường hợp 2 (Tự động): Antigravity SDK hỗ trợ một GitHub Action tự động xem xét mọi PR, đăng các phát hiện bảo mật có cấu trúc dưới dạng bình luận PR.
Kiến thức bạn học được
- Cách lập trình theo cảm hứng tạo ra rủi ro bảo mật và lý do quy trình xem xét tự động phát hiện được những điểm mà quy trình đánh giá thủ công bỏ sót
- Cách cài đặt và sử dụng kỹ năng của tác nhân để cung cấp cho Antigravity CLI kiến thức chuyên môn về bảo mật có cấu trúc
- Cách xem xét một cách tương tác điểm khác biệt của nhánh tính năng, khắc phục vấn đề và tạo một PR rõ ràng
- Cách tạo một tác nhân đánh giá chỉ đọc bằng Antigravity SDK bằng cách sử dụng các chính sách từ chối theo mặc định và các lệnh gọi lại vòng đời
- Cách triển khai quy trình xem xét tự động dưới dạng một Thao tác trên GitHub có hỗ trợ theo dõi tương tác
Dọn dẹp
Đóng các yêu cầu kéo
Chuyển đến từng PR trên nhánh của bạn trong GitHub rồi nhấp vào Đóng yêu cầu kéo. Đừng hợp nhất PR feature/bulk-operations vì PR này vẫn chứa mã dễ bị tấn công chưa được vá.
Xoá kho lưu trữ được phân nhánh (không bắt buộc)
Nếu bạn không cần nhánh rẽ nữa, hãy chuyển đến nhánh rẽ của bạn trên GitHub: Settings (Cài đặt) -> di chuyển đến Danger Zone (Khu vực nguy hiểm) -> Delete this repository (Xoá kho lưu trữ này).
Bước tiếp theo
- Các trình bổ trợ và kỹ năng Antigravity CLI – tạo các kỹ năng và trình bổ trợ tuỳ chỉnh
- Quyền và hộp cát của Antigravity CLI – các chính sách chi tiết về công cụ và cơ chế hộp cát ở cấp hệ điều hành
- Các lệnh gọi và chính sách của Antigravity SDK – các mẫu nâng cao (giới hạn tốc độ, khôi phục lỗi, phần mềm trung gian)
- Ví dụ về Antigravity SDK –
agent_middleware.pycho các mẫu sản xuất