Hướng dẫn BookLeme: Biên dịch một cuốn sách thành Agent Skill có thể cài đặt và xác minh

BookLeme là gì

BookLeme, tên tiếng Trung là “读了么”, là một chuỗi công cụ biên dịch sách thành Agent Skill. Công cụ không tập trung tạo bản tóm tắt thông thường, mà trích xuất phương thức làm việc trong sách, chẳng hạn như thứ tự đặt câu hỏi, điều kiện phán đoán, quy tắc bằng chứng, trạng thái quy trình và ranh giới không áp dụng, sau đó tổ chức chúng thành các sản phẩm có thể cài đặt, gọi và kiểm chứng.

Dự án chia quá trình xử lý sách thành thời điểm biên dịch và thời điểm chạy: khi biên dịch, hệ thống đọc và xử lý sách gốc; khi chạy, hệ thống chỉ tải các mảnh kiến thức đã tạo theo nhu cầu. Nhờ đó, mỗi lần gọi Skill không cần đọc lại toàn bộ sách.

Lưu ý: “Chắt lọc cấu trúc thay vì tóm tắt” là một lựa chọn thiết kế kỹ thuật của dự án, nhưng README nêu rõ đây vẫn là giả định chưa được dự án kiểm chứng, không phải kết luận đã được chứng minh.

BookLeme tạo ra những gì

BookLeme cung cấp hai bộ máy tạo sản phẩm. Chúng dùng chung biểu diễn trung gian ở các giai đoạn trích xuất và kiểm tra, chỉ phân nhánh ở giai đoạn kết xuất. Vì vậy, khi chọn tạo đồng thời hai loại sản phẩm, không cần xử lý một cuốn sách hai lần.

Gói kiến thức knowledge_pack

Gói kiến thức là một cơ sở tri thức có cấu trúc để tra cứu, chủ yếu gồm bảng định tuyến Topic Index, các mảnh khung được tải theo nhu cầu, bảng tra cứu quyết định và danh mục nguồn. Gói này phù hợp để trả lời những câu hỏi như “sử dụng một khung nào đó trong sách như thế nào”.

Skill hành vi behavior_skill

Skill hành vi dùng để chạy toàn bộ quy trình, có thể bao gồm định nghĩa vai trò, ràng buộc cứng, máy trạng thái, hợp đồng đầu ra có tên, phản mẫu và hàng rào cảm xúc. Nó phù hợp để thực hiện các tác vụ nhiều bước như đối thoại huấn luyện, thay vì chỉ tra cứu kiến thức.

Tính năng cốt lõi

• Định tuyến tự động hai bộ máy: Dựa trên 12 đặc điểm thể loại mang tính xác định để chọn gói kiến thức hoặc Skill hành vi; cũng có thể chỉ định bộ máy thủ công.
• Plugin thể loại có thể cắm: Khi thêm thể loại, chỉ cần thêm một tệp Python trong thư mục plugin của người dùng, không cần sửa pipeline cốt lõi.
• Kiểm tra lại độ trung thực từng chữ: Trích dẫn phải là chuỗi con chính xác trong văn bản gốc và vượt qua nhiều chỉ số có thể đo lường.
• Cổng kiểm soát bản quyền nghiêm ngặt: Thực hiện kiểm tra bản quyền mang tính xác định trước khi cài đặt và phát hành; Skill được tạo từ sách bên thứ ba mặc định ở chế độ riêng tư.
• Không phụ thuộc bên thứ ba khi chạy: Phần triển khai cốt lõi chỉ sử dụng thư viện chuẩn của Python.
• Tính bất biến theo từng giai đoạn: Pipeline sử dụng SHA-256 để hỗ trợ chạy tiếp; sau khi xóa sản phẩm của một giai đoạn, chỉ cần chạy lại giai đoạn tương ứng.

Cài đặt và chuẩn bị môi trường

BookLeme yêu cầu Python 3.9 trở lên. Sau khi sao chép kho lưu trữ, có thể chạy trực tiếp thông qua điểm vào module Python mà không cần cài đặt các thư viện runtime bên thứ ba trước.

git clone https://github.com/bookleme/bookleme.git
cd bookleme
python3 -m bookleme --version

Nếu lệnh xuất ra thông tin phiên bản, môi trường cơ bản đã sẵn sàng. Kho lưu trữ tuyên bố hỗ trợ các định dạng đầu vào như PDF, EPUB, DOCX, Markdown, HTML, RTF và MOBI; phần dưới đây dùng bản thảo Markdown tổng hợp đi kèm dự án để minh họa toàn bộ quy trình.

Biên dịch lần đầu: tạo Skill từ bản thảo

Chạy lệnh con run, dùng --input để chỉ định bản thảo và --title để đặt tiêu đề:

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "我的第一本书"

Theo mặc định, BookLeme sẽ phân tích đặc điểm thể loại của bản thảo và tự động chọn bộ máy tạo phù hợp. Quá trình biên dịch đi qua các giai đoạn đăng ký đầu vào, trích xuất văn bản, phân đoạn tiếng Trung, định tuyến thể loại, trích xuất năng lực nguyên tử, kiểm tra độ trung thực, kết xuất, kiểm tra tổng hợp, cài đặt và đánh giá smoke test.

Khuyến nghị: Khi trải nghiệm lần đầu, nên ưu tiên bản thảo kiểm thử tổng hợp do kho lưu trữ cung cấp. Trước khi xử lý sách của bên thứ ba, cần xác nhận mình có quyền sử dụng tương ứng và hiểu các hạn chế phân phối đối với sản phẩm được tạo.

Chọn bộ máy tạo

Dùng --engine để kiểm soát loại đầu ra:

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "教练对话示例" \
  --engine behavior_skill

Các giá trị khả dụng gồm:

• auto: để bộ định tuyến tự động lựa chọn.
• knowledge_pack: chỉ tạo gói kiến thức có cấu trúc.
• behavior_skill: chỉ tạo Skill hành vi có thể chạy.
• both: đồng thời tạo cả hai loại sản phẩm.

Nếu muốn tắt định tuyến và để cả hai bộ máy cùng xuất sản phẩm, có thể dùng --no-router:

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "双引擎示例" \
  --no-router

Chỉ định plugin thể loại

Plugin thể loại quyết định máy trạng thái, hợp đồng đầu ra, ràng buộc cứng và cách diễn đạt của sản phẩm. Các plugin đã được triển khai hiện nay gồm:

• coach_dialogue: dùng cho huấn luyện hoặc tự đối thoại, hỗ trợ máy trạng thái hỏi đáp, hàng rào cảm xúc, ngắt quãng và tiếp tục trò chuyện.
• knowledge_reference: dùng để tra cứu nhanh khung, định tuyến nội dung qua Topic Index; khi gặp thông tin không có trong sách thì phải từ chối trả lời.

professional_analysis và decision_checklist vẫn thuộc nội dung trong lộ trình M4 tiếp theo, hiện không nên xem chúng là tính năng đã hoàn thiện.

Có thể dùng --genre để buộc chọn một plugin đã triển khai:

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "人生设计对话" \
  --engine behavior_skill \
  --genre coach_dialogue

Kiểm tra sản phẩm được tạo

Sau khi tạo xong, nên dùng lệnh kiểm tra do dự án cung cấp để kiểm tra sản phẩm. README dùng examples/coach làm ví dụ:

python3 -m bookleme validate examples/coach

Bước này sẽ chạy trình kiểm tra chính thức, lint nội bộ và cổng kiểm soát bản quyền nghiêm ngặt. BookLeme chia độ trung thực thành các chỉ số có thể kiểm tra, gồm tỷ lệ phân tích trích dẫn, tỷ lệ vi phạm từng chữ, tỷ lệ từ chối đúng ở ca âm, tỷ lệ khớp từ kích hoạt, tỷ lệ tuân thủ sản phẩm, giới hạn chồng lấp shingle và độ bao phủ.

Dự án cũng giữ lại chỉ số heuristic groundedness, nhưng README nêu rõ LLM judge chưa được tích hợp, nên hiện tại giá trị này chỉ được báo cáo và không được dùng làm cổng kiểm soát bắt buộc.

Chạy kiểm thử hồi quy

Sau khi sửa mã cốt lõi, plugin hoặc mẫu, hãy chạy toàn bộ kiểm thử:

python3 -m unittest discover -s tests -v

Nếu đang phát triển plugin, cũng có thể kiểm tra schema trạng thái và xác thực riêng tệp plugin:

python3 -m bookleme schema --state
python3 -m bookleme plugin validate bookleme/plugins/builtin/coach_dialogue.py

Cài đặt sản phẩm và khai báo quyền sử dụng

Theo mặc định, lệnh tạo không ghi sản phẩm vào thư mục nguồn kỹ năng. Khi cần cài đặt, phải thêm rõ ràng --install. Đồng thời có thể dùng --user-rights để khai báo trạng thái quyền đối với nội dung đầu vào:

python3 -m bookleme run \
  --input path/to/book.md \
  --title "内部知识 Skill" \
  --engine both \
  --install \
  --user-rights owned

--user-rights hỗ trợ các giá trị sau:

• owned: người dùng sở hữu quyền đối với nội dung.
• licensed: đã nhận được giấy phép tương ứng.
• public_domain: nội dung thuộc phạm vi công cộng.
• unknown: chưa rõ trạng thái quyền.

Khai báo quyền không thay thế phán đoán pháp lý. Giấy phép MIT chỉ bao phủ mã của bộ chuyển đổi BookLeme và định nghĩa kỹ năng, không bao phủ sách đầu vào, cũng không tự động trao cho người dùng quyền phân phối sản phẩm phái sinh.

Hiểu về cổng kiểm soát bản quyền nghiêm ngặt

BookLeme định vị đầu ra là ghi chú phái sinh có cấu trúc, không phải bản tái hiện văn bản gốc. Dự án thiết lập sáu cổng kiểm soát bản quyền nghiêm ngặt; chỉ cần một cổng thất bại là sẽ ngăn việc cài đặt hoặc phát hành:

1. Mỗi trích dẫn không quá 150 chữ và có thể truy nguyên từng chữ về văn bản gốc đầu vào.
2. Tỷ lệ trích dẫn tổng thể không quá 0.03.
3. Nội dung sao chép liên tục không quá 150 chữ.
4. Mức chồng lấp shingle 13 chữ không quá 0.10.
5. Sản phẩm không được chứa toàn văn hoặc các mảnh nguyên bản.
6. contains_original_text phải là false.

Skill được tạo từ sách bên thứ ba mặc định ở chế độ riêng tư và không được phân phối. Nếu thực sự có quyền phân phối công khai, vẫn cần cung cấp rõ ràng hai tham số xác nhận:

--public --confirm-public PUBLISH

Tham số công khai là một cổng xác nhận kỹ thuật, không đồng nghĩa với việc được cấp phép bản quyền. Người sử dụng vẫn phải tự xác nhận phạm vi giấy phép, luật áp dụng và trạng thái quyền đối với tài liệu đầu vào.

Kỹ thuật nâng cao: tận dụng chạy tiếp theo tính bất biến từng giai đoạn

Pipeline S0 đến S9 của BookLeme sử dụng thiết kế bất biến theo từng giai đoạn và dùng SHA-256 để nhận diện kết quả hiện có. Khi quá trình xử lý tài liệu dài bị gián đoạn ngoài ý muốn, có thể giữ lại sản phẩm của các giai đoạn đã hoàn tất; nếu chỉ xóa đầu ra của một giai đoạn, công cụ sẽ chạy lại giai đoạn tương ứng mà không cần xử lý lại toàn bộ sách.

Thiết kế này cũng phù hợp để gỡ lỗi plugin hoặc logic kết xuất. Vì hai bộ máy dùng chung kết quả trích xuất, phân đoạn, trích xuất năng lực và kiểm tra độ trung thực ở các giai đoạn trước, khi sửa tầng kết xuất không cần đọc lại bản thảo.

Kỹ thuật nâng cao: phát triển plugin thể loại tùy chỉnh

Plugin tùy chỉnh nên được đặt tại bookleme/plugins/user/<genre_id>.py. Dự án yêu cầu plugin khai báo các trường quan trọng; nếu thiếu trường bắt buộc, plugin sẽ bị từ chối tải.

• state_machine: định nghĩa trạng thái và chuyển đổi của quy trình.
• output_contract: định nghĩa đầu ra mà sản phẩm bắt buộc phải cung cấp.
• hard_constraints: định nghĩa các quy tắc không được vi phạm.
• anti_patterns: liệt kê các hành vi sai cần tránh.
• voice_calibration: định nghĩa giọng điệu, cách xưng hô, từ ngữ bị cấm và chủ thể của kết luận.
• copyright_profile: khai báo cấu hình liên quan đến kiểm soát bản quyền.
• trigger_words: cung cấp 3 đến 5 từ kích hoạt tiếng Trung.
• eval_prompts: cung cấp các prompt đánh giá, trong đó ít nhất có một ca âm.

Trước khi viết plugin, nên đọc đặc tả plugin; sau khi hoàn tất, dùng plugin validate để xác thực. Không được dùng plugin để vượt qua kiểm tra độ trung thực, cổng kiểm soát bản quyền nghiêm ngặt hoặc yêu cầu từ chối trả lời ở ca âm.

Pipeline S0–S9 hoạt động như thế nào

1. S0–S2: Đăng ký đầu vào, trích xuất xác định, chuẩn hóa và phân đoạn tiếng Trung, không phụ thuộc vào các thẻ Chapter cố định trong tiếng Anh.
2. S3: Định tuyến thể loại dựa trên 12 đặc trưng; khi gặp sự mơ hồ, có thể tự động chọn cả hai engine.
3. S4: Trích xuất năng lực nguyên tử, có thể sử dụng trình trích xuất xác định và trình trích xuất LLM tương thích với OpenAI tùy chọn; nếu thiếu cấu hình, hệ thống sẽ tự động chuyển về phương án dự phòng.
4. S5: Kiểm tra trích dẫn theo từng chữ, duy trì claim ledger và tính toán các chỉ số độ trung thực.
5. S6: Kết xuất gói kiến thức hoặc Skill hành vi theo plugin; đây là nơi thực sự phân luồng giữa hai engine.
6. S7–S9: Thực hiện kiểm tra tổng hợp, cài đặt idempotent và đánh giá smoke test.

S3 và S4 đều sử dụng kết quả của S2 làm đầu vào và có thể hoạt động song song. Hai engine dùng chung các biểu diễn trung gian của S1, S2, S4 và S5, tránh phải đọc và trích xuất lặp lại.

Khuyến nghị thực tế

• Trước tiên, hãy làm quen với các lệnh bằng bản thảo sách tổng hợp đi kèm dự án, sau đó mới xử lý sách thực.
• Khi không chắc chắn về loại sản phẩm đầu ra, hãy sử dụng --engine auto; khi cần đồng thời so sánh kết quả của hai engine, hãy sử dụng both hoặc --no-router.
• Sau mỗi lần sửa plugin hoặc template, hãy chạy kiểm tra sản phẩm đầu ra và các bài kiểm thử đơn vị.
• Đối với thông tin không được cung cấp trong sách, hãy giữ khả năng từ chối trả lời; không dùng kiến thức thông thường của mô hình để bổ sung thiếu hụt nguồn.
• Không đưa nguyên văn sách, bìa sách hoặc bản quét vào kho lưu trữ, cũng không trực tiếp công khai sản phẩm của các sách bên thứ ba vốn mặc định là riêng tư.
• Hãy đọc tài liệu về độ trung thực và tài liệu bản quyền để hiểu các chỉ số và ranh giới phát hành.

Phạm vi hiện tại

BookLeme hiện đang ở giai đoạn M0–M3. coach_dialogue và knowledge_reference đã được triển khai, nhưng các plugin phân tích chuyên môn và danh sách kiểm tra quyết định vẫn nằm trong lộ trình tiếp theo. LLM judge chưa được tích hợp, vì vậy một số chỉ số liên quan vẫn là null. Khi sử dụng, cần phân biệt giữa các năng lực đã triển khai, đã được kiểm thử thực tế và vẫn đang chờ xác minh.

Kết luận

BookLeme biến “đọc sách” thành một quy trình kỹ thuật có thể kiểm thử: trước tiên trích xuất và phân đoạn, sau đó trích xuất năng lực, kiểm tra độ trung thực, cuối cùng kết xuất thành gói kiến thức hoặc Skill hành vi. Sau khi hoàn tất lần biên dịch đầu tiên, nên đưa việc kiểm tra, kiểm thử, tuyên bố quyền và kiểm tra bản quyền vào quy trình cố định, ताकि vừa tái sử dụng được các phương pháp trong sách vừa duy trì ranh giới nguồn và khả năng kiểm chứng.