Kiểm tra an toàn các chỉ dẫn AI lỗi thời với Skill Sunset

Skill Sunset là gì?

Skill Sunset là một công cụ dòng lệnh dùng để kiểm tra các hướng dẫn dành cho tác nhân AI đã tích lũy. Công cụ quét các tệp như AGENTS.md, CLAUDE.md và SKILL.md để xác định các tham chiếu lỗi thời, Skill bị trùng lặp, nội dung luôn được tải quá lớn, frontmatter sai định dạng và các vấn đề bảo trì khác.

Công cụ kết hợp các kiểm tra xác định với những giả thuyết đánh giá thận trọng. Công cụ không xem mọi hướng dẫn có vẻ cũ là không còn cần thiết, và không phát hiện nào cho phép xóa. Thay vào đó, công cụ phân tách các vấn đề có thể xác minh bằng phân tích tĩnh khỏi các quy tắc liên quan đến hành vi cần được kiểm thử.

Quan trọng: Kết luận TEST có nghĩa là “đánh giá giả thuyết này”. Điều đó không có nghĩa là một mô hình AI mới hơn đã khiến hướng dẫn trở nên không cần thiết.

Việc kiểm tra được thực hiện cục bộ và chỉ ở chế độ đọc. Phần lõi của công cụ không gọi API AI, tiêu thụ hạn mức mô hình hoặc đọc thông tin xác thực của nhà cung cấp.

Tính năng chính

• Kiểm tra hướng dẫn tĩnh: Tìm các tham chiếu cục bộ bị hỏng, đường dẫn tuyệt đối lỗi thời, frontmatter Skill sai định dạng, tệp luôn được tải quá lớn và thông tin xác thực có thể ở dạng văn bản thuần.
• Xử lý trùng lặp thận trọng: Phát hiện các Skill trùng tên và xác minh toàn bộ gói trước khi đề xuất ngừng sử dụng theo cách có thể khôi phục.
• Giả thuyết về hành vi: Gắn nhãn các quy tắc bù trừ theo thời kỳ của mô hình là TEST thay vì tuyên bố chúng đã lỗi thời.
• Nhiều định dạng báo cáo: Tạo HTML song ngữ, Markdown, JSON, lời nhắc bàn giao cho Codex và Claude, kế hoạch đánh giá, mẫu thử nghiệm và bản kê khai khôi phục.
• Danh mục hướng dẫn được bảo vệ: Loại trừ kiến thức miền, quy tắc an toàn, cổng phân quyền và bất biến của dự án khỏi việc tự động ngừng sử dụng.
• Hỗ trợ CI: Có thể trả về mã thoát theo mức độ nghiêm trọng thông qua --fail-on.
• Báo cáo chú trọng quyền riêng tư: Che các đường dẫn bên dưới thư mục chính của người dùng thành $HOME/... và biểu diễn các đích tuyệt đối khác là $ABSOLUTE/<name>.

Yêu cầu và môi trường được hỗ trợ

Skill Sunset hỗ trợ Node.js 20, 22 và 24. Công cụ được xác minh thông qua GitHub Actions trên Ubuntu, macOS và Windows. Các bản phân phối Linux khác được kỳ vọng sẽ hoạt động với Node.js 20 trở lên, dù hiện chưa được đưa vào ma trận CI của dự án.

Các đích quét đặt sẵn có sẵn cho Codex tại ~/.codex và Claude Code tại ~/.claude. Bạn cũng có thể kiểm tra bất kỳ thư mục giới hạn nào được cung cấp rõ ràng.

Cài đặt và thiết lập

Không cần cài đặt toàn cục. Chạy trực tiếp gói mới nhất đã phát hành bằng npx:

npx skill-sunset@latest audit --codex --open

Lệnh này kiểm tra cấu hình Codex và mở báo cáo HTML được tạo. Để kiểm tra Claude Code, hãy chạy:

npx skill-sunset@latest audit --claude --open

Để quét một dự án hoặc thư mục giới hạn khác, truyền đường dẫn của thư mục đó cho audit:

npx skill-sunset@latest audit /path/to/setup

Ngôn ngữ báo cáo chính mặc định là --lang auto. Chọn ngôn ngữ rõ ràng bằng --lang en hoặc --lang zh-CN. Mỗi gói báo cáo vẫn bao gồm các trang HTML tiếng Anh và tiếng Trung giản thể có thể sử dụng độc lập.

Chạy lần kiểm tra đầu tiên

Kiểm tra thư mục hiện tại

Trước khi thay đổi các tệp hướng dẫn, hãy tạo một bản sao có thể khôi phục. Ví dụ, sao lưu AGENTS.md và ghi báo cáo vào một thư mục riêng:

cp AGENTS.md AGENTS.md.skill-sunset.bak
npx skill-sunset@latest audit . --out .skill-sunset --open

Việc kiểm tra chỉ ở chế độ đọc. Công cụ báo cáo các công việc bảo trì tiềm năng nhưng không sửa đổi hoặc xóa các tệp được quét.

Tìm hiểu gói báo cáo

Theo mặc định, một gói được tạo có thể chứa các thành phần sau:

.skill-sunset/
├── index.html
├── index.en.html
├── index.zh-CN.html
├── audit-report.md
├── audit.json
├── execution-prompt-codex.md
├── execution-prompt-claude.md
├── eval-plan.md
├── experiment-template.json
└── rollback-manifest.json

Dùng các tệp HTML để đánh giá tương tác thủ công, audit-report.md cho báo cáo văn bản có thể sử dụng độc lập và audit.json cho tự động hóa. Các lời nhắc thực thi hỗ trợ bàn giao cho Codex hoặc Claude Code, trong khi kế hoạch đánh giá và mẫu thử nghiệm giúp xác thực các giả thuyết về hành vi.

rollback-manifest.json được tạo vẫn để trống cho đến khi một tác nhân thực thi được ủy quyền ghi nhận các thay đổi thực tế và mã băm.

Diễn giải các kết luận

• MERGE: Các Skill trùng khớp hoàn toàn hoặc trùng tên nhưng xung đột cần được xem xét để hợp nhất.
• UPDATE: Một đường dẫn, tham chiếu, giả định về công cụ hoặc hướng dẫn phụ thuộc phiên bản có thể cần được sửa.
• DEMOTE: Chi tiết hữu ích đang được tải quá rộng và có thể phù hợp hơn với cơ chế tiết lộ dần.
• RETIRE: Các gói Skill chung, đầy đủ, giống hệt từng byte và cùng tên tồn tại trong một gốc quét. Chỉ đề xuất lưu trữ theo cách có thể khôi phục.
• TEST: Một tuyên bố có thể về việc đã lỗi thời cần được đánh giá hành vi giữa phiên bản cũ và mới trước khi dọn dẹp.

Các kết luận này là danh mục đánh giá, không phải phê duyệt thay đổi tự động. Hãy xác nhận từng vấn đề với kho mã, các công cụ hiện tại và những tác vụ đại diện trước khi chỉnh sửa hướng dẫn.

Ví dụ: Từ phát hiện đến khôi phục

Giả sử một tệp AGENTS.md chứa yêu cầu công cụ không có điều kiện và liên kết đến một hướng dẫn triển khai bị thiếu:

Luôn sử dụng Context7 cho mọi tác vụ.
[Runbook triển khai](docs/deploy.md)

Nếu docs/deploy.md không tồn tại, Skill Sunset có thể báo cáo ba mối lo ngại riêng biệt:

• UPDATE / broken-reference vì không thể phân giải đích của runbook.
• UPDATE / context7-assumption vì cần xác minh tính khả dụng hiện tại của công cụ.
• TEST / unconditional-tooling vì “cho mọi tác vụ” yêu cầu đánh giá hành vi mang tính đại diện.

Chỉ Áp Dụng Các Thay Đổi Đã Xác Nhận

Trước tiên, tìm runbook triển khai thực tế và xác minh danh sách công cụ hiện tại. Chỉ sửa tham chiếu đã cũ mà bạn có thể xác nhận. Xem quy tắc sử dụng công cụ vô điều kiện như một ứng viên thí nghiệm riêng, thay vì xóa quy tắc đó chỉ dựa trên báo cáo tĩnh.

Sau khi chỉnh sửa, chạy lại kiểm tra và các bài kiểm thử riêng của dự án:

npx skill-sunset@latest audit . --out .skill-sunset --format json
npm test

Xác Thực Phát Hiện TEST

Đối với một mục TEST, hãy hoàn tất .skill-sunset/experiment-template.json được tạo ra. Xác thực manifest mà không thực thi các lệnh trong đó:

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root .

Chỉ riêng thao tác xác thực sẽ không chạy lệnh nào. Việc thực thi yêu cầu cờ --run riêng:

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root . --run

Một thí nghiệm đạt yêu cầu chỉ chứng minh các tiêu chí chấp nhận được mã hóa trong manifest đó. Nó không xác lập rằng hướng dẫn này không cần thiết trong mọi trường hợp.

Khôi Phục Khi Có Hồi Quy

Nếu các tham chiếu, bài kiểm thử của dự án hoặc hành vi của tác vụ bị hồi quy, hãy khôi phục tệp đã lưu và kiểm tra lại:

cp AGENTS.md.skill-sunset.bak AGENTS.md
npx skill-sunset@latest audit . --out .skill-sunset

Sử Dụng Skill Sunset Trong CI

Yêu cầu đầu ra JSON và đặt ngưỡng mức độ nghiêm trọng cho tự động hóa:

npx skill-sunset@latest audit /path/to/setup --format json --fail-on high

Dạng này phù hợp với các pipeline CI cần đầu ra có thể đọc bằng máy và điều kiện thất bại đối với các phát hiện có mức độ nghiêm trọng cao. Hãy xem xét hiện vật JSON thay vì coi trạng thái thoát là quyền cho phép thay đổi hoặc xóa hướng dẫn.

Mẹo An Toàn Và Quy Trình Nâng Cao

Giới Hạn Phạm Vi Quét

Truyền vào thư mục nhỏ nhất chứa bộ hướng dẫn mà bạn dự định kiểm tra. Phân tích trùng lặp và các đề xuất loại bỏ được đánh giá trong cùng một thư mục gốc quét, vì vậy ranh giới rõ ràng sẽ giúp diễn giải kết quả dễ hơn.

Tách Bản Sửa Tĩnh Khỏi Thay Đổi Hành Vi

Các liên kết hỏng và đường dẫn cũ đã được xác nhận thường có thể được điều tra trực tiếp. Các quy tắc liên quan đến hành vi của mô hình hoặc việc sử dụng công cụ vô điều kiện nên được giữ thành những ứng viên riêng biệt, với tiêu chí chấp nhận rõ ràng, các tác vụ mang tính đại diện và kế hoạch khôi phục.

Coi Việc Thực Thi Thí Nghiệm Là Hoạt Động Đặc Quyền

Các manifest thí nghiệm chỉ dùng để xác thực trừ khi cung cấp --run. Theo mặc định, các lệnh được thực thi mà không thông qua shell và chỉ nhận một danh sách cho phép tối thiểu gồm các biến môi trường không chứa bí mật.

Việc kế thừa toàn bộ môi trường yêu cầu --inherit-env cùng với --run. Vì các biến được kế thừa có thể bao gồm thông tin xác thực của nhà cung cấp, chỉ sử dụng tùy chọn này với các lệnh đáng tin cậy. Không bao giờ đặt thông tin xác thực trong manifest thí nghiệm.

Hiểu Dữ Liệu Thí Nghiệm Được Lưu Trữ

Các lượt chạy thử và tệp kết quả lưu lại tên tệp thực thi, số lượng đối số, mã băm lệnh, kích thước đầu ra và mã băm đầu ra. Chúng không lưu lại đối số lệnh hoặc nội dung đầu ra. Điều này giúp giảm mức độ lộ lọt, nhưng vẫn cần xem xét cẩn thận định nghĩa và các lệnh của thí nghiệm.

Không Coi Quét Bí Mật Là Bằng Chứng

Skill Sunset có thể đánh dấu các thông tin xác thực dạng văn bản thuần túy có khả năng là bí mật, còn dự án sử dụng Gitleaks như một cơ chế bảo vệ trước khi phát hành. Tuy nhiên, README nêu rõ rằng đây không phải bằng chứng cho thấy mọi định dạng thông tin xác thực đều có thể được nhận diện.

Phát Triển Cục Bộ

Để làm việc trực tiếp trên kho lưu trữ, hãy chạy các bài kiểm thử, kiểm tra nội dung gói và tạo báo cáo minh họa từ fixture đi kèm:

npm test
npm pack --dry-run
node ./bin/skill-sunset.js audit ./test/fixtures/sample-setup --out ./demo-report --open

Quy trình GitHub Actions của dự án chạy Gitleaks và các bài kiểm thử trên ma trận hệ điều hành và Node.js được hỗ trợ. Thông tin bổ sung về dự án có trong nhật ký thay đổi, hướng dẫn đóng góp và chính sách bảo mật của kho lưu trữ.

Phạm Vi Hiện Tại

Phiên bản 0.2.0 cung cấp các kiểm tra tĩnh, cơ chế loại bỏ trùng lặp thận trọng, báo cáo bản địa hóa, che giấu đường dẫn, bộ khung thí nghiệm lệnh có kiểm soát, mã thoát CI theo mức độ nghiêm trọng và các bài kiểm thử đầu ra đối nghịch. Ảnh chụp khả năng của nhà cung cấp hiện tại, bộ chuyển đổi sử dụng phiên và bộ chuyển đổi chất lượng tác vụ được mô tả như các lớp bằng chứng trong tương lai, thay vì những tính năng hiện có.

Kết Luận

Skill Sunset cung cấp một quy trình thận trọng để duy trì các tệp hướng dẫn AI mà không mặc định rằng các quy tắc cũ đã tự động lỗi thời. Hãy bắt đầu bằng một lượt kiểm tra chỉ đọc, phân biệt các vấn đề xác định được với các giả thuyết về hành vi, xác thực thay đổi bằng các bài kiểm thử của dự án và các thí nghiệm có kiểm soát, đồng thời duy trì khả năng khôi phục trong suốt quy trình.