AstraCode

Coding agent cho VS Code, chạy trên model FPT Cloud qua gateway AstraWork.

Cài đặt

code --install-extension astracode.vsix

Rồi mở biểu tượng AstraCode ở activity bar.

Hai biểu tượng, hai toggle

AstraCode đóng góp hai container, nên có hai biểu tượng toggle độc lập trong activity bar:

Cả hai dùng chung một provider nên luôn cùng trạng thái — đổi model ở bên này thì bên kia cập nhật ngay.

Đưa vào cùng hàng tab với Claude Code

Mục tiêu: AstraCode nằm cùng hàng với CHAT / CLAUDE CODE ở thanh bên phải.

Cách nhanh — bấm nút $(layout-sidebar-right-dock) trên title bar của panel AstraCode, rồi chọn Secondary Side Bar trong danh sách hiện ra.

Cách chắc chắn — kéo biểu tượng AstraCode (phải) từ activity bar bên trái, thả vào đúng hàng tab đó. Không thấy thanh bên phải thì bật bằng Ctrl+Alt+B.

Làm một lần là xong, VS Code nhớ vĩnh viễn kể cả sau khi khởi động lại.

Vì sao không tự động hoàn toàn: VS Code không mở API cho extension đặt view vào thanh bên phải — vị trí panel là quyết định của người dùng. Đây là giới hạn của nền tảng, mọi extension đều vậy. Lệnh trên chỉ mở sẵn hộp chọn đích và hướng dẫn.

Nút trên title bar

Chỉ hai nút, cho hai việc làm hằng ngày:

Phần bố cục (đưa sang thanh bên phải, mở cả hai thanh, mở thành tab) và Xem log nằm trong menu ... cùng chỗ.

Hoặc mở thành tab

AstraCode: Mở chat thành tab bên cạnh biến giao diện thành một tab thật cạnh file code. Cách này không phụ thuộc bố cục thanh bên, luôn dùng được.

Quyền — thứ quyết định agent làm được gì

Ba chế độ, đổi bằng hộp chọn ở dưới ô chat hoặc lệnh AstraCode: Đổi chế độ quyền:

Hai ràng buộc không tắt được bằng cấu hình:

• bash không bao giờ được tự duyệt. Nằm ở PermissionManager.ALWAYS_ASK trong core. Nút "luôn cho phép" cũng không hiện cho nó — hai lần gọi bash giống tên nhau có thể làm hai việc hoàn toàn khác.
• Hạ cấp quyền theo nguồn. Sau khi agent đọc phải nội dung có dấu hiệu prompt injection, phiên tự rơi về "hỏi trước khi sửa" dù bạn đang bật tự duyệt, và mọi quyền đã nhớ bị xoá. Đây là chỗ cắt chuỗi đọc nội dung độc → tự động ghi file theo lời nội dung đó. Chỉ bạn gỡ được, bằng cách chọn lại chế độ.

"Luôn cho phép" có phạm vi là thư mục chứa file, không phải cả workspace: duyệt sửa src/api/user.ts không kéo theo .github/workflows.

Theo dõi thay đổi

Mọi file agent đụng vào đều vào sổ thay đổi của phiên, hiện ở ba chỗ cùng lúc:

Diff so với bản gốc trước khi agent đụng vào, không phải bản trên đĩa — sổ giữ nội dung gốc riêng, nên nó vẫn đúng sau khi file đã bị ghi đè nhiều lần.

Sửa file được ghi bằng WorkspaceEdit chứ không phải fs.writeFile. Đổi lại được ba thứ: Ctrl+Z hoàn tác được, không ghi đè bản chưa lưu bạn đang gõ dở, và editor thấy thay đổi ngay.

Chạy lệnh

Tắt mặc định. Bật bằng astra.sandbox:

AstraCode không bao giờ tự chuyển từ docker sang host. Docker không chạy được thì tool bash biến mất kèm lý do — chứ không phải lệnh vẫn chạy, chỉ là mất lớp cách ly mà không ai nói gì.

Ở chế độ host, chat hiện banner cảnh báo thường trực, không phải một lần rồi thôi.

Đường dẫn được dịch hai chiều C:\Work epo ↔ /workspace, cả trong lệnh gửi vào lẫn output trả ra. Không dịch thì model thấy đường dẫn lạ trong output và đi sửa nhầm file.

Bộ nhớ và phiên dài

ASTRA.md — ghi chú project, nạp vào prompt mỗi lượt. Tạo bằng AstraCode: Sửa ASTRA.md của project, hoặc để ở ~/.astra/ASTRA.md cho ghi chú cá nhân dùng chung mọi repo.

Viết ngắn. Mỗi dòng ở đây tốn ngữ cảnh của mọi câu hỏi về sau. File từ repo bị giới hạn 12k ký tự và bị quét dấu hiệu prompt injection — nó có sức nặng ngang lời của hệ thống, nên bạn phải biết khi nó chứa thứ đáng ngờ.

Ngữ cảnh — đồng hồ hiện từ 70%. Ở 85% hội thoại tự nén: vài lượt gần nhất giữ nguyên văn, phần đầu thành bản tóm tắt (mục tiêu / đã tìm hiểu / đã thay đổi / còn dở). Tắt bằng astra.autoCompact, khi đó tự gõ /compact.

/undo — đưa file về trạng thái trước lượt vừa rồi, không phải trước cả phiên. Không khôi phục được file do lệnh bash ghi ra: sandbox ghi thẳng vào workspace, ngoài tầm lớp theo dõi thay đổi.

Phiên — tự lưu sau mỗi lượt, ngoài repo. Thanh tiêu đề của panel chat có đúng hai nút cho việc này:

Cùng việc đó gọi được từ Command Palette (AstraCode: Hội thoại mới / Hội thoại cũ / Mở lại phiên cũ) hoặc /sessions. Phiên mở lại bắt đầu với lịch sử undo trống — file trên đĩa đã đi tiếp từ lúc lưu.

Danh sách chỉ hiện phiên của đúng thư mục đang mở, và một hội thoại chỉ được lưu sau lượt trả lời đầu tiên.

Slash command

Gõ / trong ô nhập để chọn.

Lệnh tự viết đặt ở ~/.astra/commands/<tên>.md:

---
name: review
description: Soát lại diff hiện tại
---
Đọc diff của nhánh này và chỉ ra lỗi thật, bỏ qua chuyện phong cách.
Tập trung vào $ARGUMENTS.

$ARGUMENTS nhận toàn bộ phần gõ sau tên lệnh, $1…$9 nhận từng từ. Không có placeholder nào thì đối số được nối xuống cuối.

Lệnh trong repo (.astra/commands/) chỉ chạy khi workspace được tin cậy, và hiện nhãn từ repo trong danh sách gợi ý — đó là prompt do người khác viết.

Tự kiểm tra sau khi sửa

astra.verifyCommand chạy sau mỗi lượt agent có sửa file. Cần bật astra.sandbox.

// settings.json của NGƯỜI DÙNG, không phải của workspace
"astra.verifyCommand": "pnpm test"

Đỏ thì output được đưa vào hội thoại để agent tự sửa tiếp. Xanh thì không nhét gì vào ngữ cảnh.

Giá trị đặt trong .vscode/settings.json của repo bị bỏ qua và có báo. Lệnh đó đến từ bất kỳ ai gửi PR vào repo — chạy nó tự động là cấp quyền thực thi cho một thư mục chỉ vì bạn mở nó lên.

Cấu hình

Mọi thứ dưới đây nằm trong bảng cài đặt bên trong panel chat — bấm nút bánh răng cạnh nút đính kèm, hoặc AstraCode: Mở cài đặt. Không còn view "Cài đặt" riêng: một bề mặt cài đặt duy nhất, để không có hai bảng lệch nhau.

Bảng có bốn mục: Tài khoản · Mức dùng · Model · Capability profile.

Chưa đăng nhập thì chat bị chắn. Model của AstraCode đến từ tài khoản AstraWork và không có nguồn nào khác, nên "chưa đăng nhập" không phải trạng thái dùng hạn chế — nó là trạng thái chưa dùng được. Panel hiện cửa đăng nhập thay vì một ô nhập gõ vào cũng không gửi được.

1. Đăng nhập

Bấm Đăng nhập AstraWork → trình duyệt mở <trang web AstraWork>/login. Đã đăng nhập Microsoft ở đó rồi thì không phải nhập lại gì — chỉ dán access token của phiên đó về VS Code. Extension nhận cả access token (JWT) lẫn mã đăng nhập một lần của SSO.

Token lưu trong SecretStorage của VS Code (mã hoá bởi hệ điều hành), không bao giờ ghi vào settings.json.

Không có refresh token trong AstraWork nên hết hạn là phải đăng nhập lại — đây là thiết kế của gateway, không phải thiếu sót của extension.

2. Chọn model

Danh sách model, quyền dùng từng model và hạn mức đều đi ra từ tài khoản vừa đăng nhập. Ba vai trò riêng: editor (sửa code), planner (lập kế hoạch), fast (việc nhẹ). Để trống thì extension tự chọn theo năng lực model.

3. Địa chỉ máy chủ (phải điền ở lần chạy đầu)

Gấp trong mục Tài khoản. Hai ô này để trống sẵn — đội vận hành AstraWork của bạn cấp địa chỉ:

• API gateway — không kèm /v1, extension tự thêm. Chạy gateway trên máy thì điền http://localhost:8000.
• Trang web AstraWork — nơi đăng nhập, khác endpoint API ở trên.

Chưa điền ô đầu thì khung chat nói rõ đang thiếu gì thay vì báo lỗi mạng.

Capability profile

Bảng model hiện tool calling, context, kháng injection — endpoint không cung cấp những thông tin này. Chúng đến từ models.json (capability profile), sinh bằng astracode measure.

Không cần đo để bắt đầu dùng. Model không có trong file đó chạy bằng năng lực giả định — native tool-calling, đọc được ảnh, cửa sổ ngữ cảnh lấy từ danh sách model của gateway. Giả định sai thì lượt đầu tiên vấp và AstraCode tự chuyển sang đường XML rồi ghi nhớ, kèm một dòng thông báo.

Chỉ cần đo khi muốn biết mức kháng prompt injection trước lúc giao vai editor (quyền ghi file) — đó là thứ duy nhất không dò được lúc chạy, nên chưa đo thì nó ở mức unknown chứ không phải low.

Cài đặt trong settings.json

Xem log: AstraCode: Xem log trong Command Palette. Mọi log đã đi qua bộ lọc secret.