Chuyển đến nội dung chính
Hướng dẫn AI

Bảo toàn chính xác ngữ cảnh Claude Code với fast-jev-compaction

Tìm hiểu cách cài đặt và sử dụng fast-jev-compaction dưới dạng thư viện npm hoặc plugin Claude Code. Hướng dẫn này giải thích các quyết định dựa trên Jev, tùy chọn cấu hình, hỗ trợ transport tùy chỉnh, cách xử lý lỗi và các kỹ thuật rút gọn an toàn bản ghi dài mà vẫn giữ nguyên văn những đoạn văn bản quan trọng.

Thời gian đọc khoảng 22 phút
Bảo toàn chính xác ngữ cảnh Claude Code với fast-jev-compaction

fast-jev-compaction hoạt động như thế nào

fast-jev-compaction là một thư viện npm và plugin Claude Code dùng để giảm độ dài bản ghi phiên làm việc của agent mà không viết lại chúng thành bản tóm tắt. Thay vào đó, thư viện yêu cầu mô hình Jev chấm điểm các lệnh gọi công cụ cũ và kết quả công cụ, sau đó giữ lại, rút gọn hoặc xóa chúng theo các ngưỡng có thể cấu hình.

Văn bản của người dùng và assistant vẫn được giữ nguyên từng chữ và theo đúng thứ tự ban đầu. Chỉ các lệnh gọi công cụ và kết quả tương ứng mới có thể bị xóa. Điều này giúp tránh làm mất các ràng buộc chính xác, đường dẫn tệp, lệnh và thông báo lỗi do việc tóm tắt thông thường.

Kho mã nguồn chứa cả gói có thể tái sử dụng trong src/ và plugin function-hook cho Claude Code trong hooks/ và .claude-plugin/.

Cách thức rút gọn

  1. Mỗi tool_use được ghép với tool_result tương ứng thông qua tool_use_id.

  2. Các lệnh gọi trong tin nhắn đầu tiên và preserveRecentMessages tin nhắn mới nhất được ghim, vì vậy chúng không bị thay đổi.

  3. Toàn bộ cuộc hội thoại được cung cấp cho Jev theo thứ tự từ cũ nhất đến mới nhất. Trong trạng thái ra quyết định này, nội dung kết quả công cụ được thay thế bằng các ghi chú ngắn như ok, 4213 chars (omitted), còn đầu vào công cụ và văn bản vẫn có sẵn.

  4. Với mỗi lệnh gọi không được ghim, Jev trả lời hai câu hỏi: việc biết về lệnh gọi đó còn quan trọng hay không, và có cần giữ nguyên toàn bộ kết quả hay không.

  5. Các xác suất được trả về sẽ được so sánh với keepThreshold.

  6. Bản ghi được dựng lại mà không để lại kết quả mồ côi.

Kết quả quyết định

  • Nếu điểm kết quả đạt ngưỡng, cả lệnh gọi và toàn bộ kết quả đều được giữ lại.

  • Nếu chỉ điểm lệnh gọi đạt ngưỡng, lệnh gọi được giữ lại và kết quả được rút gọn còn truncateHeadChars ký tự đầu tiên, theo sau là một ghi chú.

  • Nếu không điểm nào đạt ngưỡng, lệnh gọi và kết quả của nó sẽ bị xóa cùng nhau.

Các tin nhắn trở nên rỗng sẽ bị xóa. Những tin nhắn không cần thay đổi được trả về dưới dạng chính các object ban đầu.

Đưa lịch sử lớn vào các yêu cầu Jev

Trạng thái ra quyết định có giới hạn mặc định là 25000 token ước tính. Nếu trạng thái ban đầu quá lớn, thư viện sẽ lần lượt rút gọn biểu diễn được hiển thị cho Jev. Thư viện cắt ngắn đầu vào công cụ, rút gọn văn bản dài bằng cách giữ phần đầu và phần cuối, gom các tin nhắn cũ, giảm các lệnh gọi cũ thành bản ghi một dòng, bỏ qua các tin nhắn cũ không có lệnh gọi và gộp các chuỗi tin nhắn cũ chỉ chứa lệnh gọi.

Các phép biến đổi này chỉ ảnh hưởng đến trạng thái dùng để chấm điểm, không ảnh hưởng đến văn bản được giữ lại trong bản ghi cuối cùng. Nếu trạng thái vẫn không thể vừa khung, quá trình rút gọn sẽ báo lỗi.

Các câu hỏi cũng được chia thành nhiều lô để mỗi yêu cầu gồm trạng thái và câu hỏi vẫn nằm dưới maxRequestTokens, mặc định là 30000. Các yêu cầu chạy đồng thời và các quyết định của chúng được hợp nhất.

Cài đặt thư viện npm

Cài đặt gói và cung cấp khóa API TypeSafe thông qua biến môi trường:

npm install fast-jev-compaction
export TYPESAFE_API_KEY=...

Không commit khóa API hoặc đặt trực tiếp khóa này trong tệp mã nguồn.

Client mặc định đọc process.env.TYPESAFE_API_KEY. Bạn cũng có thể cung cấp tùy chọn apiKey khi gọi API.

Rút gọn bản ghi

Import compactMessages, chuẩn bị một bản ghi và truyền vào mọi tùy chọn khác với giá trị mặc định:

import {
  compactMessages,
  reductionRatio,
  type Message,
} from 'fast-jev-compaction';

const transcript: Message[] = [
  {
    role: 'user',
    text: 'Fix the failing test. Never edit src/generated.',
    toolUses: [],
  },
  {
    role: 'assistant',
    text: '',
    toolUses: [
      {
        tool_use_id: 'toolu_1',
        tool: 'Read',
        input: { file_path: 'src/a.ts' },
      },
    ],
  },
  {
    role: 'user',
    text: '',
    toolUses: [],
    toolResults: [
      { tool_use_id: 'toolu_1', text: '…file contents…' },
    ],
  },
];

const result = await compactMessages(transcript, {
  preserveRecentMessages: 4,
});

console.log(result.messages);
console.log(result.decisions);
console.log(result.stats);

Kiểu Message được export là một tập con của SessionMessage trong Claude Code, vì vậy bản ghi phiên Claude Code có thể được truyền trực tiếp vào gói.

Kiểm tra liệu việc rút gọn có đáng thực hiện hay không

Gói export reductionRatio, có thể giúp ứng dụng quyết định có nên sử dụng lịch sử đã rút gọn hay không:

const result = await compactMessages(transcript);

if (reductionRatio(result) < 0.25) {
  // Keep the original transcript or use another fallback.
} else {
  // Continue with result.messages.
}

Thống kê kết quả bao gồm số lượng tin nhắn và ký tự trước và sau khi rút gọn, số lượng quyết định được nhóm theo lý do, kích thước trạng thái ước tính, giai đoạn điều chỉnh đã sử dụng và số lượng yêu cầu Jev.

Cấu hình hành vi rút gọn

Các tùy chọn chính gồm:

  • apiKey: Khóa API TypeSafe. Mặc định là TYPESAFE_API_KEY.

  • model: Tên model Jev. Mặc định là jev-latest.

  • baseUrl: Endpoint System One. Mặc định là https://api.typesafe.ai/v1/systemone.

  • fetch: Triển khai fetch có thể chèn, đặc biệt hữu ích trong các bài kiểm thử.

  • goal: Mô tả tác vụ đang thực hiện được đưa vào state. Mặc định sử dụng ba prompt gần nhất của người dùng.

  • keepThreshold: Xác suất tối thiểu cần có để giữ một lệnh gọi hoặc toàn bộ kết quả. Mặc định là 0.5.

  • preserveRecentMessages: Số tin nhắn mới nhất không thể bị sửa đổi. Mặc định là 6; tin nhắn đầu tiên cũng luôn được giữ lại.

  • maxStateTokens: Giới hạn token ước tính cho state quyết định. Mặc định là 25000.

  • maxRequestTokens: Giới hạn token ước tính cho state và các câu hỏi trong một request. Mặc định là 30000.

  • truncateHeadChars: Số ký tự đầu được giữ lại khi cắt ngắn một kết quả. Mặc định là 300.

const result = await compactMessages(transcript, {
  goal: 'Fix the test without editing generated files',
  keepThreshold: 0.6,
  preserveRecentMessages: 8,
  truncateHeadChars: 500,
});

keepThreshold cao hơn yêu cầu xác suất giữ lại mạnh hơn và do đó có thể loại bỏ nhiều hoạt động công cụ hơn. Vì xác suất không chứng minh rằng việc xóa là an toàn, hãy đánh giá các thay đổi ngưỡng trên những transcript đại diện.

Sử dụng transport Jev tùy chỉnh

Nếu client TypeSafe tích hợp sẵn không phù hợp với môi trường của bạn, hãy triển khai interface JevAsker được export. Interface này yêu cầu phương thức ask(state, questions). Sau đó gọi compact(messages, asker, options) thay vì compactMessages.

Package cũng export buildJevRequest để tạo body của HTTP request và parseJevResponse để xác thực response. Các khối xây dựng cấp thấp hơn có sẵn cho những tích hợp chuyên biệt hơn:

  • collectToolCalls ghép các lệnh gọi với kết quả tương ứng.

  • fitState chuẩn bị state trong giới hạn kích thước đã cấu hình.

  • batchCalls chia các câu hỏi thành nhiều request.

  • decideCall chuyển điểm số thành quyết định giữ lại, cắt ngắn hoặc xóa.

  • applyDecisions dựng lại lịch sử tin nhắn.

Cài đặt plugin Claude Code

Plugin yêu cầu Claude Code 2.1.274 trở lên. Function hook là tính năng truy cập sớm, vì vậy hãy bật chúng ở mọi nơi Claude Code chạy. Ví dụ, thêm các thiết lập môi trường vào ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1",
    "TYPESAFE_API_KEY": "<your key>"
  }
}

Thêm repository làm plugin marketplace và cài đặt plugin:

claude plugin marketplace add tamaratran/fast-jev-compaction
claude plugin install fast-jev-compaction@fast-jev-compaction

Trình cài đặt sẽ hỏi các tùy chọn như ngưỡng và truncateHeadChars. Giữ tùy chọn API key ở giá trị mặc định để sử dụng TYPESAFE_API_KEY từ môi trường.

Khởi động lại Claude Code hoặc chạy:

/reload-plugins

Sau khi kích hoạt, cả /compact và việc compact tự động đều đi qua hook Jev. Một lần thay thế thành công sẽ hiển thị toast tương tự fast-jev-compaction: kept N/M messages, no summary (...). Nếu Jev gặp lỗi hoặc mức giảm không đủ, hook sẽ chuyển sang bản tóm tắt tích hợp sẵn của Claude Code.

Chạy plugin trực tiếp từ checkout

Bạn có thể kiểm thử repository mà không cần phát hành hoặc cài đặt:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .

Chạy lệnh này từ thư mục gốc của repository.

Mẹo sử dụng nâng cao

Bảo vệ công việc đang thực hiện

Tăng preserveRecentMessages khi các đầu ra công cụ gần đây có khả năng được sử dụng lại. Các lệnh gọi trong những tin nhắn này được ghim và không thể bị xóa hoặc cắt ngắn.

Cung cấp mục tiêu chính xác

Mục tiêu mặc định được suy ra từ ba prompt gần nhất của người dùng. Với các phiên dài hoặc thay đổi hướng, đặt goal một cách rõ ràng có thể giúp Jev hiểu rõ hơn về tác vụ đang thực hiện.

Sử dụng thống kê để xác định chính sách dự phòng

Kiểm tra result.stats và reductionRatio(result) thay vì tự động chấp nhận mọi kết quả đã compact. Các phiên ngắn có thể không giảm đủ để việc thay thế transcript gốc là hợp lý.

Lập kế hoạch xử lý lỗi

Compaction sẽ throw khi Jev gặp lỗi, trả về dữ liệu không đúng định dạng, thiếu khóa bắt buộc hoặc nhận một lịch sử không thể vừa trong giới hạn state. Hãy bọc các lệnh gọi thư viện trong cơ chế xử lý lỗi và giữ lại transcript gốc hoặc gọi một chiến lược compact khác khi cần. Hook Claude Code đã tự động chuyển sang bản tóm tắt tích hợp sẵn.

Hiểu chi phí request

State đầy đủ sau khi được điều chỉnh kích thước sẽ được lặp lại cho mỗi nhóm câu hỏi. Do đó, một lịch sử gần sát giới hạn state có thể cần một request lớn cho mỗi nhóm câu hỏi nhỏ. Hãy xem số lượng request trong result.stats khi tinh chỉnh các giới hạn.

Kiểm thử mà không gọi mạng

Các unit test của repository sử dụng một triển khai Jev giả và không bao giờ kết nối đến TypeSafe. JevAsker tùy chỉnh hoặc triển khai fetch được chèn cũng có thể hỗ trợ cách tiếp cận tương tự trong các bài kiểm thử ứng dụng của bạn.

Các lệnh phát triển

Khi làm việc từ repository, hãy cài đặt các dependency và chạy những bước kiểm tra hiện có:

npm install
npm run typecheck
npm test
npm run build
npm run validate:plugin
TYPESAFE_API_KEY="$(cat ~/.typesafe_key)" npm run demo

Lệnh demo thực hiện kiểm tra kết nối mạng trực tiếp. Kho lưu trữ cũng chứa một hoạt ảnh macOS SwiftUI tại demo/JevDemo. Hoạt ảnh mô phỏng việc nén bằng một bản ghi hội thoại có sẵn và không gọi API:

demo/JevDemo/build.sh

Nhấn phím cách trong ứng dụng để phát lại hoạt ảnh.

Các giới hạn quan trọng

  • Chỉ các lệnh gọi công cụ và kết quả mới có thể bị xóa hoặc cắt ngắn. Các tin nhắn văn bản vẫn không thay đổi trong đầu ra.

  • Số lượng token là các ước tính được suy ra từ mẫu ký tự thay vì từ bộ tokenizer.

  • Xác suất của Jev không đảm bảo rằng một kết quả an toàn để xóa, mặc dù trợ lý có thể chạy lại lệnh gọi công cụ đã bị xóa khi cần.

  • Mỗi lô yêu cầu lặp lại toàn bộ trạng thái, điều này có thể làm tăng chi phí đối với các lịch sử gần mức trần đã cấu hình.

Kết luận

fast-jev-compaction cung cấp một giải pháp thay thế cho việc tóm tắt hội thoại làm mất thông tin bằng cách giữ nguyên văn bản của người dùng và trợ lý, đồng thời chọn lọc loại bỏ hoạt động công cụ đã cũ. Sử dụng API npm để kiểm soát ở cấp ứng dụng, plugin Claude Code để tích hợp tự động, cùng các ngưỡng, tùy chọn bảo toàn, số liệu thống kê và cơ chế dự phòng được cung cấp để tinh chỉnh việc nén cho quy trình làm việc của bạn.