Xây dựng quy trình quyết định nhanh, chuyên biệt cho từng tác vụ với JevHarness

JevHarness thực hiện những gì

JevHarness giúp một LLM biên soạn tạo ra một bộ khung ra quyết định dành riêng cho tác vụ của Jev. Bộ khung này chuyển đổi các quan sát được phép thành những đặc trưng hữu ích, xây dựng các câu hỏi và tiêu chí Jev có cấu trúc, rồi kết hợp các câu trả lời thành những hành động hợp lệ cho tác vụ.

Ý tưởng cốt lõi là tách quá trình phát triển chiến lược tốn kém khỏi việc thực thi thường nhật:

Suy luận sâu trong quá trình phát triển. Đóng băng chiến lược. Để Jev đưa ra các quyết định nhanh và linh hoạt.

Trong quá trình phát triển, một LLM có thể sửa đổi mã bộ khung, câu hỏi, đồ thị, trạng thái, tiêu chí và bộ nhớ. Sau khi bạn chọn và đóng băng một bộ khung, các quyết định lúc chạy sẽ sử dụng logic cố định đó cùng các lệnh gọi Jev của nó. LLM biên soạn không cần phải suy luận lại từng hành động.

Điều này khiến JevHarness phù hợp với các tác vụ mà mã có thể tính toán những dữ kiện đáng tin cậy, nhưng một số quyết định vẫn mang tính ngữ cảnh hoặc mơ hồ. Ví dụ, mã có thể xác định các hành động hợp lệ và tính toán những đặc trưng số, trong khi Jev đánh giá hành động khả dụng nào đáp ứng tốt nhất các tiêu chí dành riêng cho tác vụ.

Kiến trúc và ranh giới trách nhiệm

JevHarness tách bộ điều hợp tác vụ đáng tin cậy khỏi bộ khung ra quyết định. Ranh giới này ngăn bộ khung tự thay đổi phần thưởng hoặc truy cập trạng thái ẩn của tác vụ.

• Bộ điều hợp tác vụ: Sở hữu các quan sát, hành động hợp lệ, hiệu ứng phụ và việc chấm điểm.
• Bộ khung: Sở hữu việc xây dựng đặc trưng, các phán đoán Jev và logic ra quyết định.
• Môi trường: Thực thi hành động và trả về kết quả hoặc phần thưởng đáng tin cậy.
• LLM biên soạn: Tạo hoặc sửa đổi bộ khung trong quá trình phát triển và phản tư tùy chọn.

Một PipelineSpec đã được xác thực sẽ được thực thi thông qua PipelineRuntime. Sau khi được chọn, pipeline có thể được đóng băng cùng với đặc tả, runtime, bộ đánh giá và các tài nguyên tác vụ đã khai báo.

Tính năng chính

Phán đoán Jev có cấu trúc

Jev hỗ trợ các loại câu trả lời choice, score và noul. Một yêu cầu có thể chứa nhiều câu hỏi được đặt tên, đồng thời các nút độc lập trong đồ thị có thể thực thi đồng thời.

Biểu diễn chiến lược rõ ràng

Chiến lược được duy trì trong mã, các đặc trưng được tính toán, trạng thái, hướng dẫn, tiêu chí, bộ nhớ và luồng điều khiển. Điều này khiến quá trình ra quyết định có thể kiểm tra và tái sử dụng, thay vì bị giữ lại trong một cuộc hội thoại biên soạn.

Dấu vết thực thi đầy đủ

Phản tư có thể nhận các bản ghi đầy đủ của những episode được chọn, bao gồm quan sát, quyết định, đầu vào và đầu ra của nút, câu hỏi và câu trả lời Jev, bộ nhớ và lỗi. Việc loại bỏ trùng lặp không mất dữ liệu giúp giảm sự lặp lại. Nếu dữ liệu đầu vào cho phản tư vượt quá giới hạn byte đã cấu hình, dữ liệu sẽ được lưu trữ và từ chối thay vì bị cắt ngầm.

Cải thiện tùy chọn dựa trên phần thưởng

Tích hợp GEPA tùy chọn chọn các phiên bản cha từ frontier của instance, so sánh từng phiên bản cha và đề xuất trên cùng một batch huấn luyện, rồi đánh giá các đề xuất được chấp nhận trên Eval. Tích hợp này ghi lại quan hệ tổ tiên thực tế, bao gồm cả các đề xuất bị từ chối.

Các hiện vật đã đóng băng có thể kiểm tra

Việc đóng băng bảo toàn bộ khung đã chọn cùng các phần phụ thuộc đã khai báo. Một bộ khung đã đóng băng chứa các nút Jev vẫn cần Jev lúc chạy. Cũng cần lưu ý rằng bí danh mô hình được lưu trữ không đảm bảo hành vi tương lai của nhà cung cấp sẽ không thay đổi, vì vậy các phản hồi đã lưu trữ và các lệnh gọi mới cung cấp những mức độ tái lập khác nhau.

Điều kiện tiên quyết

Chọn các yêu cầu phù hợp với nội dung bạn muốn chạy:

• Website lưu trữ: Node.js và một trình duyệt hiện đại. Không cần thông tin xác thực mô hình, game engine hoặc sandbox Python.
• Dự án Python: Python 3.11 trở lên.
• Các nút Python chức năng: Sandbox native macOS được hỗ trợ. Nếu không thể cô lập, quá trình thực thi sẽ dừng an toàn.
• Các luồng biểu thức và Jev phiên bản 2: Những luồng này không khởi chạy các worker Python chức năng.
• Các lệnh gọi Jev trực tiếp: Tài khoản nhà cung cấp được hỗ trợ và API key tương ứng.
• Biên soạn và phản tư tùy chọn: Một Proposer đã được cấu hình, sử dụng Claude CLI cục bộ hoặc endpoint OpenAI, Azure hay Anthropic.

Cài đặt Skill trong Claude Code

Cách thiết lập Claude Code nhanh nhất là thêm repository dưới dạng plugin marketplace, cài đặt plugin rồi tải lại các plugin.

/plugin marketplace add https://github.com/TianyuCodings/JevHarness.git
/plugin install jev-harness@jevharness
/reload-plugins

Việc cài đặt plugin sẽ tải skill và các tài liệu tham chiếu của skill, nhưng không cài đặt các phần phụ thuộc Python hoặc cấu hình thông tin xác thực mô hình. Nếu repository ở chế độ riêng tư, xác thực GitHub phải hoạt động trước và tài khoản của bạn phải có quyền đọc.

Cài đặt Skill trong Codex

Trong một máy chủ Codex có cung cấp skill-installer tích hợp, hãy yêu cầu cài đặt trực tiếp từ repository:

$skill-installer Install the jev-harness skill from https://github.com/TianyuCodings/JevHarness/tree/main/skills/jev-harness

Sử dụng skill ở lượt tiếp theo. Nếu Codex không phát hiện skill ngay lập tức, hãy khởi động lại phiên.

Cài đặt thủ công

Bạn có thể cài đặt skill thủ công cho Claude Code, Codex hoặc cả hai. Thay /path/to/your-project bằng một thư mục dự án hiện có.

git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
python3 scripts/install-skill.py --target both --scope project --project /path/to/your-project

Lệnh này tạo các bản cài đặt cấp dự án tại .agents/skills/jev-harness/ cho Codex và .claude/skills/jev-harness/ cho Claude Code. Sử dụng --target codex hoặc --target claude để chỉ cài đặt một bên.

Để cài đặt ở cấp người dùng và dùng được trên nhiều dự án, hãy chạy:

python3 scripts/install-skill.py --target both --scope user

Các vị trí cài đặt cá nhân là ~/.agents/skills/jev-harness/ và ~/.claude/skills/jev-harness/. Trình cài đặt sẽ từ chối ghi đè một bản cài đặt khác đang tồn tại. Hãy khởi động lại phiên tác nhân nếu không phát hiện được skill.

Khám phá ví dụ Pokémon đã lưu trữ

Ví dụ Pokémon đi kèm cung cấp một lần chạy đã lưu trữ, harness được chọn, cây tiến hóa có thể duyệt, đầy đủ bản ghi quyết định, các đề xuất bị từ chối và những điểm nổi bật khi phát lại được đồng bộ với câu trả lời của Jev. Việc duyệt kho lưu trữ này không gửi yêu cầu đến mô hình và không khởi chạy trận đấu nào.

1. Sao chép repository.
2. Build website.
3. Khởi động máy chủ xem trước cục bộ.
4. Mở trang web trong một trình duyệt hiện đại.

git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
node website/build.mjs
node website/preview.mjs --port 8768

Mở localhost:8768. Hoạt ảnh trận đấu sẽ tải tài nguyên từ trình kết xuất Pokémon Showdown chính thức. Nhật ký trận đấu đã lưu trữ vẫn nằm trong trình duyệt và không được tải lên máy chủ phát lại.

Kết quả Pokémon được báo cáo đã cải thiện tỷ lệ thắng Eval từ 25 phần trăm, tương đương 3 trong 12 trận, lên 75 phần trăm, tương đương 9 trong 12 trận, sau năm vòng phản tư. Quá trình tìm kiếm giữ lại ứng viên ở vòng ba làm harness tốt nhất. Kết quả này được đo trên tập Eval dùng để lựa chọn và không nên được xem là ước tính độc lập về hiệu suất trên các trận đấu chưa được thấy.

Hiểu một quyết định cơ bản

Một harness tạo yêu cầu Jev dành riêng cho tác vụ, bao gồm state, các questions có tên, type của câu trả lời, cùng instructions và criteria dùng để đánh giá các hành động khả dụng.

Trong ví dụ Pokémon được ghi lại, harness tính toán rằng Slowbro có khả năng thua Gastrodon trong cuộc đua sát thương. Harness đưa ra bốn lựa chọn hợp lệ, gồm ba chiêu thức và việc chuyển sang Scizor. Câu hỏi về hành động sử dụng kiểu choice và yêu cầu Jev trả về chính xác một ID hành động được liệt kê.

{
  "questions": {
    "action": {
      "type": "choice",
      "instructions": "Chọn hành động duy nhất có khả năng thắng toàn bộ trận đấu cao nhất, không chỉ lượt này.",
      "criteria": {
        "switch:2": "chuyển sang Scizor; chuyển đổi đồng nghĩa với việc cho đối thủ một đòn đánh miễn phí",
        "move:2": "Psychic; cần khoảng 3 đòn để hạ mục tiêu",
        "move:3": "Ice Beam; cần khoảng 4 đòn để hạ mục tiêu",
        "move:4": "Slack Off; sát thương dự kiến nhận vào vượt quá HP hiện tại"
      }
    }
  }
}

Jev chọn switch:2 với xác suất chọn hành động là 0.72, và harness chấp nhận lựa chọn đó. Giá trị này dùng để so sánh các hành động được liệt kê; nó không dự đoán rằng người chơi có 72 phần trăm cơ hội thắng trận.

Yêu cầu, câu trả lời, thời gian và nguồn gốc đầy đủ được ghi lại trong bản ghi JSON lượt 12 của Pokémon.

Xây dựng harness của riêng bạn

Bạn không cần tự viết toàn bộ hướng dẫn và tiêu chí cho Jev. Hãy gọi skill đã cài đặt và mô tả tác vụ, sau đó để coding agent thu thập các chi tiết cần thiết của hợp đồng.

Gọi plugin Claude Code

/jev-harness:jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

Gọi Claude Code độc lập

/jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

Gọi Codex

$jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

Skill trước hết nên làm rõ tác vụ thay vì ngay lập tức tạo pipeline. Hãy chờ skill thu thập thông tin về:

• Các quan sát tác vụ được phép và ranh giới trạng thái ẩn.
• Các hành động hợp lệ và cách xác thực hành động.
• Các ví dụ đại diện và dữ liệu hiện có.
• Tiêu chí thành công, phần thưởng hoặc quy trình đánh giá.
• Yêu cầu về thời gian chạy và cô lập.
• Thông tin xác thực và khả năng cung cấp của nhà cung cấp.
• Ngân sách thử nghiệm và tài nguyên tối ưu hóa.

Khi hợp đồng đã rõ ràng, agent có thể xây dựng và xác thực harness. Nếu có phản hồi đáng tin cậy và bạn yêu cầu tối ưu hóa, agent có thể sử dụng các quỹ đạo và phần thưởng để phản tư trước khi cố định kết quả được chọn.

Cấu hình thông tin xác thực Jev

JevHarness hỗ trợ hai cấu hình truyền tải Jev được ghi nhận:

• Vercel AI Gateway: Tạo JevClient(transport="vercel") và đặt AI_GATEWAY_API_KEY.
• Trực tiếp qua TypeSafe: Tạo JevClient(transport="typesafe") và đặt TYPESAFE_API_KEY.

Các bộ chuyển đổi nhà cung cấp không đảm bảo mọi mô hình hoặc endpoint đều khả dụng với tài khoản của bạn. Lưu thông tin xác thực trong biến môi trường hoặc tệp .env cục bộ đã được bỏ qua. Không bao giờ đưa thông tin xác thực vào các quan sát tác vụ, trace hoặc artifact đã cố định.

Đánh giá và cải thiện harness

Phản tư là tùy chọn. Chỉ sử dụng khi bạn có phương pháp đánh giá hoặc phần thưởng đáng tin cậy. Một quy trình thực tế là:

1. Xác định phạm vi tác vụ. Giữ trạng thái ẩn, việc tính điểm, xác thực hành động hợp lệ và các tác động phụ trong bộ điều hợp đáng tin cậy.
2. Tạo bộ khung cơ sở. Tính các đặc trưng đáng tin cậy bằng mã và dành Jev cho những phán đoán phụ thuộc vào ngữ cảnh.
3. Xác thực quy trình. Xác nhận rằng PipelineSpec và runtime đáp ứng hợp đồng của tác vụ.
4. Thu thập trace đầy đủ. Lưu giữ các quan sát, đầu vào và đầu ra của nút, câu hỏi, câu trả lời, bộ nhớ, lỗi và phần thưởng.
5. Đề xuất các bản sửa đổi. Cho phép LLM soạn thảo kiểm tra bằng chứng và sửa đổi mã, prompt, cấu trúc đồ thị hoặc bộ nhớ.
6. So sánh công bằng. So sánh bản gốc và bản đề xuất trên cùng một batch huấn luyện.
7. Đánh giá các đề xuất được chấp nhận. Chạy đánh giá Eval đầy đủ và lưu lại nguồn gốc thực tế của ứng viên, bao gồm cả các đề xuất bị từ chối.
8. Đóng băng bộ khung đã chọn. Gắn đặc tả chiến thắng với runtime, bộ đánh giá và các tài nguyên tác vụ đã khai báo.

Giữ bằng chứng huấn luyện và kết quả lựa chọn của Eval tách biệt rõ ràng. Nếu Eval được dùng để chọn ứng viên, hãy báo cáo đó là hiệu suất lựa chọn thay vì ước tính không thiên lệch về hiệu suất trên các tác vụ chưa thấy.

Độ trễ và tính đồng thời

Trong lần chạy Eval Pokémon được lưu trữ, bộ khung đã chọn hoàn tất một quyết định đầy đủ trong thời gian trung vị 568 mili giây. Các yêu cầu Jev riêng lẻ có thời lượng trung vị 269 mili giây. Bộ khung ban đầu có thời gian quyết định đầy đủ trung vị 678 mili giây.

• Quyết định đầy đủ của bộ khung ban đầu: trung vị 678 ms, P95 1.495 ms, 238 quyết định.
• Quyết định đầy đủ của bộ khung đã chọn: trung vị 568 ms, P95 657 ms, 113 quyết định.
• Yêu cầu Jev riêng lẻ của bộ khung đã chọn: trung vị 269 ms, P95 348 ms, 226 yêu cầu.

Thời gian quyết định đầy đủ bao gồm việc tính đặc trưng, các lệnh gọi Jev song song và lựa chọn hành động cuối cùng. Thời gian của từng yêu cầu bao gồm chi phí của client và mạng. Thời lượng các lệnh gọi song song chồng lấp lên nhau, vì vậy không nên cộng chúng lại. Mô phỏng trận đấu và thời gian soạn thảo hoặc phản tư nằm ngoài các phép đo quyết định này.

Các quan sát được lưu trữ này không bao gồm các lần truy cập bộ nhớ đệm phản hồi cục bộ, nhưng chúng cũng không phải là phép đo chuẩn có kiểm soát so với một LLM thực hiện mọi quyết định runtime.

Mẹo nâng cao

Tính toán sự kiện trước khi yêu cầu phán đoán

Sử dụng mã hoặc biểu thức xác định cho các sự kiện như hành động hợp lệ, ước tính số, ngưỡng và trạng thái suy ra. Cung cấp cho Jev trạng thái tập trung cùng các tiêu chí rõ ràng cho lựa chọn còn mơ hồ.

Làm cho tiêu chí hành động trở nên cụ thể

Mô tả từng hành động khả dụng bằng bằng chứng liên quan đến tác vụ. Trong bộ khung Pokémon, các tiêu chí bao gồm lượng máu còn lại, ước tính sát thương, tốc độ, số lượt cần để hạ gục và cái giá của việc bỏ lỡ một đòn tấn công miễn phí khi đổi Pokémon.

Sử dụng các nút song song khi thực sự độc lập

Các nút độc lập trong đồ thị có thể chạy đồng thời và nhiều câu hỏi có thể dùng chung một yêu cầu. Cấu trúc đồ thị để tận dụng điều này mà không tạo ra các phụ thuộc không cần thiết cho tác vụ.

Kiểm tra xác suất đúng cách

Xác suất lựa chọn xếp hạng các tùy chọn được cung cấp trong yêu cầu. Không diễn giải lại nó thành xác suất đã hiệu chuẩn của thành công toàn bộ tác vụ, trừ khi bộ đánh giá của bạn xác lập riêng ý nghĩa đó.

Lưu giữ đầy đủ các lỗi

Lỗi có thể cho thấy các giả định không hợp lệ, những quan sát bị thiếu và các tiêu chí mong manh. Giữ chúng trong trace cùng với các quyết định thành công để quá trình phản tư nhận được đầy đủ bằng chứng.

Tránh cắt ngắn âm thầm

Cấu hình giới hạn byte phản tư thực tế. JevHarness lưu trữ và từ chối các đầu vào phản tư quá kích thước thay vì cắt ngắn chúng, qua đó bảo vệ tính toàn vẹn của bằng chứng nhưng yêu cầu bạn lập kế hoạch quy mô thí nghiệm phù hợp.

Phân biệt logic bị đóng băng với hành vi của nhà cung cấp bị đóng băng

Việc đóng băng bộ khung cố định pipeline và các tài nguyên đã khai báo mà bạn chọn, nhưng bí danh mô hình được lưu trữ có thể thay đổi theo thời gian. Lưu giữ các phản hồi đã ghi lại khi cần kiểm tra chính xác trong quá khứ và xem các lệnh gọi mới đến nhà cung cấp là một điều kiện tái lập khác.

Sử dụng bản đồ kho mã

• auto_jev/ chứa chức năng xác thực đặc tả, runtime song song, các phương thức truyền tải Jev, phản tư, GEPA, lưu trữ và đóng băng.
• examples/pokemon/ chứa bộ điều hợp trận đấu đáng tin cậy, cầu nối đến engine cục bộ có seed, các bộ khung và mã trình bày.
• examples/pokemon/sample/ chứa bộ khung đã chọn và kho lưu trữ website được tuyển chọn.
• docs/ chứa tài liệu soạn thảo tác vụ, một lệnh gọi Jev đã ghi lại, video và ảnh chụp màn hình.
• skills/jev-harness/ chứa hướng dẫn dành cho các tác nhân lập trình soạn bộ khung chuyên biệt cho từng tác vụ.
• website/ chứa bản trình diễn chỉ đọc và bộ điều hợp triển khai.

Kết luận

JevHarness biến chiến lược do LLM phát triển thành logic runtime rõ ràng và có thể kiểm tra. Hãy bắt đầu bằng việc xác định ranh giới tác vụ nghiêm ngặt, để skill xây dựng và xác thực pipeline, đồng thời sử dụng trace đầy đủ cùng phần thưởng đáng tin cậy nếu muốn cải thiện dựa trên phản tư. Khi đã chọn được ứng viên, hãy đóng băng ứng viên đó để các quyết định thường lệ có thể sử dụng mã của nó và những phán đoán Jev tập trung mà không cần gọi LLM soạn thảo cho từng hành động.