Công cụ agent tích hợp

Đây là những công cụ gắn với máy chủ mà runtime agent tích hợp đăng ký trực tiếp — máy chủ ngôn ngữ, tìm kiếm cấu trúc, trình gỡ lỗi, kernel, câu hỏi và điều khiển worker — khác với các công cụ MCP mà nó bắc vào và những công cụ tệp, tìm kiếm và shell chung từ runtime của harness. Chúng không nằm trên sổ đăng ký MCP: một máy khách MCP bên ngoài sẽ không thấy chúng, bởi mỗi công cụ đều gắn với một tài nguyên phía máy chủ đang sống — một tiến trình máy chủ ngôn ngữ, một bộ điều hợp gỡ lỗi, một trình thông dịch — thuộc về đúng một lượt chạy.

Mọi công cụ ở đây chỉ được đăng ký khi tài nguyên chống lưng của nó được nối cho lượt chạy — một bộ giám sát máy chủ ngôn ngữ hoặc gỡ lỗi, một bộ phân tích cú pháp tree-sitter, một nhà máy kernel, một cổng câu hỏi, một danh sách vibe. Việc phát hiện một máy chủ ngôn ngữ hay bộ điều hợp gỡ lỗi cho bản checkout này là một phép kiểm tra riêng, diễn ra sau đó (status / adapters): những công cụ ấy vẫn nằm trên bề mặt để agent có thể hỏi vì sao không có gì dùng được, thay vì đoán mò.

Cấp phê duyệt

Mỗi công cụ khai báo một cấp, và cấp đó quyết định những bề mặt nào nhìn thấy nó — chứ không chỉ là liệu nó có hỏi phê duyệt hay không. Chế độ Kế hoạch và các subagent chỉ đọc đều bị khống chế ở cấp read, nên một công cụ thuộc cấp write hay exec hoàn toàn không có mặt trong lược đồ của chúng.

Cấp	Ý nghĩa	Công cụ ở đây
`read`	Không có tác dụng phụ	`lsp`, `ast_grep`, `ask_user`, năm công cụ `vibe_*`
`write`	Thay đổi tệp	`lsp_rename`, `ast_edit`, `resolve`
`exec`	Khởi động hoặc điều khiển một tiến trình	`debug`, `eval`

`lsp` — truy vấn máy chủ ngôn ngữ

Được đăng ký khi lượt chạy có một bộ giám sát máy chủ ngôn ngữ và một thư mục làm việc. Việc một máy chủ có thực sự trả lời được hay không được phát hiện ở thời điểm gọi, dưới dạng một phép giao: một dấu hiệu gốc phải tồn tại và tệp nhị phân của máy chủ phải phân giải được. Chỉ riêng một trong hai thì không máy chủ nào khởi động — status sẽ nói rõ điều đó — thay vì đoán mò trong im lặng.

Vị trí được xác định bằng line cộng với một chuỗi con symbol, không bao giờ bằng cột. Một mô hình bị yêu cầu cho một cột sẽ đoán, và một lần đoán sai sẽ phân giải thành một ký hiệu khác trên cùng dòng — một câu trả lời trông có vẻ đúng nhưng lại nói về thứ khác. Bỏ qua symbol trong một hành động điều hướng là một lỗi, chứ không phải một lần đoán lấy cột đầu tiên.

Hành động	Tham số	Trả về
`diagnostics`	`file` (hoặc `"*"`)	Lỗi và cảnh báo; `"*"` chạy trình kiểm tra của dự án thay vào đó
`definition`	`file`, `line`, `symbol`	Nơi ký hiệu được khai báo
`type_definition`	`file`, `line`, `symbol`	Nơi kiểu của nó được khai báo
`implementation`	`file`, `line`, `symbol`	Các hiện thực cụ thể
`references`	`file`, `line`, `symbol`	Mọi lần sử dụng, giới hạn ở 50
`hover`	`file`, `line`, `symbol`	Chữ ký và chú thích tài liệu
`symbols`	`query` hoặc `file`	Tìm kiếm trong không gian làm việc với `query` (giới hạn ở 100); ký hiệu trong tài liệu với `file` (giới hạn ở 200)
`code_actions`	`file`, `line`, `symbol`	Các bản sửa nhanh mà máy chủ đưa ra
`status`	—	Những máy chủ nào đang chạy, và cho những gốc nào
`reload`	—	Khởi động lại máy chủ cho gốc này

Chẩn đoán khi ghi

Lợi ích thật sự không nằm ở công cụ. write, edit và apply_patch được bọc lại: sau khi ghi, tệp được đồng bộ và lưu qua máy chủ ngôn ngữ, và chỉ những chẩn đoán mới xuất hiện mới được gộp vào kết quả công cụ. Agent biết mình vừa làm hỏng bản dựng ngay tại lúc nó làm hỏng, mà không cần phải nhớ để hỏi.

Những chẩn đoán đã được báo trước đó sẽ bị chặn lại bởi một sổ cái theo từng lượt chạy, khóa theo mức độ nghiêm trọng, mã và thông điệp — vị trí được cố ý loại trừ, nên một chẩn đoán chỉ dịch xuống bốn dòng sẽ không bị báo lại như thể là mới.

`lsp_rename` — đổi tên toàn dự án

Một công cụ riêng, thuộc cấp write, vì đúng một lý do: cấp quyết định khả năng hiển thị. Gộp việc đổi tên vào lsp sẽ hoặc trao cho một kẻ khám phá chỉ đọc khả năng viết lại kho mã, hoặc đặt mọi lệnh hover sau một lời nhắc phê duyệt.

Tham số	Ý nghĩa
`file`	Nơi ký hiệu nằm
`line`	Dòng tính từ 1
`symbol`	Chuỗi con nhận diện nó trên dòng đó
`new_name`	Tên muốn đặt

`ast_grep` — tìm kiếm cấu trúc

Tìm mã theo hình dạng thay vì theo văn bản. $NAME khớp với bất kỳ nút nào, $$$NAME khớp với một dãy nút cùng cấp, và $_ là ký tự đại diện không bắt giữ gì.

Tính chất khiến nó là một bộ so khớp chứ không chỉ là một regex thêm vài bước: một biến meta lặp lại trong cùng một mẫu phải bắt được cùng một đoạn văn bản.

ast_grep(pattern: "if ($X != null) $X.dispose()", language: "dart")

sẽ khớp với một điều kiện bảo vệ giải phóng đúng thứ nó vừa kiểm tra, và không khớp với một điều kiện giải phóng một thứ khác.

Tham số	Ý nghĩa
`pattern`	Một mảnh mã có các biến meta
`path`	Tệp hoặc thư mục cần tìm; mặc định là toàn bộ không gian làm việc
`language`	Id ngữ pháp đi kèm (`dart`, `python`, `rust`, `c`, …). Được suy ra khi `path` nêu tên một tệp
`max_results`	Mặc định 50

`ast_edit` — viết lại theo cấu trúc, có tạm giữ

Cùng cách so khớp, cộng thêm một mẫu rewrite với các biến meta được thay ngược trở lại. Không có gì được ghi. Thay đổi được tạm giữ và kết quả nêu tên một edit_id.

ast_edit(pattern: "dispose($X)", rewrite: "$X.dispose()", language: "dart")
→ (proposed) 12 replacements in 4 files … call resolve with edit_id "edit_1"

Tham số	Ý nghĩa
`pattern`	Thứ cần khớp
`rewrite`	Thứ cần đặt vào đó, với `$NAME` được thay thế
`path`	Phạm vi; mặc định là toàn bộ không gian làm việc
`language`	Id ngôn ngữ

`resolve` — xác nhận hoặc hủy bỏ một thay đổi đã tạm giữ

Tham số	Ý nghĩa
`edit_id`	Từ kết quả `(proposed)`
`action`	`accept` hoặc `discard`

Mỗi tệp đều được đối chiếu với nội dung đã ghi nhận tại thời điểm tạm giữ, và mọi sai lệch đều khiến toàn bộ thay đổi bị từ chối. Một thao tác viết lại theo cấu trúc được áp dụng dở dang sẽ để lại một cây mã không biên dịch được theo hình dạng nào cả.

`debug` — điều khiển trình gỡ lỗi

Được đăng ký khi lượt chạy có một bộ giám sát phiên gỡ lỗi, một thư mục làm việc và một id hội thoại. Việc một bộ điều hợp có thực sự khởi động được hay không được phát hiện ở thời điểm gọi, theo cùng quy tắc giao như với máy chủ ngôn ngữ (dấu hiệu gốc và tệp nhị phân). Cấp exec; không an toàn khi chạy song song (một phiên là trạng thái xuyên suốt các lần gọi, nên continue vượt mặt stack sẽ đọc một khung đã di chuyển).

Mỗi cuộc hội thoại chỉ có một phiên, với TTL cứng (30 phút). Lệnh launch thứ hai sẽ bị từ chối thay vì âm thầm thay thế lệnh đầu tiên.

Thao tác	Tham số	Ghi chú
`adapters`	—	Những bộ điều hợp nào dùng được ở đây, và vì sao không
`status`	—	Liệu một phiên có đang chạy không, và nó dừng ở đâu
`breakpoints`	`file`, `lines[]`	`lines` rỗng sẽ xóa tệp. Có thể đặt trước khi khởi chạy
`launch`	`program`, `args[]`	Khởi động chương trình và dừng lại tại các điểm dừng của bạn
`attach`	`port`	Kết nối tới một chương trình được gỡ lỗi đang chạy sẵn
`continue`	`thread_id?`	Chạy cho đến lần dừng kế tiếp
`pause`	`thread_id?`	Dừng nó ngay tại chỗ
`step_over` / `step_in` / `step_out`	`thread_id?`	Di chuyển một bước
`threads`	—	Id và tên luồng
`stack`	`thread_id?`	Các khung, giới hạn ở 30
`scopes`	`frame_id`	Các phạm vi trên một khung, mỗi phạm vi có một `reference`
`variables`	`reference`	Các đối tượng con, giới hạn ở 50, giá trị giới hạn ở 400 ký tự
`evaluate`	`expression`, `frame_id?`	Được tính trong chính phạm vi của khung
`output`	—	stdout/stderr của chương trình được gỡ lỗi, có giới hạn
`terminate`	—	Kết thúc phiên và giết bộ điều hợp

Bộ điều hợp

Id	Lệnh	Dấu hiệu gốc
`dart`	`dart debug_adapter`	`pubspec.yaml`
`debugpy`	`python3 -m debugpy.adapter`	`pyproject.toml`, `setup.py`, `requirements.txt`
`lldb`	`lldb-dap`	`Cargo.toml`, `CMakeLists.txt`
`delve`	`dlv dap`	`go.mod`

debugpy ưu tiên .venv/bin hoặc venv/bin cục bộ trong dự án hơn $PATH: một python trên $PATH là một môi trường khác, và việc gắn vào từ nhầm môi trường sẽ thất bại theo cách trông như mã hỏng.

`eval` — trình thông dịch bền vững

Một ô Python hoặc JavaScript mà biến, import và dữ liệu đã nạp vẫn còn nguyên giữa các lần gọi. Cấp exec; không an toàn khi chạy song song.

Tham số	Ý nghĩa
`code`	Ô
`description`	Bắt buộc. 5–10 từ cho nhãn trong bản ghi hội thoại
`language`	`python` (mặc định) hoặc `javascript`
`reset`	Vứt bỏ trình thông dịch hiện tại và khởi động một cái sạch trước tiên

Biểu thức cuối cùng được hiển thị theo cách một notebook vẫn làm.
display() hoạt động, một frame của pandas được kết xuất thành bảng, và một hình matplotlib quay về dưới dạng ảnh mà bản ghi hội thoại hiển thị.
Những cú pháp IPython mà người ta theo phản xạ vẫn gõ — %pip, %cd, !cmd, %%bash, %%timeit — được viết lại thành mã thuần. %pip còn xóa sys.modules, nên lần import kế tiếp nhìn thấy thứ vừa được cài.

Gọi công cụ của chính bạn từ bên trong một ô

contents = tool("read", {"path": "lib/auth.dart"})

Cầu nối đi vào lại sổ đăng ký công cụ của harness, nên rào chắn, việc phê duyệt và mọi lớp bọc đều áp dụng y hệt như với một lệnh gọi do mô hình phát ra. Nó đi trên chính đường ống của kernel thay vì một socket loopback: không cổng, không secret, không quy tắc lưu lượng ra.

Thời gian chờ của ô là một ngân sách không hoạt động (mặc định 5 phút) và ngân sách đó bị tạm ngưng trong khi một lệnh gọi qua cầu còn đang chờ xử lý, nên một ô tỏa ra tới các subagent không bị giết giữa lúc tỏa ra.

`ask_user` — hỏi con người một câu hỏi

Cấp read. Cách duy nhất để một lượt chạy hỏi người vận hành bất cứ điều gì. Nó hiển thị một thẻ đánh số trong cuộc hội thoại và chặn cho đến khi có người trả lời, bỏ qua, hoặc câu hỏi hết thời gian chờ. Đừng bao giờ viết câu hỏi dưới dạng tin nhắn chat — làm vậy sẽ kết thúc lượt.

Tham số	Ý nghĩa
`question`	Cần hỏi điều gì
`context`	Tùy chọn: vì sao bạn đang hỏi và câu trả lời ảnh hưởng tới điều gì
`options[]`	Các lựa chọn, mỗi mục là `{label, description?}`
`allow_free_text`	Liệu câu trả lời tự nhập có được chấp nhận
`multi_select`	Liệu có được chọn nhiều lựa chọn

Bỏ qua là thành công: hãy tiếp tục dựa trên một giả định đã nêu rõ và đừng hỏi lại. Hết thời gian chờ là một lỗi với cùng chỉ dẫn đó. Lời nhắc cấp quyền (“tôi có được làm việc này không?”) là một cổng riêng và hiển thị thành cùng loại thẻ trong cuộc hội thoại.

Chỉ được đăng ký khi tồn tại cả một cổng câu hỏi lẫn một space đích. Khi không có người nào được gắn vào, lời gọi thất bại thay vì chặn mãi mãi — cùng tư thế đóng khi lỗi mà một prompt của rào chắn áp dụng khi không có người phê duyệt nào được kết nối.

`vibe_*` — điều khiển worker nền

Chỉ được đăng ký khi chế độ vibe đang bật. Cả năm đều thuộc cấp read: cổng gác thuộc về công cụ của worker, nơi việc chỉnh sửa thực sự diễn ra.

Công cụ	Tham số	Ghi chú
`vibe_spawn`	`brief`, `label`, `tier?`	Trả về ngay lập tức; worker vẫn tiếp tục chạy
`vibe_send`	`worker_id`, `message`	Nối thêm vào bản giao việc và chạy lại
`vibe_wait`	`worker_id`, `timeout_seconds?`	Chặn cho đến khi nó kết thúc
`vibe_kill`	`worker_id`	Dừng nó
`vibe_list`	—	Hạng, trạng thái, thời gian đã chạy và kết quả cuối

tier là fast (công việc cơ học với đặc tả rõ ràng) hoặc good (thiết kế, phán đoán, hoặc đánh giá đầu ra của một worker fast).

Công cụ agent tích hợp

Cấp phê duyệt

lsp — truy vấn máy chủ ngôn ngữ

Chẩn đoán khi ghi

lsp_rename — đổi tên toàn dự án

ast_grep — tìm kiếm cấu trúc

ast_edit — viết lại theo cấu trúc, có tạm giữ

resolve — xác nhận hoặc hủy bỏ một thay đổi đã tạm giữ

debug — điều khiển trình gỡ lỗi