Chuyển đến nội dung chính

​
Yêu cầu

  • Node.js >= 20.9.0
  • Bun >= 1.3.0 (tùy chọn - chỉ cần thiết khi build từ source)

​
Cài đặt

npm install -g failproofai

​
Bắt đầu nhanh

1

Kích hoạt policies

Policies là những quy tắc chạy trước và sau mỗi lần agent gọi công cụ. Chúng bắt các lệnh có khả năng gây hủy hoại, rò rỉ bí mật, và các tình huống thất bại khác trước khi chúng gây ra thiệt hại.
failproofai policies --install
Điều này ghi hook entries vào các agent CLIs đã cài đặt của bạn (tệp ~/.claude/settings.json của Claude Code, ~/.codex/hooks.json của OpenAI Codex, ~/.copilot/hooks/failproofai.json của GitHub Copilot CLI, ~/.cursor/hooks.json của Cursor Agent, plugin shim được tạo tại ~/.config/opencode/plugins/failproofai.mjs của OpenCode cộng với entry đăng ký trong mảng plugin của ~/.config/opencode/opencode.json, ~/.pi/agent/settings.json của Pi, hoặc ~/.gemini/settings.json của Gemini CLI). Khi có nhiều hơn một được cài đặt, bạn sẽ được hỏi; truyền --cli claude codex copilot cursor opencode pi gemini (bất kỳ subset nào) để bỏ qua lời nhắc.Hỗ trợ cho GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, và Gemini CLI là beta — cài đặt với --cli copilot, --cli cursor, --cli opencode, --cli pi, hoặc --cli gemini.
failproofai policies --install --scope project
failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli gemini --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
2

Xác minh

failproofai policies
Hiển thị mỗi policy, cho dù nó được kích hoạt hay không, và bất kỳ tham số nào được cấu hình.
3

Khởi chạy bảng điều khiển

failproofai
Mở một bảng điều khiển cục bộ tại http://localhost:8020 nơi bạn có thể duyệt phiên, kiểm tra các lệnh gọi công cụ, và quản lý policies.
4

Chạy agent của bạn

Khởi chạy Claude Code như bình thường. Nếu agent cố gắng làm điều gì đó rủi ro, failproofai sẽ chặn nó tự động. Để nó chạy không tham dự và xem xét những gì đã xảy ra trên bảng điều khiển.

​
Policies hoạt động như thế nào

Mỗi khi một agent chạy một công cụ, Claude Code gọi failproofai như một subprocess: 
Claude Code  →  failproofai --hook PreToolUse  →  đọc JSON từ stdin
                                                 đánh giá policies
                                                 ghi quyết định vào stdout
Mỗi policy trả về một trong ba quyết định:
  • allow - agent tiếp tục bình thường
  • deny - hành động bị chặn, agent được thông báo lý do
  • instruct - ngữ cảnh bổ sung được thêm vào prompt của agent
Policies chạy trong quá trình cục bộ của bạn. Không có gì được gửi tới dịch vụ từ xa.

​
Thiết lập team policies với convention-based policies

Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên toàn team là convention .failproofai/policies/. Thả các tệp policy vào thư mục này và chúng sẽ được tải tự động — không có flags, không có thay đổi config, không có lệnh cài đặt.
1

Tạo thư mục policies

mkdir -p .failproofai/policies
2

Thêm tệp policies

Sao chép các ví dụ khởi đầu hoặc viết của riêng bạn:
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
Hoặc tạo một tệp mới:
// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
      return instruct("Chạy tests trước khi commit.");
    }
    return allow();
  },
});
3

Commit vào git

git add .failproofai/policies/
git commit -m "Thêm team quality policies"
Mỗi thành viên trong team có failproofai được cài đặt sẽ tự động nhận các policies này. Không cần thiết lập cho từng developer.
Commit .failproofai/policies/ vào repo của bạn để toàn bộ team chia sẻ các tiêu chuẩn giống nhau. Khi team của bạn phát hiện ra các tình huống thất bại mới, thêm policies và push — mọi người sẽ nhận được cập nhật trên lần git pull tiếp theo của họ. Theo thời gian, những policies này trở thành một tiêu chuẩn chất lượng sống động luôn được cải thiện.

​
Lưu trữ dữ liệu

Tất cả các cấu hình và logs vẫn ở trên máy của bạn:
Đường dẫnNội dung lưu trữ
~/.failproofai/policies-config.jsonCấu hình policy toàn cầu
~/.failproofai/hook-activity.jsonlLịch sử thực thi hook
~/.failproofai/hook.logDebug log cho các lỗi hook tùy chỉnh
.failproofai/policies-config.jsonCấu hình cho mỗi dự án (committed)
.failproofai/policies-config.local.jsonOverrides cá nhân (gitignored)

​
Gỡ cài đặt

failproofai policies --uninstall
Xóa hook entries từ ~/.claude/settings.json. Các tệp config trong ~/.failproofai/ được giữ lại.

​
Bước tiếp theo

Configuration

Scopes và định dạng tệp config

Built-in policies

Tất cả 26 policies với tham số

Custom policies

Viết policies của riêng bạn trong JavaScript

Agent monitor

Giám sát phiên và xem xét hoạt động policy