failproofai 0.0.5 → 0.0.6-beta.1

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

@@ -1,10 +1,10 @@
 ---
 title: Пользовательские политики
-description: "Напишите свои собственные политики на JavaScript - применяйте соглашения, предотвращайте дрейф, обнаруживайте сбои, интегрируйте с внешними системами"
+description: "Напишите свои собственные политики на JavaScript — обеспечьте соблюдение соглашений, предотвратите отклонения, обнаружьте сбои, интегрируйте с внешними системами"
 icon: code
 ---
 
-Пользовательские политики позволяют написать правила для любого поведения агента: применять соглашения проекта, предотвращать дрейф, блокировать деструктивные операции, обнаруживать зависшие агенты или интегрироваться с Slack, рабочими процессами одобрения и многим другим. Они используют ту же систему событий перехватчиков и решения `allow`, `deny`, `instruct`, что и встроенные политики.
+Пользовательские политики позволяют вам написать правила для любого поведения агента: обеспечить соблюдение проектных соглашений, предотвратить отклонения, заблокировать деструктивные операции, обнаружить зависшие агенты или интегрироваться с Slack, рабочими процессами утверждения и т. д. Они используют ту же систему событий hook и решения `allow`, `deny`, `instruct`, что и встроенные политики.
 
 ---
 
@@ -41,48 +41,48 @@ failproofai policies --install --custom ./my-policies.js
 
 ### Вариант 1: На основе соглашений (рекомендуется)
 
-Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они будут загружены автоматически — никаких флагов или изменений конфигурации не требуется. Это работает как git hooks: поместите файл, и он просто работает.
+Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они будут автоматически загружены — не требуется никаких флагов или изменений конфигурации. Это работает как git hooks: поместите файл, и он просто работает.
 
 ```
-# На уровне проекта — коммитится в git, делится с командой
+# Уровень проекта — коммитится в git, общий для всей команды
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
-# На уровне пользователя — личные, применяется ко всем проектам
+# Уровень пользователя — личный, применяется ко всем проектам
 ~/.failproofai/policies/my-policies.mjs
 ```
 
 **Как это работает:**
-- Сканируются оба каталога — проекта и пользователя (объединение — не первый приоритет)
-- Файлы загружаются в алфавитном порядке в каждом каталоге. Используйте префиксы `01-`, `02-` для управления порядком
-- Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}`; остальные файлы игнорируются
+- Оба директория проекта и пользователя сканируются (объединение — не первый находит победителя)
+- Файлы загружаются в алфавитном порядке в каждом директории. Используйте префикс `01-`, `02-` для управления порядком
+- Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}`; другие файлы игнорируются
 - Каждый файл загружается независимо (fail-open для каждого файла)
-- Работает вместе с явным `--custom` и встроенными политиками
+- Работает наряду с явным `--custom` и встроенными политиками
 
 <Tip>
-Политики на основе соглашений — это самый простой способ поделиться политиками с командой. Закоммитьте `.failproofai/policies/` в git, и каждый член команды получит их автоматически.
+Политики соглашений — самый простой способ поделиться политиками с командой. Коммитьте `.failproofai/policies/` в git, и каждый член команды получит их автоматически.
 </Tip>
 
-### Вариант 2: Явный путь к файлу
+### Вариант 2: Явный путь файла
 
 ```bash
 # Установите с файлом пользовательских политик
 failproofai policies --install --custom ./my-policies.js
 
-# Замените путь к файлу политик
+# Замените путь файла политик
 failproofai policies --install --custom ./new-policies.js
 
-# Удалите путь к пользовательским политикам из конфигурации
+# Удалите путь пользовательских политик из конфигурации
 failproofai policies --uninstall --custom
 ```
 
-Разрешённый абсолютный путь сохраняется в `policies-config.json` как `customPoliciesPath`. Файл загружается заново при каждом событии перехватчика — кэширования между событиями нет.
+Разрешённый абсолютный путь сохраняется в `policies-config.json` как `customPoliciesPath`. Файл загружается заново при каждом событии hook — кеширования между событиями нет.
 
-### Использование обоих способов вместе
+### Использование обоих вместе
 
-Политики на основе соглашений и явный файл `--custom` могут сосуществовать. Порядок загрузки:
+Политики соглашений и явный файл `--custom` могут сосуществовать. Порядок загрузки:
 
-1. Явный файл `customPoliciesPath` (если настроен)
+1. Файл явной `customPoliciesPath` (если настроена)
 2. Файлы соглашений проекта (`{cwd}/.failproofai/policies/`, в алфавитном порядке)
 3. Файлы соглашений пользователя (`~/.failproofai/policies/`, в алфавитном порядке)
 
@@ -98,46 +98,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-Регистрирует политику. Вызывайте столько раз, сколько нужно для нескольких политик в одном файле.
+Регистрирует политику. Вызовите это столько раз, сколько требуется, для нескольких политик в одном файле.
 
 ```ts
 customPolicies.add({
   name: string;                         // обязательно - уникальный идентификатор
-  description?: string;                 // отображается в выводе `failproofai policies`
-  match?: { events?: HookEventType[] }; // фильтр по типу события; опустите, чтобы совпадал все
+  description?: string;                 // показывается в выводе `failproofai policies`
+  match?: { events?: HookEventType[] }; // фильтр по типу события; опустите для совпадения со всеми
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
 
-### Помощники для принятия решений
+### Вспомогательные функции решений
 
-| Функция | Эффект | Используйте когда |
-|---------|--------|------------------|
+| Функция | Эффект | Используйте, когда |
+|---------|--------|----------|
 | `allow()` | Разрешить операцию молча | Действие безопасно, сообщение не требуется |
 | `deny(message)` | Заблокировать операцию | Агент не должен выполнять это действие |
-| `instruct(message)` | Добавить контекст без блокировки | Дайте агенту дополнительный контекст для выполнения задачи |
+| `instruct(message)` | Добавить контекст без блокирования | Дайте агенту дополнительный контекст для правильного выполнения |
 
-`deny(message)` — сообщение отображается Claude с префиксом `"Blocked by failproofai:"`. Один `deny` короткозамыкает всю дальнейшую оценку.
+`deny(message)` — сообщение появляется Claude с префиксом `"Blocked by failproofai:"`. Одно `deny` прерывает всю дальнейшую оценку.
 
-`instruct(message)` — сообщение добавляется в контекст Claude для текущего вызова инструмента. Все сообщения `instruct` накапливаются и доставляются вместе.
+`instruct(message)` — сообщение добавляется к контексту Claude для текущего вызова инструмента. Все сообщения `instruct` накапливаются и доставляются вместе.
 
 <Tip>
-Вы можете добавить дополнительные рекомендации к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных (`failproofai-project/`) и пользовательских (`failproofai-user/`) политик. См. [Конфигурация → hint](/ru/configuration#hint-cross-cutting) для подробностей.
+Вы можете добавить дополнительное руководство к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных соглашений (`.failproofai-project/`) и пользовательских соглашений (`.failproofai-user/`) политик. Подробнее см. [Configuration → hint](/ru/configuration#hint-cross-cutting).
 </Tip>
 
 ### Информационные сообщения allow
 
+`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответ stdout обработчика hook — того же механизма, используемого `instruct`, но семантически отличного: это обновление статуса, а не предупреждение.
 
-`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика перехватчика — тот же механизм, используемый `instruct`, но семантически отличается: это обновление статуса, а не предупреждение.
-
-| Функция | Эффект | Используйте когда |
-|---------|--------|------------------|
-| `allow(message)` | Разрешить и отправить контекст Claude | Подтвердить, что проверка прошла, или объяснить, почему проверка была пропущена |
+| Функция | Эффект | Используйте, когда |
+|---------|--------|----------|
+| `allow(message)` | Разрешить и отправить контекст Claude | Подтвердить прохождение проверки или объяснить, почему проверка была пропущена |
 
 Варианты использования:
-- **Подтверждения статуса:** `allow("All CI checks passed.")` — указывает Claude, что всё зелено
-- **Объяснения fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — указывает Claude, почему проверка была пропущена, чтобы он имел полный контекст
-- **Несколько сообщений накапливаются:** если несколько политик возвращают `allow(message)`, все сообщения объединяются с новыми строками и доставляются вместе
+- **Подтверждения статуса:** `allow("All CI checks passed.")` — говорит Claude, что всё хорошо
+- **Объяснения fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — говорит Claude, почему проверка была пропущена, чтобы у неё был полный контекст
+- **Несколько сообщений накапливаются:** если несколько политик возвращают `allow(message)`, все сообщения объединяются с переводами строк и доставляются вместе
 
 ```js
 customPolicies.add({
@@ -159,35 +158,35 @@ customPolicies.add({
 ### Поля `PolicyContext`
 
 | Поле | Тип | Описание |
-|------|-----|---------|
+|------|------|-------------|
 | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | Вызываемый инструмент (например `"Bash"`, `"Write"`, `"Read"`) |
+| `toolName` | `string \| undefined` | Вызываемый инструмент (например, `"Bash"`, `"Write"`, `"Read"`) |
 | `toolInput` | `Record<string, unknown> \| undefined` | Входные параметры инструмента |
-| `payload` | `Record<string, unknown>` | Полная необработанная полезная нагрузка события от Claude Code |
+| `payload` | `Record<string, unknown>` | Полное необработанное событие от Claude Code |
 | `session` | `SessionMetadata \| undefined` | Контекст сессии (см. ниже) |
 
 ### Поля `SessionMetadata`
 
 | Поле | Тип | Описание |
-|------|-----|---------|
+|------|------|-------------|
 | `sessionId` | `string` | Идентификатор сессии Claude Code |
-| `cwd` | `string` | Рабочий каталог сессии Claude Code |
+| `cwd` | `string` | Рабочий директорий сессии Claude Code |
 | `transcriptPath` | `string` | Путь к файлу транскрипта JSONL сессии |
 
 ### Типы событий
 
 | Событие | Когда срабатывает | Содержимое `toolInput` |
-|---------|------------------|----------------------|
-| `PreToolUse` | До запуска инструмента Claude | Вход инструмента (например `{ command: "..." }` для Bash) |
-| `PostToolUse` | После завершения инструмента | Вход инструмента + `tool_result` (выход) |
-| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - перехватчики должны всегда возвращать `allow()`, они не могут блокировать уведомления |
-| `Stop` | Когда сессия Claude заканчивается | Пусто |
+|--------|--------------|----------------------|
+| `PreToolUse` | Перед запуском инструмента Claude | Входные данные инструмента (например, `{ command: "..." }` для Bash) |
+| `PostToolUse` | После завершения инструмента | Входные данные инструмента + `tool_result` (результат) |
+| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks должны всегда возвращать `allow()`, они не могут блокировать уведомления |
+| `Stop` | Когда сессия Claude завершается | Пусто |
 
 ---
 
 ## Порядок оценки
 
-Политики оцениваются в следующем порядке:
+Политики оцениваются в таком порядке:
 
 1. Встроенные политики (в порядке определения)
 2. Явные пользовательские политики из `customPoliciesPath` (в порядке `.add()`)
@@ -195,7 +194,7 @@ customPolicies.add({
 4. Политики соглашений из пользователя `~/.failproofai/policies/` (файлы в алфавитном порядке, `.add()` внутри)
 
 <Note>
-Первый `deny` короткозамыкает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе.
+Первое `deny` прерывает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе.
 </Note>
 
 ---
@@ -219,11 +218,11 @@ customPolicies.add({
 });
 ```
 
-Все относительные импорты, достижимые из входного файла, разрешаются. Это реализуется путём переписывания импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM.
+Все относительные импорты, достижимые из файла входа, разрешаются. Это реализовано переписыванием импортов `from "failproofai"` на фактический путь dist и созданием временных файлов `.mjs` для обеспечения совместимости ESM.
 
 ---
 
-## Фильтрация по типам событий
+## Фильтрация типов событий
 
 Используйте `match.events` для ограничения срабатывания политики:
 
@@ -245,20 +244,20 @@ customPolicies.add({
 
 ## Обработка ошибок и режимы отказа
 
-Пользовательские политики — это **fail-open**: ошибки никогда не блокируют встроенные политики и не приводят к сбою обработчика перехватчика.
+Пользовательские политики — **fail-open**: ошибки никогда не блокируют встроенные политики и не вызывают крах обработчика hook.
 
 | Отказ | Поведение |
-|-------|----------|
-| `customPoliciesPath` не установлен | Явные пользовательские политики не запускаются; встроенные политики продолжают нормально работать |
-| Файл не найден | Предупреждение записывается в `~/.failproofai/hook.log`; встроенные политики продолжают работать |
-| Синтаксис/ошибка импорта (явная) | Ошибка записывается в `~/.failproofai/hook.log`; явные пользовательские политики пропускаются |
-| Синтаксис/ошибка импорта (соглашение) | Ошибка записывается; этот файл пропускается, другие файлы соглашений загружаются |
-| `fn` выбрасывает ошибку во время выполнения | Ошибка записывается; этот перехватчик рассматривается как `allow`; другие перехватчики продолжают работу |
-| `fn` занимает больше 10 секунд | Истечение времени ожидания записывается; рассматривается как `allow` |
-| Каталог соглашений отсутствует | Политики соглашений не запускаются; нет ошибки |
+|---------|----------|
+| `customPoliciesPath` не установлена | Явные пользовательские политики не запускаются; встроенные и политики соглашений работают нормально |
+| Файл не найден | Предупреждение логируется в `~/.failproofai/hook.log`; встроенные работают |
+| Ошибка синтаксиса/импорта (явная) | Ошибка логируется в `~/.failproofai/hook.log`; явные пользовательские политики пропущены |
+| Ошибка синтаксиса/импорта (соглашение) | Ошибка логируется; этот файл пропущен, другие файлы соглашений всё ещё загружаются |
+| `fn` выбрасывает во время выполнения | Ошибка логируется; этот hook рассматривается как `allow`; другие hooks продолжают работать |
+| `fn` работает дольше 10 сек | Timeout логируется; рассматривается как `allow` |
+| Директорий соглашений отсутствует | Политики соглашений не запускаются; нет ошибки |
 
 <Tip>
-Для отладки ошибок пользовательских политик используйте файл журнала:
+Для отладки ошибок пользовательской политики смотрите файл журнала:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -273,7 +272,7 @@ tail -f ~/.failproofai/hook.log
 // my-policies.js
 import { customPolicies, allow, deny, instruct } from "failproofai";
 
-// Предотвращайте запись агента в каталог secrets/
+// Предотвратите запись агента в директорий secrets/
 customPolicies.add({
   name: "block-secrets-dir",
   description: "Prevent agent from writing to secrets/ directory",
@@ -286,7 +285,7 @@ customPolicies.add({
   },
 });
 
-// Держите агента на правильном пути: проверьте тесты перед коммитом
+// Удерживайте агента на правильном пути: проверьте тесты перед коммитом
 customPolicies.add({
   name: "remind-test-before-commit",
   description: "Keep the agent on track: verify tests pass before committing",
@@ -301,7 +300,7 @@ customPolicies.add({
   },
 });
 
-// Предотвращайте незапланированные изменения зависимостей во время заморозки
+// Предотвратите неплановые изменения зависимостей во время заморозки
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -324,16 +323,16 @@ export { customPolicies };
 
 ## Примеры
 
-Каталог `examples/` содержит готовые файлы политик:
+Директорий `examples/` содержит готовые файлы политик:
 
 | Файл | Содержимое |
-|------|-----------|
-| `examples/policies-basic.js` | Пять начальных политик, охватывающих типичные режимы отказа агента |
-| `examples/policies-advanced/index.js` | Продвинутые паттерны: транзитивные импорты, асинхронные вызовы, очистка выводов и перехватчики завершения сессии |
-| `examples/convention-policies/security-policies.mjs` | Политики безопасности на основе соглашений (блокировка записей .env, предотвращение переписывания истории git) |
+|------|----------|
+| `examples/policies-basic.js` | Пять начальных политик, охватывающих частые режимы отказа агента |
+| `examples/policies-advanced/index.js` | Продвинутые паттерны: транзитивные импорты, асинхронные вызовы, очистка вывода и hooks завершения сессии |
+| `examples/convention-policies/security-policies.mjs` | Политики безопасности на основе соглашений (блокировка записи .env, предотвращение переписывания истории git) |
 | `examples/convention-policies/workflow-policies.mjs` | Политики рабочего процесса на основе соглашений (напоминания о тестах, аудит записей файлов) |
 
-### Использование примеров явных файлов
+### Использование примеров явного файла
 
 ```bash
 failproofai policies --install --custom ./examples/policies-basic.js
@@ -351,4 +350,4 @@ mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-Команда установки не требуется — файлы выбираются автоматически при следующем событии перехватчика.
+Команда install не требуется — файлы будут подхвачены автоматически при следующем событии hook.