failproofai 0.0.6-beta.2 → 0.0.6-beta.4

package/.next/standalone/docs/vi/custom-policies.mdx

@@ -1,353 +0,0 @@
----
-title: Chính sách tùy chỉnh
-description: "Viết các quy tắc của riêng bạn bằng JavaScript - thực thi quy ước, ngăn chặn sự trôi dạt, phát hiện lỗi, tích hợp với các hệ thống bên ngoài"
-icon: code
----
-
-Chính sách tùy chỉnh cho phép bạn viết các quy tắc cho bất kỳ hành vi nào của agent: thực thi quy ước dự án, ngăn chặn sự trôi dạt, kiểm soát các hoạt động tàn phá, phát hiện agent bị mắc kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, và nhiều hơn nữa. Chúng sử dụng cùng một hệ thống hook event và các quyết định `allow`, `deny`, `instruct` như các chính sách tích hợp.
-
----
-
-## Ví dụ nhanh
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-customPolicies.add({
-  name: "no-production-writes",
-  description: "Block writes to paths containing 'production'",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("production")) {
-      return deny("Writes to production paths are blocked");
-    }
-    return allow();
-  },
-});
-```
-
-Cài đặt nó:
-
-```bash
-failproofai policies --install --custom ./my-policies.js
-```
-
----
-
-## Hai cách để tải chính sách tùy chỉnh
-
-### Tùy chọn 1: Dựa trên quy ước (được khuyến nghị)
-
-Thả các tệp `*policies.{js,mjs,ts}` vào `.failproofai/policies/` và chúng sẽ được tải tự động — không cần cờ hoặc thay đổi cấu hình. Điều này hoạt động giống như git hooks: thả một tệp, nó sẽ hoạt động.
-
-```
-# Cấp độ dự án — được commit vào git, chia sẻ với nhóm
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# Cấp độ người dùng — cá nhân, áp dụng cho tất cả các dự án
-~/.failproofai/policies/my-policies.mjs
-```
-
-**Cách nó hoạt động:**
-- Cả thư mục dự án và thư mục người dùng đều được quét (kết hợp — không phải first-scope-wins)
-- Các tệp được tải theo thứ tự bảng chữ cái trong mỗi thư mục. Sử dụng tiền tố `01-`, `02-` để kiểm soát thứ tự
-- Chỉ các tệp khớp với `*policies.{js,mjs,ts}` được tải; các tệp khác bị bỏ qua
-- Mỗi tệp được tải độc lập (fail-open cho mỗi tệp)
-- Hoạt động cùng với các chính sách `--custom` rõ ràng và chính sách tích hợp
-
-<Tip>
-Chính sách quy ước là cách dễ nhất để xây dựng một tiêu chuẩn chất lượng cho tổ chức của bạn. Commit `.failproofai/policies/` vào git và mỗi thành viên nhóm sẽ tự động nhận được các quy tắc tương tự — không cần thiết lập trên mỗi nhà phát triển. Khi nhóm của bạn khám phá ra các chế độ lỗi mới, hãy thêm một chính sách và push. Theo thời gian, những quy tắc này trở thành một tiêu chuẩn chất lượng sống động liên tục cải thiện với mỗi đóng góp.
-</Tip>
-
-### Tùy chọn 2: Đường dẫn tệp rõ ràng
-
-```bash
-# Cài đặt với một tệp chính sách tùy chỉnh
-failproofai policies --install --custom ./my-policies.js
-
-# Thay thế đường dẫn tệp chính sách
-failproofai policies --install --custom ./new-policies.js
-
-# Xóa đường dẫn chính sách tùy chỉnh khỏi cấu hình
-failproofai policies --uninstall --custom
-```
-
-Đường dẫn tuyệt đối đã giải quyết được lưu trữ trong `policies-config.json` dưới dạng `customPoliciesPath`. Tệp được tải mới trên mỗi hook event - không có bộ nhớ đệm giữa các sự kiện.
-
-### Sử dụng cả hai cùng nhau
-
-Chính sách quy ước và tệp `--custom` rõ ràng có thể coexist. Thứ tự tải:
-
-1. Tệp `customPoliciesPath` rõ ràng (nếu được cấu hình)
-2. Tệp quy ước dự án (`{cwd}/.failproofai/policies/`, theo thứ tự bảng chữ cái)
-3. Tệp quy ước người dùng (`~/.failproofai/policies/`, theo thứ tự bảng chữ cái)
-
----
-
-## API
-
-### Import
-
-```js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-```
-
-### `customPolicies.add(hook)`
-
-Đăng ký một chính sách. Gọi hàm này bao nhiêu lần tùy ý cho nhiều chính sách trong cùng một tệp.
-
-```ts
-customPolicies.add({
-  name: string;                         // required - unique identifier
-  description?: string;                 // shown in `failproofai policies` output
-  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### Các trợ giúp quyết định
-
-| Hàm | Tác dụng | Sử dụng khi |
-|----------|--------|----------|
-| `allow()` | Cho phép hoạt động im lặng | Hành động là an toàn, không cần tin nhắn |
-| `deny(message)` | Chặn hoạt động | Agent không nên thực hiện hành động này |
-| `instruct(message)` | Thêm ngữ cảnh mà không chặn | Cung cấp cho agent ngữ cảnh bổ sung để giữ đúng hướng |
-
-`deny(message)` - tin nhắn xuất hiện cho Claude với tiền tố `"Blocked by failproofai:"`. Một `deny` duy nhất sẽ ngắn mạch tất cả đánh giá tiếp theo.
-
-`instruct(message)` - tin nhắn được thêm vào ngữ cảnh của Claude cho lệnh gọi công cụ hiện tại. Tất cả các tin nhắn `instruct` được tích lũy và cung cấp cùng nhau.
-
-<Tip>
-Bạn có thể thêm hướng dẫn bổ sung vào bất kỳ tin nhắn `deny` hoặc `instruct` nào bằng cách thêm trường `hint` trong `policyParams` — không cần thay đổi mã. Điều này hoạt động với chính sách tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), và quy ước người dùng (`.failproofai-user/`) cũng vậy. Xem [Configuration → hint](/vi/configuration#hint-cross-cutting) để biết thêm chi tiết.
-</Tip>
-
-### Tin nhắn cho phép thông tin
-
-`allow(message)` cho phép hoạt động **và** gửi một tin nhắn thông tin trở lại Claude. Tin nhắn được cung cấp dưới dạng `additionalContext` trong phản hồi stdout của trình xử lý hook — cơ chế tương tự được sử dụng bởi `instruct`, nhưng về mặt ngữ nghĩa khác: nó là một cập nhật trạng thái, không phải một cảnh báo.
-
-| Hàm | Tác dụng | Sử dụng khi |
-|----------|--------|----------|
-| `allow(message)` | Cho phép và gửi ngữ cảnh cho Claude | Xác nhận một kiểm tra đã vượt qua, hoặc giải thích tại sao một kiểm tra bị bỏ qua |
-
-Các trường hợp sử dụng:
-- **Xác nhận trạng thái:** `allow("All CI checks passed.")` — cho Claude biết mọi thứ đều ổn
-- **Giải thích fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết tại sao một kiểm tra bị bỏ qua để nó có bối cảnh đầy đủ
-- **Nhiều tin nhắn tích lũy:** nếu nhiều chính sách mỗi cái trả về `allow(message)`, tất cả các tin nhắn được kết hợp với ngắt dòng và cung cấp cùng nhau
-
-```js
-customPolicies.add({
-  name: "confirm-branch-status",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    const cwd = ctx.session?.cwd;
-    if (!cwd) return allow("No working directory, skipping branch check.");
-
-    // ... check branch status ...
-    if (allPushed) {
-      return allow("Branch is up to date with remote.");
-    }
-    return deny("Unpushed changes detected.");
-  },
-});
-```
-
-### Các trường `PolicyContext`
-
-| Trường | Loại | Mô tả |
-|-------|------|-------------|
-| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | Công cụ đang được gọi (ví dụ `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | Các tham số đầu vào của công cụ |
-| `payload` | `Record<string, unknown>` | Tải trọng sự kiện thô đầy đủ từ Claude Code |
-| `session` | `SessionMetadata \| undefined` | Ngữ cảnh phiên làm việc (xem bên dưới) |
-
-### Các trường `SessionMetadata`
-
-| Trường | Loại | Mô tả |
-|-------|------|-------------|
-| `sessionId` | `string` | Định danh phiên làm việc Claude Code |
-| `cwd` | `string` | Thư mục làm việc của phiên Claude Code |
-| `transcriptPath` | `string` | Đường dẫn đến tệp bảng điểm JSONL của phiên |
-
-### Các loại sự kiện
-
-| Sự kiện | Khi nó kích hoạt | Nội dung `toolInput` |
-|-------|--------------|----------------------|
-| `PreToolUse` | Trước khi Claude chạy công cụ | Đầu vào của công cụ (ví dụ `{ command: "..." }` cho Bash) |
-| `PostToolUse` | Sau khi công cụ hoàn thành | Đầu vào của công cụ + `tool_result` (kết quả) |
-| `Notification` | Khi Claude gửi thông báo | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks phải luôn trả về `allow()`, chúng không thể chặn thông báo |
-| `Stop` | Khi phiên Claude kết thúc | Rỗng |
-
----
-
-## Thứ tự đánh giá
-
-Chính sách được đánh giá theo thứ tự này:
-
-1. Chính sách tích hợp (theo thứ tự định nghĩa)
-2. Chính sách tùy chỉnh rõ ràng từ `customPoliciesPath` (theo thứ tự `.add()`)
-3. Chính sách quy ước từ dự án `.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, thứ tự `.add()` bên trong)
-4. Chính sách quy ước từ người dùng `~/.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, thứ tự `.add()` bên trong)
-
-<Note>
-`deny` đầu tiên sẽ ngắn mạch tất cả các chính sách tiếp theo. Tất cả các tin nhắn `instruct` được tích lũy và cung cấp cùng nhau.
-</Note>
-
----
-
-## Imports truyền bá
-
-Các tệp chính sách tùy chỉnh có thể import các mô-đun cục bộ sử dụng đường dẫn tương đối:
-
-```js
-// my-policies.js
-import { isBlockedPath } from "./utils.js";
-import { checkApproval } from "./approval-client.js";
-
-customPolicies.add({
-  name: "approval-gate",
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
-    return approved ? allow() : deny("Approval required for this command");
-  },
-});
-```
-
-Tất cả các nhập tương đối có thể đạt được từ tệp mục nhập đều được giải quyết. Điều này được thực hiện bằng cách viết lại các nhập `from "failproofai"` thành đường dẫn dist thực tế và tạo các tệp `.mjs` tạm thời để đảm bảo khả năng tương thích ESM.
-
----
-
-## Lọc theo loại sự kiện
-
-Sử dụng `match.events` để giới hạn khi nào một chính sách kích hoạt:
-
-```js
-customPolicies.add({
-  name: "require-summary-on-stop",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    // Only fires when the session ends
-    // ctx.session.transcriptPath contains the full session log
-    return allow();
-  },
-});
-```
-
-Bỏ qua `match` hoàn toàn để kích hoạt trên mọi loại sự kiện.
-
----
-
-## Xử lý lỗi và chế độ hỏng
-
-Chính sách tùy chỉnh **fail-open**: lỗi không bao giờ chặn chính sách tích hợp hoặc làm hỏng trình xử lý hook.
-
-| Lỗi | Hành vi |
-|---------|----------|
-| `customPoliciesPath` không được đặt | Không có chính sách tùy chỉnh rõ ràng chạy; chính sách quy ước và tích hợp tiếp tục bình thường |
-| Tệp không tìm thấy | Cảnh báo được ghi vào `~/.failproofai/hook.log`; tích hợp tiếp tục |
-| Lỗi Syntax/import (rõ ràng) | Lỗi được ghi vào `~/.failproofai/hook.log`; chính sách tùy chỉnh rõ ràng bị bỏ qua |
-| Lỗi Syntax/import (quy ước) | Lỗi được ghi; tệp đó bị bỏ qua, các tệp quy ước khác vẫn tải |
-| `fn` ném khi chạy | Lỗi được ghi; hook đó được coi là `allow`; các hook khác tiếp tục |
-| `fn` mất quá lâu hơn 10 giây | Timeout được ghi; được coi là `allow` |
-| Thư mục quy ước bị thiếu | Không có chính sách quy ước chạy; không có lỗi |
-
-<Tip>
-Để gỡ lỗi lỗi chính sách tùy chỉnh, hãy theo dõi tệp nhật ký:
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Ví dụ đầy đủ: nhiều chính sách
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Prevent agent from writing to secrets/ directory
-customPolicies.add({
-  name: "block-secrets-dir",
-  description: "Prevent agent from writing to secrets/ directory",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
-    return allow();
-  },
-});
-
-// Keep the agent on track: verify tests before committing
-customPolicies.add({
-  name: "remind-test-before-commit",
-  description: "Keep the agent on track: verify tests pass before committing",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    if (/git\s+commit/.test(cmd)) {
-      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
-    }
-    return allow();
-  },
-});
-
-// Prevent unplanned dependency changes during freeze
-customPolicies.add({
-  name: "dependency-freeze",
-  description: "Prevent unplanned dependency changes during freeze period",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
-    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
-      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
-    }
-    return allow();
-  },
-});
-
-export { customPolicies };
-```
-
----
-
-## Ví dụ
-
-Thư mục `examples/` chứa các tệp chính sách sẵn sàng chạy:
-
-| Tệp | Nội dung |
-|------|----------|
-| `examples/policies-basic.js` | Năm chính sách khởi động bao gồm các chế độ lỗi agent phổ biến |
-| `examples/policies-advanced/index.js` | Các mẫu nâng cao: nhập truyền bá, lệnh gọi async, scrubbing đầu ra, và hook kết thúc phiên |
-| `examples/convention-policies/security-policies.mjs` | Chính sách bảo mật dựa trên quy ước (chặn ghi .env, ngăn viết lại lịch sử git) |
-| `examples/convention-policies/workflow-policies.mjs` | Chính sách quy trình công việc dựa trên quy ước (nhắc nhở kiểm tra, tệp ghi kiểm toán) |
-
-### Sử dụng các ví dụ tệp rõ ràng
-
-```bash
-failproofai policies --install --custom ./examples/policies-basic.js
-```
-
-### Sử dụng các ví dụ dựa trên quy ước
-
-```bash
-# Copy to project level
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# Or copy to user level
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-Không cần lệnh cài đặt — các tệp được nhận diện tự động trên hook event tiếp theo.

package/.next/standalone/docs/vi/dashboard.mdx

@@ -1,142 +0,0 @@
----
-title: Dashboard
-description: "Giám sát các phiên làm việc của agent, xem xét các lệnh gọi công cụ và quản lý chính sách"
-icon: chart-line
----
-
-Dashboard failproofai là một ứng dụng web cục bộ để giám sát các phiên làm việc của agent AI và quản lý chính sách. Xem những gì các agent của bạn đã làm khi bạn vắng mặt.
-
----
-
-## Khởi động dashboard
-
-```bash
-failproofai
-```
-
-Mở tại `http://localhost:8020`.
-
-Dashboard đọc trực tiếp từ hệ thống tập tin - các thư mục dự án Claude Code của bạn và các tệp cấu hình failproofai. Không có dữ liệu nào được ghi vào dịch vụ từ xa.
-
----
-
-## Các trang
-
-### Projects
-
-Liệt kê tất cả các dự án Claude Code được tìm thấy trên máy của bạn. Các dự án được phát hiện từ `~/.claude/projects/` (hoặc đường dẫn được đặt bởi `CLAUDE_PROJECTS_PATH`).
-
-Mỗi dự án hiển thị:
-- Tên dự án (được lấy từ đường dẫn thư mục)
-- Số lượng phiên làm việc
-- Ngày hoạt động phiên làm việc gần nhất
-
-Nhấp vào một dự án để xem các phiên làm việc của nó.
-
-### Sessions
-
-Liệt kê tất cả các phiên làm việc trong một dự án. Mỗi phiên làm việc hiển thị:
-- ID phiên làm việc
-- Dấu thời gian bắt đầu và kết thúc
-- Số lượng lệnh gọi công cụ
-- Số lượng hoạt động hook (các chính sách đã được kích hoạt)
-
-Sử dụng bộ lọc phạm vi ngày và tìm kiếm ID phiên làm việc để thu hẹp danh sách. Các phiên làm việc được chia thành các trang.
-
-Nhấp vào một phiên làm việc để mở trình xem phiên làm việc.
-
-### Session viewer
-
-Trình xem phiên làm việc trả lời câu hỏi chính cho các agent tự động hóa: agent đã làm gì và có ở đúng hướng không? Nó hiển thị một dòng thời gian của mọi thứ đã xảy ra trong một phiên làm việc:
-
-- **Messages** - Các phản hồi văn bản của Claude và các lời nhắc từ người dùng
-- **Tool calls** - Mọi công cụ mà Claude đã gọi, kèm theo đầu vào và đầu ra của nó
-- **Policy activity** - Đối với mỗi lệnh gọi công cụ, các chính sách nào đã được kích hoạt và quyết định nào mà chúng trả về
-
-Thanh thống kê ở phía trên cùng hiển thị thời lượng phiên làm việc, tổng số lệnh gọi công cụ và tóm tắt quyết định hook (số lượng allow / deny / instruct).
-
-Bạn có thể xuất phiên làm việc dưới dạng tệp ZIP hoặc JSONL bằng nút tải xuống.
-
-### Policies
-
-Một trang có hai tab để quản lý chính sách và xem xét hoạt động.
-
-<Tabs>
-  <Tab title="Policies tab">
-  - Bật hoặc tắt các chính sách riêng lẻ bằng một cú nhấp chuột (ghi vào `~/.failproofai/policies-config.json`)
-  - Mở rộng một chính sách để cấu hình các tham số của nó (đối với các chính sách hỗ trợ `policyParams`)
-  - Cài đặt hoặc xóa hook cho một phạm vi nhất định
-  - Đặt đường dẫn tệp chính sách tùy chỉnh
-  </Tab>
-  <Tab title="Activity tab">
-  - Lịch sử đầy đủ được chia trang của mọi sự kiện hook đã được kích hoạt trên tất cả các phiên làm việc
-  - Tìm kiếm theo tên chính sách, ID phiên làm việc, tên công cụ hoặc quyết định
-  - Mỗi hàng hiển thị: dấu thời gian, tên chính sách, quyết định, tên công cụ, ID phiên làm việc và lý do cho các quyết định deny/instruct
-  </Tab>
-</Tabs>
-
----
-
-## Tự động làm mới
-
-Dashboard có một công tắc tự động làm mới trong thanh điều hướng trên cùng. Khi được bật, trang hiện tại được làm mới định kỳ để hiển thị các phiên làm việc và hoạt động chính sách mới khi chúng xuất hiện. Thiết yếu để giám sát các phiên làm việc của agent tự động hóa chạy lâu dài.
-
----
-
-## Vô hiệu hóa các trang
-
-Nếu bạn chỉ cần một số phần của dashboard, hãy đặt `FAILPROOFAI_DISABLE_PAGES` thành một danh sách tên trang được phân tách bằng dấu phẩy:
-
-```bash
-FAILPROOFAI_DISABLE_PAGES=policies failproofai
-```
-
-Các giá trị hợp lệ: `policies`, `projects`.
-
----
-
-## Chủ đề
-
-Dashboard hỗ trợ chế độ sáng và chế độ tối. Chuyển đổi qua nút trong thanh điều hướng. Tùy chọn được lưu trữ trong bộ nhớ cục bộ của trình duyệt của bạn.
-
----
-
-## Cấu hình đường dẫn dự án
-
-Theo mặc định, dashboard đọc từ thư mục dự án Claude Code tiêu chuẩn. Ghi đè nó cho các thiết lập tùy chỉnh:
-
-```bash
-CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
-```
-
----
-
-## Truy cập từ máy chủ không phải localhost
-
-Khi chạy dashboard ở **chế độ phát triển** (`npm run dev`) và truy cập nó từ tên máy chủ khác ngoài `localhost` - ví dụ như một miền tùy chỉnh, IP từ xa hoặc URL được đường hầm - bạn có thể thấy cảnh báo như:
-
-```text
-⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
-```
-
-Đây là Next.js chặn quyền truy cập cross-origin vào websocket HMR (hot module reload) của nó, đây là một tính năng chỉ cho phát triển. Để cho phép máy chủ của bạn, hãy sử dụng cờ `--allowed-origins`:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com
-```
-
-Để có nhiều máy chủ hoặc IP, hãy chuyển một danh sách được phân tách bằng dấu phẩy:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
-```
-
-Bạn cũng có thể đặt biến môi trường `FAILPROOFAI_ALLOWED_DEV_ORIGINS`:
-
-```bash
-FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
-```
-
-<Note>
-Điều này chỉ áp dụng cho chế độ phát triển. Khi chạy `failproofai` (chế độ production), không có websocket HMR và không có vấn đề tài nguyên phát triển cross-origin.
-</Note>