Lệnh trong phiên

VelaTerm bổ sung một bộ lệnh ngắn vào mọi phiên do VelaTerm khởi động. Bạn và các tác nhân dùng những lệnh này để khởi chạy phiên khác, mở tệp, đọc và tìm kiếm các cuộc hội thoại khác, kiểm tra phiên nào đang bận, gửi tin nhắn giữa các phiên và chờ các lệnh chạy lâu. Chương này là tài liệu tra cứu cho từng lệnh và cho các kỹ năng tác nhân tương ứng.

1. Nơi các lệnh hoạt động

Các lệnh này nằm trên PATH của mọi phiên do VelaTerm khởi động: terminal thông thường và phiên tác nhân, ở cả chế độ terminal lẫn chế độ hội thoại, kể cả các phiên trên máy chủ VelaTerm từ xa. Các lệnh không cần cài đặt. Bên ngoài những phiên như vậy, lệnh sẽ dừng với thông báo “not inside a VelaTerm session”.

Chạy một lệnh với --help để xem cách sử dụng lệnh đó.

Một số lệnh nhận tham chiếu phiên: ID phiên đầy đủ, tiền tố ID dài ít nhất 8 ký tự, tên phiên chính xác, hoặc một phần của tên đủ để xác định duy nhất một phiên. Hãy đặt tên có chứa dấu cách trong dấu ngoặc kép. Khi một tham chiếu khớp với nhiều phiên, lệnh sẽ liệt kê các phiên phù hợp.

2. Kỹ năng tác nhân (Kỹ năng Vela)

Cài đặt ▸ Chung ▸ “Kỹ năng Vela” cài đặt các kỹ năng tương ứng vào Claude Code và Codex; “Cài đặt lại” làm mới các kỹ năng này. Sau đó, hãy bắt đầu một cuộc hội thoại Claude hoặc Codex mới để tác nhân nhận các kỹ năng. Trong Claude Code, kỹ năng được gọi bằng /name; trong Codex, bằng $name.

Các kỹ năng ghi “Bạn” chỉ chạy khi bạn gọi; những kỹ năng còn lại cũng có thể được tác nhân tự dùng khi bạn nhắc đến một phiên khác hoặc công việc trước đó. vask chỉ tồn tại dưới dạng kỹ năng; kỹ năng này chạy vrefer <session> --ask "<question>".

3. vspawn và vspawn-tree

vspawn [--worktree] [--cwd <path>] [--yes] [--claude|--codex|--copilot|--kiro] [--model <name>] [--effort <level>] <task description...>

Khởi chạy một phiên mới bên dưới phiên hiện tại và gửi nhiệm vụ làm tin nhắn đầu tiên của phiên đó. vspawn-tree là cùng lệnh này nhưng kèm một worktree git riêng.

Chi tiết: Tạo phiên và hợp tác Git và Lập kế hoạch và thực hiện.

4. vopen

vopen <file|url>...

Mở từng đối số trong khung giữa. Tệp Markdown mở trong trình soạn thảo Markdown, hình ảnh mở trong trình xem ảnh, còn các tệp khác mở trong trình soạn thảo mã. Địa chỉ web (http hoặc https) mở trong thẻ trình duyệt, tính năng này chỉ có trong ứng dụng máy tính. Đường dẫn tương đối được tính từ thư mục hiện tại. Xem Thẻ tài liệu và thẻ trình duyệt.

5. vrefer và vask

vrefer <session> [--last N] [--range A:B] [--json]
vrefer <session> --ask "<question>" [--with <agent>] [--timeout N]
vrefer --list [--json]

In ra cuộc hội thoại của một phiên khác. Phiên đó không cần đang chạy, và không có gì được gửi tới phiên đó.

--ask khởi động một tiến trình tác nhân riêng để trả lời và chỉ trả về câu trả lời, nhờ vậy một cuộc hội thoại dài không làm đầy ngữ cảnh hiện tại. Cài đặt ▸ Hành vi ▸ “Ngữ cảnh tham chiếu phiên” quyết định cách chuyển cuộc hội thoại cho tác nhân trả lời: “Toàn bộ bản ghi” (mặc định) hoặc “Tóm tắt trước”, tùy chọn này rút gọn cuộc hội thoại trước bằng “Tác nhân tóm tắt”, mô hình và mức suy luận được chọn tại đó. Nếu không tạo được câu trả lời, vrefer sẽ giải thích lý do và in ra cuộc hội thoại thay thế.

Có thể đọc hội thoại của Claude Code, Codex, OpenCode, Pi, OMP, Grok Build và Kiro (chỉ với bản ghi văn bản). Các loại phiên khác, cũng như các phiên chưa ghi lại hội thoại của tác nhân, không thể đọc được.

6. vsearch

vsearch <words...> [--session <session>] [--all|--archived] [--limit N] [--json]

Tìm kiếm trong hội thoại của mọi phiên trên VelaTerm đang kết nối. Mọi từ đều phải khớp, theo thứ tự bất kỳ.

Mỗi kết quả hiển thị tên phiên, tiền tố ID, số lần khớp, một vài đoạn trích kèm số thứ tự tin nhắn, và lệnh vrefer để đọc toàn bộ cuộc hội thoại. Số thứ tự tin nhắn có thể dùng với vrefer --range. Kết quả chỉ lấy từ hội thoại của tác nhân; những kết quả chỉ có trong bản ghi terminal sẽ không được trả về. “no matches” là một kết quả bình thường.

7. vstat

vstat [--wait] [--follow] [--timeout N] [--json]

Hiển thị trạng thái của từng phiên: working, asking (đang chờ cấp quyền hoặc chờ câu trả lời), waiting (đã kết thúc lượt) hoặc unknown. Trạng thái phản ánh hoạt động, không cho biết nhiệm vụ đã hoàn thành hay chưa.

Đối số đầu tiên (không bắt buộc) dùng để lọc theo ID điều phối của các phiên bản VelaTerm cũ; quy trình lập kế hoạch và thực hiện dùng vflow status thay thế.

8. vtell

vtell <session> [--steer] [--message-id msg-UUID] [message...]
vtell [planner-session] --report --round N [--message-id msg-UUID] [message...]

Gửi tin nhắn tới một phiên khác. Khi không có đối số tin nhắn, nội dung được đọc từ đầu vào chuẩn. Bên nhận thấy biểu tượng tác nhân và tên phiên của bên gửi trong cuộc hội thoại của mình, kể cả sau khi mở lại phiên.

• Bên nhận phải là một phiên Claude Code, Codex, OpenCode, Pi hoặc OMP đang ở chế độ hội thoại. Phiên đã lưu trữ và chính phiên gửi sẽ bị từ chối.
• Bên nhận đang rảnh sẽ bắt đầu một lượt mới. Bên nhận đang bận sẽ xếp tin nhắn vào hàng chờ cho đến khi lượt hiện tại kết thúc; --steer sẽ thêm tin nhắn vào lượt đang chạy thay vì xếp hàng.
• Mỗi tin nhắn có thể chứa tối đa 65.536 byte văn bản.
• Lệnh in ra một biên nhận: sent, queued hoặc steered. blocked nghĩa là bên nhận đang chờ cấp quyền hoặc chờ câu trả lời. Biên nhận chỉ xác nhận tin nhắn đã được chuyển đến, không xác nhận bên nhận đã hoàn thành công việc.
• Lệnh in ra một ID tin nhắn. Để thử lại một lần gửi chưa rõ kết quả, hãy chạy lại lệnh với --message-id và cùng nội dung; tin nhắn sẽ không bị gửi hai lần.
• --report --round N được các phiên thực hiện trong quy trình lập kế hoạch và thực hiện dùng để nộp kết quả cho bước nghiệm thu. Báo cáo được gửi tới phiên lập kế hoạch của phiên thực hiện đó. Xem Lập kế hoạch và thực hiện.

9. vrun

vrun [-t <seconds>] <label> <command> [arguments...]
vrun --status <label>

Khởi động một lệnh, chờ lệnh kết thúc, rồi in ra mã thoát, thời gian đã chạy và phần cuối nhật ký của lệnh. Mã thoát của lệnh được trả về nguyên vẹn. vrun dành cho các tác vụ build và kiểm thử chạy lâu: tác nhân chạy chúng bằng vrun sẽ biết kết quả ngay khi có.

• -t <seconds> đặt thời gian vrun chờ (mặc định 1800). Khi hết thời gian, vrun thoát với mã 124 và lệnh vẫn tiếp tục chạy.
• --status <label> báo cáo về một lệnh đã khởi động trước đó với nhãn này.
• Trong lúc lệnh chạy, phiên vẫn giữ trạng thái “đang làm việc”. Trong chế độ terminal, dòng “Lệnh chạy nền” phía trên terminal liệt kê các lệnh đang chạy kèm “Nhật ký” và “Dừng”; xem Sử dụng terminal §6.1.

10. vkb

vkb explore <query> | search <query> | node <symbol-id> | callers <id> [depth] | callees <id> [depth]
    | impact <id> [depth] | path <from-id> <to-id> | files [path]
    | memories <query> | memory <entry-id> | notes <query> | note <vault-id> <path> | status

Truy vấn đồ thị mã nguồn của bản checkout hiện tại và kho kiến thức của VelaTerm đang kết nối. Truy vấn mã cần bật lập chỉ mục trên trang Đồ thị mã nguồn của dự án. vkb chỉ đọc dữ liệu; lệnh này không thay đổi bài viết kiến thức nào. Xem Đồ thị mã nguồn và kho kiến thức, Kho kiến thức theo phiên và Cơ sở tri thức cục bộ.

11. vflow

vflow status|stop|propose|dispatch|accept|block <workflow-id> [--round N --message-id msg-UUID] < message.txt

Điều khiển quy trình lập kế hoạch và thực hiện. Phiên lập kế hoạch dùng propose, dispatch, accept và block trong quá trình vận hành quy trình. Thông thường, bạn chỉ cần hai thao tác:

• vflow status <workflow-id> hiển thị trạng thái của quy trình, các nhiệm vụ, các phiên và vòng hiện tại.
• vflow stop <workflow-id> dừng các vòng tiếp theo và yêu cầu các phiên đang chạy dừng lại.

12. Lệnh vela

Trên macOS, Cài đặt ▸ Chung ▸ “Lệnh shell” có nút “Cài đặt lệnh ‘vela’”. Nút này thêm vela <project-path> vào shell của bạn, tương tự lệnh code của VS Code. Chạy lệnh này trong bất kỳ terminal nào sẽ mở dự án trong VelaTerm, hoặc chuyển sang dự án đó nếu dự án đã được mở. VelaTerm không ghi đè một lệnh vela có sẵn mà không phải do VelaTerm cài đặt.