Cách cài đặt và sử dụng Jev Skills cho các quyết định của tác nhân

Jev Skills thực hiện những gì

Awesome Jev Skills là bộ sưu tập gồm chín skill có thể cài đặt để bổ sung các quyết định có cấu trúc vào quy trình làm việc của tác tử AI. Jev chọn giữa các ứng viên, phân loại đầu vào và chấm điểm các tiêu chí đã xác định. Tác tử của bạn vẫn chịu trách nhiệm thu thập ngữ cảnh, gọi công cụ, thực hiện công việc và xác minh kết quả.

Kho lưu trữ bao gồm 90 kịch bản và 14 ví dụ đầu vào-đầu ra được ghi lại. Các công thức bao quát tác tử chạy dài, đánh giá, định tuyến, quản lý ngữ cảnh, tương tác với trình duyệt, phân loại hộp thư đến, bằng chứng từ tài liệu, công cụ dành cho nhà phát triển, mô phỏng, trò chơi và quy trình sáng tạo.

Jev chọn hoặc chấm điểm. Jev không nhấp nút, gửi tin nhắn, sửa đổi tệp, kết xuất nội dung đa phương tiện hoặc thực thi hành động đã chọn.

Tính năng chính

• Loại quyết định có cấu trúc: Dùng choice để chọn một ứng viên, noul cho một phán định đúng hoặc sai độc lập và score cho các mức độ được chấm điểm.
• Skill chuyên biệt: Cài đặt skill cho việc phân loại, tài liệu, giao diện người dùng, định tuyến, ngữ cảnh, rà soát mã, tìm mã và mô phỏng.
• Điểm kiểm tra của tác tử: Yêu cầu Jev phát hiện các lỗi lặp lại, đánh giá bằng chứng hoàn tất, chọn một tuyến xử lý hoặc xác định liệu một hành động được đề xuất có thúc đẩy mục tiêu hay không.
• Phán định song song: Đặt nhiều câu hỏi độc lập trên cùng trạng thái vào một yêu cầu, hoặc để tác tử máy chủ lập lịch các yêu cầu độc lập với mức đồng thời giới hạn.
• Xác thực ngoại tuyến: Dùng --dry-run để xác thực đầu vào mà không gọi mạng hoặc tạo kết quả phân loại.
• Chế độ mô phỏng minh bạch: Nếu không có khóa OpenRouter, tác tử hiện tại của bạn chỉ có thể mô phỏng cùng phán định sau khi bạn phê duyệt chế độ này.

Chọn skill

• jev: Xác định một quyết định tùy chỉnh hoặc thêm một điểm kiểm tra chung cho tác tử.
• jev-triage: Phân loại và ưu tiên tin nhắn, phiếu yêu cầu hoặc phản hồi.
• jev-documents: Chọn các đoạn nguồn và đánh giá bằng chứng hỗ trợ.
• jev-ui: Chọn giữa các hành động trên trình duyệt hoặc máy tính để bàn đã được quan sát.
• jev-route: Đề xuất một công cụ, mô hình hoặc chuyên gia.
• jev-context: Đánh giá mức độ liên quan và xác định khi nào nên nén ngữ cảnh.
• jev-code-review: Ưu tiên các thay đổi mã cần rà soát.
• jev-find-code: Chọn vị trí tiếp theo từ danh mục tệp đã được quan sát.
• jev-simulation: Chọn các hành động hợp lệ trong một thế giới mô phỏng.

Cài đặt

Cài đặt có sự hỗ trợ của tác tử được khuyến nghị

Cách được khuyến nghị là giao nhiệm vụ cài đặt cho Codex, Claude Code hoặc OpenCode. Dán lời nhắc sau vào tác tử của bạn:

Cài đặt Jev Skills cho tác tử hiện tại của tôi, bao gồm skill chung và tất cả skill kịch bản. Đọc và làm theo hướng dẫn cài đặt này, sau đó xác minh việc cài đặt:
https://raw.githubusercontent.com/wuyoscar/jev-skill/main/docs/install.md

Tác tử sẽ kiểm tra môi trường của bạn, mặc định cài đặt vào dự án hiện tại và xác minh cài đặt ở chế độ ngoại tuyến. Cách cài đặt mặc định không yêu cầu Node, npm hoặc tài khoản Vercel. Xử lý mọi yêu cầu phê duyệt do tác tử đưa ra.

Để cài đặt thủ công hoặc khắc phục sự cố, hãy tham khảo hướng dẫn cài đặt thủ công.

Cấu hình quyền truy cập Jev thực

Các lệnh gọi Jev thực yêu cầu OPENROUTER_API_KEY. Tạo khóa thông qua cài đặt OpenRouter và cấu hình khóa cục bộ. Không bao giờ dán khóa vào cuộc trò chuyện. Các lệnh gọi trực tiếp sử dụng API và có thể phát sinh phí sử dụng.

Nếu không tìm thấy khóa, tác tử phải cảnh báo bạn và chờ một trong các lựa chọn sau:

1. Lựa chọn A: Lấy và cấu hình khóa cục bộ, sau đó sử dụng Jev thực.
2. Lựa chọn B: Cho phép tác tử hiện tại mô phỏng việc phân loại với cùng ngữ cảnh, ứng viên và tiêu chí.

Kết quả mô phỏng phải được gắn nhãn mode: agent_simulation và jev_called: false. Đây không phải là phản hồi Jev hoặc các xác suất Jev đã được hiệu chuẩn, vì vậy tác tử không được tự tạo các giá trị xác suất.

Chế độ mô phỏng và chế độ chạy thử là khác nhau. Mô phỏng tạo ra phán định của tác tử hiện tại. Chạy thử chỉ xác thực định dạng yêu cầu và không thực hiện phân loại.

Cách sử dụng cơ bản

Thử ví dụ phân loại đã cài đặt

Sau khi cài đặt, yêu cầu tác tử sử dụng ví dụ đi kèm với jev-triage. Bài thực hành này hiển thị đầu vào, xác nhận chế độ thực thi và ngăn tác tử thực hiện hành động trên hộp thư.

Sử dụng skill jev-triage và đọc assets/example.json từ thư mục đã cài đặt của skill đó. Hiển thị ngữ cảnh, câu hỏi và các ứng viên của tệp. Nếu thiếu OPENROUTER_API_KEY, yêu cầu tôi chọn A: cấu hình khóa cho Jev thực; hoặc B: cho phép tác tử hiện tại mô phỏng. Chờ lựa chọn của tôi. Ở chế độ API, xác thực bằng --dry-run, sau đó thực hiện một lệnh gọi Jev. Ở chế độ mô phỏng, gắn nhãn kết quả là "Agent simulation; Jev not called" và không tự tạo xác suất. Hiển thị đầy đủ đầu vào, đầu ra và chế độ. Không truy cập hộp thư hoặc thực thi hành động.

Nếu tác tử không thể tìm thấy skill vừa cài đặt, yêu cầu tác tử kiểm tra thư mục cài đặt và tải lại phiên nếu ứng dụng của bạn yêu cầu.

Hiểu cấu trúc yêu cầu

Một yêu cầu Jev cung cấp một mô hình, trạng thái dùng chung và một hoặc nhiều câu hỏi. Mỗi câu hỏi xác định loại, hướng dẫn và tiêu chí ứng viên nếu có. Ví dụ rút gọn sau đây hỏi tác nhân nên làm gì sau khi cùng một lỗi phân tích cú pháp lặp lại:

{
  "model": "typesafe/jev-1.13",
  "state": {
    "goal": "Sửa bộ phân tích cú pháp CSV và xác minh các bài kiểm thử trước khi tuyên bố hoàn tất.",
    "recent_result": "Cùng một UnicodeDecodeError xuất hiện hai lần; không có thay đổi mã nguồn.",
    "observation": "Bộ phân tích cú pháp mở tệp mà không chỉ định bảng mã rõ ràng."
  },
  "questions": {
    "next_step": {
      "type": "choice",
      "instructions": "Chọn bước tiếp theo hữu ích dựa trên bằng chứng.",
      "criteria": {
        "inspect_input": "Kiểm tra dữ liệu đầu vào và mã mở tệp.",
        "retry_unchanged": "Chỉ thử lại nếu điều kiện tạm thời đã thay đổi.",
        "report_done": "Chỉ báo cáo hoàn tất khi các bài kiểm thử đạt.",
        "ask_user": "Hỏi khi thiếu thẩm quyền hoặc thông tin quan trọng."
      }
    },
    "stuck": {
      "type": "noul",
      "instructions": "Các lần thử không thay đổi có lặp lại cùng một lỗi không?"
    }
  }
}

Trong ví dụ API tổng hợp được ghi lại của kho lưu trữ, Jev đã chọn inspect_input và trả về stuck = true. Đây là quyết định dựa trên bằng chứng được cung cấp, không phải việc thực thi sửa chữa.

Sử dụng dòng lệnh tùy chọn

Nếu đã cài đặt jev-decide, hãy lưu một yêu cầu hoàn chỉnh dưới dạng request.json. Trước tiên, hãy xác thực yêu cầu ngoại tuyến:

jev-decide decide request.json --dry-run

Sau khi xem xét và phê duyệt dữ liệu sẽ được gửi đến OpenRouter, hãy thực hiện một yêu cầu trực tiếp và lưu kết quả:

jev-decide decide request.json > result.json

Nếu chỉ cài đặt kỹ năng tổng quát và không có lệnh này, hãy sử dụng tập lệnh Python:

python3 <actual-skill-directory>/scripts/jev.py decide request.json --dry-run

Luôn kiểm tra result.json. Mã thoát 0 có nghĩa là một kết quả đã được chọn hoặc chấm điểm, 2 có nghĩa là cần xem xét, còn 1 có nghĩa là đã xảy ra lỗi. Việc chọn thành công vẫn không thực thi hành động đã chọn.

Quy trình thực tế: Thêm các điểm kiểm tra quyết định

Jev được thiết kế cho những điểm quyết định có ý nghĩa thay vì mọi bước nhỏ của tác nhân. Hãy thêm một điểm kiểm tra khi lỗi lặp lại, cần chọn một hướng xử lý hoặc tác nhân sắp tuyên bố hoàn tất.

Sử dụng kỹ năng jev để hỗ trợ các quyết định trong khi sửa lỗi phân tích cú pháp CSV và làm cho các bài kiểm thử ban đầu đạt. Nếu thiếu khóa, hãy yêu cầu tôi chọn Jev thực hoặc mô phỏng bằng tác nhân hiện tại. Sử dụng chế độ đã chọn khi lỗi lặp lại, cần chọn hướng xử lý hoặc bạn sắp tuyên bố hoàn tất. Cung cấp mục tiêu, các kiểm tra chấp nhận, lịch sử liên quan, kết quả công cụ mới nhất, quyền hạn và ý nghĩa của từng hành động ứng viên. Chỉ hành động trong phạm vi được cấp phép hiện có và xác minh kết quả sau đó.

Điểm kiểm tra hoàn tất nên nhận bằng chứng thực tế như mã định danh hiện vật, biên nhận kiểm thử, hàm băm bản sửa đổi, kiểm tra hệ thống tệp và trạng thái công việc. Jev có thể đánh giá liệu bằng chứng được cung cấp có hỗ trợ một tuyên bố hay không, nhưng không thể xác nhận rằng một bài kiểm thử thực sự đã chạy hoặc một tệp thực sự tồn tại. Những sự thật đó phải đến từ các công cụ.

Phân loại bản ghi an toàn

Đối với phản hồi, phiếu hỗ trợ hoặc các bản ghi khác, hãy bắt đầu bằng một mẫu nhỏ đã loại bỏ thông tin nhạy cảm. Thống nhất về danh mục, câu hỏi và dữ liệu gửi đi trước khi xử lý một lô lớn hơn.

1. Chọn ba bản ghi tiêu biểu.
2. Giữ nguyên mã định danh, văn bản gốc và ngữ cảnh liên quan của từng bản ghi.
3. Xác định các danh mục như billing, bug, how-to và other.
4. Xem chính xác những gì sẽ rời khỏi máy của bạn.
5. Chọn chế độ API thực hoặc chế độ mô phỏng được phê duyệt rõ ràng.
6. Giữ riêng các kết quả không chắc chắn để con người xem xét.
7. Kiểm tra mẫu trước khi tăng kích thước lô hoặc ngân sách.

Bạn có thể đặt nhiều câu hỏi về mỗi bản ghi trong một yêu cầu, chẳng hạn như danh mục và mức độ khẩn cấp. Với các yêu cầu độc lập, tác nhân máy chủ có thể sử dụng mức đồng thời giới hạn; bản thân CLI không khởi chạy các công việc song song.

Mẹo nâng cao

Cung cấp ngữ cảnh đầy đủ

Jev không tự động kế thừa cuộc trò chuyện của tác nhân. Hãy bao gồm mục tiêu, quy tắc, lịch sử liên quan, bằng chứng nguồn, quan sát hiện tại, quyền hạn, ý nghĩa của các ứng viên và các kiểm tra chấp nhận. Giữ câu hỏi quyết định ở phạm vi hẹp, nhưng đừng làm cho bằng chứng của nó nhỏ đi một cách giả tạo.

Cập nhật tất cả các trường liên quan

Khi điều chỉnh một mẫu, hãy cập nhật đồng thời state, questions và criteria. Chỉ thay đổi văn bản ví dụ có thể khiến định nghĩa ứng viên không nhất quán với tác vụ thực tế.

Tách quyết định khỏi quyền cấp phép

Một hành động đạt điểm cao không tự động được phép thực hiện. Các quyền hiện có và biện pháp kiểm soát an toàn vẫn chi phối việc thực thi. Tương tự, sự nhất quán giữa một kế hoạch và một lệnh gọi công cụ được đề xuất không chứng minh rằng một trong hai đã được cấp phép.

Sử dụng trạng thái mới cho các bước phụ thuộc

Các phán đoán độc lập có thể dùng chung một trạng thái hoặc chạy đồng thời. Các quyết định phụ thuộc nên sử dụng quan sát mới sau hành động trước đó. Jev không thay thế việc lập kế hoạch mở, thực thi công cụ hoặc tạo văn bản.

Diễn giải giá trị chính xác

Đối với câu hỏi noul, probability biểu thị xác suất tuyên bố là đúng, ngay cả khi giá trị được chọn là false. Điểm rubric như 1.29 / 2 là điểm được chấm, không phải xác suất.

Bảo toàn bằng chứng và chế độ

Lưu toàn bộ đầu vào, đầu ra đã chuẩn hóa, biên nhận thô khi có và chế độ thực thi. Giữ nguyên các bằng chứng mâu thuẫn thay vì viết lại để khớp với câu trả lời đã chọn. Không bao giờ trình bày một mô phỏng tác nhân như phản hồi API thực tế.

Kết hợp Jev với các công cụ máy chủ

Thao tác nhấp trong trình duyệt, gửi tin nhắn, chỉnh sửa tệp, tạo nhạc và kết xuất video cần các công cụ riêng biệt. Jev có thể xếp hạng các ứng viên hoặc chọn trong số những hành động hợp lệ đã quan sát, trong khi ứng dụng máy chủ thực thi và xác minh thao tác được chọn.

Kết luận

Jev Skills cung cấp các mẫu có thể tái sử dụng để bổ sung lựa chọn, phân loại, điểm số và kiểm tra bằng chứng rõ ràng vào quy trình làm việc của tác nhân. Hãy bắt đầu bằng quá trình cài đặt có tác nhân hỗ trợ, kiểm thử một ví dụ được cung cấp, xác thực yêu cầu bằng --dry-run và xem xét một mẫu nhỏ trước khi mở rộng quy mô. Kết quả tốt nhất đến từ ngữ cảnh đầy đủ, các ứng viên được xác định rõ ràng, chế độ thực thi minh bạch và việc xác minh độc lập sau mỗi hành động có hệ quả.