failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/vi/getting-started.mdx

@@ -0,0 +1,200 @@
+---
+---
+title: Bắt đầu
+description: "Cài đặt failproofai, bật các chính sách và cho phép các agent của bạn chạy một cách đáng tin cậy"
+icon: rocket
+---
+
+## Yêu cầu
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (tùy chọn - chỉ cần thiết khi xây dựng từ nguồn)
+
+---
+
+## Cài đặt
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Khởi động nhanh
+
+<Steps>
+  <Step title="Bật các chính sách">
+    Các chính sách là các quy tắc chạy trước và sau mỗi lần agent gọi tool. Chúng bắt các lệnh huỷ diệt, rò rỉ bí mật và các chế độ lỗi khác trước khi chúng gây thiệt hại.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Lệnh này ghi các hook entries vào các CLI agent đã cài đặt (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generated plugin shim at `~/.config/opencode/plugins/failproofai.mjs` plus a registration entry in `~/.config/opencode/opencode.json`'s `plugin` array, Pi's `~/.pi/agent/settings.json`, Hermes's `~/.hermes/config.yaml`, OpenClaw's `~/.openclaw/openclaw.json`, Factory Droid's `~/.factory/hooks.json`, Devin CLI's `~/.config/devin/config.json`, Antigravity CLI's `~/.gemini/config/hooks.json`, hoặc Goose's auto-discovered plugin dir at `~/.agents/plugins/failproofai/hooks/hooks.json`). Khi có nhiều hơn một CLI, bạn sẽ được nhắc; hãy truyền `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (bất kỳ tập con nào) để bỏ qua câu nhắc.
+
+    GitHub Copilot CLI, Cursor Agent, OpenCode và Pi support là **beta** — cài đặt với `--cli copilot`, `--cli cursor`, `--cli opencode`, hoặc `--cli pi`. Hermes (hermes-agent, một gateway Slack/Telegram) cài đặt user-scope với `--cli hermes` và cũng là **offline audit source**. OpenClaw (openclaw gateway, một multi-channel assistant tự lưu trữ) cài đặt user-scope với `--cli openclaw` — enforcement chạy thông qua in-process plugin hooks của nó (`before_agent_finalize` là một real turn-end gate, vì vậy `require-*-before-stop` builtins enforce) — và cũng là **offline audit source**. Factory Droid (`droid`) cài đặt với `--cli factory` (user + project scope) và cũng là **offline audit source**. Devin CLI (`devin`, Cognition) cài đặt với `--cli devin` (user + project scope) và cũng là **offline audit source**. Antigravity CLI (`agy`) cài đặt với `--cli antigravity` (user + project scope) và cũng là **offline audit source**. Goose (codename goose, Block) cài đặt với `--cli goose` (user + project scope) — trình cài đặt chỉ tạo một plugin dir at `~/.agents/plugins/failproofai/` mà Goose tự động khám phá, và nó cũng là **offline audit source**.
+
+    ```bash
+    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 hermes --scope user
+    failproofai policies --install --cli openclaw --scope user
+    failproofai policies --install --cli factory --scope project
+    failproofai policies --install --cli devin --scope project
+    failproofai policies --install --cli antigravity --scope project
+    failproofai policies --install --cli goose --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Xác minh">
+    ```bash
+    failproofai policies
+    ```
+
+    Hiển thị mỗi chính sách, liệu nó có được bật hay không, và bất kỳ tham số cấu hình nào.
+  </Step>
+  <Step title="Khởi chạy bảng điều khiển">
+    ```bash
+    failproofai
+    ```
+
+    Mở bảng điều khiển cục bộ tại `http://localhost:8020` nơi bạn có thể duyệt các phiên, kiểm tra các lệnh gọi tool và quản lý các chính sách.
+  </Step>
+  <Step title="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 mà không cần giám sát và xem lại những gì đã xảy ra trong bảng điều khiển.
+  </Step>
+</Steps>
+
+---
+
+## Cách thức hoạt động của các chính sách
+
+Mỗi lần một agent chạy một tool, Claude Code gọi failproofai như một subprocess:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
+                                                 evaluates policies
+                                                 writes decision to stdout
+```
+
+Mỗi chính sách 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** - thêm context vào prompt của agent
+
+<Note>
+Các chính sách chạy trong quá trình cục bộ của bạn. Không có gì được gửi đến dịch vụ từ xa.
+</Note>
+
+---
+
+## Thiết lập chính sách nhóm với chính sách dựa trên quy ước
+
+Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên toàn nhóm là quy ước `.failproofai/policies/`. Thả các tệp chính sách vào thư mục này và chúng sẽ được tải tự động — không có cờ, không có thay đổi config, không có lệnh cài đặt.
+
+<Steps>
+  <Step title="Tạo thư mục chính sách">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+  </Step>
+  <Step title="Thêm tệp chính sách">
+    Sao chép các ví dụ khởi động hoặc viết chính sách của riêng bạn:
+
+    ```bash
+    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
+    ```
+
+    Hoặc tạo một tệp mới:
+
+    ```js
+    // .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("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Commit vào git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+
+    Mỗi thành viên nhóm có failproofai cài đặt sẽ nhận các chính sách này tự động. Không cần thiết lập cho từng nhà phát triển.
+  </Step>
+</Steps>
+
+<Tip>
+Commit `.failproofai/policies/` vào repo của bạn để toàn bộ nhóm chia sẻ các tiêu chuẩn giống nhau. Khi nhóm của bạn phát hiện ra các chế độ lỗi mới, hãy thêm chính sách và push — mọi người sẽ nhận được bản cập nhật trên `git pull` tiếp theo của họ. Theo thời gian, các chính sách này trở thành một tiêu chuẩn chất lượng sống được cải thiện liên tục.
+</Tip>
+
+---
+
+## Lưu trữ dữ liệu
+
+Tất cả cấu hình và nhật ký vẫn ở trên máy của bạn:
+
+| Đường dẫn | Nó lưu trữ gì |
+|------|----------------|
+| `~/.failproofai/policies/local-policies/policies-config.json` | Cấu hình chính sách toàn cục |
+| `~/.failproofai/hook-activity/` | Lịch sử thực thi hook (paged JSONL) |
+| `~/.failproofai/logs/` | Nhật ký gỡ lỗi cho các lỗi hook tùy chỉnh |
+| `.failproofai/policies-config.json` | Cấu hình cho mỗi dự án (được commit) |
+| `.failproofai/policies-config.local.json` | Ghi đè cá nhân (gitignored) |
+
+---
+
+## Gỡ cài đặt
+
+```bash
+failproofai policies --uninstall
+```
+
+Xóa hook entries từ `~/.claude/settings.json`. Các tệp cấu hình trong `~/.failproofai/` được giữ lại.
+
+---
+
+## Các bước tiếp theo
+
+<CardGroup cols={2}>
+
+<Card title="Cấu hình" icon="gear" href="/vi/configuration">
+  Các scopes và định dạng tệp cấu hình
+</Card>
+
+<Card title="Chính sách tích hợp" icon="shield" href="/vi/built-in-policies">
+  Tất cả 26 chính sách với các tham số
+</Card>
+
+<Card title="Chính sách tùy chỉnh" icon="code" href="/vi/custom-policies">
+  Viết các chính sách của riêng bạn bằng JavaScript
+</Card>
+
+<Card title="Giám sát agent" icon="chart-line" href="/vi/dashboard">
+  Giám sát các phiên và xem lại hoạt động chính sách
+</Card>
+
+</CardGroup>

package/.next/standalone/docs-old/vi/introduction.mdx

@@ -0,0 +1,57 @@
+---
+title: "Failproof AI"
+description: "FailproofAI cung cấp 39 chính sách xử lý lỗi tích hợp sẵn giúp bắt các vòng lặp, rò rỉ bí mật, lệnh gọi công cụ hủy diệt, và nhiều hơn nữa chỉ với một lần cài đặt."
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hooks và chính sách cho **xử lý lỗi AI**, **phục hồi lỗi**, và **độ tin cậy LLM**. Giữ cho các đại lý AI của bạn hoạt động đáng tin cậy và tự trị trên **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI**, và **Agents SDK**.
+
+Các đại lý AI thất bại theo những cách có thể dự đoán được. Chúng chạy các lệnh hủy diệt, rò rỉ bí mật, lệch khỏi tác vụ, mắc kẹt trong các vòng lặp, hoặc đẩy trực tiếp lên nhánh chính. Nếu không được giám sát, các lỗi nhỏ có thể dẫn đến sự cố hệ thống, rò rỉ thông tin xác thực, và mất công việc.
+
+FailproofAI giải quyết vấn đề này bằng **chính sách**. Những quy tắc này kết nối vào mọi lệnh gọi công cụ của đại lý để **phát hiện lỗi**, **giảm nhẹ chúng** (chặn, hướng dẫn, làm sạch), và **cảnh báo bạn** khi có điều gì cần chú ý. Một bảng điều khiển cục bộ cho phép bạn xem lại mọi lệnh gọi công cụ, lỗi đại lý, và hành động khôi phục sau đó.
+
+Các bản ghi và đánh giá chính sách được giữ trên máy của bạn. Dữ liệu chỉ được gửi khi bạn rõ ràng sử dụng một tính năng trực tuyến, chẳng hạn như nhắc nhở kiểm toán được xác thực hoặc lời mời.
+
+## Bắt đầu
+
+<CardGroup cols={2}>
+
+<Card title="39 chính sách tích hợp sẵn" icon="shield" href="/vi/built-in-policies">
+  Chặn các lệnh hủy diệt, ngăn chặn rò rỉ bí mật, giữ các đại lý trong giới hạn dự án, và nhiều hơn nữa. Tất cả đều có sẵn ngoài hộp.
+</Card>
+
+<Card title="Chính sách tùy chỉnh" icon="code" href="/vi/custom-policies">
+  Viết các quy tắc của riêng bạn trong JavaScript với API allow / deny / instruct đơn giản.
+</Card>
+
+<Card title="Công cụ giám sát đại lý" icon="chart-line" href="/vi/dashboard">
+  Xem những gì các đại lý của bạn đã làm khi bạn vắng mặt. Duyệt qua các phiên, kiểm tra các lệnh gọi công cụ, xem lại nơi các chính sách được kích hoạt.
+</Card>
+
+<Card title="Cấu hình dễ dàng" icon="gear" href="/vi/configuration">
+  Điều chỉnh bất kỳ chính sách nào mà không cần mã. Đặt danh sách cho phép, nhánh được bảo vệ, hoặc ngưỡng cho mỗi dự án hoặc toàn cầu.
+</Card>
+
+</CardGroup>
+
+## Bắt đầu nhanh chóng
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies (or skip — `failproofai` will offer to set them up on first run)
+failproofai                      # launch the dashboard
+```
+
+Xem hướng dẫn [Bắt đầu](/vi/getting-started) để có hướng dẫn đầy đủ.

package/.next/standalone/docs-old/vi/package-aliases.mdx

@@ -0,0 +1,83 @@
+---
+---
+title: Bí danh Gói
+description: "Các bí danh phòng chống lỗi đánh máy đã đăng ký và cách chúng hoạt động"
+icon: copy
+---
+
+## Gói chính thức
+
+Gói npm chính tắc là **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# hoặc
+bun add -g failproofai
+```
+
+---
+
+## Tại sao chúng tôi sở hữu các bí danh
+
+Typosquatting là một cuộc tấn công chuỗi cung ứng phổ biến, trong đó một diễn viên độc hại đăng ký tên gói chỉ cách một phím bấm so với gói phổ biến. Những người dùng vô tình gõ sai lệnh cài đặt sẽ chạy mã được kiểm soát bởi kẻ tấn công với toàn quyền truy cập hệ thống - chính xác là loại mối đe dọa mà Failproof AI được thiết kế để phòng chống.
+
+Để loại bỏ bề mặt này, **chúng tôi chủ động sở hữu tất cả các lỗi đánh máy phổ biến và các biến thể định dạng** của `failproofai` trên npm. Không tên nào trong số này có thể được đăng ký bởi bên thứ ba. Mỗi tên là một proxy mỏng cài đặt và ủy quyền cho gói `failproofai` thực tế.
+
+---
+
+## Các bí danh đã đăng ký
+
+**Biến thể định dạng** - những cách khác nhau để viết "failproof ai":
+
+| Gói | Trạng thái |
+|---------|--------|
+| `failproof` | ✅ Đã xuất bản |
+| `failproof-ai` | ⏳ Chờ hỗ trợ npm |
+| `fail-proof-ai` | ⏳ Chờ hỗ trợ npm |
+| `failproof_ai` | ⏳ Chờ hỗ trợ npm |
+| `fail_proof_ai` | ⏳ Chờ hỗ trợ npm |
+| `fail-proofai` | ⏳ Chờ hỗ trợ npm |
+
+**Lỗi `failprof*`** - thiếu một `o` từ "proof":
+
+| Gói | Trạng thái |
+|---------|--------|
+| `failprof` | ✅ Đã xuất bản |
+| `failprof-ai` | ✅ Đã xuất bản |
+| `failprofai` | ⏳ Chờ hỗ trợ npm |
+| `fail-prof-ai` | ⏳ Chờ hỗ trợ npm |
+| `failprof_ai` | ⏳ Chờ hỗ trợ npm |
+
+**Lỗi `faliproof*`** - chữ `a` và `i` bị đảo lộn:
+
+| Gói | Trạng thái |
+|---------|--------|
+| `faliproof` | ✅ Đã xuất bản |
+| `faliproof-ai` | ✅ Đã xuất bản |
+| `faliproofai` | ⏳ Chờ hỗ trợ npm |
+
+> **Tại sao đang chờ?** Chính sách chống spam của npm chặn các tên được chuẩn hóa thành chuỗi giống với gói hiện có sau khi loại bỏ dấu câu và chạy kiểm tra tương tự. Chúng tôi đã liên hệ với hỗ trợ npm để đặt trữ những tên này cho mục đích chống squatting. Chúng sẽ được kích hoạt sau khi được phê duyệt.
+
+Bạn có thể xác minh bất kỳ bí danh đã xuất bản nào là của chúng tôi:
+
+```bash
+npm info failproof
+# Tìm: "ExosphereHost Inc." trong trường maintainers
+```
+
+---
+
+## Cách các bí danh hoạt động
+
+Mỗi gói bí danh:
+
+1. Liệt kê `failproofai` như một phụ thuộc - vì vậy gói thực tế được cài đặt và nhị phân của nó trở nên khả dụng
+2. Hiển thị một nhị phân khớp với tên của nó (ví dụ: `failprof-ai`) mà proxy tất cả các đối số cho nhị phân `failproofai`
+
+Proxy là một kịch bản Node hai dòng; không có logic, không có lệnh gọi mạng và không có bộ sưu tập dữ liệu ngoài những gì `failproofai` tự làm.
+
+---
+
+## Nếu bạn tìm thấy một tên chúng tôi đã bỏ lỡ
+
+Mở một vấn đề tại [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) và chúng tôi sẽ đăng ký nó.

package/.next/standalone/docs-old/vi/testing.mdx

@@ -0,0 +1,261 @@
+---
+---
+title: Kiểm thử
+description: "Kiểm thử đơn vị, kiểm thử end-to-end và trợ giúp kiểm thử"
+icon: flask-vial
+---
+
+failproofai có hai bộ kiểm thử: **kiểm thử đơn vị** (nhanh, được mock) và **kiểm thử end-to-end** (gọi subprocess thực tế).
+
+---
+
+## Chạy kiểm thử
+
+```bash
+# Chạy tất cả kiểm thử đơn vị một lần
+bun run test:run
+
+# Chạy kiểm thử đơn vị ở chế độ watch
+bun run test
+
+# Chạy kiểm thử E2E (yêu cầu thiết lập - xem bên dưới)
+bun run test:e2e
+
+# Kiểm tra loại mà không cần xây dựng
+bunx tsc --noEmit
+
+# Lint
+bun run lint
+```
+
+---
+
+## Kiểm thử đơn vị
+
+Kiểm thử đơn vị nằm trong `__tests__/` và sử dụng [Vitest](https://vitest.dev) với `jsdom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Logic chính sách cho mỗi builtin
+    hooks-config.test.ts          # Tải cấu hình và hợp nhất phạm vi
+    policy-evaluator.test.ts      # Tiêm param và thứ tự đánh giá
+    custom-hooks-registry.test.ts # Đăng ký globalThis add/get/clear
+    custom-hooks-loader.test.ts   # Trình tải ESM, import bắc cầu, xử lý lỗi
+    manager.test.ts               # Các hoạt động install/remove/list
+  components/
+    sessions-list.test.tsx        # Thành phần danh sách phiên
+    project-list.test.tsx         # Thành phần danh sách dự án
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### Viết kiểm thử đơn vị chính sách
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## Kiểm thử end-to-end
+
+Kiểm thử E2E gọi nhị phân `failproofai` thực tế như một subprocess, truyền một payload JSON đến stdin và khẳng định về stdout đầu ra và mã thoát. Điều này kiểm thử đường dẫn tích hợp hoàn chỉnh mà Claude Code sử dụng.
+
+### Thiết lập
+
+Kiểm thử E2E chạy nhị phân trực tiếp từ nguồn kho lưu trữ. Trước lần chạy đầu tiên, xây dựng CJS bundle mà các tệp hook tùy chỉnh sử dụng khi nhập từ `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Sau đó chạy kiểm thử:
+
+```bash
+bun run test:e2e
+```
+
+Xây dựng lại `dist/` mỗi khi bạn thay đổi API hook công khai (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` hoặc `src/hooks/policy-types.ts`).
+
+### Cấu trúc kiểm thử E2E
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Spawn nhị phân, truyền JSON payload, ghi mã thoát + stdout + stderr
+    fixture-env.ts      # Thư mục temp cách ly mỗi kiểm thử với tệp cấu hình
+    payloads.ts         # Nhà máy payload chính xác Claude cho mỗi loại sự kiện
+  hooks/
+    builtin-policies.e2e.test.ts   # Mỗi chính sách builtin với subprocess thực tế
+    custom-hooks.e2e.test.ts       # Tải và đánh giá hook tùy chỉnh
+    config-scopes.e2e.test.ts      # Hợp nhất cấu hình trên project/local/global
+    policy-params.e2e.test.ts      # Tiêm tham số cho mỗi chính sách tham số hóa
+```
+
+### Sử dụng trợ giúp E2E
+
+**`FixtureEnv`** - môi trường cách ly cho mỗi kiểm thử:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - thư mục temp; chuyển làm payload.cwd để chọn .failproofai/policies-config.json
+// env.home   - thư mục home cách ly; không có rò rỉ ~/.failproofai thực tế
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` tự động đăng ký dọn dẹp `afterEach`.
+
+**`runHook`** - gọi nhị phân:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** - nhà máy payload sẵn sàng:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### Viết kiểm thử E2E
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → empty stdout
+  });
+});
+```
+
+### Hình dạng phản hồi E2E
+
+| Quyết định | Mã thoát | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | stdout trống; lý do trong stderr |
+| Allow | `0` | chuỗi trống |
+
+### Cấu hình Vitest
+
+Kiểm thử E2E sử dụng `vitest.config.e2e.mts` với:
+
+- `environment: "node"` - không cần toàn cục trình duyệt
+- `pool: "forks"` - cách ly quy trình thực sự (các kiểm thử sinh subprocess)
+- `testTimeout: 20_000` - 20 giây cho mỗi kiểm thử (khởi động nhị phân + đánh giá hook)
+
+Pool `forks` rất quan trọng: các worker dựa trên luồng chia sẻ `globalThis`, điều này có thể can thiệp với các kiểm thử sinh subprocess. Các fork dựa trên quy trình tránh được điều này.
+
+---
+
+## CI
+
+Chạy CI đầy đủ (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) là bắt buộc phải vượt qua trước khi hợp nhất. Bộ kiểm thử E2E chạy như một công việc CI riêng biệt song song.
+
+Xem [Contributing](../CONTRIBUTING.md) để biết danh sách kiểm tra đầy đủ trước khi hợp nhất.

package/.next/standalone/docs-old/zh/agenteye/alerts.mdx

@@ -0,0 +1,63 @@
+---
+title: "告警"
+description: "在问题越过你的底线时立即获知，通过团队已在使用的渠道，而不是等到客户反映才知道。"
+---
+
+
+在问题越过你的底线时立即获知，通过团队已在使用的渠道，而不是等到客户反映才知道。规则只需设置一次，Failproof AI Observability 便会按计划检查，并通过邮件、Slack、webhook 或直接在仪表盘中通知你。
+
+![告警页面：告警规则卡片网格，每张卡片显示触发条件、评估窗口、通知渠道，以及信息、警告或严重等级标识](/agenteye/images/alerts.png)
+*一览所有告警规则：监控内容、检查频率、通知渠道及紧急程度。*
+
+## 在用户发现之前，先行了解问题
+
+不必盯着仪表盘刷新，祈祷能碰巧发现问题。只要是你希望在无人值守时也能及时收到通知的信号，就配置一条告警，让通知落到你本来就在用的地方：
+
+- **邮件**，发给需要知道的人。
+- **Slack**，附带直接跳转到事件的按钮的富文本消息。
+- **Webhook**，向 PagerDuty、Opsgenie 或你自己的端点发送 JSON POST，支持可选签名以便接收方验证来源。
+- **仪表盘内通知**，默认静默，适合在调试规则、暂时不想通知任何人时使用。
+
+一条规则可以同时绑定多个通知渠道，严重等级（信息、警告或严重）会一并传递，确保紧急告警一眼就能看出来。
+
+## 用表单配置规则，而非 JSON
+
+你只需在表单中描述什么叫"出了问题"，Failproof AI Observability 会自动生成底层规则。JSON 格式不过是表单背后生成的产物，你可以通过读它来理解规则，但几乎不需要手写。
+
+![新建告警表单：名称与描述、启用开关，以及包含指标阈值、自定义 SQL、评估分数、复合评估、单事件条件的触发器选项](/agenteye/images/alert-new.png)
+*选择触发器后，表单会自动切换为对应字段；点击保存即写入规则。*
+
+常规流程很快：填写名称、选择**触发器**（监控什么）、设置**阈值和窗口**（偏差多大、持续多久）、绑定至少一个**通知渠道**，然后**保存**，再点击**测试**发送一条模拟通知，确认每个目标渠道都已正确配置。在底层，这会生成一个简洁的规则描述，例如：
+
+```json
+{ "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 }
+```
+
+你不限于一种信号类型。选择最符合你对该故障理解的触发器：
+
+| 触发器 | 触发时机 |
+|---|---|
+| **指标阈值** | 预设指标（错误率、p95 或 p99 延迟、事件或错误次数、Token 消耗）在指定时间窗口内超过设定值 |
+| **自定义 SQL** | 你的只读查询返回了结果行，或计算值超过了阈值 |
+| **评估分数** | 某项评估的平均分（例如幻觉率）超过阈值 |
+| **复合评估** | 多项分数检查通过 any、all 或至少 N 项逻辑组合，用于捕捉仅在多项指标上共同体现的退化 |
+| **单事件** | 某个匹配的事件出现：特定 Agent、特定错误类型，或特定消息子字符串 |
+
+已经在[错误页面](/zh/agenteye/error-tracking)盯着某个故障看了？每一行都有一个 **+ alert** 按钮，点击即可打开预填好的表单，专门用于捕获该故障的再次发生——你刚刚排查过的事件，下次出现时就会主动通知你。
+
+**在哪里找到它：** 告警位于 `/<org-slug>/alerts`。创建、编辑、删除和测试规则需要 **`alerts:write`** 权限；仅查看只需 `alerts:read`。接收人选择器会按姓名列出你组织的成员，无需离开表单即可指定通知对象。
+
+## 只在真正需要时通知我
+
+一次偶发的异常测量不应该把你叫醒。**M of N** 降噪过滤器控制在最近几次检查中，需要有多少次失败才会真正触发告警通知。设为 **3 of 5** 后，只有在最近五次检查中至少有三次超标才会触发告警，从而避免抖动信号频繁误报；保留默认值 **1 of 1** 则在首次超标时立即触发。你还可以选择规则的执行频率，预设选项包括 1 分钟、5 分钟、15 分钟和 1 小时，根据信号的实际变化速度灵活选择。
+
+## 告警触发后会发生什么
+
+一旦触发，系统会创建一个**事件**并通知你的渠道一次。之后由团队确认、分配负责人、跟进处理并最终解决——全程有清晰归属的记录可查。这套分诊流程有专属页面，详见[事件管理](/zh/agenteye/incidents)。
+
+## 相关内容
+
+- [事件管理](/zh/agenteye/incidents)：追踪告警从触发到确认再到解决的全过程。
+- [错误追踪](/zh/agenteye/error-tracking)：对 Agent 故障进行分组，一键将其转化为告警规则。
+- [仪表盘](/zh/agenteye/dashboards)：查看共享看板，告警所依据的阈值均来源于此。
+- [CLI 与 Agents](/zh/agenteye/cli-and-agents)：从终端创建告警、确认事件，或将其脚本化集成到 CI 中。