Jev thực chiến: quyết định có kiểu dữ liệu, quyền hạn theo phạm vi

Xây dựng cơ chế ủy quyền an toàn cho agent với Jev, LangGraph và Tenuo.

Tóm tắt nhanh: safe-upgrade là một agent nâng cấp thư viện phụ thuộc được xây dựng trên Jev, LangGraph và Tenuo. Jev biến bằng chứng từ kho mã thành các quyết định xác suất có kiểu dữ liệu. LangGraph dẫn dắt những quyết định đó qua một luồng công việc bền vững. Tenuo cấp cho mỗi hành động kết quả một chứng thư giới hạn theo tác vụ. Nguyên tắc thiết kế xuyên suốt: giữ phán đoán, luồng điều khiển và quyền hạn tách biệt nhau.

Chúng tôi bắt đầu từ câu hỏi của một người xây dựng: một luồng công việc hữu ích sẽ trông như thế nào khi Jev, LangGraph và Tenuo mỗi bên đảm nhận một phần riêng biệt của hệ thống?

Nâng cấp thư viện phụ thuộc cho chúng tôi một cách trả lời thực tế, bởi vì — như bất kỳ người bảo trì kho mã nào cũng sớm nhận ra — một quy trình trông có vẻ máy móc lại có thể che giấu những câu hỏi tương thích hóc búa. Bạn đổi một phiên bản, cài gói, chạy kiểm thử, rồi mở pull request, thế nhưng bản phát hành mới có thể đã loại bỏ một API mà kho mã vẫn gọi, thay đổi định dạng module, hoặc thay đổi hành vi mà bộ kiểm thử hiện có không hề chạm tới. Việc cài đặt và CI có thể thành công trong khi ứng dụng vẫn hỏng.

Một agent nâng cấp hữu ích phải diễn giải bằng chứng từ bản phát hành, liên hệ nó với một kho mã xa lạ, quyết định cần làm những gì, sửa mã, và chứng minh rằng kết quả là đáng tin. Nó cũng được cấp quyền truy cập vào tệp nguồn, cài đặt gói, lệnh kiểm thử, Git, và đôi khi cả một kho mã từ xa.

Sự kết hợp này cho phép chúng tôi nghiên cứu cả hai mặt của việc phát triển agent: đưa ra quyết định hữu ích từ ngữ cảnh lộn xộn và kiểm soát những hành động nảy sinh sau đó.

Bắt đầu từ một quyết định mà chương trình có thể dùng được

Kiến trúc ủy quyền an toàn cho agent

Jev là điểm khởi đầu của chúng tôi vì việc nâng cấp thư viện phụ thuộc chứa những câu hỏi ngữ nghĩa mà các quy tắc thông thường xử lý rất kém:

• Ghi chú phát hành này có ảnh hưởng tới cách kho mã này dùng gói hay không?
• Liệu một bài kiểm thử hiện có có phát hiện được lỗi vỡ được báo cáo hay không?
• Bước nào đang đủ điều kiện sẽ giảm được nhiều rủi ro nhất?
• Bản vá cuối cùng có giải quyết từng phát hiện migration hay không?

Jev là một System One Model dành cho các quyết định bên trong phần mềm, nơi lập trình viên cung cấp trạng thái và các câu hỏi có kiểu dữ liệu. Với một Choice (lựa chọn), lập trình viên định nghĩa các phương án sẵn có, và Jev trả về phương án được chọn, một phân phối xác suất, cùng độ tin cậy mà chương trình có thể dùng để định tuyến.

Trong safe-upgrade, mã tất định tính toán trước các hành động đủ điều kiện cùng lý do cho từng hành động. Bộ chuyển đổi production sau đó thực hiện lời gọi TypeSafe SDK như sau:

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient();
const criteria = Object.fromEntries(
  input.eligibleActions.map(({ action, reason }) => [action, reason]),
);
const result = await client.systemOne({
  state: JSON.parse(JSON.stringify(input)),
  questions: {
    next: choice(
      "Choose the eligible action that most directly reduces the unresolved " +
      "risk in this upgrade. Every option is already permitted; pick the " +
      "most useful one.",
      criteria,
    ),
  },
});
const answer = result.answers.next;

Phản hồi Choice thực tế có dạng kiểu dữ liệu như sau. Các giá trị dưới đây minh họa một lần chạy mà việc thêm một bài kiểm thử hồi quy là bước tiếp theo mạnh nhất:

{
  "type": "choice",
  "choice": "author_tests",
  "confidence": 0.82,
  "probabilities": {
    "author_tests": 0.74,
    "assess_verification": 0.18,
    "implement": 0.08
  }
}

Bộ định tuyến xác thực nhãn được chọn so với các ứng viên ban đầu và dùng độ tin cậy bằng TypeScript thông thường:

const choice = validateRouteChoice(
  {
    action: answer.choice,
    confidence: answer.confidence,
    probabilities: answer.probabilities,
  },
  eligibleActions.map(({ action }) => action),
);
const selected = choice.confidence >= confidenceThreshold
  ? choice
  : deterministicFallback(input);
const worker = ACTION_WORKER[selected.action];

Jev đặc biệt hữu ích ở đây vì trạng thái kho mã phong phú có thể vẫn giữ nguyên độ phong phú trong khi kết quả bước vào đồ thị dưới dạng một quyết định nhỏ có kiểu dữ liệu. Độ tin cậy thấp, phản hồi sai định dạng, hoặc lỗi truyền tải sẽ đẩy luồng công việc đi theo một tuyến tất định. Tập ứng viên được thiết lập trước khi gửi yêu cầu, và runtime lại xác thực lựa chọn được trả về một lần nữa sau đó.

Từ quyết định của Jev đến chứng thư Tenuo

Phản hồi của Jev kết thúc bằng một hành động được chọn và độ tin cậy. Việc thực thi bắt đầu khi mã định tuyến đáng tin cậy ánh xạ hành động đó tới một worker đã biết. Điều này dẫn tới câu hỏi kiến trúc tiếp theo: worker đó nên nhận được quyền hạn gì cho lần gọi này?

Với author_tests, câu trả lời là các công cụ đọc kho mã, ghi tệp kiểm thử, và chạy kiểm thử. Trong môi trường production, Tenuo được khởi tạo với một khóa công khai của bên phát hành được tin cậy tường minh, sau đó nhập vào một chứng thư chạy (run warrant) được phát hành từ bên ngoài cùng khóa giữ bằng chứng sở hữu. Đoạn trích bắt đầu từ bước nhập đó. Các bản demo cục bộ dùng một root phát triển và ghi rõ chế độ đó trong kết quả lệnh.

Worker nhận một phiên đầu cuối ngắn hạn được thu hẹp từ chứng thư cha của lần chạy:

const parentSession = tenuo.sessionFromWire({
  warrant: process.env.TENUO_RUN_WARRANT!,
  holderKey: createTenuo.holderKeyFromEnv(
    "TENUO_RUN_HOLDER_SECRET",
  ),
});
const testAuthor = tighten(
  pick(ceilings, [
    ...READ_ONLY,
    "write_test_file",
    "run_check",
  ]),
  "run_check",
  "kind",
  oneOf(["test"]),
);
const childSession = tenuo.narrow(parentSession, testAuthor, {
  terminal: true,
  ttlSeconds: 600,
});

Chứng thư cha đặt ra mức quyền hạn tối đa cho lần chạy. Việc thu hẹp sẽ chọn một tập công cụ nhỏ hơn, siết run_check chỉ còn kiểm thử, rút ngắn thời gian sống, và biến chứng thư con thành phiên đầu cuối (terminal) để nó không thể ủy quyền tiếp.

Worker triển khai nhận một phiên con riêng cho các thay đổi mã nguồn và bản cập nhật thư viện chính xác, với write_test_file bị loại khỏi hồ sơ quyền của nó. Nếu mã triển khai cố gắng làm suy yếu một bài kiểm thử hồi quy, việc ủy quyền sẽ chạy trước công cụ ghi:

await broker.withWorker("implementer", "implement", (handle) =>
  handle.tools.write_test_file({
    path: "src/sneaky.test.ts",
    expectedBeforeHash: "absent",
    content: "test.skip('regression', () => {});",
  }),
);

Bản ghi từ chối trong kiểm thử bắt đầu như sau:

TENUO_TOOL_NOT_AUTHORIZED
worker: implementer
capability: write_test_file

Bài kiểm thử ủy quyền cũng xác nhận rằng hàm ghi bên dưới không hề được chạy. Bản ghi từ chối bao gồm worker, năng lực, hàm băm đối số và mã định danh phiên, đồng thời bỏ đi nội dung tệp đã cố ghi. Điều này biến các vai trò trong đồ thị thành những ranh giới thực thi được cưỡng chế: người viết kiểm thử viết kiểm thử, người triển khai viết mã nguồn, còn người xác minh chỉ đọc và chạy kiểm tra với các tệp ứng viên được giữ ở chế độ chỉ đọc.

LangGraph dẫn kết quả qua luồng công việc

LangGraph lưu giữ các dữ kiện về kho mã, phát hiện, quyết định, nỗ lực và bằng chứng xuyên suốt lần chạy. Mỗi nút nhận trạng thái tường minh và trả về một cập nhật, trong khi các checkpoint bảo toàn tiến độ tại những ranh giới có ý nghĩa.

bằng chứng kho mã
       |
       v
mã đáng tin cậy tính toán các chuyển tiếp đủ điều kiện
       |
       v
Jev lựa chọn trong tập có kiểu dữ liệu đó
       |
       v
mã đáng tin cậy ánh xạ hành động tới một worker
       |
       v
Tenuo thu hẹp chứng thư cho worker đó
       |
       v
các công cụ được bảo vệ trả bằng chứng về LangGraph

Một bước đánh giá chỉ dùng các worker thiên về đọc và ghi lại các tệp bị ảnh hưởng, phát hiện migration, các kiểm tra hiện tại và lỗ hổng xác minh. Việc áp dụng đánh giá đó có thể thêm một bài kiểm thử tập trung, di trú mã nguồn, cập nhật đúng thư viện phụ thuộc, và xác minh ứng viên trong một Git worktree dùng một lần. Bản đánh giá được ràng buộc với commit, manifest, lockfile và trạng thái working tree mà nó đã khảo sát.

Vì sao điều này quan trọng trong CI

Những ranh giới tương tự trở nên quan trọng hơn khi agent chạy không giám sát trong GitHub Actions. Một job CI có thể có bản checkout kho mã, bộ nhớ đệm của trình quản lý gói, token GitHub, và quyền bình luận hoặc mở pull request. Quyền hạn ở cấp job xác định danh tính luồng công việc có thể chạm tới đâu. Chúng chỉ cung cấp rất ít chi tiết về việc vì sao lần chạy cụ thể này lại được phép thay đổi một gói, một nhánh hay một tệp cụ thể.

safe-upgrade có thể đánh giá một pull request Dependabot từ sự kiện của nó hoặc mở một bản nâng cấp đã được xác minh dưới dạng bản nháp. Trong production, tiến trình CI nhập vào một chứng thư chạy do một root tin cậy phát hành. Chứng thư đó có thể ràng buộc lần chạy với gói và phiên bản chính xác được yêu cầu, worktree tạm thời, một nhánh, và chỉ được xuất bản dạng nháp. Mỗi nút đồ thị nhận một chứng thư con hẹp hơn từ mức trần đó.

Điều này mang lại cho pipeline hai mức kiểm soát:

• Quyền của GitHub Actions giới hạn danh tính luồng công việc, ví dụ contents: read và pull-requests: write cho một job đánh giá.
• Chứng thư Tenuo giới hạn từng tác vụ được ủy quyền, bao gồm công cụ được phép, đối số, đường dẫn, phiên bản gói, nhánh và thời gian sống.

Sự phân biệt này quan trọng với bất kỳ agent CI nào có thể sửa mã hoặc dùng thông tin xác thực của kho mã. Danh tính luồng công việc trả lời câu hỏi chủ thể nào đang chạy. Chứng thư ở cấp tác vụ mang quyền hạn của bản nâng cấp cụ thể xuyên suốt mọi bước được ủy quyền.

"An toàn" ở đây nghĩa là gì

Kiến trúc này định nghĩa an toàn thông qua những thuộc tính có thể kiểm tra được:

• Quyết định đóng. Jev chỉ chọn trong số các chuyển tiếp mà mã đáng tin cậy đã xác định là đủ điều kiện.
• Thực thi theo phạm vi. Mỗi worker nhận một chứng thư ngắn hạn cho công cụ và đối số của nó.
• Tách biệt nhiệm vụ. Việc viết kiểm thử, triển khai, xác minh và xuất bản dùng các quyền ghi khác nhau.
• Bằng chứng độc lập. Việc xác minh đánh giá từng phát hiện trong khi các tệp ứng viên vẫn ở chế độ chỉ đọc.
• Tiến trình bị cô lập. Tenuo ủy quyền cho các lời gọi công cụ được bảo vệ, trong khi một sandbox của hệ điều hành giới hạn những gì tiến trình kho mã và gói có thể truy cập.
• Bất định tường minh. Độ tin cậy thấp, trạng thái cũ, vi phạm chính sách và bằng chứng không đầy đủ đều tạo ra kết quả bị chặn hoặc bị đánh dấu có điều kiện.

Jev vẫn có thể đọc sai phần mô tả bản phát hành, các kiểm tra kho mã vẫn có thể bỏ sót hành vi quan trọng, và lớp bọc đáng tin cậy vẫn có thể mã hóa một chính sách sai. Những câu hỏi hẹp, định tuyến nhận biết độ tin cậy, chứng thư theo phạm vi và bằng chứng độc lập giúp những bất định đó trở nên hữu hình và giới hạn các hành động có thể nảy sinh từ chúng.

Giữ thành phần đề xuất hành động tách biệt khỏi thành phần định nghĩa quyền hạn của hành động đó.

Mô thức có thể tái sử dụng

Mô thức này mở rộng ra ngoài phạm vi nâng cấp thư viện phụ thuộc:

1. Tính toán các chuyển tiếp hợp lệ từ trạng thái đáng tin cậy.
2. Hỏi Jev một câu hỏi ngữ nghĩa có giới hạn trên những chuyển tiếp đó.
3. Xác thực phản hồi có kiểu dữ liệu và ánh xạ nó tới một worker đã biết.
4. Ủy quyền một chứng thư Tenuo đã thu hẹp cho tác vụ của worker đó.
5. Trả bằng chứng về LangGraph và xác minh nó một cách độc lập.

Toàn bộ chồng công nghệ này dựa trên một nguyên tắc duy nhất: giữ thành phần đề xuất hành động tách biệt khỏi thành phần định nghĩa quyền hạn của nó.

Bạn có thể khám phá phần triển khai trong kho mã safe-upgrade hoặc chạy nó từ npm:

npx @tenuo/safe-upgrade doctor
npx @tenuo/safe-upgrade assess --repository .

Phần triển khai được trình bày ở đây được xây dựng dựa trên @typesafe-ai/sdk 0.6.0 và @tenuo/core 0.3.0-beta.0. Chúng tôi cũng đã xác minh toàn bộ luồng phê duyệt với API Jev đang hoạt động, và kho mã có kèm bài kiểm thử smoke đầu-cuối.

Mô hình yêu cầu và phản hồi của Jev được tài liệu hóa trong phần TypeSafe quick start, còn Tenuo có sẵn trên GitHub.

safe-upgrade là một agent nâng cấp thư viện phụ thuộc mã nguồn mở được xây dựng với Jev, LangGraph và Tenuo. Mã nguồn và các ví dụ chạy được có sẵn trong kho mã safe-upgrade.